darkdoomrag3/Threat-model-generator

# threatmodel-gen [](https://github.com/darkdoomrag3/Threat-model-generator/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) [](CONTRIBUTING.md) 输入某个功能的用户故事/验收标准（以及可选的实现它们的 repo），即可获得一份可版本化的 **STRIDE 威胁建模文档**：组件、信任边界、每个 STRIDE 类别的威胁，以及可以直接放入你的 backlog 的 Given/When/Then **安全验收标准**。 它的设计初衷是与其所建模的代码一起提交，就像任何其他设计文档一样——每个功能对应一个 `THREAT_MODEL.md`，在与该功能相同的 PR 中进行审查和更新。 ## 功能特性 - **基于 Repo，而非闭门造车** —— 扫描实际的代码库以寻找入口点、数据存储、认证逻辑和第三方集成，而不是要求你手动描述架构。 - **离线可用** —— 规则脚手架无需任何 API 调用即可生成可用的报告；通过 `ANTHROPIC_API_KEY` 可以选择性地开启 Claude 增强。 - **对 CI 友好** —— 使用 `--json` 获取机器可读的输出，使用 `--fail-on-gaps` 根据 STRIDE 覆盖率的缺口进行拦截。 - **像代码一样进行版本控制** —— 每个功能生成一个 Markdown 文件，可 diff，可在 PR 中审查。 ## 输出示例

由 examples/example_story.md 生成（规则脚手架模式，无 API key）

``` flowchart LR Client["Client"] Service["Service"] Client -->|"Public network edge"| Service ``` | ID | Component | Threat | |---|---|---| | S-1 | Service | 账户恢复流程可能被滥用于接管其他用户的账户 | | D-1 | Service | 面向公众的 endpoint 没有速率限制或节流 | 亲自运行试试：`threatmodel gen examples/example_story.md --no-llm -o /tmp/THREAT_MODEL.md`

## 设计初衷 大多数威胁建模工具要么是重量级的绘图应用（Threat Dragon、IriusRisk），要么是“威胁建模即代码”框架，要求你使用 DSL 手动描述你的架构（pytm、Threagile）。这款工具从大多数团队已有的产物——用户故事和 ACs——出发，如果你为它指定了 repo，它就会将模型建立在真实证据（路由、数据存储、认证代码、第三方集成）的基础之上，而不是对系统进行凭空的描述。 ## 工作原理 1. **规则脚手架** —— 对你的故事进行一次确定性的遍历（基于关键字规则），如果指定了 `--repo`，还会进行轻量级的静态扫描（`src/threatmodel/repo_scan.py`），以寻找入口点、数据存储、认证逻辑、外部集成和包含密钥的配置。这一步会构建出初步的组件列表、信任边界以及预设的 STRIDE 威胁——单凭这一步就足以离线生成一份可用的（尽管可能比较通用的）报告。 2. **LLM 填充** —— 如果设置了 `ANTHROPIC_API_KEY`，脚手架将被传递给 Claude，它会为每个威胁编写具体的描述/影响/可能性/缓解措施，补充规则可能遗漏的内容，并生成安全验收标准。模型被要求*完善*脚手架，而不是凭空捏造一个新的——它的依据与你在 `--no-llm` 模式下看到的证据相同。 3. **Markdown 报告** —— 生成一个单一的 `THREAT_MODEL.md`，其中包含 mermaid 信任边界图、组件表格、按类别划分的 STRIDE 威胁表格以及安全 ACs。 ## 安装 ``` pip install -e ".[llm]" # editable install with the anthropic SDK for enrichment # 或者，对于没有额外依赖的 rule-scaffold-only 模式： pip install -e . ``` ## 用法 ``` export ANTHROPIC_API_KEY=sk-ant-... # optional — omit for rule-scaffold-only mode threatmodel gen stories.md --repo ./my-app -o THREAT_MODEL.md ``` ``` usage: threatmodel gen [-h] [--repo REPO] [-o OUTPUT] [--title TITLE] [--no-llm] [--model MODEL] stories positional arguments: stories path to a text/markdown file of user stories and ACs options: --repo REPO path to a repo to scan for entry points, data stores, auth, and integrations -o, --output OUTPUT output file path (default: THREAT_MODEL.md) --json JSON_OUTPUT also write the threat model as machine-readable JSON to this path (components, trust boundaries, threats, security ACs, STRIDE coverage counts) --title TITLE title for the document (default: stories filename) --no-llm skip the Claude enrichment step even if ANTHROPIC_API_KEY is set --model MODEL Claude model to use for enrichment (default: claude-sonnet-5, override with THREATMODEL_LLM_MODEL) --fail-on-gaps exit with status 2 if any STRIDE category has zero threats — use as a CI gate to catch an incomplete review (e.g. nobody considered Denial of Service at all). The report is still written either way. ``` ### CI 覆盖率门禁 在 CI 中使用 `--fail-on-gaps` 参数运行 `threatmodel gen`，如果生成的模型中存在某个 STRIDE 类别完全没有威胁，则使构建失败——这是一个低成本的信号，表明某个类别从未被考虑过，而不是考虑后发现属于低风险： ``` threatmodel gen stories.md --repo . --json THREAT_MODEL.json --fail-on-gaps ``` 针对内置示例尝试运行一下： ``` threatmodel gen examples/example_story.md --no-llm -o /tmp/THREAT_MODEL.md ``` ## 项目布局 ``` src/threatmodel/ repo_scan.py # static-scan heuristics: entry points, data stores, auth, integrations, secrets stride_rules.py # deterministic scaffold: components, trust boundaries, seeded threats llm.py # optional Claude enrichment (structured tool-use output) report.py # renders the ThreatModel into Markdown + mermaid serialize.py # JSON export + STRIDE coverage checks (used by --json / --fail-on-gaps) cli.py # `threatmodel gen ...` models.py # shared dataclasses ``` ## 开发 ``` pip install -e ".[dev,llm]" pytest ``` ## 路线图 - [ ] Diff 模式：针对更新后的 repo/story 重新运行，并高亮显示新增/已解决的威胁 - [ ] 提供对更多框架感知的入口点检测（目前基于正则表达式，而不是 AST） - [ ] 除了 Markdown/JSON 之外，支持 SARIF 导出 - [ ] 支持使用 OpenAI/本地模型作为 Claude 的替代方案 ## 许可证 MIT —— 详情请参阅 [LICENSE](LICENSE)。

标签：Python, STRIDE, 威胁建模, 安全测试, 攻击性安全, 无后门, 网络调试, 自动化, 逆向工具