ParvLab/CryptoTrace

# CryptoTrace [](https://github.com/parv68/CryptoTrace/actions/workflows/ci.yml) [](LICENSE) [](Cargo.toml) CryptoTrace 是一个开源的**加密指纹识别与数据分类引擎**。 给它一个可疑文件、一串字节或一个字符串。 CryptoTrace 会分类出它最可能是什么。 分类示例： - Hash (MD5, SHA-1, SHA-256, bcrypt, Argon2, NTLM, PBKDF2 变体) - 编码 (Base64, Hex, Base32, Base58, Ascii85, Z85, Base91, URL 编码) - 压缩格式 (GZIP, Zstd, XZ, BZ2, Brotli, LZ4, ZIP) - 文件格式 (用于常见格式和子类型的 magic-byte 注册表) - 高熵 payload 和可能的加密启发式检测 CryptoTrace 不会进行解密。 它不声称具有确定性。 它会解释它看到了什么、它的可信度以及原因。 默认处于 Air-gapped（物理隔离）状态。 网络功能需要主动开启（opt-in）。 ## 目录 1. 本项目解决的问题 2. CryptoTrace 是什么（以及不是什么） 3. 适用人群 4. 快速开始 5. 工作原理（架构） 6. 功能概览 7. CLI 参考 8. 输出 Schema 9. 配置参考 10. 安全模型 11. 威胁情报（Opt-In） 12. SIEM 集成 (CEF/LEEF) 13. 报告 (JSON/HTML) 14. 签名数据库与更新 15. 校准（置信度模型） 16. 测试、模糊测试与质量门禁 17. 打包与分发（v1 计划） 18. 开发 19. 故障排除 20. 项目状态与路线图 21. 贡献 22. 许可证 ## 本项目解决的问题 在真正的安全工作中，你经常会遇到未知数据： - PowerShell 脚本中的一段 blob - 日志中看起来像 base64 的字符串 - 一个“打不开”但带有可识别文件头的文件 - 一个可能是打包 payload 的可疑附件 - 包含混合 hash 格式的凭据转储文件 你需要快速得到答案： - 这最有可能是什么 - 它是否被分层包裹 - 它是否是弱加密 - 处理它是否安全 - 我能否将其通过管道传入 pipeline 并获得确定性输出 CryptoTrace 旨在通过以下方式回答这些问题： - 确定性信号 - 保守的启发式算法 - 可解释性 - 安全防护机制 ## CryptoTrace 是什么（以及不是什么） CryptoTrace 是： - 一个分类器和信号聚合器 - 用于分诊的取证助手 - 针对攻击者可控输入的安全默认分析器 CryptoTrace 不是： - 解密工具 - 恶意软件沙箱 - 完全逆向工程的替代品 CryptoTrace 坦诚其局限性： - 高熵并不意味着加密 - 许多编码器和打包器是自定义的 - 恶意软件可以逃避常见的检测器 ## 适用人群 CryptoTrace 专为以下人员设计： 1. SOC 分析师 2. 事件响应人员 3. 恶意软件研究人员 4. 取证工程师 5. 安全审计员 6. 学习加密格式和 payload 处理的学生 ## 快速开始 ### 安装（任何操作系统只需一条命令） **选项 1 — 已安装 Rust：** ``` cargo install cryptotrace ``` **选项 2 — macOS：** ``` brew install parv68/tap/cryptotrace ``` **选项 3 — Linux / macOS（无 Rust）：** ``` curl -sSfL https://github.com/parv68/CryptoTrace/releases/latest/download/install.sh | sh ``` **选项 4 — Windows (PowerShell，无 Rust)：** ``` powershell -c "iwr https://github.com/parv68/CryptoTrace/releases/latest/download/install.ps1 | iex" ``` ### 验证 ``` cryptotrace version ``` ### 分析字符串 ``` cryptotrace analyze "5f4dcc3b5aa765d61d8327deb882cf99" --explain ``` ### 分析文件 ``` cryptotrace analyze suspicious.bin --deep --sandbox ``` ### JSON 输出 ``` cryptotrace analyze suspicious.bin --json ``` ## 工作原理（架构） CryptoTrace 将输入转化为信号。 信号转化为置信度得分。 置信度转化为可解释的决策。 作为可选项，CryptoTrace 会解包各层。 ``` flowchart TD A[Input file / string / bytes] --> B[Sanitization size limits null policy path validation] B --> C[Signal Extraction hash detection encoding detection compression detection magic bytes entropy + sliding entropy encryption heuristics] C --> D[Confidence Engine multi-signal weighting correlated cap] D --> E[Calibration Layer optional Platt scaling] E --> F[Recursive Layer Analyzer depth limit timeout expansion ratio guard cycle detection] F --> G[Intelligence risk mapping CVE mapping recommendations] G --> H[Outputs terminal JSON HTML CEF/LEEF] ``` 安全防护机制是不可妥协的： - 最大文件大小 - 最大递归深度 - 最大递归时间 - 最大扩展比率 - worker 隔离 ## 功能概览 本节是一个实用的概述。 详细信息在 README 的后面部分。 ### 1. Hash 检测 CryptoTrace 检测常见的 hash。 它还避免了格式重叠时的误报。 示例： - UUID 与 MD5 的消歧义 - NTLM 与常规 32 位十六进制字符串的消歧义 - 去除命令输出格式中的空格 ### 2. 编码检测 CryptoTrace 检测常见的编码。 它会尝试解码以进行验证。 它使用置信度评分而不是简单的“是/否”。 ### 3. 压缩检测 CryptoTrace 通过 magic bytes 和尝试解压来检测压缩。 它实施硬性限制以避免解压炸弹。 ### 4. 熵分析 CryptoTrace 计算 Shannon 熵。 CryptoTrace 还计算滑动窗口熵。 为什么滑动窗口很重要： - 恶意 payload 通常嵌入在低熵的包装器中 - 单个全局熵值可能会隐藏嵌入的区域 ### 5. 递归层解包 CryptoTrace 可以解包嵌套的层。 常见模式： - Base64 套 GZIP - Base64 套 ZIP - 多层编码 防护机制： - 深度限制 - 时间限制 - 扩展比率限制 - 循环检测 ### 6. 可解释性 CryptoTrace 不仅仅输出一个分数。 它输出： - 信号分解 - 主要驱动因素 - 冲突信号 - 决策追踪 ### 7. 威胁情报 CryptoTrace 可以选择性地查询 VirusTotal。 CryptoTrace 可以选择性地运行 YARA 扫描。 这些都是 opt-in（需主动开启）的。 Air-gapped（物理隔离）操作仍然是默认设置。 ### 8. 报告 CryptoTrace 可以生成： - JSON（机器可读） - HTML（人类可读） ### 9. SIEM 输出 CryptoTrace 提供 CEF 和 LEEF 行格式化程序。 它们专为在 SOC pipeline 中摄入而设计。 ## CLI 参考 CLI 实现在 `src/cli.rs` 中。 运行： ``` cryptotrace --help cryptotrace analyze --help ``` ### `cryptotrace analyze` 概要： ``` cryptotrace analyze --context forensics|malware|password --deep --json --explain --ai --sandbox ``` 参数： - `` `` 可以是： - 字面字符串 - 文件路径 标志： - `--context` - `--deep` - `--json` - `--explain` - `--ai` - `--sandbox` 示例： ``` cryptotrace analyze "aGVsbG8=" --explain cryptotrace analyze suspicious.bin cryptotrace analyze suspicious.bin --deep --explain cryptotrace analyze suspicious.bin --deep --sandbox --json cryptotrace analyze "8846F7EAEE8FB117AD06BDD830B7586C" --context password --explain ``` ### `cryptotrace update` 概要： ``` cryptotrace update cryptotrace update --rollback cryptotrace update --from-file --verify ``` 注意： - 更新已通过验证。 - 支持回滚。 - 支持 Air-gap 导入。 ### `cryptotrace version` ``` cryptotrace version ``` ### `cryptotrace cache` ``` cryptotrace cache clear # Clear AI narrative cache cryptotrace cache status # Show cache capacity and entry count ``` ### `cryptotrace config show` ``` cryptotrace config show ``` ### `cryptotrace calibrate` 子命令： - `generate` - `train` - `status` 示例： ``` cryptotrace calibrate generate --samples 200 --output calibration_data/train.csv cryptotrace calibrate train --data calibration_data/train.csv cryptotrace calibrate status ``` ## 输出 Schema 规范的输出结构是 `src/types.rs` 中的 `DetectionResult`。 关键字段： - `detected_type` - `algorithm` - `confidence` - `calibrated` - `risk_level` - `weakness_cve` - `signals` - `primary_drivers` - `conflicting_signals` - `decision_trace` - `layers` JSON 示例（为便于阅读已略作删减）： ``` { "input_hash": "...", "source_type": "String", "entropy": 3.8, "detected_type": "hash", "algorithm": "MD5", "confidence": 0.98, "calibrated": true, "risk_level": "Critical", "weakness_cve": ["CVE-2013-6623"], "signals": { "entropy": 0.87, "block_alignment": 0.0, "magic_bytes": 0.0, "length_pattern": 1.0, "charset_purity": 1.0, "window_variance": 0.0 }, "primary_drivers": ["length_pattern", "charset_purity"], "conflicting_signals": [], "decision_trace": "...", "layers": [] } ``` ## 配置参考 CryptoTrace 从当前目录读取 `cryptotrace.toml`。 默认值被刻意设置得非常保守。 AI 保持禁用状态。 如需完整指南： - `docs/GETTING_STARTED.md` - `docs/AIR_GAP_GUIDE.md` ## 安全模型 CryptoTrace 假定输入是对抗性的。 ### 清理 实施的策略示例： - 大小限制 - 字符串的空字节策略 - 安全的路径处理 ### 递归解包 硬限制： - `max_depth` - `max_time_secs` - `max_expansion_ratio` ### 解压炸弹防御 如果解压扩展比例超过 100:1，CryptoTrace 将中止提取。 ### 子进程隔离 `cryptotrace-worker` 二进制文件运行有风险的解析操作。 如果它崩溃，父进程仍会保持存活。 ### Air Gap 默认设置 除非你主动开启，否则不会发生任何网络调用。 威胁情报和 AI 功能需要显式配置。 有关报告策略，请参见 `SECURITY.md`。 ## 威胁情报 威胁情报在 `src/intelligence/threat_intel.rs` 中实现。 功能： - VirusTotal v3 查询（需要 API 密钥） - YARA CLI 扫描（需要安装 yara） 这些默认处于关闭状态。 ## SIEM 集成 (CEF/LEEF) SIEM 格式化在 `src/intelligence/siem.rs` 中实现。 可用功能： - `format_cef(&DetectionResult) -> String` - `format_leef(&DetectionResult) -> String` 这些适用于嵌入了 CryptoTrace 的集成。 ## 报告 (JSON/HTML) HTML 报告生成位于 `src/reports/html.rs` 中。 JSON 是引擎和 API 的规范输出。 ## 签名数据库与更新 签名注册表： - magic bytes - 风险映射 - 位于 `signatures/cve_map.yaml` 的 CVE 映射 更新： - 验证 - 来源日志 - 回滚 - Air-gap 导入 ## 校准（置信度模型） 校准位于 `src/core/calibration.rs` 中。 模型文件位于： - `calibration_data/model.json` CLI 支持训练。 置信度可以是已校准的或临时的。 ## 测试、模糊测试与质量门禁 CryptoTrace 使用： - 单元测试 - 集成测试 - 准确性测试 - 模糊测试目标 (Fuzz targets) 运行测试： ``` cargo test ``` 模糊测试： - 需要 nightly 版本 - 建议在 Linux 上进行长时间的模糊运行 命令： ``` make fuzz make fuzz-long bash scripts/fuzz-long.sh ``` ## 打包与分发 CryptoTrace 通过以下方式分发： | 方式 | 命令 | |--------|---------| | **crates.io** | `cargo install cryptotrace` | | **Homebrew** | `brew install parv68/tap/cryptotrace` | | **GitHub Releases** | 适用于 Linux、macOS、Windows 的预编译二进制文件 | 安装脚本： ``` # Linux / macOS curl -sSfL https://github.com/parv68/CryptoTrace/releases/latest/download/install.sh | sh # Windows PowerShell powershell -c "iwr https://github.com/parv68/CryptoTrace/releases/latest/download/install.ps1 | iex" ``` ## 开发 常用命令： ``` cargo build cargo build --release cargo fmt cargo clippy --all-targets -- -D warnings cargo test ``` ## 故障排除 ### "worker not found" 错误 如果你使用 `--sandbox`，请确保 `cryptotrace-worker` 位于 PATH 中。 如果从源代码构建，请同时构建这两个二进制文件。 ### Windows 模糊测试 建议在 Linux 上进行长时间的模糊运行。 ## 项目状态 当前状态： - 已实现核心引擎 - 已实现测试和安全防护机制 - 打包（crates.io、Homebrew、GitHub Releases） - 发布自动化 ## 贡献 请参见 `CONTRIBUTING.md`。 请参见 `CODE_OF_CONDUCT.md`。 请参见 `SECURITY.md`。 ## 许可证 Apache-2.0。 请参见 `LICENSE`。

标签：Rust, 加密指纹识别, 可视化界面, 数字取证, 数据分类, 文件格式识别, 构建工具, 网络流量审计, 自动化脚本, 通知系统