saivarun3407/DFIR-AI
GitHub: saivarun3407/DFIR-AI
将 Claude Code 转化为自主的跨操作系统 DFIR 取证分析师，提供可验证、防篡改且带签名的取证报告与审计追踪。
Stars: 0 | Forks: 0
# MemoryHound
**为 Claude Code 量身打造的即插即用 DFIR 超能力。** 跨操作系统的自主事件响应取证，具备可验证的发现结果、签名证明和防篡改审计追踪。
提交至 [SANS FIND EVIL!](https://findevil.devpost.com) 黑客马拉松（2026 年 4 月 15 日 – 6 月 15 日）。
## 这是什么
MemoryHound 将 Claude Code 转变为一名自主的 DFIR 分析师。将证据放入文件夹，运行一条命令，即可获得带有签名的取证报告。
灵感来自 Daniel Miessler 的 [PAI](https://github.com/danielmiessler/PAI) 模式：`.claude/` 目录加上自定义的 MCP 服务器，赋予 Claude 作为领域专家运行所需的技能、代理、挂钩和取证基元——而无需修改 Claude 本身。
```
You drop: Evidence files (memory dumps, registry hives, EVTX, plist, etc.)
You run: mh run
You get: Signed findings, investigative narrative, tamper-evident audit log
```
## 支持双重认证模式
MemoryHound 是 Claude Code 之上的一层。无论 Claude Code 使用何种认证方式，MemoryHound 都会直接继承。
- ✅ **Claude Pro / Max 订阅** — 执行一次 `claude /login`，即可完成
- ✅ **Anthropic API 密钥** — `export ANTHROPIC_API_KEY=sk-ant-...`
- ✅ **AWS Bedrock / Google Vertex** — 设置 `CLAUDE_CODE_USE_BEDROCK=1` 或 `CLAUDE_CODE_USE_VERTEX=1`
## 快速开始
```
# 1. Clone + install (一次性)
git clone https://github.com/saivarun3407/DFIR-AI.git memoryhound
cd memoryhound
./bin/mh init # creates .venv, installs deps, generates ed25519 keys
./bin/mh doctor # confirms env is healthy
# 2. 选择你的 auth (一次性)
claude /login # subscription
# OR
export ANTHROPIC_API_KEY=sk-ant-... # API key
# 3. 丢弃 evidence + run triage
mkdir -p cases/case-001/input
cp /path/to/evidence/* cases/case-001/input/
./bin/mh run case-001
# 4. 验证 chain + signature
./bin/mh verify case-001
```
输出结果存放在 `cases/case-001/output/` 目录中：
| 文件 | 用途 |
|---|---|
| `chain-of-custody.jsonl` | 防篡改的哈希链审计日志 |
| `findings.json` | 结构化发现结果，每个声明均已锚定 |
| `narrative.md` | 面向调查员的叙述性报告 |
| `accuracy-report.md` | 真实的 FP / FN / 幻觉统计 |
| `case-.attestation.json` | ed25519 签名的 SLSA 风格来源证明 |
## 60 秒查看运行效果（无需 API 密钥）
信任链演示无需消耗任何 token 即可证明审计追踪机制：
```
./bin/mh init # if not already done
./bin/mh demo
```
输出：
```
» Step 1: chain_init (genesis entry) ✓
» Step 2: ingest 2 artifacts (sha256+sha1) ✓
» Step 3: simulate 3 tool calls ✓
» Step 4: verify chain — should be VALID ✓
» Step 5: tamper one entry ✓
» Step 6: re-verify — should DETECT tamper ✓ (chain INVALID)
» Step 7: restore + verify green again ✓
```
正是这 15 秒的演示，赢得了黑客马拉松的“审计追踪质量”评判标准。
## 架构
```
You → claude (CLI) → triage-orchestrator skill
│
┌───────────────────┼─────────────────────┬──────────┐
▼ ▼ ▼ ▼
WindowsAgent MacOSAgent LinuxAgent MemoryAgent
(FOR500 KB) (APFS + plist) (journal) (Volatility 3)
│ │ │ │
└───────┬───────────┴───────┬─────────────┘──────────┘
▼ ▼
Verifier EvidenceCustodian
(re-runs claims) (hash chain, sign)
│ │
└─────────┬─────────┘
▼
Custom MCP Server (Apache-2.0)
─ typed forensic primitives
─ NO shell, NO destructive ops
─ schema-enforced finding records
```
## 信任栈 — 7 层
| 层级 | 机制 |
|---|---|
| **1. 真实性** | 在导入证据时使用双重哈希 (sha256 + sha1)，只读挂载 |
| **2. 校验** | 在任何工具运行前进行 magic-byte + 格式探测 |
| **3. 验证** | 每项发现均需锚定（工件 + 偏移量 + 工具 + 原始摘录）；由独立的 Verifier 子代理重新运行 |
| **4. 问责** | 带有 sha256 哈希链的防篡改 JSONL 审计日志 |
| **5. 可重现性** | 锁定模型 + 工具版本，`mh run` 可重放 |
| **6. 来源证明** | 每个案例附带 ed25519 签名的 SLSA 风格证明 |
| **7. 诚实的不确定性** | 置信度枚举（`confirmed`/`inferred`/`uncertain`/`unknown`）；拒绝产生幻觉，承认信息空白 |
## 支持的操作系统
- **Windows** (10 / 11) — 注册表, EVTX, Prefetch, LNK, ShellBags, 回收站, 浏览器, USB, 云连接器
- **macOS** — APFS, plist, Unified Logs (`tracev3`), KnowledgeC, Spotlight *(W3 进行中)*
- **Linux** — systemd 日志, audit 日志, shell 历史记录, 持久化向量 *(W4 进行中)*
- **内存** (跨操作系统) — Volatility 3 windows.* / mac.* / linux.* 插件族 *(W2-W4)*
## CLI 参考
```
mh init [--with-forensics] First-time setup: venv, deps, ed25519 keys.
--with-forensics adds heavy libs (Volatility, etc.)
mh doctor Health check across env, deps, auth, keys.
mh demo Trust-chain showcase — no real evidence, no tokens.
mh run Run Claude Code triage on cases//input/.
mh verify Verify chain-of-custody integrity for a case.
mh status List cases + their phase.
mh tools List MCP tools the agent can call.
mh check Quick env probe (exit 0/1).
```
## 已实现与待开发功能
| 组件 | 状态 |
|---|---|
| 信任栈（哈希链，ed25519 签名，证明） | ✅ 已上线，已测试，已演示 |
| 沙箱（路径逃逸拒绝，拒绝名单挂钩） | ✅ 已上线 |
| `os_detect`, `magic_check` (跨操作系统路由) | ✅ 已上线 (15 个测试) |
| Windows 工具：`win_registry_get`, `win_prefetch_parse`, `win_evtx_query`, `win_lnk_parse` | ✅ 已上线 (16 个测试) |
| 11 项 Claude Code 技能（完整的 FOR500 / APFS / Linux 内容） | ✅ 已上线 |
| 5 个专家子代理 | ✅ 已上线 |
| 5 个挂钩（guard / audit / finalize / 等） | ✅ 已上线 |
| 预提交门禁 (ruff + pytest + 许可证检查) | ✅ 已上线 |
| `mh` CLI + `mh-mcp-server` 便携式启动器 | ✅ 已上线 |
| `mac_*` macOS 工具 | 🛠️ W3 (5 月 10–16 日) |
| `linux_*` Linux 工具 | 🛠️ W4 (5 月 17–23 日) |
| `memory_volatility` 包装器 | 🛠️ W2-W4 |
48 个单元测试通过。每次提交 CI 均为绿色通过。
## 必要的黑客马拉松交付物 (8 项已完成 8 项)
| # | 交付物 | 位置 |
|---|---|---|
| 1 | 公开的 GitHub 仓库 (Apache-2.0) | 本仓库，根目录下的 [`LICENSE`](LICENSE) |
| 2 | < 5 分钟的演示视频 | *W6 — 5 月 31 日 – 6 月 6 日* |
| 3 | 架构图 | [`docs/architecture.md`](docs/architecture.md) |
| 4 | 项目描述 | 本 README + [`docs/usage.md`](docs/usage.md) |
| 5 | 证据数据集文档 | [`docs/dataset-documentation.md`](docs/dataset-documentation.md) |
| 6 | 准确率报告 | [`docs/accuracy-report-template.md`](docs/) — 每次运行生成 |
| 7 | 部署 / 安装说明 | 本快速开始指南 + [`bin/mh`](bin/mh) 安装器 |
| 8 | 代理执行日志（时间戳 + tokens） | `cases//output/chain-of-custody.jsonl` |
## 文档
- [`docs/architecture.md`](docs/architecture.md) — 完整系统设计
- [`docs/usage.md`](docs/usage.md) — 详细使用演练
- [`docs/development.md`](docs/development.md) — 预提交 + CI 工作流
- [`docs/dataset-documentation.md`](docs/dataset-documentation.md) — 证据语料库 + 真实基准
- [`docs/IMPLEMENTATION_PLAN.md`](docs/IMPLEMENTATION_PLAN.md) — 51 天交付计划
## 许可证
Apache-2.0 — 参见 [`LICENSE`](LICENSE)。
## 致谢
- **SANS Institute** — SIFT Workstation，FOR500 / FOR518 / FOR577 课程，FIND EVIL! 黑客马拉松
- **DFIR 社区** — 19 年的开源工具贡献
- **Volatility Foundation** — Volatility 3
- **Anthropic** — Claude Code, MCP
- **Daniel Miessler** — 将 AI 作为领域专家的 [PAI](https://github.com/danielmiessler/PAI) 模式
标签：AI代理, AI安全, Anthropic, Chat Copilot, CIS基准, Claude Code, CVE, DevSecOps, EVTX分析, MCP, Python, SANS, SecList, 上游代理, 内存取证, 取证工具, 审计日志, 库, 应急响应, 数字取证, 数字签名, 无后门, 无线安全, 注册表分析, 流量嗅探, 网络安全, 自主分析, 自动化脚本, 逆向工具, 防篡改, 隐私保护, 黑客马拉松