4n6_nexus

# 4n6 Nexus - 自主DFIR代理 [](https://opensource.org/licenses/MIT) [](https://www.sans.org) [](https://www.python.org/downloads/) [](docs/ACCURACY_REPORT.md) **4n6 Nexus**（法医连接）是一个用于数字取证和事件响应的自主AI代理，具有架构自我修正能力——为现实世界的法医调查设计的生产级架构。 > **命名：** **4n6 Nexus** 是产品名称。它曾以 *SIFT Find Evil* 的名义提交到 **SANS FIND EVIL! Hackathon** （2026），Python包和命令行界面仍为 `sift_find_evil`。这三个名称指的是同一系统——产品、竞赛提交项和代码模块。 **新来者？** 请参阅 **[docs/START_HERE.md](docs/START_HERE.md)** 获取包含视觉地图和快速路径的文档导航指南，适用于不同角色（评委、用户、开发者、研究人员）。 --- ## 这是什么：SIFT协议的扩展 4n6 Nexus通过自主、自我修正的DFIR代理扩展了 **SANS SIFT工作站 / SIFT协议** 环境。**SIFT工作站是基础** ，是进行实际调查的先决条件：它提供了法院认可的法医工具（MFTECmd、PECmd、EvtxECmd、RECmd、Volatility 3、Sleuth Kit、tshark），而我们的代理实际上驱动这些工具。在实际证据上，我们的MCP服务器调用这些二进制文件，因此 **您需要先安装SIFT协议，然后在此基础上安装此工具** （参见 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)）。我们在该基础上添加了一个多代理推理层、跨工件自我修正和 **架构** （而非基于提示）证据完整性防护。 它实现了 **四种支持的FIND EVIL！架构方法中的两种** ： - **方法 #2 - 自定义MCP服务器。** 每个法医工具都通过为特定用途而构建的MCP服务器（`sift_find_evil/mcp/server.py`）访问，该服务器暴露类型化的只读函数而不是通用shell。代理 *无法物理运行* 破坏性命令，因为服务器未暴露这些命令；代码中强制执行允许列表、路径包含和断路器。服务器在模型到达之前解析原始工具输出，防止上下文窗口过载。 - **方法 #3 - 多代理框架。** 主导调度器调度一个分诊代理和三个领域分析师（磁盘、内存、网络）；验证者挑战每个发现。没有单个代理持有所有原始证据在其上下文中，每个代理到代理的消息和工具执行都记录有时间戳到一个相关的审计跟踪。 这两种方法在架构上是最健全的——防护措施在边界强制执行，而不是通过信任提示。参见 **[docs/ARCHITECTURAL_APPROACHES.md](docs/ARCHITECTURAL_APPROACHES.md)** 获取完整的竞赛规则映射，带有代码引用。 ### 两种运行方式（双路径） 两者都在SIFT工作站基础上运行；它们在驱动代理的内容上有所不同。 | 路径 | 运行时 | 何时使用 | |------|---------|-------------| | **Claude Code 代理** | dfir-* 代理作为 Claude Code 子代理（`.claude/agents/dfir-*.md`）通过我们的MCP服务器驱动SIFT工具 | 交互式取证在Protocol SIFT主机上；现场演示。安装方式：`./install-claude-agents.sh`。 | | **独立Python** | 进程内调度器 + 分析器通过相同的MCP边界 | 确定性、可重现的工件（试用 + 审计日志）；CI/CD和自动化。 | 两种路径共享 **完全相同的核心** ：MCP服务器（`EvidenceMCPServer`）、自我修正引擎（`SelfCorrectionEngine`）、防护措施（`ToolGuard`）和A2A审计跟踪。独立路径生成每次都相同的审计日志（其重现性的优势）；Claude Code路径是现场演示的真实Protocol SIFT扩展。参见下面的[快速入门](#快速入门)和 [docs/DUAL_PATH_STRATEGY.md](docs/DUAL_PATH_STRATEGY.md)。 > **关于“不使用SIFT运行”：** 合成验证工具和独立自我修正演示在纯Python合成装置上运行（不需要SIFT工具），这使得它们对CI友好。 这是一种*测试*便利，而不是部署模型—— **实际证据分析需要SIFT工作站工具。** --- ## 检测准确率：15种场景 @ F1=1.00 **所有评估场景的精确度和召回率均完美：** | 场景 | 发现（TP）| FP | FN | F1 | |----------|---------------|----|----|-----| | 01_clean_baseline | 0 | 0 | 0 | **1.00** | | 02_ransomware | 3 | 0 | 0 | **1.00** | | 03_timestomping | 2 | 0 | 0 | **1.00** | | 04_edge_cases | 2 | 0 | 0 | **1.00** | | 05_missing_prefetch | 3 | 0 | 0 | **1.00** | | 06_webmail_exfiltration | 1 | 0 | 0 | **1.00** | | 07_cloud_upload | 1 | 0 | 0 | **1.00** | | 08_persistence_run_keys | 2 | 0 | 0 | **1.00** | | 09_shimcache_only | 2 | 0 | 0 | **1.00** | | 10_timestomping_with_bam | 3 | 0 | 0 | **1.00** | | 11_yara_malware | 1 | 0 | 0 | **1.00** | | 12_memory_intrusion | 27 | 0 | 0 | **1.00** | | 16_powershell_obfuscated | 5 | 0 | 0 | **1.00** | | 19_credential_dumping | 5 | 0 | 0 | **1.00** | | 22_lateral_movement_logons | 5 | 0 | 0 | **1.00** | | **总计** | **62** | **0** | **0** | **1.00** | **验证方法：** 带有真实预期结果的自动化场景工具，支持1,000+测试。所有场景都在每次提交时在CI/CD上运行。已在准确性报告中单独记录验证的真实证据运行（CIRCL wiped-disk, M57-Jean, Nitroba）。 ```bash # 自己运行验证工具 PYTHONPATH=. python3 tests/scenario_harness.py ``` 参见 [ACCURACY_REPORT.md](docs/ACCURACY_REPORT.md) 获取完整的方法论、真实证据结果和诚实的检测差距列表。 --- ## 核心创新：架构自我修正 **与依赖输出的提示工程工具不同，4n6 Nexus自主检测证据源之间的矛盾并触发重新调查，并附有完整的审计跟踪。** ### 自我修正示例 **场景：** MFT显示`malware.exe`在14:40修改，但Prefetch显示在14:25执行（比修改时间早15分钟——因果冲突）。 **没有自我修正：** 报告两个时间戳，留下冲突未解决，混淆检查人员。 **有自我修正：** 1. **检测矛盾：** 文件在创建之前无法执行 2. **降低置信度：** 初始0.95 → 0.45（矛盾惩罚后 -0.50） 3. **查询仲裁者：** 检查事件日志4688（进程创建） 4. **解决：** 事件日志确认14:25:03执行时间（与Prefetch匹配） 5. **调整置信度：** 应用恢复（+0.30）→ 最终置信度：0.75 6. **透明推理：** 完整链路记录在审计跟踪中 ``` [发现 1] 可疑活动：malware.exe 严重程度：高 置信度：0.75（中等） 检测到的矛盾：1 1. 因果冲突（高） 文件 malware.exe 在 14:40 修改，但在 14:25 执行 应用的解决方案：1 1. event_log_confirms_prefetch（恢复：+0.30） 推理链： 1. 找到 3 种工件类型（MFT、Prefetch、EventLog） 2. 初始置信度：0.95（高工件计数） 3. 检测到因果冲突（影响：-0.50） 4. 事件日志确认 Prefetch 时间（恢复：+0.30） 5. 最终置信度：0.75（中等） ``` **结果：** 检查人员收到具有透明推理的已解决发现，而不是冲突数据。 --- ## 主要功能 ### 1. 人机审批工作流 所有发现最初都标记为`DRAFT`，需要人工批准后才能包含在报告中。 ```bash # 生成发现（所有发现最初标记为 DRAFT） python -m sift_find_evil.cli analyze --mft mft.csv --prefetch prefetch.csv --evtx evtx.csv -o findings.json # 审查发现 python -m sift_find_evil.cli list --findings findings.json --status draft # 批准发现 python -m sift_find_evil.cli approve --findings findings.json --finding-ids F-001 F-002 --reviewer "John Doe" --reason "Confirmed via timeline analysis" # 拒绝误报 python -m sift_find_evil.cli reject --findings findings.json --finding-ids F-003 --reviewer "John Doe" --reason "Benign system maintenance" # 列出已批准的发现 python -m sift_find_evil.cli list --findings findings.json --status approved ``` **功能：** - 防止篡改的SHA-256签名哈希 - 所有批准/拒绝操作的追加审计跟踪（`audit.jsonl`） - 审查者身份和时间戳跟踪 - 每个决策的可选原因/备注 - 发现JSON包含每个发现的批准元数据 ### 2. 案件管理 具有证据注册和完整性验证的结构化案件生命周期。 > **注意：** 案件命令默认为 `--case-root /cases`，在大多数系统上为root所有。 在普通用户运行时，请传递可写入的路径（例如 `--case-root ./cases`）。 以下示例为简洁起见显示 `/cases`。 ```bash # 创建新案件 python -m sift_find_evil.cli case init \ --case-id INC-2026-001 \ --name "M57 Jean Investigation" \ --examiner "John Doe" \ --description "Patent theft investigation" # 创建案件目录结构： # /cases/INC-2026-001/ # ├── evidence/ # 证据文件（只读） # ├── analysis/ # 分析输出 # ├── reports/ # 生成的报告 # ├── exports/ # IOC导出、时间线CSV # ├── CASE.yaml # 案件元数据 # ├── evidence.json # 证据注册，含SHA-256 # ├── findings.json # 检测发现 # └── audit.jsonl # 审计日志 # 注册证据，含SHA-256哈希 python -m sift_find_evil.cli case register \ --case-id INC-2026-001 \ --file /evidence/image.E01 \ --description "Suspect workstation disk image" \ --type disk_image # 输出： # 证据已注册： # SHA-256：e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 # 大小：8,589,934,592 字节 # 已注册：2026-04-23T22:10:00Z # 验证证据完整性 python -m sift_find_evil.cli case verify --case-id INC-2026-001 # 输出： # 总计：1 # 已验证：1 # 失败：0 # 缺失：0 # 案件状态摘要 python -m sift_find_evil.cli case status --case-id INC-2026-001 # 输出： # 名称：M57 Jean Investigation # 状态：open # 检查人员：John Doe # 创建时间：2026-04-23T22:05:00Z # 证据文件：1 # 发现：6 # 审计条目：23 ``` **功能：** - 结构化目录层次结构（evidence/、analysis/、reports/、exports/） - SHA-256哈希注册，自动验证 - 案件元数据存储在 `CASE.yaml` 中（case_id、name、examiner、created_at、status） - 证据类型：disk_image、memory_dump、pcap、log、other - 通过哈希验证防止篡改（失败时退出 1） - 案件状态跟踪（OPEN → ACTIVE → CLOSED） ### 3. 链条保管审计日志 所有法医工具调用和案件操作的追加JSONL审计跟踪。 ```bash # 查看最近的审计条目 python -m sift_find_evil.cli audit log --audit-file /cases/INC-2026-001/audit.jsonl --limit 10 # 输出： # [2026-04-23T22:15:33.505490] case_created # 检查人员：John Doe # 详情：{"case_id": "INC-2026-001", "name": "M57 Jean Investigation"} # # [2026-04-23T22:15:45.123456] tool_invocation # 检查人员：John Doe # 工具：volatility # 命令：vol.py -f memory.raw windows.pslist # 退出代码：0 # 持续时间：1234毫秒 # 输出哈希：5a5c4332e5167d2d # 审计日志统计 python -m sift_find_evil.cli audit summary --audit-file /cases/INC-2026-001/audit.jsonl # 输出： # 总计条目：23 # 独特工具：5 # 使用的工具： # - mftecmd # - pecmd # - evtxecmd # - volatility # - yara # 检查人员： # - John Doe # 操作： # tool_invocation：18 # case_created：1 # evidence_registered：3 # finding_approved：1 ``` **JSONL格式示例：** ```json { "timestamp": "2026-04-23T22:15:45.123456", "action": "tool_invocation", "examiner": "John Doe", "details": { "tool": "volatility", "command": "vol.py -f memory.raw windows.pslist", "exit_code": 0, "duration_ms": 1234, "output_hash": "5a5c4332e5167d2d", "working_dir": "/cases/INC-2026-001", "stdout": "PID PPID ImageFileName\n1234 5678 malware.exe", "stderr": null } } ``` **功能：** - 追加JSONL格式（每行一个JSON对象） - 工具输出的SHA-256哈希（前16个字符）用于篡改检测 - 捕获stdout/stderr（前1KB）、退出代码、持续时间、工作目录 - 支持直接日志记录和子进程包装器，自动捕获 - 按案例存储`audit.jsonl`文件 - 统计数据：总条目、唯一工具、操作明细、检查人员列表 ### 4. 报告生成 生成Markdown和HTML格式的调查报告。 ```bash # 生成Markdown报告（仅批准的发现） python -m sift_find_evil.cli report \ --case-id INC-2026-001 \ --output report.md \ --format markdown # 生成HTML报告 python -m sift_find_evil.cli report \ --case-id INC-2026-001 \ --output report.html \ --format html # 包括所有发现（草稿/批准/拒绝） python -m sift_find_evil.cli report \ --case-id INC-2026-001 \ --output full_report.md \ --format markdown \ --all-findings ``` **报告章节：** 1. **案件元数据** - 案件ID、检查人员、日期、状态、描述 2. **执行摘要** - 根据发现数量和严重程度自动生成 3. **证据摘要** - 文件处理、SHA-256哈希、大小（Markdown表格） 4. **发现** - 按严重程度分组（关键/高/中/低），默认仅批准 5. **泄露指标（IOCs）** - 从发现证据字典中提取的IP、域名、文件哈希、进程 6. **建议** - 根据严重程度分布自动生成 7. **页脚** - 时间戳、工具归属 **样本Markdown输出：** ```markdown # 法医调查报告 ## 案件：M57 Jean Investigation ## 案件元数据 - **案件ID：** INC-2026-001 - **检查人员：** John Doe - **创建时间：** 2026-04-23T22:05:00Z - **状态：** open ## 执行摘要 在分析过程中检测到47个可疑发现。 5个关键，12个高，20个中等严重性。 所有发现都已审查并批准纳入本报告。 ## 证据摘要 | 文件 | SHA-256哈希 | 大小 | |------|--------------|------| | image.E01 | e3b0c44298fc1c14... | 8192.00 MB | ## 发现 ### 关键严重性（5） #### [F-001] 勒索软件加密活动 **置信度：** 0.92 检测到1,247个文件中的大规模文件加密... ``` **HTML输出包括：** - 嵌入式CSS样式 - 响应式布局 - 打印机友好格式 - 表格用于证据摘要 **功能：** - 默认仅限已批准（过滤草稿/已拒绝的发现） - 证据摘要的Markdown表格 - 自动生成的执行摘要：“检测到X个可疑发现。Y个关键，Z个高…” - 自动生成的建议：“立即的事件响应：隔离受影响的系统…” - 从发现证据字典中提取IOCs（IP、域名、哈希、进程） - 按严重性分组和排序 - 支持PDF输出 --- ## 架构概述 **模式：自定义MCP服务器上的多代理框架。** 主导调度器调度一个分诊代理和三个领域分析师（磁盘、内存、网络）；每个分析师仅通过具有架构防护措施的自定义MCP服务器访问法医工具；验证者通过自我修正引擎挑战每个发现。 一个相关的A2A审计日志记录所有内容。 ```mermaid graph TD ORCH[调度器] --> TRIAGE[分诊] ORCH --> DA[磁盘分析师] ORCH --> MA[内存分析师] ORCH --> NA[网络分析师] ORCH --> VER[验证者] DA & MA & NA -->|仅通过MCP运行工具| MCP[自定义MCP服务器<br>允许列表 · 路径包含 · 断路器] MCP --> TOOLS[SIFT工具：MFTECmd、PECmd、EvtxECmd、Volatility、tshark] TOOLS --> ENGINE[检测 + 自我修正引擎] VER -->|挑战/解决| ENGINE ENGINE --> FIND[发现 + 置信度 + 推理] MCP -.->|每个调用 + 每个块| AUDIT[(A2A审计.jsonl)] FIND --> AUDIT style MCP fill:#c0392b,color:#fff,stroke:#7b241c,stroke-width:2px style ENGINE fill:#1e8449,color:#fff,stroke:#145a32 style AUDIT fill:#b7950b,color:#fff,stroke:#7d6608 ``` MCP服务器（红色）是一个可靠的信任边界：代理不持有任何工具二进制文件，也没有证据写入路径，因此在代码中强制执行只读和路径包含，而不是通过提示。参见 **[docs/ARCHITECTURE_DIAGRAM.md](docs/ARCHITECTURE_DIAGRAM.md)** 获取完整的图表、架构防护措施与提示的分类，以及A2A跟踪序列。 --- ## 支持的工件 ### Windows 法医 - **MFT（主文件表）** - 文件元数据、时间戳、$DATA属性 - **Prefetch** - 应用程序执行历史记录，带时间戳 - **事件日志** - Windows事件ID 4688（进程创建） - **注册表** - 运行键、Shimcache、AmCache、BAM/DAM、UserAssist - **LNK文件** - 快捷方式分析、文档访问跟踪 - **跳转列表** - 每个应用程序的MRU、UNC共享访问 ### 内存法医 - **Volatility 3集成** - pslist、psscan、malfind、cmdline、netscan - **Linux内存** - bash历史、pslist、sockstat - **进程注入检测** - MITRE T1055 - **网络连接** - 活动套接字、可疑端口 ### 网络法医 - **浏览器历史记录** - Chrome、Firefox、Edge（WebCacheV01.dat） - **PCAP分析** - HTTP请求、DNS查询、TCP会话 - **Webmail外泄** - 文件哈希与电子邮件附件相关联 ### 恶意软件分析 - **YARA 扫描** - 规则编译，目录/文件扫描 - **NSRL 集成** - 已知良好哈希过滤（可选） - **文件恢复** - 从擦除的磁盘中提取可执行文件 ### MITRE ATT&CK 覆盖范围 | 技术编号 | 描述 | 检测器 | |-----------|-------------|----------| | **T1027** | 模糊文件或信息 | YARA，熵分析 | | **T1055** | 进程注入 | 内存（malfind） | | **T1059** | 命令和脚本解释器 | 事件日志，预取 | | **T1070.004** | 指示器移除：文件删除 | MFT，磁盘擦除 | | **T1071** | 应用层协议 | PCAP，DNS | | **T1083** | 文件和目录发现 | MFT，预取 | | **T1140** | 文件解模糊/解码 | YARA，文件恢复 | | **T1486** | 数据加密影响 | MFT 大量更改 | | **T1547.001** | 启动或登录自动启动：注册表运行键 | 注册表 | | **T1566.001** | 钓鱼：鱼叉式钓鱼附件 | 电子邮件，浏览器历史 | | **T1620** | 反射代码加载 | 内存（malfind） | --- ## 快速入门 > **评委/首次操作员：** 最具代表性的命令是下面的步骤 2 中的多代理调查。对于完整的、分步骤的演练和预期输出，请参见 **[docs/TRY_IT_OUT.md](docs/TRY_IT_OUT.md)** 和 **[docs/DEMO_RECORDING_VERIFIED.md](docs/DEMO_RECORDING_VERIFIED.md)**。 ### 先决条件 - **Python 3.12** （CI 运行的版本，引擎测试的版本） - **Git** - **对于真实证据：** **SIFT 工作站** （法医工具基础） + 本地库 - 参见步骤 3 和 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。 可重复演示的验证环境运行在捆绑的合成夹具上，不需要这些，但现实调查需要 SIFT。 ### 1. 安装 ```bash git clone https://github.com/Strike48-public/4n6_nexus.git sift_find_evil cd sift_find_evil python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 核心依赖 - 纯 Python，在任何平台上安装。足以应对合成演示、验证框架和针对合成夹具的每个检测器。实际证据还需要 SIFT 工具（步骤 3 + DEPLOY_TO_SIFT.md）。 pip install -r requirements.txt python -m sift_find_evil.cli --help # 验证它加载 ``` ### 2. 运行多代理调查（可重复演示） 这是确定性的、可供评委重复的工件：一个协调器调度一个分类代理和三个域分析师（磁盘、内存、网络），跨自定义 MCP 边界；一个验证器挑战每个发现并解决矛盾；一个相关代理到代理（A2A）审计日志被写入 - 每次运行都相同。 > **对于 SIFT 主机上的交互式 Claude 代码路径（叙事协议 SIFT 扩展）**，请参见步骤 5 和 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。 ```bash PYTHONPATH=. python3 -m sift_find_evil.orchestration --output-dir analysis/demo_run ``` 预期输出： ``` 案例 INC-2026-001 -- 6 个发现 F-001 [disk_timeline] ransom_note.exe 矛盾已解决 置信度 0.95 -> 0.75 F-002 [disk_timeline] crypt_engine.exe 矛盾已解决 置信度 0.95 -> 0.75 F-003 [disk_timeline] persist.exe 矛盾已解决 置信度 0.95 -> 0.75 F-004 [memory ] crypt_engine.exe 矛盾已解决 置信度 0.95 -> 0.75 F-005 [network ] 203.0.113.66 矛盾检测 置信度 0.9 -> 0.45 F-006 [network ] 1.1.1.1 矛盾已解决 置信度 0.9 -> 0.75 ``` 跟踪任何发现到产生它的确切工具执行： ```bash PYTHONPATH=. python3 -c "from sift_find_evil.audit.logger import AuditLogger; \ [print(e.entry_id, e.action) for e in AuditLogger('analysis/demo_run/audit.jsonl').trace('F-005')]" ``` 显示阻止超出边界读取的架构护栏： ```bash PYTHONPATH=. python3 -m sift_find_evil.orchestration --bypass-demo --output-dir analysis/bypass_run grep tool_blocked analysis/bypass_run/audit.jsonl ``` ### 3. （可选）真实证据的法医额外内容 磁盘镜像（E01/raw）、PST 电子邮件和内存转储需要原生库（Sleuth Kit、libewf、libpff、YARA）。这些需要编译器，因此它们是分开的： ```bash # Debian/Ubuntu/SIFT：系统库首先 sudo apt-get install libtsk-dev libewf-dev libpff-dev libyara-dev # 然后 Python 绑定 + Volatility 3 pip install -r requirements-forensic.txt ``` 应用程序加载并运行，无需这些；需要它们的代码路径会引发清晰的、面向安装的错误，而不是在启动时失败。 ### 4. 单域自我纠正演示（最快的健全性检查） 一个 30 秒的检查，运行在捆绑的合成数据上，无需参数： ```bash python -m sift_find_evil.cli demo ``` 此演示： - 因果关系违规检测（文件修改后于执行） - 事件日志仲裁者解决 - 置信度调整（-0.50 惩罚，+0.30 恢复） - 透明推理链（5 步） **示例输出：** ``` [发现 1] 可疑活动：malware.exe 严重程度：高 置信度：0.75（中等） 类型：指示器 描述： 对 malware.exe 的分析检测到 1 个矛盾： - 文件 malware.exe 在 2025-03-15 14:40:00+00:00 修改，但在 2025-03-15 14:25:00.123456+00:00 执行（因果关系违规） 应用 1 个解决方案： - event_log_confirms_prefetch 检测到的矛盾：1 1. causality_violation （高） 影响：-0.50 文件 malware.exe 在 14:40 修改，但在 14:25 执行（因果关系违规） 应用的解决方案：1 1. event_log_confirms_prefetch 恢复：+0.30 推理链： 1. 为 malware.exe 找到 3 种工件类型：MFT、Prefetch、EventLog 2. 初始置信度：0.95（3 个工件，3 种类型） 3. 检测到 causality_violation（影响：-0.50） 4. 通过事件日志解决：event_log_confirms_prefetch（恢复：+0.30） 5. 最终置信度：0.75（中等） 证据： - 可执行文件：malware.exe - 检测到的矛盾：1 - 应用的解决方案：1 - 工件类型：['MFT', 'Prefetch', 'EventLog'] ``` ### 5. 在 SIFT 主机上通过 Claude Code 运行（交互式/演示路径） 在安装了 `claude` CLI 的 SIFT 工作站上，注册我们的自定义 MCP 服务器，并让 dfir-* 子代理通过架构边界驱动真正的法医工具： ```bash # 克隆 + 在 SIFT 主机上安装 pip 后： ./install-claude-agents.sh \ --case-id INC-2026-001 \ --evidence-root /cases/INC-2026-001/evidence \ --audit-path /cases/INC-2026-001/audit.jsonl claude mcp list # 确认 'sift-find-evil' claude "对案例 INC-2026-001 执行完整的法医分析" ``` 存储库附带代理定义（`.claude/agents/dfir-*.md`）和项目范围的 `.mcp.json`。有关完整的 SIFT 部署演练，请参见 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。 ### 分析真实证据 ```bash # 分析法医工具 CSV 输出 python -m sift_find_evil.cli analyze \ --mft /path/to/mft.csv \ --prefetch /path/to/prefetch.csv \ --evtx /path/to/evtx.csv \ --output findings.json # 带有内存分析 python -m sift_find_evil.cli analyze \ --mft mft.csv \ --prefetch prefetch.csv \ --evtx evtx.csv \ --memory memory.raw \ --output findings.json # 带有网络分析 python -m sift_find_evil.cli analyze \ --mft mft.csv \ --prefetch prefetch.csv \ --evtx evtx.csv \ --pcap capture.pcap \ --browser-history history.csv \ --output findings.json # 带有 YARA 扫描 python -m sift_find_evil.cli analyze \ --mft mft.csv \ --prefetch prefetch.csv \ --evtx evtx.csv \ --yara-rules ./rules \ --yara-scan /path/to/scan \ --output findings.json ``` ### 完整工作流程示例 ```bash # 1. 创建案例 python -m sift_find_evil.cli case init \ --case-id INC-2026-001 \ --name "勒索软件调查" \ --examiner "John Doe" # 2. 注册证据 python -m sift_find_evil.cli case register \ --case-id INC-2026-001 \ --file /evidence/disk.E01 \ --description "感染的工作站" \ --type disk_image # 3. 运行检测引擎（输出到案例 findings.json） python -m sift_find_evil.cli analyze \ --mft mft.csv \ --prefetch prefetch.csv \ --evtx evtx.csv \ --output /cases/INC-2026-001/findings.json # 4. 审查和批准发现 python -m sift_find_evil.cli list \ --findings /cases/INC-2026-001/findings.json \ --status draft python -m sift_find_evil.cli approve \ --findings /cases/INC-2026-001/findings.json \ --finding-ids F-001 F-002 F-003 \ --reviewer "John Doe" \ --reason "确认勒索软件活动" # 5. 生成报告 python -m sift_find_evil.cli report \ --case-id INC-2026-001 \ --output /cases/INC-2026-001/reports/final_report.md \ --format markdown # 6. 验证证据完整性 python -m sift_find_evil.cli case verify --case-id INC-2026-001 # 7. 审查审计轨迹 python -m sift_find_evil.cli audit summary \ --audit-file /cases/INC-2026-001/audit.jsonl ``` --- ## 文档 本存储库包括综合文档： - **[文档索引](docs/DOCUMENTATION_INDEX.md)** - 所有文档的完整地图 - **[架构](docs/ARCHITECTURE.md)** - 系统设计和组件架构 - **[准确性报告](docs/ACCURACY_REPORT.md)** - 检测指标和方法 - **[贡献](docs/CONTRIBUTING.md)** - 开发指南和编码标准 - **[示例](docs/EXAMPLES.md)** - 现实世界使用示例 - **[测试指南](BATCH_TESTING.md)** - 系统化测试方法 请参见 [docs/DOCUMENTATION_INDEX.md](docs/DOCUMENTATION_INDEX.md) 以获取完整的文档地图。 --- ## CLI 参考 ### 核心命令 ```bash # 演示模式 python -m sift_find_evil.cli demo [--output findings.json] # 分析证据 python -m sift_find_evil.cli analyze \ --mft MFT.csv \ --prefetch PREFETCH.csv \ --evtx EVTX.csv \ [--memory MEMORY.raw] \ [--pcap CAPTURE.pcap] \ [--browser-history HISTORY.csv] \ [--yara-rules RULES_DIR --yara-scan TARGET] \ [--output findings.json] # 运行场景 python -m sift_find_evil.cli run \ --scenario scenarios/synthetic/02_ransomware \ [--output report.json] \ [--strict] ``` ### 案例管理 ```bash # 初始化案例 python -m sift_find_evil.cli case init \ --case-id CASE_ID \ --name "案例名称" \ --examiner "检查者姓名" \ [--description "描述"] \ [--case-root /cases] # 注册证据 python -m sift_find_evil.cli case register \ --case-id CASE_ID \ --file FILE_PATH \ --description "描述" \ [--type disk_image|memory_dump|pcap|log|other] \ [--case-root /cases] # 验证证据 python -m sift_find_evil.cli case verify \ --case-id CASE_ID \ [--case-root /cases] # 案例状态 python -m sift_find_evil.cli case status \ --case-id CASE_ID \ [--case-root /cases] ``` ### 批准工作流 ```bash # 列出发现 python -m sift_find_evil.cli list \ --findings findings.json \ [--status draft|approved|rejected] # 批准发现 python -m sift_find_evil.cli approve \ --findings findings.json \ --finding-ids F-001 F-002 ... \ --reviewer "姓名" \ --reviewer "姓名" \ [--reason "原因"] # 拒绝发现 python -m sift_find_evil.cli reject \ --findings findings.json \ --finding-ids F-003 F-004 ... \ --reviewer "姓名" \ --reason "原因" ``` ### 审计日志记录 ```bash # 查看审计日志 python -m sift_find_evil.cli audit log \ --audit-file audit.jsonl \ [--limit 20] # 审计摘要 python -m sift_find_evil.cli audit summary \ --audit-file audit.jsonl ``` ### 报告生成 ```bash # 生成报告 python -m sift_find_evil.cli report \ --case-id CASE_ID \ --output report.md \ [--format markdown|html|pdf] \ [--case-root /cases] \ [--approved-only] \ [--all-findings] ``` --- ## 开发 ### 项目结构 ``` sift_find_evil/ ├── sift_find_evil/ # 主要 Python 包 │ ├── __init__.py │ ├── cli.py # CLI 入口点（1,700+ 行） │ ├── approval/ # 人机协作工作流 │ │ ├── __init__.py │ │ ├── models.py # ApprovalStatus, ApprovalMetadata, FindingWithApproval │ │ └── manager.py # ApprovalManager │ ├── audit/ # 审计日志 │ │ ├── __init__.py │ │ ├── models.py # AuditEntry, ToolInvocation │ │ └── logger.py # AuditLogger │ ├── case/ # 案例管理 │ │ ├── __init__.py │ │ ├── models.py # Case, CaseStatus, EvidenceFile │ │ └── manager.py # CaseManager │ ├── reporting/ # 报告生成 │ │ ├── __init__.py │ │ ├── models.py # Report, ReportFormat │ │ └── generator.py # ReportGenerator │ ├── parsers/ # 法医工具解析器 │ │ ├── mft_parser.py # MFTECmd CSV 解析器 │ │ ├── prefetch_parser.py # PECmd CSV 解析器 │ │ ├── evtx_parser.py # EvtxECmd CSV 解析器 │ │ ├── registry_parser.py # 注册表工件解析器 │ │ ├── lnk_jumplist_parser.py │ │ ├── pcap_parser.py # PCAP 分析 │ │ └── browser_history_parser.py │ ├── detectors/ # 检测模块 │ │ ├── lnk_jumplist_detector.py │ │ ├── memory_detector.py # 内存分析 │ │ ├── network_detector.py # 网络分析 │ │ ├── registry_detector.py │ │ └── yara_detector.py │ ├── self_correction/ # 自我纠正引擎 │ │ ├── engine.py # 主要纠正逻辑 │ │ ├── models.py # Contradiction, Resolution │ │ └── strategies.py # 解决方案策略 │ ├── disk/ # 磁盘法医 │ │ ├── wipe_detector.py # GPT 擦除检测 │ │ └── exfil_detector.py # 文件外流相关性 │ ├── memory/ # 内存法医 │ │ ├── volatility_runner.py # Volatility 3 包装器 │ │ └── models.py # 内存工件模型 │ ├── yara_scan/ # YARA 集成 │ │ └── scanner.py # YARA 规则编译 │ ├── carving/ # 文件恢复 │ │ └── nsrl.py # NSRL 集成 │ ├── validation/ # 对抗性验证 │ │ └── validator.py # 发现验证 │ └── scenario_runner.py # 场景套件 ├── tests/ │ ├── fixtures/ # 合成测试数据 │ │ ├── synthetic_mft.csv │ │ ├── synthetic_prefetch.csv │ │ └── synthetic_evtx.csv │ ├── scenario_harness.py # 自动验证 │ └── unit/ # 单元测试 ├── orchestration.py # 多代理调查套件（演示入口） ├── mcp/ # 自定义 MCP 服务器 + 架构护栏 │ ├── server.py # EvidenceMCPServer（工具边界） │ └── guardrails.py # ToolGuard：允许列表，路径包含，断路器 ├── scenarios/ │ ├── synthetic/ # 21 个场景目录；14 个有 scenario.yaml + 运行 │ │ ├── 01_clean_baseline/ ... 12_memory_intrusion/ │ │ ├── 16_powershell_obfuscated/ │ │ ├── 19_credential_dumping/ │ │ │ # （13-15,17-18,20-21 是规范存根，不运行） │ │ └── 02_ransomware/ # 还附带 demo 的 memory_/network_fixtures │ └── real/ # 真实证据场景 │ ├── circl-2023-wiped/ │ ├── m57-jean/ │ ├── nitroba/ │ └── apt_attack_2015/ ├── docs/ │ ├── ARCHITECTURE.md # 组件架构 │ ├── CONTRIBUTING.md # 开发指南 │ ├── ACCURACY_REPORT.md # 检测指标 │ ├── SELF_CORRECTION.md # 自我纠正逻辑 │ ├── PRD.md # 产品需求文档 │ └── SELF_CORRECTION.md # 自我纠正逻辑 ├── requirements.txt # Python 依赖项 ├── LICENSE # MIT 许可证 ├── CLAUDE.md # AI 代理说明 └── README.md # 本文件 ``` ### 运行测试 ```bash # 场景验证套件 PYTHONPATH=. python3 tests/scenario_harness.py # 完整的测试套件（需要 pytest） pytest # 覆盖率（匹配 CI 网关：85% 至少） pytest --cov=sift_find_evil --cov-report=html ``` > 自动跳过在核心安装时测试原生法医库（E01 镜像，PST，NSRL 彭霍夫，PCAP 综合）。一旦安装了法医额外项，测试就会运行一次。参见 `requirements-forensic.txt`。 ### 代码质量 ```bash # 使用 ruff 检查 ruff check sift_find_evil/ # 使用 black 格式化 black sift_find_evil/ # 类型检查，使用 mypy mypy sift_find_evil/ ``` ### 贡献 参见 [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) 获取： - 开发环境设置 - 编码标准（PEP 8，类型提示） - 测试要求（至少 85% 覆盖率） - 拉取请求工作流程 - 添加新的检测器、解析器、场景 --- ## 性能指标 | 指标 | 结果 | |--------|--------| | **检测准确率（F1）** | 1.00（15 个场景） | | **精确度** | 1.00（无误报） | | **召回率** | 1.00（无漏报） | | **综合发现（合成套件）** | 62 | | **测试** | 1,300+ 通过 | | **测试覆盖率** | ~94%（行） | | **CI/CD** | ruff + pytest，全部通过 | --- ## 文档 | 文档 | 描述 | |----------|-------------| | [ARCHITECTURE.md](docs/ARCHITECTURE.md) | 组件架构，数据流，扩展点 | | [CONTRIBUTING.md](docs/CONTRIBUTING.md) | 开发指南，编码标准，PR 工作流 | | [ACCURACY_REPORT.md](docs/ACCURACY_REPORT.md) | 精确度/召回率结果，验证方法 | | [SELF_CORRECTION.md](docs/SELF_CORRECTION.md) | 自我纠正场景和逻辑 | | [PRD.md](docs/PRD.md) | 产品需求文档 | --- ## 路线图 完成（v1.0 - 黑客马拉松提交） - 多智能体系统（编排器 + 分类 + 3 名领域分析师 + 验证器） - 核心检测引擎（场景，62 项发现，F1=1.00） - 跨领域自我纠正（磁盘/时间线，内存，网络矛盾） - 人机协作审批工作流（草稿 → 已批准/已拒绝） - 案件管理（SHA-256 注册，完整性验证） - 审计日志（ JSONL，保管链） - 报告生成（Markdown，HTML） - MITRE ATT&CK 映射（10+ 技术） - 场景验证工具（自动化测试） - 持续集成/持续部署（GitHub Actions，ruff + pytest） ### 🚧 进行中（黑客马拉松后） - Claude 代码路径的实时 SIFT OVA 验证（stdio MCP 服务器，`.mcp.json` 和 `install-claude-agents 均已交付；针对真实证据的 OVA 端到端运行是剩余的验证步骤） - 真实证据处理（M57-专利，国家美术馆） - PDF 报告生成 - 演示视频制作 ### 📋 计划中（v2.0） - 案件管理的 Web UI - 时间线可视化（Mermaid/D3.js） - 多案件队列支持 - 团队协作功能 - 自定义剧本编辑器 - SIEM 集成（Splunk，ELK） ### 🔮 未来（v3.0） - 基于机器学习的异常检测 - 持续学习（跨案例 IoC 情报） - 云证据分析（AWS，Azure，GCP） - 商业 SaaS 产品 --- ## 许可证 MIT 许可证 - 详情请参见 [LICENSE](LICENSE)。 开源社区版。商业 SaaS 产品将于 2026 年推出。 --- ## 致谢 - **SANS Institute** 举办的 FIND EVIL! 黑客马拉松 - **SANS SIFT Workstation** 法医工具和社区 - **NIST CFReDS** 提供真实测试数据集 - **Volatility Foundation** 提供内存分析框架 - **YARA** 提供恶意软件分类 - **Claude Code** （Anthropic）提供自主代理架构 --- ## 联 - **GitHub:** https://github.com/Strike48-public/4n6_nexus - **问题:** https://github.com/Strike48-public/4n6_nexus/issues - **作者:** Jonathan Tomek（hackathon@example.com） 展示自主 DFIR 的未来。