Strike48-public/4n6_nexus
GitHub: Strike48-public/4n6_nexus
4n6 Nexus 是基于 SIFT Workstation 的自主 DFIR 多智能体引擎，通过架构级自我纠正和证据完整性防护实现高准确率的自动化数字取证分析。
Stars: 1 | Forks: 0
# 4n6 Nexus - 自主 DFIR Agent
[](https://opensource.org/licenses/MIT)
[](https://www.sans.org)
[](https://www.python.org/downloads/)
[](docs/ACCURACY_REPORT.md)
**4n6 Nexus** (forensics nexus) 是一个用于数字取证和事件响应 (DFIR) 的自主 AI agent，具备架构级自我纠正功能 —— 专为真实世界取证调查设计的生产级架构。
**新来的？** 请参阅 **[docs/START_HERE.md](docs/START_HERE.md)** 获取带有可视化地图和基于角色（评委、用户、开发者、研究人员）快速路径的文档导航指南。
## 这是什么：Protocol SIFT 的扩展
4n6 Nexus 通过引入一个自主、自我纠正的 DFIR agent，扩展了 **SANS SIFT Workstation / Protocol SIFT** 环境。**SIFT Workstation 是基础**，也是进行真实调查的前提：它提供了经过法庭验证的取证工具（MFTECmd、PECmd、EvtxECmd、RECmd、Volatility 3、Sleuth Kit、tshark），我们的 agent 实际上就是在驱动这些工具。处理真实证据时，我们的 MCP server 会通过 shell 调用这些二进制程序，因此**你需要先安装 Protocol SIFT，然后再在此基础上安装本工具**（参见 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)）。我们在这个基础之上添加的内容是一个多 agent 推理层、跨证据交叉的自我纠正机制，以及**基于架构**（而非基于提示词）的证据完整性防护机制。
它实现了 **FIND EVIL! 支持的四种架构方法中的两种**：
- **方法 #2 - 自定义 MCP Server。** 每个取证工具都通过一个专门构建的 MCP server (`sift_find_evil/mcp/server.py`) 访问，该 server 暴露的是类型化的、只读的函数，而不是通用的 shell。agent *在物理层面上无法* 运行破坏性命令，因为 server 没有暴露这些命令；allowlist、路径限制和熔断机制都在代码中强制执行。server 会在原始工具输出到达模型之前对其进行解析，从而防止 context-window 过载。
- **方法 #3 - 多 Agent 框架。** 主 orchestrator 会分派一个 triage agent 和三个领域分析器（磁盘、内存、网络）；一个 verifier 会质疑每一个发现。没有任何单个 agent 会将所有原始证据保留在其 context 中，并且每个 agent 到 agent 的消息和工具执行都会带有时间戳地记录到一个关联的审计追踪中。
这两种是竞赛中架构上最健全的方法——防护机制是在边界强制执行的，而不是通过信任 prompt。请参见 **[docs/ARCHITECTURAL_APPROACHES.md](docs/ARCHITECTURAL_APPROACHES.md)** 获取与竞赛规则的完整映射及代码参考。
### 两种运行方式（双路径）
两者都运行在 SIFT Workstation 基础之上；它们的区别在于驱动 agent 的方式。
| 路径 | Runtime | 何时使用 |
|------|---------|-------------|
| **Claude Code agents** | 将 dfir-* agents 作为 Claude Code subagents (`.claude/agents/dfir-*.md`)，通过我们的 MCP server 驱动 SIFT 工具 | 在 Protocol SIFT 主机上进行交互式取证；这是实时的、符合叙事的演示。使用 `./install-claude-agents.sh` 安装。 |
| **独立 Python** | 通过相同的 MCP 边界运行进程内 orchestrator + 分析器 | 这是确定性的、评委可复现的产物（可试运行 + 审计日志）；适用于 CI/CD 和自动化。 |
这两条路径共享**完全相同的核心**：MCP server (`EvidenceMCPServer`)、自我纠正引擎 (`SelfCorrectionEngine`)、防护机制 (`ToolGuard`) 以及 A2A 审计追踪。独立路径会产生每次运行结果完全相同的审计日志（这是其在可重复性方面的优势）；而 Claude Code 路径则是用于现场演示的正宗 Protocol SIFT 扩展。请参阅下方的[快速开始](#quick-start)和 [docs/DUAL_PATH_STRATEGY.md](docs/DUAL_PATH_STRATEGY.md)。
## 检测准确率：15 个场景 @ F1=1.00
**在所有评分场景中实现了完美的精确率和召回率：**
| 场景 | 发现 (TP) | FP | FN | F1 |
|----------|---------------|----|----|-----|
| 01_clean_baseline | 0 | 0 | 0 | **1.00** |
| 02_ransomware | 3 | 0 | 0 | **1.00** |
| 03_timestompping | 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_timestompping_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 擦除磁盘、M57-Jean、Nitroba）在准确率报告中单独记录。
```
# 自行运行 validation harness
PYTHONPATH=. python3 tests/scenario_harness.py
```
完整的方法论、真实证据结果以及一份客观真实的检测差距列表，请参见 [ACCURACY_REPORT.md](docs/ACCURACY_REPORT.md)。
## 核心创新：架构级自我纠正
**不同于盲目信任输出的 prompt 工程工具，4n6 Nexus 能够自主检测证据源之间的矛盾，并通过完整的审计追踪触发重新调查。**
### 自我纠正示例
**场景：** MFT 显示 `malware.exe` 在 14:40 被修改，但 Prefetch 显示其在 14:25 执行（在修改前 15 分钟 —— 因果关系冲突）。
**未进行自我纠正时：** 同时报告这两个时间戳，冲突未解决，让检验人员感到困惑。
**进行自我纠正后：**
1. **检测矛盾：** 文件无法在创建之前执行
2. **降低置信度：** 初始 0.95 → 矛盾惩罚后降至 0.45 (-0.50)
3. **查询裁决依据：** 检查 Event Log 4688（进程创建）
4. **解决：** Event Log 确认执行时间为 14:25:03（与 Prefetch 匹配）
5. **调整置信度：** 应用恢复值 (+0.30) → 最终置信度：0.75
6. **透明推理：** 完整的推理链记录在审计追踪中
```
[Finding 1] Suspicious Activity: malware.exe
Severity: HIGH
Confidence: 0.75 (Medium)
Contradictions Detected: 1
1. causality_violation (high)
File malware.exe modified at 14:40 but executed at 14:25
Resolutions Applied: 1
1. event_log_confirms_prefetch (recovery: +0.30)
Reasoning Chain:
1. Found 3 artifact types (MFT, Prefetch, EventLog)
2. Initial confidence: 0.95 (high artifact count)
3. Detected causality_violation (impact: -0.50)
4. Event Log confirms Prefetch time (recovery: +0.30)
5. Final confidence: 0.75 (Medium)
```
**结果：** 检验人员获得的是带有透明推理过程的已解决发现，而不是相互冲突的数据。
## 核心特性
### 1. 人类在环审批工作流
所有发现都以 `DRAFT` 状态开始，在纳入报告之前需要人工批准。
```
# 生成 findings（初始状态均为 DRAFT）
python -m sift_find_evil.cli analyze --mft mft.csv --prefetch prefetch.csv --evtx evtx.csv -o findings.json
# 审查 findings
python -m sift_find_evil.cli list --findings findings.json --status draft
# 批准 findings
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"
# 列出已批准的 findings
python -m sift_find_evil.cli list --findings findings.json --status approved
```
**特性：**
- 用于防篡改检测的 SHA-256 签名哈希
- 用于所有批准/拒绝操作的仅追加审计追踪 (`audit.jsonl`)
- 审核人身份和时间戳追踪
- 每个决策可选的理由/备注
- 发现结果 JSON 包含每个发现的批准元数据
### 2. 案件管理
具备证据注册表和完整性验证的结构化案件生命周期。
```
# 创建新 case
python -m sift_find_evil.cli case init \
--case-id INC-2026-001 \
--name "M57 Jean Investigation" \
--examiner "John Doe" \
--description "Patent theft investigation"
# Case 目录结构已创建：
# /cases/INC-2026-001/
# ├── evidence/ # Evidence files (read-only)
# ├── analysis/ # Analysis outputs
# ├── reports/ # Generated reports
# ├── exports/ # IOC exports, timeline CSVs
# ├── CASE.yaml # Case metadata
# ├── evidence.json # Evidence registry with SHA-256
# ├── findings.json # Detection findings
# └── audit.jsonl # Audit log
# 使用 SHA-256 hash 注册 evidence
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
# 输出：
# Evidence registered:
# SHA-256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
# Size: 8,589,934,592 bytes
# Registered: 2026-04-23T22:10:00Z
# 验证 evidence 完整性
python -m sift_find_evil.cli case verify --case-id INC-2026-001
# 输出：
# Total: 1
# Verified: 1
# Failed: 0
# Missing: 0
# Case 状态摘要
python -m sift_find_evil.cli case status --case-id INC-2026-001
# 输出：
# Name: M57 Jean Investigation
# Status: open
# Examiner: John Doe
# Created: 2026-04-23T22:05:00Z
# Evidence files: 1
# Findings: 6
# Audit entries: 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 审计追踪。
```
# 查看最近的 audit 条目
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
# Examiner: John Doe
# Details: {"case_id": "INC-2026-001", "name": "M57 Jean Investigation"}
# # [2026-04-23T22:15:45.123456] tool_invocation
# Examiner: John Doe
# Tool: volatility
# Command: vol.py -f memory.raw windows.pslist
# Exit code: 0
# Duration: 1234ms
# Output hash: 5a5c4332e5167d2d
# Audit log 统计信息
python -m sift_find_evil.cli audit summary --audit-file /cases/INC-2026-001/audit.jsonl
# 输出：
# Total entries: 23
# Unique tools: 5
# Tools used:
# - mftecmd
# - pecmd
# - evtxecmd
# - volatility
# - yara
# Examiners:
# - John Doe
# Actions:
# tool_invocation: 18
# case_created: 1
# evidence_registered: 3
# finding_approved: 1
```
**JSONL 格式示例：**
```
{
"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）、退出代码、执行时长、工作目录
- 支持直接日志记录和带有自动捕获功能的 subprocess 包装器
- 每个案件独立的 `audit.jsonl` 文件
- 统计信息：总条目数、唯一工具、操作分解、检验人员列表
### 4. 报告生成
以 Markdown 和 HTML 格式生成调查报告。
```
# 生成 Markdown 报告（仅包含已批准的 findings）
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
# 包含所有 findings（DRAFT/approved/rejected）
python -m sift_find_evil.cli report \
--case-id INC-2026-001 \
--output full_report.md \
--format markdown \
--all-findings
```
**报告部分：**
1. **案件元数据** - Case ID, examiner, 日期, 状态, 描述
2. **执行摘要** - 根据发现数量和严重性自动生成
3. **证据摘要** - 处理的文件、SHA-256 哈希、大小（Markdown 表格）
4. **发现结果** - 按严重性分组 (CRITICAL/HIGH/MEDIUM/LOW)，默认仅包含已批准的
5. **入侵指标 (IOCs)** - 从发现结果中提取的 IP、域名、文件哈希、进程
6. **建议** - 根据严重性分布自动生成
7. **页脚** - 时间戳，工具归属
**Markdown 输出示例：**
```
# Forensic Investigation Report
## Case: M57 Jean Investigation
## Case Metadata
- **Case ID:** INC-2026-001
- **Examiner:** John Doe
- **Created:** 2026-04-23T22:05:00Z
- **Status:** open
## Executive Summary
Detected 47 suspicious finding(s) during analysis. 5 CRITICAL, 12 HIGH, 20 MEDIUM severity.
All findings have been reviewed and approved for inclusion in this report.
## Evidence Summary
| File | SHA-256 Hash | Size |
|------|--------------|------|
| image.E01 | e3b0c44298fc1c14... | 8192.00 MB |
## Findings
### CRITICAL Severity (5)
#### [F-001] Ransomware Encryption Activity
**Confidence:** 0.92
Mass file encryption detected across 1,247 files...
```
**HTML 输出包含：**
- 嵌入的 CSS 样式
- 响应式布局
- 适合打印的格式
- 用于证据摘要的表格
**特性：**
- 默认仅包含已批准的（过滤掉 DRAFT/REJECTED 状态的发现）
- 使用 Markdown 表格展示证据摘要
- 自动生成的执行摘要：“检测到 X 个可疑发现。其中 Y 个 CRITICAL，Z 个 HIGH……”
- 自动生成的建议：“立即启动事件响应：隔离受影响的系统……”
- 从发现证据字典中提取 IOC（IP、域名、哈希、进程）
- 基于严重性的分组和排序
- 已将 PDF 支持列为未来的增强功能
## 架构概述
**模式：构建于自定义 MCP Server 之上的多 Agent 框架。** 主 orchestrator 分派一个 triage agent 和三个领域分析器（磁盘、内存、网络）；每个分析器*只能*通过架构防护机制所在的 Custom MCP server 访问取证工具；verifier 通过自我纠正引擎对每个发现提出质疑。一个关联的 A2A 审计日志记录了这一切。
```
graph TD
ORCH[Orchestrator] --> TRIAGE[Triage]
ORCH --> DA[Disk Analyst]
ORCH --> MA[Memory Analyst]
ORCH --> NA[Network Analyst]
ORCH --> VER[Verifier]
DA & MA & NA -->|run_tool ONLY via MCP| MCP[Custom MCP Server
allowlist · path containment · circuit breaker] MCP --> TOOLS[SIFT tools: MFTECmd, PECmd, EvtxECmd, Volatility, tshark] TOOLS --> ENGINE[Detection + Self-Correction Engine] VER -->|challenge / resolve| ENGINE ENGINE --> FIND[Findings + confidence + reasoning] MCP -.->|every call + every block| AUDIT[(A2A audit.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 server（红色部分）是一个严格的信任边界：agent 不持有任何工具二进制文件，也没有针对证据的写入路径，因此只读和路径限制是在代码中强制执行的，而不是依赖 prompt。完整的图表、架构级与基于 prompt 的防护机制分类法，以及 A2A 追踪序列，请参见 **[docs/ARCHITECTURE_DIAGRAM.md](docs/ARCHITECTURE_DIAGRAM.md)**。 ## 支持的取证证据形式 ### Windows 取证 - **MFT (Master File Table)** - 文件元数据、时间戳、$DATA 属性 - **Prefetch** - 带有时间戳的应用程序执行历史记录 - **Event Logs** - Windows Event ID 4688（进程创建） - **Registry** - Run keys, Shimcache, AmCache, BAM/DAM, UserAssist - **LNK 文件** - 快捷方式分析，文档访问追踪 - **Jump Lists** - 按应用程序划分的 MRU，UNC 共享访问 ### 内存取证 - **Volatility 3 集成** - pslist, psscan, malfind, cmdline, netscan - **Linux 内存** - bash history, pslist, sockstat - **注入检测** - MITRE T1055 - **网络连接** - 活动套接字，可疑端口 ### 网络取证 - **浏览器历史记录** - Chrome, Firefox, Edge (WebCacheV01.dat) - **PCAP 分析** - HTTP 请求，DNS 查询，TCP 会话 - **Webmail 数据外发** - 文件哈希与电子邮件附件的关联 ### 恶意软件分析 - **YARA 扫描** - 规则编译，目录/文件扫描 - **NSRL 集成** - 已知良好哈希过滤（可选） - **文件雕刻** - 从被擦除的磁盘中提取可执行文件 ### MITRE ATT&CK 覆盖范围 | 技术 | 描述 | 检测器 | |-----------|-------------|----------| | **T1027** | 混淆的文件或信息 | YARA, 熵分析 | | **T1055** | 进程注入 | 内存| | **T1059** | 命令和脚本解释器 | Event Logs, Prefetch | | **T1070.004** | 指标移除：文件删除 | MFT, 磁盘擦除 | | **T1071** | 应用层协议 | PCAP, DNS | | **T1083** | 文件和目录发现 | MFT, Prefetch | | **T1140** | 解混淆/解码文件 | YARA, 文件雕刻 | | **T1486** | 用于影响的数据加密 | MFT 大规模更改 | | **T1547.001** | 启动或登录自启动：Registry Run Keys | Registry | | **T1566.001** | 钓鱼：鱼叉式钓鱼附件 | 电子邮件，浏览器历史记录 | | **T1620** | 反射式代码加载 | 内存| ## 快速开始 ### 前置条件 - **Python 3.12**（CI 运行的版本，也是引擎测试所针对的版本） - **Git** - **用于真实证据：** **SIFT Workstation**（取证工具基础） 加上原生库 —— 参见第 3 步和 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。下文可复现的演示运行在捆绑的合成测试数据上，这两者都不需要，这正是使其对 CI 友好的原因；而真实的调查则需要 SIFT。 ### 1. 安装 ``` 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，可在任何平台上安装。足以用于 # 可重现的演示、validation harness 以及针对 synthetic # fixtures 的每个 detector。真实 evidence 还需要 SIFT 工具（步骤 3 + DEPLOY_TO_SIFT.md）。 pip install -r requirements.txt python -m sift_find_evil.cli --help # verify it loads ``` ### 2. 运行多 agent 调查（可复现的演示） 这是一个确定性的、评委可复现的产物：orchestrator 通过 Custom MCP 边界分派一个 triage agent 和三个领域分析器（磁盘、内存、网络）；verifier 会质疑每个发现并解决矛盾；最终生成一个关联的 agent 到 agent (A2A) 审计日志 —— 每次运行完全一致。 ``` PYTHONPATH=. python3 -m sift_find_evil.orchestration --output-dir analysis/demo_run ``` 预期输出： ``` Case INC-2026-001 -- 6 findings F-001 [disk_timeline] ransom_note.exe contradiction_resolved confidence 0.95 -> 0.75 F-002 [disk_timeline] crypt_engine.exe contradiction_resolved confidence 0.95 -> 0.75 F-003 [disk_timeline] persist.exe contradiction_resolved confidence 0.95 -> 0.75 F-004 [memory ] crypt_engine.exe contradiction_resolved confidence 0.95 -> 0.75 F-005 [network ] 203.0.113.66 contradiction_detected confidence 0.9 -> 0.45 F-006 [network ] 1.1.1.1 contradiction_resolved confidence 0.9 -> 0.75 ``` 将任何发现追溯到产生它的具体工具执行过程： ``` 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')]" ``` 展示架构级防护机制如何阻止越界读取： ``` 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）。这些需要编译器，因此是单独的： ``` # Debian/Ubuntu/SIFT：优先安装系统库 sudo apt-get install libtsk-dev libewf-dev libpff-dev libyara-dev # 然后安装 Python bindings + Volatility 3 pip install -r requirements-forensic.txt ``` ### 4. 单领域自我纠正演示（最快的健全性检查） 一个 30 秒的检查，在捆绑的合成数据上运行，无需参数： ``` python -m sift_find_evil.cli demo ``` 演示内容包括： - 因果冲突检测（文件在执行后被修改） - Event Log 裁决机制解决冲突 - 置信度分数调整（-0.50 惩罚，+0.30 恢复） - 透明的推理链（5 步） **输出示例：** ``` [Finding 1] Suspicious Activity: malware.exe Severity: HIGH Confidence: 0.75 (Medium) Type: indicator Description: Analysis of malware.exe detected 1 contradiction(s): - File malware.exe modified at 2025-03-15 14:40:00+00:00 but executed at 2025-03-15 14:25:00.123456+00:00 (causality violation) Applied 1 resolution(s): - event_log_confirms_prefetch Contradictions Detected: 1 1. causality_violation (high) Impact: -0.50 File malware.exe modified at 14:40 but executed at 14:25 (causality violation) Resolutions Applied: 1 1. event_log_confirms_prefetch Recovery: +0.30 Reasoning Chain: 1. Found 3 artifact types for malware.exe: MFT, Prefetch, EventLog 2. Initial confidence: 0.95 (3 artifacts, 3 types) 3. Detected causality_violation (impact: -0.50) 4. Resolved via Event Log: event_log_confirms_prefetch (recovery: +0.30) 5. Final confidence: 0.75 (Medium) Evidence: - executable: malware.exe - contradictions_detected: 1 - resolutions_applied: 1 - artifact_types: ['MFT', 'Prefetch', 'EventLog'] ``` ### 5. 在 SIFT 主机上通过 Claude Code 运行（交互式 / 演示路径） 在安装了 `claude` CLI 的 SIFT Workstation 上，注册我们的 Custom MCP server，并让 dfir-* subagents 通过架构边界驱动真实的取证工具： ``` # 在 SIFT 主机上执行 git clone + pip install 后： ./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 # confirm 'sift-find-evil' claude "Run a full forensic analysis on case INC-2026-001" ``` 该仓库提供了 agent 定义 (`.claude/agents/dfir-*.md`) 以及项目范围的 `.mcp.json`。完整的 SIFT 部署演示请参见 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。 ### 分析真实证据 ``` # 分析 forensic 工具的 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 ``` ### 完整工作流示例 ``` # 1. 创建 case python -m sift_find_evil.cli case init \ --case-id INC-2026-001 \ --name "Ransomware Investigation" \ --examiner "John Doe" # 2. 注册 evidence python -m sift_find_evil.cli case register \ --case-id INC-2026-001 \ --file /evidence/disk.E01 \ --description "Infected workstation" \ --type disk_image # 3. 运行 detection engine（输出到 case 的 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. 审查并批准 findings 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 "Confirmed ransomware activity" # 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. 验证 evidence 完整性 python -m sift_find_evil.cli case verify --case-id INC-2026-001 # 7. 审查 audit trail 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 参考 ### 核心命令 ``` # Demo 模式 python -m sift_find_evil.cli demo [--output findings.json] # 分析 evidence 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] ``` ### 案件管理 ``` # 初始化 case python -m sift_find_evil.cli case init \ --case-id CASE_ID \ --name "Case Name" \ --examiner "Examiner Name" \ [--description "Description"] \ [--case-root /cases] # 注册 evidence python -m sift_find_evil.cli case register \ --case-id CASE_ID \ --file FILE_PATH \ --description "Description" \ [--type disk_image|memory_dump|pcap|log|other] \ [--case-root /cases] # 验证 evidence python -m sift_find_evil.cli case verify \ --case-id CASE_ID \ [--case-root /cases] # Case 状态 python -m sift_find_evil.cli case status \ --case-id CASE_ID \ [--case-root /cases] ``` ### 审批工作流 ``` # 列出 findings python -m sift_find_evil.cli list \ --findings findings.json \ [--status draft|approved|rejected] # 批准 findings python -m sift_find_evil.cli approve \ --findings findings.json \ --finding-ids F-001 F-002 ... \ --reviewer "Name" \ [--reason "Reason"] # 驳回 findings python -m sift_find_evil.cli reject \ --findings findings.json \ --finding-ids F-003 F-004 ... \ --reviewer "Name" \ --reason "Reason" ``` ### 审计日志记录 ``` # 查看 audit log python -m sift_find_evil.cli audit log \ --audit-file audit.jsonl \ [--limit 20] # Audit 摘要 python -m sift_find_evil.cli audit summary \ --audit-file audit.jsonl ``` ### 报告生成 ``` # 生成报告 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/ # Main Python package │ ├── __init__.py │ ├── cli.py # CLI entry point (1,700+ lines) │ ├── approval/ # Human-in-the-loop workflow │ │ ├── __init__.py │ │ ├── models.py # ApprovalStatus, ApprovalMetadata, FindingWithApproval │ │ └── manager.py # ApprovalManager │ ├── audit/ # Audit logging │ │ ├── __init__.py │ │ ├── models.py # AuditEntry, ToolInvocation │ │ └── logger.py # AuditLogger │ ├── case/ # Case management │ │ ├── __init__.py │ │ ├── models.py # Case, CaseStatus, EvidenceFile │ │ └── manager.py # CaseManager │ ├── reporting/ # Report generation │ │ ├── __init__.py │ │ ├── models.py # Report, ReportFormat │ │ └── generator.py # ReportGenerator │ ├── parsers/ # Forensic tool parsers │ │ ├── mft_parser.py # MFTECmd CSV parser │ │ ├── prefetch_parser.py # PECmd CSV parser │ │ ├── evtx_parser.py # EvtxECmd CSV parser │ │ ├── registry_parser.py # Registry artifact parsers │ │ ├── lnk_jumplist_parser.py │ │ ├── pcap_parser.py # PCAP analysis │ │ └── browser_history_parser.py │ ├── detectors/ # Detection modules │ │ ├── lnk_jumplist_detector.py │ │ ├── memory_detector.py # Memory analysis │ │ ├── network_detector.py # Network analysis │ │ ├── registry_detector.py │ │ └── yara_detector.py │ ├── self_correction/ # Self-correction engine │ │ ├── engine.py # Main correction logic │ │ ├── models.py # Contradiction, Resolution │ │ └── strategies.py # Resolution strategies │ ├── disk/ # Disk forensics │ │ ├── wipe_detector.py # GPT wiping detection │ │ └── exfil_detector.py # File exfiltration correlation │ ├── memory/ # Memory forensics │ │ ├── volatility_runner.py # Volatility 3 wrapper │ │ └── models.py # Memory artifact models │ ├── yara_scan/ # YARA integration │ │ └── scanner.py # YARA rule compilation │ ├── carving/ # File carving │ │ └── nsrl.py # NSRL integration │ ├── validation/ # Adversarial validation │ │ └── validator.py # Finding validation │ └── scenario_runner.py # Scenario harness ├── tests/ │ ├── fixtures/ # Synthetic test data │ │ ├── synthetic_mft.csv │ │ ├── synthetic_prefetch.csv │ │ └── synthetic_evtx.csv │ ├── scenario_harness.py # Automated validation │ └── unit/ # Unit tests ├── orchestration.py # Multi-agent investigation harness (demo entry) ├── mcp/ # Custom MCP server + architectural guardrails │ ├── server.py # EvidenceMCPServer (the tool boundary) │ └── guardrails.py # ToolGuard: allowlist, path containment, breaker ├── scenarios/ │ ├── synthetic/ # 21 scenario dirs; 14 have scenario.yaml + run │ │ ├── 01_clean_baseline/ ... 12_memory_intrusion/ │ │ ├── 16_powershell_obfuscated/ │ │ ├── 19_credential_dumping/ │ │ │ # (13-15,17-18,20-21 are spec stubs, not run) │ │ └── 02_ransomware/ # also carries memory_/network_fixtures for the demo │ └── real/ # Real evidence scenarios │ ├── circl-2023-wiped/ │ ├── m57-jean/ │ ├── nitroba/ │ └── apt_attack_2015/ ├── docs/ │ ├── ARCHITECTURE.md # Component architecture │ ├── CONTRIBUTING.md # Development guide │ ├── ACCURACY_REPORT.md # Detection metrics │ ├── PRD.md # Product requirements │ └── SELF_CORRECTION.md # Self-correction logic ├── requirements.txt # Python dependencies ├── LICENSE # MIT License ├── CLAUDE.md # AI agent instructions └── README.md # This file ``` ### 运行测试 ``` # 场景 validation harness PYTHONPATH=. python3 tests/scenario_harness.py # 完整测试套件（需要 pytest） pytest # 测试覆盖率（符合 CI 门控要求：最低 85%） pytest --cov=sift_find_evil --cov-report=html ``` ### 代码质量 ``` # 使用 ruff 进行 lint ruff check sift_find_evil/ # 使用 black 进行格式化 black sift_find_evil/ # 使用 mypy 进行类型检查 mypy sift_find_evil/ ``` ## 性能指标 | 指标 | 结果 | |--------|--------| | **检测准确率 (F1)** | 1.00 (15 个场景) | | **精确率** | 1.00 (0 误报) | | **召回率** | 1.00 (0 漏报) | | **总发现数 (合成测试套件)** | 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 - 黑客松提交) - 多 Agent 系统 (orchestrator + triage + 3 个领域分析器 + verifier) - 核心检测引擎 (15 个场景，62 个发现 @ F1=1.00) - 跨领域自我纠正 (磁盘/时间线，内存，网络矛盾) - 人类在环审批工作流 (DRAFT → APPROVED/REJECTED) - 案件管理 (SHA-256 注册表，完整性验证) - 审计日志记录 (仅追加 JSONL，证据保管链) - 报告生成 (Markdown, HTML) - MITRE ATT&CK 映射 (10+ 项技术) - 场景验证套件 (自动化测试) - CI/CD (GitHub Actions, ruff + pytest) ### 🚧 进行中 (黑客松后) - 对 Claude Code 路径进行实时的 SIFT OVA 验证 (stdio MCP server，`.mcp.json` 和 `install-claude-agents.sh` 已发布；在 OVA 上针对真实证据的端到端运行是剩余的验证步骤) - 真实证据处理 (M57-Patents, National Gallery) - PDF 报告生成 - 演示视频制作 ### 📋 计划中 (v2.0) - 用于案件管理的 Web UI - 时间线可视化 (Mermaid/D3.js) - 多案件队列支持 - 团队协作功能 - 自定义 playbook 编辑器 - SIEM 集成 (Splunk, ELK) ### 🔮 未来 (v3.0) - 基于 ML 的异常检测 - 持久化学习 (跨案件的 IoC 情报) - 云端证据分析 (AWS, Azure, GCP) - 商业 SaaS 产品 ## 许可证 MIT 许可证 - 详情请参见 [LICENSE](LICENSE)。 ## 致谢 - **SANS Institute** 感谢其举办 FIND EVIL! 黑客松 - **SANS SIFT Workstation** 取证工具和社区 - **NIST CFReDS** 感谢其提供真实测试数据集 - **Volatility Foundation** 感谢其内存分析框架 - **YARA** 感谢其恶意软件分类功能 - **Claude Code** (Anthropic) 感谢其自主 agent 架构 ## 联系方式 - **GitHub:** https://github.com/Strike48-public/4n6_nexus - **Issues:** https://github.com/Strike48-public/4n6_nexus/issues - **作者:** Jonathan Tomek (hackathon@example.com) 展示自主 DFIR 的未来。
allowlist · path containment · circuit breaker] MCP --> TOOLS[SIFT tools: MFTECmd, PECmd, EvtxECmd, Volatility, tshark] TOOLS --> ENGINE[Detection + Self-Correction Engine] VER -->|challenge / resolve| ENGINE ENGINE --> FIND[Findings + confidence + reasoning] MCP -.->|every call + every block| AUDIT[(A2A audit.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 server（红色部分）是一个严格的信任边界：agent 不持有任何工具二进制文件，也没有针对证据的写入路径，因此只读和路径限制是在代码中强制执行的，而不是依赖 prompt。完整的图表、架构级与基于 prompt 的防护机制分类法，以及 A2A 追踪序列，请参见 **[docs/ARCHITECTURE_DIAGRAM.md](docs/ARCHITECTURE_DIAGRAM.md)**。 ## 支持的取证证据形式 ### Windows 取证 - **MFT (Master File Table)** - 文件元数据、时间戳、$DATA 属性 - **Prefetch** - 带有时间戳的应用程序执行历史记录 - **Event Logs** - Windows Event ID 4688（进程创建） - **Registry** - Run keys, Shimcache, AmCache, BAM/DAM, UserAssist - **LNK 文件** - 快捷方式分析，文档访问追踪 - **Jump Lists** - 按应用程序划分的 MRU，UNC 共享访问 ### 内存取证 - **Volatility 3 集成** - pslist, psscan, malfind, cmdline, netscan - **Linux 内存** - bash history, pslist, sockstat - **注入检测** - MITRE T1055 - **网络连接** - 活动套接字，可疑端口 ### 网络取证 - **浏览器历史记录** - Chrome, Firefox, Edge (WebCacheV01.dat) - **PCAP 分析** - HTTP 请求，DNS 查询，TCP 会话 - **Webmail 数据外发** - 文件哈希与电子邮件附件的关联 ### 恶意软件分析 - **YARA 扫描** - 规则编译，目录/文件扫描 - **NSRL 集成** - 已知良好哈希过滤（可选） - **文件雕刻** - 从被擦除的磁盘中提取可执行文件 ### MITRE ATT&CK 覆盖范围 | 技术 | 描述 | 检测器 | |-----------|-------------|----------| | **T1027** | 混淆的文件或信息 | YARA, 熵分析 | | **T1055** | 进程注入 | 内存| | **T1059** | 命令和脚本解释器 | Event Logs, Prefetch | | **T1070.004** | 指标移除：文件删除 | MFT, 磁盘擦除 | | **T1071** | 应用层协议 | PCAP, DNS | | **T1083** | 文件和目录发现 | MFT, Prefetch | | **T1140** | 解混淆/解码文件 | YARA, 文件雕刻 | | **T1486** | 用于影响的数据加密 | MFT 大规模更改 | | **T1547.001** | 启动或登录自启动：Registry Run Keys | Registry | | **T1566.001** | 钓鱼：鱼叉式钓鱼附件 | 电子邮件，浏览器历史记录 | | **T1620** | 反射式代码加载 | 内存| ## 快速开始 ### 前置条件 - **Python 3.12**（CI 运行的版本，也是引擎测试所针对的版本） - **Git** - **用于真实证据：** **SIFT Workstation**（取证工具基础） 加上原生库 —— 参见第 3 步和 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。下文可复现的演示运行在捆绑的合成测试数据上，这两者都不需要，这正是使其对 CI 友好的原因；而真实的调查则需要 SIFT。 ### 1. 安装 ``` 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，可在任何平台上安装。足以用于 # 可重现的演示、validation harness 以及针对 synthetic # fixtures 的每个 detector。真实 evidence 还需要 SIFT 工具（步骤 3 + DEPLOY_TO_SIFT.md）。 pip install -r requirements.txt python -m sift_find_evil.cli --help # verify it loads ``` ### 2. 运行多 agent 调查（可复现的演示） 这是一个确定性的、评委可复现的产物：orchestrator 通过 Custom MCP 边界分派一个 triage agent 和三个领域分析器（磁盘、内存、网络）；verifier 会质疑每个发现并解决矛盾；最终生成一个关联的 agent 到 agent (A2A) 审计日志 —— 每次运行完全一致。 ``` PYTHONPATH=. python3 -m sift_find_evil.orchestration --output-dir analysis/demo_run ``` 预期输出： ``` Case INC-2026-001 -- 6 findings F-001 [disk_timeline] ransom_note.exe contradiction_resolved confidence 0.95 -> 0.75 F-002 [disk_timeline] crypt_engine.exe contradiction_resolved confidence 0.95 -> 0.75 F-003 [disk_timeline] persist.exe contradiction_resolved confidence 0.95 -> 0.75 F-004 [memory ] crypt_engine.exe contradiction_resolved confidence 0.95 -> 0.75 F-005 [network ] 203.0.113.66 contradiction_detected confidence 0.9 -> 0.45 F-006 [network ] 1.1.1.1 contradiction_resolved confidence 0.9 -> 0.75 ``` 将任何发现追溯到产生它的具体工具执行过程： ``` 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')]" ``` 展示架构级防护机制如何阻止越界读取： ``` 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）。这些需要编译器，因此是单独的： ``` # Debian/Ubuntu/SIFT：优先安装系统库 sudo apt-get install libtsk-dev libewf-dev libpff-dev libyara-dev # 然后安装 Python bindings + Volatility 3 pip install -r requirements-forensic.txt ``` ### 4. 单领域自我纠正演示（最快的健全性检查） 一个 30 秒的检查，在捆绑的合成数据上运行，无需参数： ``` python -m sift_find_evil.cli demo ``` 演示内容包括： - 因果冲突检测（文件在执行后被修改） - Event Log 裁决机制解决冲突 - 置信度分数调整（-0.50 惩罚，+0.30 恢复） - 透明的推理链（5 步） **输出示例：** ``` [Finding 1] Suspicious Activity: malware.exe Severity: HIGH Confidence: 0.75 (Medium) Type: indicator Description: Analysis of malware.exe detected 1 contradiction(s): - File malware.exe modified at 2025-03-15 14:40:00+00:00 but executed at 2025-03-15 14:25:00.123456+00:00 (causality violation) Applied 1 resolution(s): - event_log_confirms_prefetch Contradictions Detected: 1 1. causality_violation (high) Impact: -0.50 File malware.exe modified at 14:40 but executed at 14:25 (causality violation) Resolutions Applied: 1 1. event_log_confirms_prefetch Recovery: +0.30 Reasoning Chain: 1. Found 3 artifact types for malware.exe: MFT, Prefetch, EventLog 2. Initial confidence: 0.95 (3 artifacts, 3 types) 3. Detected causality_violation (impact: -0.50) 4. Resolved via Event Log: event_log_confirms_prefetch (recovery: +0.30) 5. Final confidence: 0.75 (Medium) Evidence: - executable: malware.exe - contradictions_detected: 1 - resolutions_applied: 1 - artifact_types: ['MFT', 'Prefetch', 'EventLog'] ``` ### 5. 在 SIFT 主机上通过 Claude Code 运行（交互式 / 演示路径） 在安装了 `claude` CLI 的 SIFT Workstation 上，注册我们的 Custom MCP server，并让 dfir-* subagents 通过架构边界驱动真实的取证工具： ``` # 在 SIFT 主机上执行 git clone + pip install 后： ./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 # confirm 'sift-find-evil' claude "Run a full forensic analysis on case INC-2026-001" ``` 该仓库提供了 agent 定义 (`.claude/agents/dfir-*.md`) 以及项目范围的 `.mcp.json`。完整的 SIFT 部署演示请参见 [DEPLOY_TO_SIFT.md](DEPLOY_TO_SIFT.md)。 ### 分析真实证据 ``` # 分析 forensic 工具的 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 ``` ### 完整工作流示例 ``` # 1. 创建 case python -m sift_find_evil.cli case init \ --case-id INC-2026-001 \ --name "Ransomware Investigation" \ --examiner "John Doe" # 2. 注册 evidence python -m sift_find_evil.cli case register \ --case-id INC-2026-001 \ --file /evidence/disk.E01 \ --description "Infected workstation" \ --type disk_image # 3. 运行 detection engine（输出到 case 的 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. 审查并批准 findings 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 "Confirmed ransomware activity" # 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. 验证 evidence 完整性 python -m sift_find_evil.cli case verify --case-id INC-2026-001 # 7. 审查 audit trail 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 参考 ### 核心命令 ``` # Demo 模式 python -m sift_find_evil.cli demo [--output findings.json] # 分析 evidence 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] ``` ### 案件管理 ``` # 初始化 case python -m sift_find_evil.cli case init \ --case-id CASE_ID \ --name "Case Name" \ --examiner "Examiner Name" \ [--description "Description"] \ [--case-root /cases] # 注册 evidence python -m sift_find_evil.cli case register \ --case-id CASE_ID \ --file FILE_PATH \ --description "Description" \ [--type disk_image|memory_dump|pcap|log|other] \ [--case-root /cases] # 验证 evidence python -m sift_find_evil.cli case verify \ --case-id CASE_ID \ [--case-root /cases] # Case 状态 python -m sift_find_evil.cli case status \ --case-id CASE_ID \ [--case-root /cases] ``` ### 审批工作流 ``` # 列出 findings python -m sift_find_evil.cli list \ --findings findings.json \ [--status draft|approved|rejected] # 批准 findings python -m sift_find_evil.cli approve \ --findings findings.json \ --finding-ids F-001 F-002 ... \ --reviewer "Name" \ [--reason "Reason"] # 驳回 findings python -m sift_find_evil.cli reject \ --findings findings.json \ --finding-ids F-003 F-004 ... \ --reviewer "Name" \ --reason "Reason" ``` ### 审计日志记录 ``` # 查看 audit log python -m sift_find_evil.cli audit log \ --audit-file audit.jsonl \ [--limit 20] # Audit 摘要 python -m sift_find_evil.cli audit summary \ --audit-file audit.jsonl ``` ### 报告生成 ``` # 生成报告 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/ # Main Python package │ ├── __init__.py │ ├── cli.py # CLI entry point (1,700+ lines) │ ├── approval/ # Human-in-the-loop workflow │ │ ├── __init__.py │ │ ├── models.py # ApprovalStatus, ApprovalMetadata, FindingWithApproval │ │ └── manager.py # ApprovalManager │ ├── audit/ # Audit logging │ │ ├── __init__.py │ │ ├── models.py # AuditEntry, ToolInvocation │ │ └── logger.py # AuditLogger │ ├── case/ # Case management │ │ ├── __init__.py │ │ ├── models.py # Case, CaseStatus, EvidenceFile │ │ └── manager.py # CaseManager │ ├── reporting/ # Report generation │ │ ├── __init__.py │ │ ├── models.py # Report, ReportFormat │ │ └── generator.py # ReportGenerator │ ├── parsers/ # Forensic tool parsers │ │ ├── mft_parser.py # MFTECmd CSV parser │ │ ├── prefetch_parser.py # PECmd CSV parser │ │ ├── evtx_parser.py # EvtxECmd CSV parser │ │ ├── registry_parser.py # Registry artifact parsers │ │ ├── lnk_jumplist_parser.py │ │ ├── pcap_parser.py # PCAP analysis │ │ └── browser_history_parser.py │ ├── detectors/ # Detection modules │ │ ├── lnk_jumplist_detector.py │ │ ├── memory_detector.py # Memory analysis │ │ ├── network_detector.py # Network analysis │ │ ├── registry_detector.py │ │ └── yara_detector.py │ ├── self_correction/ # Self-correction engine │ │ ├── engine.py # Main correction logic │ │ ├── models.py # Contradiction, Resolution │ │ └── strategies.py # Resolution strategies │ ├── disk/ # Disk forensics │ │ ├── wipe_detector.py # GPT wiping detection │ │ └── exfil_detector.py # File exfiltration correlation │ ├── memory/ # Memory forensics │ │ ├── volatility_runner.py # Volatility 3 wrapper │ │ └── models.py # Memory artifact models │ ├── yara_scan/ # YARA integration │ │ └── scanner.py # YARA rule compilation │ ├── carving/ # File carving │ │ └── nsrl.py # NSRL integration │ ├── validation/ # Adversarial validation │ │ └── validator.py # Finding validation │ └── scenario_runner.py # Scenario harness ├── tests/ │ ├── fixtures/ # Synthetic test data │ │ ├── synthetic_mft.csv │ │ ├── synthetic_prefetch.csv │ │ └── synthetic_evtx.csv │ ├── scenario_harness.py # Automated validation │ └── unit/ # Unit tests ├── orchestration.py # Multi-agent investigation harness (demo entry) ├── mcp/ # Custom MCP server + architectural guardrails │ ├── server.py # EvidenceMCPServer (the tool boundary) │ └── guardrails.py # ToolGuard: allowlist, path containment, breaker ├── scenarios/ │ ├── synthetic/ # 21 scenario dirs; 14 have scenario.yaml + run │ │ ├── 01_clean_baseline/ ... 12_memory_intrusion/ │ │ ├── 16_powershell_obfuscated/ │ │ ├── 19_credential_dumping/ │ │ │ # (13-15,17-18,20-21 are spec stubs, not run) │ │ └── 02_ransomware/ # also carries memory_/network_fixtures for the demo │ └── real/ # Real evidence scenarios │ ├── circl-2023-wiped/ │ ├── m57-jean/ │ ├── nitroba/ │ └── apt_attack_2015/ ├── docs/ │ ├── ARCHITECTURE.md # Component architecture │ ├── CONTRIBUTING.md # Development guide │ ├── ACCURACY_REPORT.md # Detection metrics │ ├── PRD.md # Product requirements │ └── SELF_CORRECTION.md # Self-correction logic ├── requirements.txt # Python dependencies ├── LICENSE # MIT License ├── CLAUDE.md # AI agent instructions └── README.md # This file ``` ### 运行测试 ``` # 场景 validation harness PYTHONPATH=. python3 tests/scenario_harness.py # 完整测试套件（需要 pytest） pytest # 测试覆盖率（符合 CI 门控要求：最低 85%） pytest --cov=sift_find_evil --cov-report=html ``` ### 代码质量 ``` # 使用 ruff 进行 lint ruff check sift_find_evil/ # 使用 black 进行格式化 black sift_find_evil/ # 使用 mypy 进行类型检查 mypy sift_find_evil/ ``` ## 性能指标 | 指标 | 结果 | |--------|--------| | **检测准确率 (F1)** | 1.00 (15 个场景) | | **精确率** | 1.00 (0 误报) | | **召回率** | 1.00 (0 漏报) | | **总发现数 (合成测试套件)** | 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 - 黑客松提交) - 多 Agent 系统 (orchestrator + triage + 3 个领域分析器 + verifier) - 核心检测引擎 (15 个场景，62 个发现 @ F1=1.00) - 跨领域自我纠正 (磁盘/时间线，内存，网络矛盾) - 人类在环审批工作流 (DRAFT → APPROVED/REJECTED) - 案件管理 (SHA-256 注册表，完整性验证) - 审计日志记录 (仅追加 JSONL，证据保管链) - 报告生成 (Markdown, HTML) - MITRE ATT&CK 映射 (10+ 项技术) - 场景验证套件 (自动化测试) - CI/CD (GitHub Actions, ruff + pytest) ### 🚧 进行中 (黑客松后) - 对 Claude Code 路径进行实时的 SIFT OVA 验证 (stdio MCP server，`.mcp.json` 和 `install-claude-agents.sh` 已发布；在 OVA 上针对真实证据的端到端运行是剩余的验证步骤) - 真实证据处理 (M57-Patents, National Gallery) - PDF 报告生成 - 演示视频制作 ### 📋 计划中 (v2.0) - 用于案件管理的 Web UI - 时间线可视化 (Mermaid/D3.js) - 多案件队列支持 - 团队协作功能 - 自定义 playbook 编辑器 - SIEM 集成 (Splunk, ELK) ### 🔮 未来 (v3.0) - 基于 ML 的异常检测 - 持久化学习 (跨案件的 IoC 情报) - 云端证据分析 (AWS, Azure, GCP) - 商业 SaaS 产品 ## 许可证 MIT 许可证 - 详情请参见 [LICENSE](LICENSE)。 ## 致谢 - **SANS Institute** 感谢其举办 FIND EVIL! 黑客松 - **SANS SIFT Workstation** 取证工具和社区 - **NIST CFReDS** 感谢其提供真实测试数据集 - **Volatility Foundation** 感谢其内存分析框架 - **YARA** 感谢其恶意软件分类功能 - **Claude Code** (Anthropic) 感谢其自主 agent 架构 ## 联系方式 - **GitHub:** https://github.com/Strike48-public/4n6_nexus - **Issues:** https://github.com/Strike48-public/4n6_nexus/issues - **作者:** Jonathan Tomek (hackathon@example.com) 展示自主 DFIR 的未来。