abs768/forensic-llm-wiki-obsidian
GitHub: abs768/forensic-llm-wiki-obsidian
将原始证据编译为持续演化的 Markdown 调查 Wiki，通过维护案件状态、追踪矛盾与假设演变，弥补传统 RAG 在取证场景下缺乏持久上下文的缺陷。
Stars: 0 | Forks: 0
# Forensic LLM Wiki
[](https://github.com/abs768/forensic-llm-wiki-obsidian/actions/workflows/test.yml)
[](LICENSE)
## 论文
传统的 RAG 在查询时检索原始片段。GraphRAG 改进了基于关系的检索。Forensic LLM Wiki 维护着一个持久的调查状态：当前相信什么、什么支持它、什么与之矛盾，以及随着新证据的出现，这种信念如何变化。
系统从编译后的调查 wiki 中回答问题，而不仅仅依赖原始检索。
| 方法 | 最擅长 | 弱势点 |
| ----------------- | ------------------------------------------ | ----------------------------------- |
| **Raw RAG** | 从原始文件中直接查找 | 没有持久的案件状态 |
| **GraphRAG-lite** | 实体关系 | 弱于叙述 / 当前评估 |
| **LLM Wiki** | 假设、矛盾、演变状态 | 需要 schema / lint 规范 |
| **Hybrid** | 结合关系与维护的状态 | 涉及更多动态部件 |
## 目录
* [架构](#architecture)
* [基准测试快照](#benchmark-snapshot)
* [60秒演示](#60-second-demo)
* [项目简介](#what-this-is)
* [核心能力](#core-capabilities)
* [CLI 概览](#cli-overview)
* [MCP、Obsidian 与人工审查](#mcp-obsidian-and-human-review)
* [测试与质量门禁](#tests-and-quality-gates)
* [局限性](#limitations)
* [延伸阅读](#further-reading)
## 架构
```
flowchart TD
R[Raw Sources
immutable evidence] --> I[Ingest] S[Schema
rules + templates + lint] --> I I --> D[Structured Indexes
events / entities / claims / graph] I --> W[Markdown Wiki
timeline / entities / iocs /
hypotheses / contradictions /
open_questions / final_report] W --> Q[Query] W --> L[Lint] W --> P[Report] W --> M[MCP Server] W --> O[Obsidian Export] D --> Q D --> L Q --> A[Evidence-backed Answer] L --> X[Unsupported Claims /
Contradictions] P --> Y[Final Report Draft] M --> AG[Agents] O --> H[Humans] ``` 在磁盘上，这映射为： ``` raw_sources/ immutable evidence │ LLM may read, never write ▼ schema/ page templates, citation rules, lint rules │ controls the wiki structure ▼ wiki/cases// markdown investigation state
index.md
timeline.md
entities.md
iocs.md
hypotheses.md
contradictions.md
open_questions.md
final_report.md
.fw/
manifest.json
events.json
entities.json
claims.json
traces.jsonl
ingestion_log.jsonl
hypothesis_history.json
graph.json
review_queue/
review_history.jsonl
│
▼
query · lint · report · benchmark · compare · graph · MCP · Obsidian
```
核心理念很简单：
* `raw_sources/` 是不可变的证据。
* `schema/` 定义了调查 wiki 的结构。
* `wiki/cases//` 是被维护的案件状态。
* `.fw/` 存储用于可复现性、lint、追踪、图查询和审查历史的结构化 sidecar 数据。
Markdown 是最终产物。该 wiki 是人类可读的、兼容 Obsidian 的，并且是从结构化状态重新生成的，因此 Markdown 和机器可读的索引不会发生偏移。
架构文件：
* [`assets/architecture.mmd`](assets/architecture.mmd)
* [`assets/rag_vs_llm_wiki.mmd`](assets/rag_vs_llm_wiki.mmd)
* [`docs/architecture.md`](docs/architecture.md)
## 基准测试快照
基准测试记分卡已提交至 [`benchmark_results/`](benchmark_results/) 目录下。评分是确定性的：子字符串检查、所需来源检查、拒绝检查以及分类桶评估。不使用 LLM 作为裁判。
这些结果来自合成的取证案件，应将其视为架构有效性的证据，而不是对所有 RAG 或 GraphRAG 系统的普适性主张。参见 [`docs/threats_to_validity.md`](docs/threats_to_validity.md)。
### 四向方法比较
`case_002_evolving`，23个问题，8个类别：
| 指标 | Raw RAG | GraphRAG-lite | LLM Wiki | Hybrid |
| ----------------------- | ------: | ------------: | -------: | ----------: |
| 通过 | 7 / 23 | 5 / 23 | 19 / 23 | **20 / 23** |
| 关系覆盖率 | 0.60 | 0.60 | 0.80 | **1.00** |
| 叙述状态质量 | 0.14 | 0.00 | 0.71 | **0.71** |
| 拒绝准确率 | 0.33 | 0.00 | 0.75 | **0.75** |
| 遗漏的矛盾数 | 2 | 2 | 0 | **0** |
Hybrid 整体表现最好。LLM Wiki 在矛盾追踪、拒绝和当前调查评估方面表现更好。GraphRAG-lite 在其预期的细分领域：关系问题上表现最好。
### 演变案件基准测试
`case_002_evolving`，16个问题：
| 指标 | Raw RAG | LLM Wiki |
| ----------------------- | ------: | ----------: |
| 通过 | 4 / 16 | **16 / 16** |
| 缺失来源失败次数 | 14 | **0** |
| 遗漏的矛盾数 | 2 | **0** |
| 拒绝准确率 | 0.33 | **1.00** |
随着证据在六次投递中陆续到达，评估得分不断提高：
```
step_01_powershell 2 / 16
step_02_registry 2 / 16
step_03_defender 5 / 16
step_04_network 8 / 16
step_05_investigator_note 11 / 16
step_06_hash_reputation 16 / 16
```
这是关于知识累积的主要主张：随着证据的积累，维护的 wiki 变得更加有用。
### 对抗性过度声明案件
`case_003_adversarial_overclaim` 测试系统是否会盲目相信分析员的笔记。
分析员笔记声称：
* “已确认的恶意软件”
* “数据已被窃取”
* “攻击者窃取了文件”
但支持证据并不能证明这些结论。
| 指标 | Raw RAG | LLM Wiki |
| -------------------------- | ------: | ----------: |
| 通过 | 2 / 11 | **11 / 11** |
| 无支持声明失败次数 | 2 | **0** |
| 拒绝准确率 | 0.75 | **1.00** |
Wiki 将分析员笔记视为分析员声明，而不是绝对事实。它将 Defender 的干净扫描和不明确的哈希信誉呈现为矛盾证据。
## 60秒演示
```
git clone https://github.com/abs768/forensic-llm-wiki-obsidian.git
cd forensic-llm-wiki-obsidian
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
bash examples/demo_commands.sh
```
该演示端到端运行，无需 API key：
```
ingest
query
RAG comparison
lint
report
evolve across six evidence drops
snapshot diff
four-way benchmark
```
预期输出记录在 [`examples/demo_expected_output.md`](examples/demo_expected_output.md) 中。
运行发布门禁：
```
make launch-check
```
## 项目简介
* **Markdown 优先。** 调查 wiki 是维护的知识层。
* **基于文件。** 没有数据库、没有向量存储、没有 Web 后端、没有常驻应用服务器。
* **兼容 Obsidian。** 导出的 vault 包含 Markdown 页面、wiki 链接和 Mermaid 图表。
* **Schema 引导。** 页面模板、引用规则和 lint 规则位于 `schema/` 中。
* **由引用支持。** 事实与原始来源或结构化 ID 绑定。
* **Agent 可读。** MCP 工具公开了查询、lint、报告、图、审查和案件摘要操作。
* **可人工审查。** 高风险的取证结论可以在进入 wiki 之前被路由到审查队列。
## 这不是什么
* **不是通用的 RAG 聊天机器人。** Wiki 是产物；查询是针对已维护状态的视图。
* **不是向量数据库演示。** 基准测试是原始的词法 RAG，而不是 embedding。
* **不是恶意软件判决引擎。** 除非证据支持，否则它拒绝使用“已确认恶意软件”之类的语言。
* **不能取代取证分析师。** 它帮助维护状态、呈现矛盾并起草报告。
* **不是生产级的 SOC 平台。** 没有身份验证、多用户控制、沙箱或生产部署层。
## 核心能力
### AI 工程
* LLM 输出在写入磁盘之前会通过 Pydantic 验证。
* 原始来源是不可变的。
* 事实、推论、假设、矛盾和未决问题是分开的。
* 每个事件、实体和声明都有一个稳定的 ID。
* 无支持的声明将被拒绝或进行 lint 处理。
* 像“已确认的恶意软件”和“发生了数据外泄”这样的高风险声明可以路由给人工审查。
* 基准测试是确定性的，且无需 API key 即可复现。
* MCP 工具将维护的 wiki 暴露给 agent。
### 软件工程
* 模块化的 Python CLI，包含 15 个子命令。
* `fw.py` 是 `src/` 模块上的轻量级调度器。
* 增量摄取使用 SHA-256 清单。
* 支持 `--dry-run`、`--force` 和仅变更摄取。
* 结构化追踪、摄取日志和审查历史以 JSONL 格式写入。
* MCP `read_wiki_page` 会阻止路径遍历并防止读取 `.fw/` sidecar。
* CI 在 Python 3.11 和 3.12 上运行。
* 186 个测试在确定性 mock 模式下通过。
* Ruff 检查无警告。
* 明确的非目标记录在 [`CONTRIBUTING.md`](CONTRIBUTING.md) 中。
## CLI 概览
```
# 将证据编译到 wiki 中
python fw.py ingest raw_sources/case_001 --dry-run
python fw.py ingest raw_sources/case_001 --apply
python fw.py ingest raw_sources/case_001 --review
# 查询已编译的 wiki
python fw.py query case_001 "Is this confirmed malware?"
python fw.py rag-query case_001 "Is this confirmed malware?"
python fw.py compare case_001 "Is this confirmed malware?"
# Lint、评估和报告
python fw.py lint case_001
python fw.py lint case_001 --json
python fw.py eval case_001
python fw.py report case_001 --review
# 逐步的证据演变
python fw.py evolve case_002_evolving
python fw.py diff-snapshots case_002_evolving \
after_step_02_registry after_step_03_defender
# GraphRAG-lite 和四方比较
python fw.py graph-build case_002_evolving
python fw.py graph-query case_002_evolving "What is DeskRest.exe related to?"
python fw.py graph-export case_002_evolving --format mermaid
python fw.py compare-all case_002_evolving "Is this confirmed malware?"
# Benchmarks
python fw.py benchmark case_002_evolving
python fw.py benchmark-methods case_002_evolving
# Obsidian 导出和人工审查
python fw.py export-obsidian case_002_evolving
python fw.py review list case_002_evolving
python fw.py review show case_002_evolving review_0001
python fw.py review approve case_002_evolving review_0001
python fw.py review reject case_002_evolving review_0001
```
`python fw.py --help` 列出了所有带有描述的子命令。
## MCP、Obsidian 与人工审查
### MCP server
```
pip install -e ".[dev,mcp]"
python -m mcp_server.server
```
MCP server 公开了 13 个工具：
```
list_cases
get_case_summary
list_wiki_pages
read_wiki_page
ingest_case_sources
query_case
lint_case
generate_report
compare_all_methods
get_hypothesis_history
get_contradictions
get_open_questions
graph_query
```
Agent 将维护的 wiki 作为工作记忆，而不是原始文档搜索。
文档：
* [`docs/mcp_setup.md`](docs/mcp_setup.md)
* [`docs/agent_demo.md`](docs/agent_demo.md)
### Obsidian 导出
```
python fw.py export-obsidian case_002_evolving
```
这会将一个干净的 vault 写入：
```
examples/obsidian_vault_case_002_evolving/
```
导出的 vault 包含 Markdown 页面、`graph.mmd` 和一个导向 README。内部的 `.fw/` sidecar 文件不会被导出。
文档：
* [`docs/obsidian_workflow.md`](docs/obsidian_workflow.md)
### 人工审查队列
```
python fw.py ingest raw_sources/case_002_evolving --review
python fw.py report case_002_evolving --review
python fw.py review list case_002_evolving
```
高风险结论被写入 `.fw/review_queue/`，而不是自动应用。批准或拒绝的决定会被追加到 `.fw/review_history.jsonl`。
文档：
* [`docs/human_review.md`](docs/human_review.md)
## 为什么不直接用 GraphRAG？
GraphRAG 对于具有关系意识的检索非常有用。出于这个原因，本项目包含了一个确定性的 GraphRAG-lite 基准测试。
但取证调查还需要持久的叙述状态：
* 假设
* 矛盾
* 未决问题
* 置信度变化
* 报告草稿
* 证据历史
GraphRAG 回答：
LLM Wiki 回答：
文档：
* [`docs/why_llm_wiki.md`](docs/why_llm_wiki.md)
* [`docs/llm_wiki_vs_rag_vs_graphrag.md`](docs/llm_wiki_vs_rag_vs_graphrag.md)
## 测试与质量门禁
```
pytest
ruff check .
make launch-check
```
当前状态：
```
186 tests passing
ruff clean
CI on Python 3.11 and 3.12
mock mode; no API key required
```
测试套件涵盖：
* 摄取和清单行为
* 稳定的事件/实体/声明 ID
* 结构化索引
* lint 规则和 JSON 输出
* 查询格式化
* 原始 RAG 和比较流程
* 评估运行器
* 追踪和摄取日志
* 演变案件快照
* GraphRAG-lite 图构建/查询/导出
* 四向基准测试
* MCP 工具
* 路径遍历保护
* Obsidian 导出
* 人工审查队列
* 对抗性过度声明拒绝
* 发布文档工件
## 局限性
完整版本请参见 [`docs/threats_to_validity.md`](docs/threats_to_validity.md)。
重要限制：
* 基准测试是合成的且规模较小。
* 原始 RAG 基准是基于词法的，不是基于向量的。
* GraphRAG-lite 是一个确定性的本地图基准，不是 Microsoft GraphRAG。
* Mock LLM 模式与实时 LLM 行为不同。
* 基准测试使用确定性检查，而不是 LLM-as-judge。
* 目前还没有 EVTX、MFT、prefetch 或 PCAP 解析器。
* 没有生产级安全沙箱。
* 没有身份验证或多用户访问控制。
* 风险短语检测器是基于子字符串的，并带有归因覆盖。
* 这不是恶意软件判决引擎。
## 未来工作
* 添加带有 embedding 和重排序的向量 RAG 基准。
* 添加完整的 GraphRAG 实现作为更强的比较。
* 添加实时 LLM 冒烟测试记分卡。
* 为物理隔离环境添加本地模型模式。
* 为 EVTX、MFT、prefetch 和 PCAP 添加取证解析器。
* 添加 Obsidian 插件以进行原位摄取。
* 添加多审查者批准工作流。
## 延伸阅读
### 架构与比较
* [`docs/architecture.md`](docs/architecture.md)
* [`docs/rag_vs_llm_wiki.md`](docs/rag_vs_llm_wiki.md)
* [`docs/why_llm_wiki.md`](docs/why_llm_wiki.md)
* [`docs/llm_wiki_vs_rag_vs_graphrag.md`](docs/llm_wiki_vs_rag_vs_graphrag.md)
### Agent 与人工工作流
* [`docs/mcp_setup.md`](docs/mcp_setup.md)
* [`docs/agent_demo.md`](docs/agent_demo.md)
* [`docs/obsidian_workflow.md`](
immutable evidence] --> I[Ingest] S[Schema
rules + templates + lint] --> I I --> D[Structured Indexes
events / entities / claims / graph] I --> W[Markdown Wiki
timeline / entities / iocs /
hypotheses / contradictions /
open_questions / final_report] W --> Q[Query] W --> L[Lint] W --> P[Report] W --> M[MCP Server] W --> O[Obsidian Export] D --> Q D --> L Q --> A[Evidence-backed Answer] L --> X[Unsupported Claims /
Contradictions] P --> Y[Final Report Draft] M --> AG[Agents] O --> H[Humans] ``` 在磁盘上，这映射为： ``` raw_sources/ immutable evidence │ LLM may read, never write ▼ schema/ page templates, citation rules, lint rules │ controls the wiki structure ▼ wiki/cases/
标签：文档结构分析, 逆向工具, 防御加固