crisroura/sift-assistant
GitHub: crisroura/sift-assistant
基于 Claude Code 的 DFIR 编排层，在 SANS SIFT 工作站上将 30 余种取证工具组织为分阶段自动化调查流程，并内置证据完整性保护与审计机制。
Stars: 0 | Forks: 0
# SIFT 助手
一个用于 SANS SIFT Ubuntu 工作站的 Claude Code 编排层，专注于数字取证与事件响应 (DFIR)。提供全局行为规则、32 项技能（30 个细粒度的 `dfir-*` 工具，加上 `case-investigate` 和 `case-init`）、集中式工具路径文件、多资产案件模板以及分阶段的调查 pipeline（解析 → 分析 → 关联 → 报告）。
## 前置条件
| 要求 | 说明 |
|-------------|-------|
| SANS SIFT Workstation | Ubuntu x86-64，已安装标准 SIFT 工具集 |
| Claude Code CLI | `npm install -g @anthropic-ai/claude-code` |
| Anthropic API key | 在首次运行 `claude` 后设置 — **切勿复制** `~/.claude/.credentials.json` |
| Python 3 + WeasyPrint + markdown | `pip3 install weasyprint markdown` — 生成 PDF 报告所需 |
| dotnet runtime v6 | SIFT 已预装；EZ Tools 位于 `/opt/zimmermantools/` |
## 安装说明
### 方法 1 — curl 一行命令安装（推荐）
```
curl -fsSL https://raw.githubusercontent.com/crisroura/sift-assistant/main/install.sh | bash
```
该脚本将：
- 将 repo 克隆到临时目录（退出时自动清理）
- 在覆盖前备份现有的 `~/.claude/{CLAUDE.md,settings.json,settings.local.json,tools.env,evidence_guard.py,action_logger.py,SIFT_SERVER_DFIR_TOOLS.json}`
- 将全局配置（包括 `tools.env`、`evidence_guard.py` PreToolUse hook、`action_logger.py` PostToolUse hook 以及 `SIFT_SERVER_DFIR_TOOLS.json` 后备工具路由器）、所有 32 项技能、案件模板和 PDF 脚本安装到 `~/.claude/`
- 提供可选的 WeasyPrint 安装（当通过管道传递 stdin 时跳过提示）
若需同时以交互方式安装 WeasyPrint：
```
curl -fsSL https://raw.githubusercontent.com/crisroura/sift-assistant/main/install.sh -o /tmp/install.sh
bash /tmp/install.sh
```
### 方法 2 — 克隆 repo
```
git clone --depth=1 https://github.com/crisroura/sift-assistant.git
cd sift-assistant
bash install.sh
```
### 方法 3 — 下载 ZIP
1. 在 GitHub 上点击 **Code → Download ZIP**
2. 解压并运行：
unzip sift-assistant-main.zip && cd sift-assistant-main
bash install.sh
## Repository 结构
```
sift-assistant/
├── README.md
├── install.sh
├── global/
│ ├── CLAUDE.md ← role, constraints, methodology, Skills reference
│ ├── settings.json ← permissions + PreToolUse evidence guard + audit Stop hook
│ ├── settings.local.json ← machine-local sudo/apt overrides
│ ├── tools.env ← single source of truth for tool paths ($VOLATILITY3, $EZ*)
│ ├── evidence_guard.py ← PreToolUse hook: blocks writes/deletes to evidence
│ ├── action_logger.py ← PostToolUse hook: appends every action to audit/forensic_actions.jsonl
│ └── SIFT_SERVER_DFIR_TOOLS.json ← fallback tool router: artifact→installed-tool catalog (parse phase)
├── skills/
│ ├── case-investigate/SKILL.md ← thin pipeline orchestrator (chains the phase skills)
│ ├── dfir-triage/SKILL.md ← Phase 0 (advisory): evidence triage & prioritization
│ ├── case-parse/SKILL.md ← Phase 1: mount + run all parsers → export/
│ ├── case-analyze/SKILL.md ← Phase 2: per-asset evidence-tagged analysis reports
│ ├── case-correlate/SKILL.md ← Phase 3: cross-asset correlation report
│ ├── case-report/SKILL.md ← Phase 4: final report + evidence verify + PDF
│ ├── case-evidence-verify/SKILL.md ← Phase 4.5: citation verification
│ ├── case-init/SKILL.md ← multi-asset case directory scaffold
│ ├── tools-preflight/SKILL.md ← Phase-0 tool availability check (run before a case)
│ ├── tools-mount/ ← mount orchestrator + gen_mount_commands.sh (EWF + raw; validate→identify→emit sudo mount→verify)
│ ├── tools-mount-e01/SKILL.md ← ewfmount EWF/E01 images (low-level reference)
│ ├── tools-mount-ntfs/SKILL.md ← loop-mount NTFS partitions (low-level reference)
│ ├── tools-mount-vss/SKILL.md ← VSS access on Linux (vss_carver/vshadowmount)
│ ├── dfir-sleuthkit-file-recovery/ ← fls, icat, tsk_recover, mactime
│ ├── dfir-file-carving/ ← bulk_extractor, photorec, foremost
│ ├── dfir-mft/ ← MFTECmd ($MFT + UsnJrnl)
│ ├── dfir-evtx/ ← EvtxECmd + key Event ID reference
│ ├── dfir-registry/ ← RECmd (Kroll batch) + RegRipper
│ ├── dfir-prefetch/ ← pref.pl + prefetch.py (PECmd absent on SIFT)
│ ├── dfir-amcache/ ← AmcacheParser
│ ├── dfir-recentfilecache/ ← RecentFileCacheParser (Win7 RecentFileCache.bcf)
│ ├── dfir-shimcache/ ← AppCompatCacheParser
│ ├── dfir-srum/ ← SrumECmd
│ ├── dfir-scheduled-tasks/ ← xmllint (Task XML) + jobparser (legacy .job)
│ ├── dfir-lnk-jumplists/ ← LECmd + JLECmd
│ ├── dfir-shellbags/ ← SBECmd
│ ├── dfir-recyclebin/ ← RBCmd ($Recycle.Bin $I/$R)
│ ├── dfir-browser/ ← SQLECmd (Chrome/Edge/Firefox) + WxTCmd
│ ├── dfir-strings/ ← bstrings + strings
│ ├── dfir-plaso-timeline/ ← log2timeline.py, psort.py, image_export.py
│ ├── dfir-memory-volatility/ ← Volatility 3 (all plugins)
│ └── dfir-yara/ ← YARA rules and IOC sweeps (python3-yara)
├── case-templates/
│ ├── CLAUDE.md ← reference-only per-case template
│ └── context/
│ └── case_context.md ← case intel template (evidence, IOCs, timeline)
└── analysis-scripts/
├── generate_pdf_report.py ← Markdown → HTML → WeasyPrint PDF generator (CLI)
└── samples/
└── baseline-memory-sample.html ← reference-only sample (never emitted as a deliverable)
```
## 工作原理
### 全局配置 (`~/.claude/CLAUDE.md`)
将 Claude 的角色设置为 DFIR Orchestrator，并附带严格的证据完整性规则：
- **无幻觉** — 所有结论仅基于原始工具输出
- **有证据支持的声明** — 每一条事实陈述都包含指向真实 `export/` 文件的内联 `[EV-NNNNN]` 引用（在阶段 4.5 中验证）
- **证据只读** — 切勿修改 `/cases/`、`/mnt/`、`/media/`；仅限取证工具写入 `./export/`
- **输出路由** — 分析和报告分别进入 `./analysis/`、`./reports/`、`./context/`
- **有限制的自我纠正** — 验证每个工具（退出代码 + 非空输出）；失败时，使用文档化的 fallback 重试一次，然后记录差异
- **自主运行** — 无需中途确认；假设和偏差记录在报告的 Gaps 部分
- **UTC 时间戳** — 始终使用，并为每个支持该参数的工具显式传递 UTC 标志
### 技能 (`~/.claude/skills/dfir-*/SKILL.md`)
每项技能都是独立的：包含特定 DFIR 任务的工具路径、关键标志、使用示例和分析提示。每个 artifact 技能分为两个带标识的部分 — **第 1 部分 · 解析**（在阶段 1 中由 `/case-parse` 使用）和 **第 2 部分 · 分析**（在阶段 2 中由 `/case-analyze` 使用） — 位于共享的前置条件 + 概述前言之下。Claude 在需要使用该工具时会读取相应的技能。技能通过名称（例如 `/dfir-evtx`）调用，或由 `case-investigate` pipeline 自动引用。
### 权限 (`~/.claude/settings.json`)
允许 `Bash(*)`，这样 Claude 在调查期间就不会因等待权限而暂停；**deny list 才是真正的边界**。Write/Edit 的范围仅限于 `./analysis/*`、`./reports/*`、`./context/*`，并在 `sources/**`、`./export/**` 和操作层面的 `./audit/**` 上被明确拒绝；`./export/` 中的已解析证据仅由取证工具 (bash) 写入，绝不使用 Write/Edit 工具，而 `./audit/` 控制 + 审计记录仅由技能 (bash) 和 hooks 写入。
Deny list 会阻止破坏性命令（`rm -r*`、`shred`、`truncate`、`mkfs`、`wipefs`、`fdisk`、`parted`、`sgdisk`、`dd`）以及所有网络出口流量（`wget`、`curl`、`ssh`、`scp`、`rsync`、`nc`、`ncat`、`netcat`、`telnet`、`ftp`、`WebFetch`）。
有两个 hooks 提供后备支持：
- **PreToolUse** (`evidence_guard.py`) — 阻止任何试图写入或删除 `sources/`、`/mnt`、`/media` 或 `*.E01` 的 Bash 命令（语义层面的监管链保障）。
- **Stop** — 将会话元数据（session id、cwd、transcript path）附加到 `./audit/forensic_audit.log`。
## 案件目录结构
每个案件都遵循此布局，支持任意数量的资产：
```
/cases/CLIENT-IR-YYYY-NNN/
CLAUDE.md ← @context/case_context.md + @case-investigate skill
context/
case_context.md ← investigator-maintained: evidence inventory,
network topology, accounts, IOCs, timeline, notes
sources/
/
base-dc-cdrive.E01 ← disk image (read-only, never modified)
.img ← memory image (read-only, never modified)
e01-base-dc-cdrive/ ← ewfmount FUSE point, named from the image (created at mount time)
mnt-001-base-dc-cdrive/ ← filesystem volume mount, named mnt-NNN- (every NTFS/FAT/exFAT partition)
mnt-001-vss-NNN-base-dc-cdrive/ ← VSS snapshot mount (created at mount time)
export/ ← parsed evidence ONLY (tool output; chmod 444, immutable)
/
mnt-001-base-dc-cdrive/ ← one subtree per Windows volume (mnt-001-, mnt-002-, ...)
mft/ usnjrnl/ evtx/ registry/ prefetch/ amcache/ shimcache/
srum/ lnk/ shellbags/ browser/ yara/
memory/ timeline/ ← asset-level (Volatility / plaso), created once per asset
← per-volume subdirs created by case-parse at parse time
analysis/
{case_id}-{asset_id}-analysis-report.md ← one per asset
{case_id}-global-correlation-report.md
reports/
{case_id}-final-report.md
{case_id}-final-report.pdf
audit/ ← operational/control plane (not evidence, not analysis output)
.dfir_phase ← pipeline phase marker (gates ./export writes)
artifact_failures.log ← parse failures / unparseable artifacts
forensic_actions.jsonl ← per-action audit trail (PostToolUse hook)
forensic_audit.log ← per-session record (Stop hook)
/
parse_state.txt ← per-volume, per-artifact status
parse.log ← per-asset parse progress log
```
## 启动调查
### 1. 创建案件目录结构
创建案件目录，从中启动 Claude，并调用 case-init 技能：
```
cd /cases
mkdir ACME-IR-2026-001 # the case directory name becomes the case_id
cd ACME-IR-2026-001
claude
# Prompt: /case-init
# case-init 检测当前目录作为 case root 并在 scaffolding 之前进行确认。
# 提供：client name 和 asset IDs（例如 dc01 rd01）——或将 assets 留空以便稍后添加。
```
或者手动创建：
```
CASE="ACME-IR-2026-001"
ASSETS="dc01 rd01"
mkdir -p /cases/${CASE}/{analysis,reports,context,audit}
for A in $ASSETS; do
mkdir -p /cases/${CASE}/sources/${A} /cases/${CASE}/export/${A} /cases/${CASE}/audit/${A}
done
cp ~/.claude/case-templates/CLAUDE.md /cases/${CASE}/CLAUDE.md
cp ~/.claude/case-templates/context/case_context.md /cases/${CASE}/context/
```
### 2. 填写案件情报
编辑 `/cases/${CASE}/context/case_context.md`：
- **事件时间窗口 (Incident Window, UTC)** — 分析的基准锚点；除非与事件相关，否则窗口之外的活动均被视为基线行为
- **资源清单 (Sources Inventory)** — 每个资产占一行：主机名、角色、磁盘镜像路径、内存镜像路径
- **网络拓扑** — 子网和关键主机
- **域账户** — DA、服务账户、本地管理员
- **已知 IOCs** — 在具有类型的 `ioc` 块中每行一个指标（`hash:`/`ip:`/`domain:`/…），以便 pipeline 确定性地 grep 它们
- **事件时间线 (Incident Timeline)** — 带有时间戳的已知事件（随着分析的进展进行更新）
- **案件备注** — 范围决策、客户限制
### 3. 投递证据并启动
```
# 将 evidence 文件复制或 symlink 到 sources//
cp /media/evidence/dc01.E01 /cases/${CASE}/sources/dc01/
# 从 case root 启动 Claude
cd /cases/${CASE} && claude
# 启动完整 pipeline
# Prompt: /case-investigate
```
### 4. 调查 pipeline
`case-investigate` 技能是一个轻量级的编排器，它链接了四个阶段的技能（每个技能也可以独立运行以便恢复/调试）：
| 阶段 | 技能 | 执行内容 |
|-------|-------|-------------|
| **1 — 解析** | `/case-parse` | 从 `case_context.md` 引导启动，通过 `/tools-mount` 挂载每个资产，以有限的并行度 (`MAX_PARALLEL`) 运行所有解析器，并在 `parse_state.txt` 中跟踪状态 |
| **2 — 分析** | `/case-analyze` | 读取 `export//`；为每个资产编写一份带证据标签的分析报告，锚定于事件时间窗口和案件 IOC 块；从不修改 export 文件 |
| **3 — 关联** | `/case-correlate` | 交叉比对所有资产报告；编写全局关联报告 |
| **4 — 报告** | `/case-report` | 编写最终报告，运行 `/case-evidence-verify`（阶段 4.5），如果 WeasyPrint 可用则生成 PDF |
## 逐文件参考
### global/CLAUDE.md → `~/.claude/CLAUDE.md`
全局系统提示。设置 DFIR Orchestrator 角色、证据完整性规则、自主运行偏好，以及一行指向 `dfir-*` 技能的指针。
```
cp global/CLAUDE.md ~/.claude/CLAUDE.md
```
### global/settings.json → `~/.claude/settings.json`
权限策略以及 PreToolUse 证据保护和审计 Stop hook。
允许的 Write/Edit：`./analysis/*`、`./reports/*`、`./context/*`（并且在 `sources/**`、`./export/**`、`./audit/**` 上被明确拒绝）。`./export/` 仅由取证工具 (bash) 写入，从不使用 Write/Edit 工具；`./audit/` 包含阶段标记、解析状态/日志以及由 hook 编写的审计追踪。
```
cp global/settings.json ~/.claude/settings.json
```
### global/settings.local.json → `~/.claude/settings.local.json`
机器本地覆盖设置（sudo apt、psort.py）。尽量保持最少。
```
cp global/settings.local.json ~/.claude/settings.local.json
```
### global/tools.env → `~/.claude/tools.env`
工具路径（`$VOLATILITY3`、`$EZ*`、`$REGRIPPER`，fallback）的唯一真相来源。技能和 pipeline 会 `source` 它；只需在这里更正一次错误的路径，而无需在技能中更改。使用 `/tools-preflight` 进行验证。
```
cp global/tools.env ~/.claude/tools.env
```
### global/evidence_guard.py → `~/.claude/evidence_guard.py`
PreToolUse hook (Bash 匹配器)。读取 stdin 上的工具调用，并通过 `exit 2` 阻止任何试图写入或删除证据（`sources/`、`/mnt`、`/media`、`*.E01`）的命令；允许读取证据。
```
cp global/evidence_guard.py ~/.claude/evidence_guard.py
```
### global/action_logger.py → `~/.claude/action_logger.py`
被 `settings.json` 引用的 PostToolUse hook (Bash|Write|Edit 匹配器)。将每个操作附加到只增不减的 `./audit/forensic_actions.jsonl` 追踪记录中（时间戳、会话、阶段、工具、目标、结果）。
```
cp global/action_logger.py ~/.claude/action_logger.py
```
### global/SIFT_SERVER_DFIR_TOOLS.json → `~/.claude/SIFT_SERVER_DFIR_TOOLS.json`
只读的后备工具路由器：一个机器可读的目录，将每种取证 artifact 类型映射到已安装的 SIFT 命令。仅在作为第三级 fallback（技能的主要工具和文档化的 fallback 均失败）或针对没有 `dfir-*` 技能涵盖的 artifact 类型时，才由 `/case-parse` 调用。`tools.env` 仍然是技能映射工具的唯一真相来源；路由器工具是由其列出的 `command` 路径调用的特许例外。
```
cp global/SIFT_SERVER_DFIR_TOOLS.json ~/.claude/SIFT_SERVER_DFIR_TOOLS.json
```
### skills/ → `~/.claude/skills/`
由安装程序单独安装的 32 个技能（30 个 `dfir-*` 加上 `case-investigate` 和 `case-init`）。
每一项都是独立的，并从 `~/.claude/tools.env` 读取工具路径。伴随文件（例如 `tools-mount/gen_mount_commands.sh`）会与其 `SKILL.md` 一起被复制。
```
# Installer 负责处理此操作。手动复制示例：
mkdir -p ~/.claude/skills/dfir-evtx
cp skills/dfir-evtx/SKILL.md ~/.claude/skills/dfir-evtx/SKILL.md
```
### case-templates/CLAUDE.md → `/cases//CLAUDE.md`
仅供参考的模板。仅包含案件元数据表和两个 `@` 引用：
- `@./context/case_context.md` — 加载特定案件的情报
- `@~/.claude/skills/case-investigate/SKILL.md` — 加载调查 pipeline
此文件中不应包含任何命令、工具路径或特定案件的数据。
```
cp ~/.claude/case-templates/CLAUDE.md /cases//CLAUDE.md
# 仅编辑：Case ID、Client、Case Root
```
### case-templates/context/case_context.md → `/cases//context/case_context.md`
由调查员维护的案件情报文件。部分：
1. 事件时间窗口 (Incident Window, UTC) — 分析的基准锚点
2. 资源清单（资产表）
3. 网络拓扑
4. 域账户
5. 已知 IOCs（具有类型的、可 grep 的 `ioc` 块）
6. 事件时间线 (UTC)
7. 案件备注
这是唯一应包含特定案件事实、IOCs 和时间线条目的文件。
Claude 在每次会话开始时读取它，并在整个分析过程中参考它。
### analysis-scripts/generate_pdf_report.py
Markdown -> HTML -> WeasyPrint PDF 生成器 (CLI: `generate_pdf_report.py --case-id ID --client NAME`)。
由安装程序安装到 `~/.claude/analysis-scripts/`。如果 WeasyPrint 和 markdown 可用，`/case-report` 阶段会在阶段 4 结束时调用它。它不包含任何内置内容；旧示例以不可执行的形式存放在 `analysis-scripts/samples/` 中。纯 Markdown 会被自动丰富为带有样式的组件（严重性徽章、`[!TYPE]` 警告标注、编号章节、深色代码块）；字体仅限系统自带（无远程 `@import`），因此可以在气隙隔离主机上运行。
```
pip3 install weasyprint markdown # add --break-system-packages on PEP 668 systems, or use a venv
# 如果缺少 WeasyPrint 的 native libs：
sudo apt-get install -y python3-gi python3-gi-cairo gir1.2-gtk-3.0 libpango-1.0-0
```
## 手动安装（复制粘贴）
```
#!/bin/bash
set -e
# 全局配置
mkdir -p ~/.claude
cp global/CLAUDE.md ~/.claude/CLAUDE.md
cp global/settings.json ~/.claude/settings.json
cp global/settings.local.json ~/.claude/settings.local.json
cp global/tools.env ~/.claude/tools.env
cp global/evidence_guard.py ~/.claude/evidence_guard.py # PreToolUse hook referenced by settings.json
cp global/action_logger.py ~/.claude/action_logger.py # PostToolUse hook referenced by settings.json
cp global/SIFT_SERVER_DFIR_TOOLS.json ~/.claude/SIFT_SERVER_DFIR_TOOLS.json # parse-phase fallback tool router
# Skills
for skill in \
tools-preflight tools-mount \
tools-mount-e01 tools-mount-ntfs tools-mount-vss \
dfir-sleuthkit-file-recovery dfir-file-carving \
dfir-mft dfir-evtx dfir-registry dfir-prefetch \
dfir-amcache dfir-recentfilecache dfir-shimcache dfir-srum \
dfir-scheduled-tasks dfir-lnk-jumplists dfir-shellbags \
dfir-recyclebin dfir-browser dfir-strings \
dfir-plaso-timeline dfir-memory-volatility \
dfir-yara case-evidence-verify \
dfir-triage case-parse case-analyze case-correlate case-report \
case-investigate case-init; do
mkdir -p ~/.claude/skills/${skill}
cp skills/${skill}/SKILL.md ~/.claude/skills/${skill}/SKILL.md
done
# 随 tools-mount 附带的配套脚本
cp skills/tools-mount/gen_mount_commands.sh ~/.claude/skills/tools-mount/gen_mount_commands.sh
# Case template 和分析脚本
mkdir -p ~/.claude/case-templates/context ~/.claude/analysis-scripts
cp case-templates/CLAUDE.md ~/.claude/case-templates/CLAUDE.md
cp case-templates/context/case_context.md ~/.claude/case-templates/context/case_context.md
cp analysis-scripts/generate_pdf_report.py ~/.claude/analysis-scripts/generate_pdf_report.py
pip3 install weasyprint markdown # add --break-system-packages on PEP 668 systems, or use a venv
echo "Done."
```
## 监管链
- Claude 从不写入 `sources/`、`/mnt/`、`/media/` 或任何证据目录
- 通过多层强制执行：只读挂载 (`ro`)、范围限定且在 `sources/**` 上被拒绝的 `Write`/`Edit`、经过强化的 Bash deny list，以及阻止任何写入或删除证据命令的 `evidence_guard.py` PreToolUse hook
- 挂载点在挂载时于 `sources//` 内部创建；证据文件从不被修改
- 所有解析后的输出都位于 `export///` 中 — 仅由取证工具写入，此后不再修改
- 分析和报告文件仅写入 `analysis/` 和 `reports/`
- `Stop` hook 会在每次会话后将案件元数据（session id、cwd、transcript path）附加到 `./audit/forensic_audit.log`
- 在分析前应验证镜像完整性：`ewfverify /cases//sources//*.E01`
## 未包含的内容
| 排除项 | 原因 |
|----------|--------|
| `~/.claude/.credentials.json` | Anthropic API key — 切勿共享 |
| `~/.claude/history.jsonl` | 会话命令历史 — 特定于机器 |
| `~/.claude/projects/` | 会话记忆 — 特定于案件 |
| 证据文件 (`*.E01`, `*.img`) | 只读证据 — 切勿复制或共享 |
| 案件分析输出 | 特定于案件 — 位于 `/cases//` |
标签：Claude Code, LLM编排, SIFT工作站, 后端开发, 库, 应急响应, 应用安全, 数字取证, 自动化报告, 自动化脚本, 防御加固