staatik/fragchain-core

# FragChain **一个漏洞防御工程工作台：给定一个漏洞，研究出严谨的防御者能够切实检测、追踪、验证、记录、缓解或投入运营的方案——并产出相应的制品。** FragChain 接收单个漏洞，并引导分析师完成一项 结构化的、由 LLM 辅助的评估：该漏洞的实际作用是什么、它在 遥测中留下了什么行为、是否真的切实可检测， 并且——只有在检测合理时——起草检测 制品（目前：Sigma 规则，以及缓解计划、遥测 契约和分析师研究任务）。经过验证的攻击链 会回馈到共享的**情报公共区**，这样下一个 遇到相同 CVE 的团队就不必从头开始了。 一个刻意的设计选择贯穿始终：**“不存在可靠的 检测”是一个有效且成功的结果。** FragChain 的构建旨在 产出*更少但更好*的防御制品，而不是为 每个 CVE 生成一条 Sigma 规则（无论是否真的需要）。  ## 它的实际情况： FragChain 处于 **1.0 版本之前**，并非一个已完成的生产级安全产品。README 首先展示了平台正在构建的方向；本节是 关于目前什么是、什么不是事实的直接版本。 **目前端到端可用的功能：** - 一个分析师驱动的**评估工作区**，它通过 分析师粘贴的来源，运行三循环 内容引擎（漏洞分析 → 威胁情报 → 检测 工程）。 - 在 Loop 2 和 Loop 3 之间设有**确定性可检测性闸口**，当 证据太薄弱而无法进行工程化检测时，会 停止合成。 - **由 LLM 合成的攻击链**映射到 MITRE ATT&CK，并附带 来源引用和逐步骤的检测机会。 - **Sigma 规则生成**由 pySigma 验证，并具有强制性的 人工审查队列以及可配置的到 PR 路由，可指向一个或多个 Sigma 仓库。 - 一个**以 embedding 为先的覆盖映射器**，可区分“通过 ATT&CK 标签匹配”和“实际由语义相似的规则覆盖”。 - 一个 **5 分类可检测性分类器**和一个**制品路由器**，在 每次评估后运行。 - **按需生成**三种非 Sigma 制品类型：缓解 计划、遥测契约和分析研究报告任务。 **咨询性质/分阶段功能（诚实的注意事项）：** - 可检测性分类器是**咨询性质**的——它记录其结论 和推荐制品，但**尚不作为任何操作的闸口**。 - 制品路由器以**兼容模式**运行——它会生成 计划并记录现实与之偏离的地方，但默认情况下 Loop 3 仍 会生成 Sigma。该计划目前无法控制任何东西。 - 非 Sigma 制品生成是**按需的且不受** 计划限制——分析师只需点击“生成”。 - 更广泛的制品词汇表（在 [`AGENTS.md`](AGENTS.md) 中）（Splunk SPL、Sentinel KQL、Elastic、YARA-L、 EDR 追踪、WAF 模式等）**已规划，但尚未发布**。目前存在的只有 Sigma 以及上述三种制品。 - 最初的连接器驱动推送流水线**保留在代码树中，但处于** 休眠状态——详见 [`CLAUDE.md`](CLAUDE.md) §12 / §12.2。 从 CVE 到 Sigma 生成器转变为工作台的分阶段采用计划记录在 [`ADR-0004`](docs/architecture/adr/ADR-0004-staged-defense-engineering-adoption.md)； 范围边界（FragChain 拥有什么与明确不拥有什么）在 [`docs/architecture/000-fragchain-scope.md`](docs/architecture/000-fragchain-scope.md)。 ## 为什么会有这个项目 今天的检测工程就像在跑步机上： - 一个 CVE 发布了。有人阅读了它。另一个人阅读了 PoC。第三个人 检查现有的 Sigma 库中是否有类似的内容。 一半的时间，他们重新推导出与另外十个 团队刚刚推导出的相同的攻击链。 - 本能反应是写一条规则——即使诚实的回答是“使用我们现有的遥测无法可靠地检测到它”，或者“这里的正确 做法是缓解，而不是检测。”这种本能反应会产生 嘈杂、低价值的规则，并掩盖了那些实际上需要追踪、 更改遥测或进行更多研究的情况。 FragChain 押注于三件事来改变这项工作的形态： 1. **在生成前进行结构化推理。** 将各个阶段分开——漏洞 机制、行为指标、可检测性分类、 制品路由——将“阅读三篇博客并猜测技术”转变为 可审查的内容，并在每一步都提供引用来源。 2. **合理的“否定”结果。** 分类器和路由器可以得出结论，认为检测是 依赖于环境的、仅限控制的，或者仅仅是 证据不足——并如实说明，而不是强制生成规则。 3. **共享的、版本化的公共资源。** 链、ATT&CK 映射和 EPSS 快照，这样新的部署就可以从预先验证的内容中进行引导， 而不是从冷启动开始运行昂贵的 LLM 合成。 介于两者之间的所有内容都是为了让这些操作变得安全而设置的管道：TLP 传播、 每个规则的出处、在任何规则进入 Sigma 仓库之前的强制性人工闸口、多目标路由，以及异步循环执行，这样缓慢的 LLM 工作就永远不会阻塞请求路径。 ## 界面展示 ### 寻找评估目标 CVE 浏览器列出了已知的漏洞，并提供日期 范围、CVSS、仅限 KEV、处理状态和来源的过滤器。这是分析师在 打开评估之前选择目标的地方。

### 评估工作区 — 主要工作流 分析师为一个漏洞开启覆盖评估——从 工单、PSIRT 公告或供应商博客粘贴——并引导平台 完成三个循环，每个循环都是一个独立的界面，拥有自己版本化的运行： - **Loop 1 — 漏洞分析。** 这是哪种类型的漏洞，以及 它提出了什么检测问题？（不输出 TTP；链是 稍后从真实证据中构建的。） - **Loop 2 — 威胁情报。** 每个可观察 类别（进程、命令行、网络、文件、注册表、 父/子进程、API 调用）的行为指标，通过 RAG 以 粘贴的来源为基础。 - **Loop 3 — 检测工程。** 每个启用的 logsource 配置文件的 Sigma 规则草案，在到达审查 队列之前由 pySigma 验证。 在 Loop 2 和 Loop 3 之间设有一个**确定性可检测性闸口**：如果 你没有足够的可观察类别（默认为 7 个中的 3 个）的指标， 合成将停止，并会告知分析师原因——他们可以使用新的来源重新运行 Loop 2，附带记录的理由进行覆盖，或者放弃。 循环在 Celery worker 上**异步**运行；工作区通过 WebSocket（带有轮询回退）显示实时 运行状态，并在完成时重新获取数据。

### 可检测性分类与制品路由 每次 Loop 2 运行后，一个**咨询性质的**分类器将漏洞 归类到五个可检测性类别之一—— `directly_detectable`、`indirectly_detectable`、`environment_dependent`、 `control_only`、`insufficient_information`——并附带理由、置信度、 遥测要求、盲点以及推荐与跳过的 制品类型。一个确定性的**制品路由器**随后将其转化为 计划（例如，*跳过 Sigma，推荐缓解计划和研究 任务*）。 在当前的构建中，两者都是**咨询性质/兼容模式**——它们 记录其结论以及现实与之偏离的地方，但 Loop 3 默认情况下仍 生成 Sigma。它们是在后期阶段将 生成翻转为计划控制的证据基础。

### 超越 Sigma 的生成制品 当检测不是全部答案时，分析师可以按需生成其他 防御制品——目前包括：**缓解计划**、**遥测 契约**和**分析师研究任务**。每一个都是结构化的 文档，包含明确的假设、限制、参考、置信度 分数和验证状态（默认情况下，制品永远不会被标记为 生产就绪）。

### 链 平台已生成的每一条链都会与其模型和 提供商（确定性评估合成与 LLM 模型）、版本、 总体置信度、来源（评估/本地/公共区）以及 TLP 一起列出——并且 可以就地重新合成。打开其中一条会显示有序的 TTP 图表： 逐步骤来源、前置条件、检测机会和逐步骤的 置信度分数。如果没有引用的来源，任何内容都无法进入 链。

### 审查队列 起草的 Sigma 规则进入按优先级评分的队列（KEV、EPSS、CVSS、 新颖性、链中位置）。每条规则都标记有 TLP 和 来源链，并且来自低可检测性覆盖的规则带有一个 徽章，以便审查者知道该闸口已被绕过。

人工可以通过并排的完整 Sigma YAML、 来源链和检测元数据来批准、编辑或拒绝每条规则。批准的规则 通过可配置的规则路由到一个或多个 Sigma 目标仓库作为 PR——**绝不自动合并**。

### Sigma 库 平台已知的所有 Sigma 规则——包括从配置的来源拉取的现有上游 内容以及进入 库的 FragChain 生成的规则——都是可搜索、可过滤的，并标记有 logsource、技术、状态和 TLP。生成的内容如果与 现有规则在语义上几乎重复，则会被标记，而不会被丢弃。

### 可调节的 LLM prompt 平台发送给 LLM 的每一个 prompt 都存在于数据库中，而不是 代码中。操作员可以按任务（链 生成、规则生成、覆盖验证、三个评估 循环、可检测性分类以及每种制品类型）对 prompt 进行版本控制、A/B 测试和调优——而无需 重新部署服务。每个 prompt 都会记录 token 成本、延迟和 针对基准集的幻觉分数。

## 它是如何整合在一起的 **部署形态。** FragChain 是你运行的盒子；LLM 代理和 （可选的）OpenCTI 是外部的。公共区和 Sigma 目标仓库是 git 远程仓库。 ``` flowchart LR A[Analyst] --> UI subgraph S3["FragChain · Server 3"] UI["UI + API"] W["Celery workers + beat"] DB[("Postgres · Qdrant · MinIO · Redis")] UI --- DB W --- DB end UI -->|"chat + embeddings
(OpenAI-compat)"| LL["LiteLLM · Server 1"] W -->|"chat + embeddings"| LL LL --> LLMs["Operator's LLMs
Anthropic · OpenAI · Bedrock · Ollama"] UI -.optional.-> OCTI["OpenCTI · Server 2"] W <-->|"sync + contribute"| COM[("Intelligence commons
git, default: public")] W -->|"approved-rule PRs"| SIG[("Sigma target repos")] ``` **工作流。** 在 FragChain 内部，评估通过 可检测性闸口运行三个循环，对可检测性进行分类，路由 制品，将 Sigma 规则放入审查队列中，并且（在人工闸口之后）向配置的 Sigma 目标开启 PR： ``` ┌─────────────────────┐ ┌────────────────────────┐ │ Analyst opens │ │ Intelligence commons │ │ assessment (vuln) │◀───────│ (chains, mappings, │ └──────────┬──────────┘ │ EPSS snapshots) │ │ └────────────▲────────────┘ ▼ │ ┌──────────────────────────┐ │ │ Loop 1 → Loop 2 → gate │ │ │ → detectability class │ │ │ → artifact routing │ │ │ → chain bridge → │ │ │ Loop 3 (Sigma drafts) │ │ └──────────┬───────────────┘ │ ▼ │ ┌──────────────────────────┐ │ │ Review queue │ │ │ (priority-scored, │ │ │ TLP-tagged) │ │ └──────────┬───────────────┘ │ ▼ │ ┌──────────────────────────┐ │ │ Human approve / edit / │ │ │ reject → PR to Sigma │ │ │ target repo(s) │ │ └──────────┬───────────────┘ │ ▼ │ ┌──────────────────────────┐ │ │ Validated chain │────────────────┘ │ contributes back │ └──────────────────────────┘ ``` 最初的推送驱动流水线（连接器 → 丰富 → 合成 → 覆盖 → 规则）保留在代码树中，但**根据设计处于休眠状态**——当连接器生态系统（OpenCTI、AttackerKB、供应商 PSIRT 等）足够密集以支持它时，它会回归。有关休眠允许列表，请参见 [`CLAUDE.md`](CLAUDE.md) §12 / §12.2。 ### 阅读指南 - **[`CLAUDE.md`](CLAUDE.md)** — 操作契约。架构、 schema、TLP 传播规则、禁止事项清单、 休眠允许列表。在接触代码之前阅读此文档。 - **[`AGENTS.md`](AGENTS.md)** — 防御工程产品 方向、目标流水线和制品词汇表（在 两者重叠时，以 `CLAUDE.md` 为准）。 - **[`docs/architecture/`](docs/architecture/)** — 活跃的设计文档： 以评估为中心的架构、可检测性分类器 （[`004`](docs/architecture/004-detectability-classifier.md)）、 制品路由器（[`005`](docs/architecture/005-artifact-router.md)）、 覆盖验证和分阶段采用的 ADR。 - **[`docs/superpowers/plans/`](docs/superpowers/plans/)** — 针对正在进行的 功能进行 TDD 任务列表。 - **[`docs/historical/`](docs/historical/)** — M1–M24 构建日志和 最初的转型前设计语料库，为提供背景而保留（非活跃 范围）。 ## 快速开始 FragChain 作为 Docker Compose 堆栈运行在单个主机上（即 下文的“服务器 3”角色）。你需要自行提供 LLM（服务器 1，通过 [LiteLLM](https://github.com/BerriAI/litellm)）；OpenCTI（服务器 2）是 可选的。 ### 前置条件 - Docker 24+ 带有 Compose v2 插件 - 一个可访问的 **LiteLLM** 端点（URL + API key）— 见下文 - `openssl`，用于一次性生成自签名 TLS 证书 - ~4 GB 可用 RAM ### 1. 启动LLM 代理（服务器 1） FragChain 通过兼容 OpenAI 的 API 与单个 LiteLLM 端点通信。将它指向你想要的任何 chat + embedding 模型——Anthropic、 OpenAI、Bedrock、Azure 或本地 Ollama。 推荐组合：**Claude Sonnet 用于 chat + 在 Ollama 上使用 nomic-embed-text 用于 embedding**（开源，768-d，与 Qdrant 完全匹配）。 ``` # Server 1 上的 litellm_config.yaml model_list: - model_name: claude-sonnet litellm_params: model: anthropic/claude-sonnet-4-6 api_key: os.environ/ANTHROPIC_API_KEY - model_name: nomic-embed-text litellm_params: model: ollama/nomic-embed-text api_base: http://ollama.internal:11434 ``` ``` ollama pull nomic-embed-text # one-time litellm --config litellm_config.yaml --port 4000 ``` 有关针对 OpenAI、Bedrock 和本地 Ollama 的实际示例，请参见 [`docs/litellm-setup.md`](docs/litellm-setup.md)。 ### 2. 配置 FragChain ``` cp .env.example .env # 至少设置： # APP_SECRET_KEY, JWT_SECRET (32+ 字节随机字符) # POSTGRES_PASSWORD, REDIS_PASSWORD, MINIO_ROOT_PASSWORD, QDRANT_API_KEY # LITELLM_BASE_URL, LITELLM_API_KEY # LITELLM_CHAT_MODEL, LITELLM_EMBEDDING_MODEL # ADMIN_PASSWORD (admin/admin 在启动时会被拒绝) ``` 生成高强度密钥： ``` python -c "import secrets; print(secrets.token_urlsafe(48))" ``` ### 3. 生成自签名 TLS 证书 nginx 仅提供 HTTPS 服务。 ``` mkdir -p nginx/certs openssl req -x509 -nodes -days 365 \ -newkey rsa:2048 \ -keyout nginx/certs/fragchain.key \ -out nginx/certs/fragchain.crt \ -subj "/CN=localhost" \ -addext "subjectAltName=DNS:localhost,IP:127.0.0.1" chmod 600 nginx/certs/fragchain.key ``` 对于生产环境，请替换为真实的证书。文件名必须保持为 `fragchain.crt` / `fragchain.key`。 ### 4. 启动堆栈 ``` docker compose up --build -d docker compose ps # wait for healthy ./setup.sh # seed prompts, profiles, presets, ATT&CK ./setup.sh --with-fixture # optionally also import Dirty Frag (CVE-2026-43284) ``` 种子脚本是幂等的，并会通过 LiteLLM 运行 ATT&CK 技术 embedding（约 700 行），因此在运行之前请确保你的 API 容器可以访问你的 embedding 模型。 ### 5. 验证 ``` curl -k https://localhost/api/v1/readyz # public curl -k https://localhost/api/v1/version | jq curl -k -X POST https://localhost/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"username":"admin","password":""}' | jq ``` 然后在浏览器中打开 （接受自签名证书 警告）。 ## 运维参考 ### 服务布局 | 服务 | 端口 (内部) | 通过 nginx 暴露 | 用途 | |---|---|---|---| | nginx | 80 / 443 | 是 — 仅有公共端口 | 终止 TLS，代理 API + UI | | fragchain-api | 8000 | `/api/`, `/ws/` | FastAPI | | fragchain-ui | 3000 | `/` | 通过 `nginxinc/nginx-unprivileged` 提供静态 SPA bundle | | fragchain-worker | — | 否 | Celery worker | | fragchain-beat | — | 否 | Celery beat 调度器 | | flower | 5555 | 否 | Celery 监控 (内部) | | postgres | 5432 | 否 | 应用数据库 | | redis | 6379 | 否 | Broker + 缓存 + 事件桥接 pub/sub | | minio | 9000 / 9001 | 否 | 对象存储 (LLM I/O + 制品) | | qdrant | 6333 | 否 | 向量存储 (服务器 3 本地) | 仅 nginx 会发布端口。其他所有服务都保留在内部 Docker 网络上。 ### 常用命令 ``` docker compose logs -f # tail all services docker compose exec fragchain-api alembic upgrade head docker compose exec fragchain-api python # API shell docker compose down -v # DEV ONLY — destroys all data ``` ### 本地前端开发 ``` cd frontend npm install npm run dev # Vite dev server on http://localhost:3000 npm run build # Production build → frontend/dist/ npm run lint # tsc --noEmit ``` ## 状态、安全、许可 **状态。** 1.0 之前版本，私人概念验证 / 参考项目 — 并非 已完成的生产安全产品。评估工作区和 三循环内容引擎是活跃的工作流；可检测性 分类器和制品路由器以咨询/兼容模式运行；推送驱动 流水线保留在代码树中，但处于休眠状态，等待更密集的 连接器生态系统。 **安全态势。** 在此仓库开放之前，完成了 F-001..F-008 公开前强化阶段——生产环境密钥验证、评估的 逐行授权、一次性 WebSocket 票据、在生产环境中禁用 `/docs` 和 `/openapi.json`、非 root 前端镜像、强化的 nginx + CSP。完整的安全态势和剩余风险记录在： - [`SECURITY.md`](SECURITY.md) — 报告流程 - [`docs/threat-model.md`](docs/threat-model.md) — 参与者、信任边界、STRIDE 表格 - [`docs/security-review-2026-05-20.md`](docs/security-review-2026-05-20.md) — 发现清单 + 方法论 - [`docs/remediation-log.md`](docs/remediation-log.md) — 包含测试覆盖率的每个发现的补救措施 **许可。** 引擎 + 连接器采用 Apache 2.0 许可。情报 公共数据采用 CC0 1.0 许可（一旦公共区发布）。 **披露。** 通过此仓库的 GitHub Security Advisories 报告安全 问题。请参见 [`SECURITY.md`](SECURITY.md)。 ## 项目布局 ``` fragchain/ Python package (API, workers, db, modules) frontend/ React + TypeScript + Vite + DarkOps v3 nginx/ Reverse-proxy config + TLS certs (not committed) chains/ Ground-truth attack chain fixtures prompts/ Seed prompts (loaded into DB by setup.sh) scripts/ Setup + seed scripts benchmarks/ Coverage benchmark ground-truth tests/ Pytest suite (unit + integration) docs/ ├── architecture/ Active design notes + ADRs ├── reviews/ Independent security/architecture reviews ├── superpowers/ In-flight plans ├── historical/ M1–M24 build log + original design corpus ├── images/ README screenshots ├── threat-model.md ├── security-review-2026-05-20.md ├── remediation-log.md └── public-readiness-checklist.md ``` 规范的 Python / 前端目录树请参见 [`CLAUDE.md`](CLAUDE.md) §17。

标签：威胁情报, 开发者工具, 搜索引擎查询, 检测规则生成, 漏洞分析, 路径探测, 逆向工具, 防御工程