rootabhi1/ThreatGuard

# 🛡 ThreatGuard — 自动化威胁建模 [](https://github.com/rootabhi1/ThreatGuard/actions/workflows/ci.yml) [](https://github.com/rootabhi1/ThreatGuard/actions/workflows/codeql.yml) [](https://rootabhi1.github.io/ThreatGuard/) [](https://python.org) [](https://fastapi.tiangolo.com) [](LICENSE) ## 项目存在的意义 威胁建模是团队在安全方面能做的最具杠杆效应的事情之一 —— 但也是最常被跳过的环节。如果纯手工进行，它不仅速度缓慢、不同审查者之间标准不一， 而且很容易被推迟到“以后再说”。结果就是，许多系统在交付时， 根本没有人系统性地问过*这里可能会出什么问题？* ThreatGuard 的存在就是为了降低这一门槛。它接收一段关于系统的描述—— 无论是输入的文字、绘制的草图，还是上传的架构图—— 并在几分钟内将其转化为结构化、有方法论支撑的威胁模型，提供一致的评分和明确的缓解措施。 它为工程师提供了一个可供审查的高质量初稿，而不是面对一张白纸，从而让威胁建模真正落地。 它是安全工程师的战力倍增器，而不是替代他们专业判断的工具。 ## 设计原则 - **AI 辅助——不替代安全工程师。** 确定性的规则引擎是核心骨干；AI 是可选的辅助增强层。 - **必须经过人工验证。** 每一次输出都是供人工审查的草稿，绝非最终签批。 - **默认安全。** 每个数据 endpoint 均设有身份验证，采用安全的默认配置（CORS、 headers），并附带测试予以验证。 - **框架无关。** 既可基于规则离线运行，也能接入 Claude 或任何兼容 OpenAI 的模型—— 包括本地模型。 - **可解释的输出。** 每个威胁都能映射到具体的方法论、CWE、CVSS 评分、ATT&CK/合规参考， 并提供具体的缓解措施——拒绝黑盒。 ## 功能介绍 ThreatGuard 接收一段关于系统的描述——无论是输入的文字、在画布上绘制的草图，还是**上传的架构图**——并将其转化为结构化的威胁模型：识别出的威胁、严重程度和 CVSS 评分、CWE 和 MITRE ATT&CK 参考、映射的合规控制措施、带有信任边界的数据流图，以及可导出的报告。 - **三种威胁建模方法论** —— STRIDE、PASTA 和 LINDDUN —— 由确定性的规则引擎应用（无需 API key），外加针对每个威胁的 **DREAD** 风险评分，以及对发现问题的 **OWASP Top 10** 参考映射。（DREAD 是一种评分模型，而 OWASP Top 10 是一种意识参考——两者都不是威胁建模方法论，因此都不能作为方法论被选择。） - **丰富的评分** —— CVSS 3.1 & 4.0、CWE、MITRE ATT&CK 技术/战术，以及 SOC 2 / ISO 27001 / PCI-DSS 控制映射。 - **信任边界与 DFD** —— 在未定义边界时自动推断边界，对跨边界的数据流进行标记，并渲染带有标签的数据流图。 - **架构图上传** —— 拖拽放入 PNG/JPEG/WebP 架构图；借助具备视觉能力的 LLM，它会被转化为系统模型；否则，您也将获得一个可编辑的起点。 - **可选的 LLM 增强** —— 通过 **Claude** 或任何兼容 **OpenAI** 的 endpoint（OpenAI、Azure、Ollama、vLLM 等），实现 AI 修复建议生成、图表提取和更丰富的叙述。如果没有配置 key，所有功能依然可以在纯规则模式下运行。 - **团队工作流** —— Release → Feature → Threat Model 层级结构，基于角色的访问控制（user / management / admin），针对单个威胁的状态跟踪，跨 Release 的差异比对，只读分享链接，自定义规则，以及审计日志。 - **报告** —— HTML、PDF、Markdown、CSV 风险登记册，以及执行摘要。 ## 示例输出 完整的生成报告已签入至 **[`docs/sample-report.html`](docs/sample-report.html)** —— 针对某零售平台示例，涵盖了横跨 STRIDE、LINDDUN 和 PASTA 的 209 个威胁，每个威胁均包含 DREAD 评分、CVSS、CWE、MITRE ATT&CK 和 OWASP Top 10 参考信息，以及合规性映射和带有自动推断信任边界的数据流图。 | Dashboard | 威胁画布 | 分析与数据流图 | |---|---|---| |  |  |  | 开箱即用的系统定义示例和生成报告位于 [`examples/`](examples/) —— 可以从 `examples/systems/simple-api.json` 开始尝试。 ## 本地运行 **一条命令** (Unix/macOS) —— 创建 virtualenv、安装依赖， 并使用安全的开发默认配置启动应用： ``` git clone https://github.com/rootabhi1/ThreatGuard cd ThreatGuard make dev # → http://localhost:8000 (or: cd threat-modeler && ./run.sh) ``` 同时也支持 `make setup` / `make test` / `make lint`。更倾向于手动操作（或者在 Windows 上运行）？以下是手动步骤： ``` # Clone git clone https://github.com/rootabhi1/ThreatGuard cd ThreatGuard/threat-modeler # 虚拟环境 + dependencies python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt # 所需环境（完整列表请参见 ../.env.example） export INITIAL_ADMIN_EMAIL=admin@example.com export INITIAL_ADMIN_PASSWORD='ChangeMe123!' export JWT_SECRET=$(python3 -c "import secrets; print(secrets.token_urlsafe(48))") # （可选）启用 LLM —— 选择一个，或者跳过以使用 rules-only mode export ANTHROPIC_API_KEY=sk-ant-... # Claude # — 或任何兼容 OpenAI 的 endpoint — # export OPENAI_API_KEY=... OPENAI_MODEL=gpt-4o OPENAI_BASE_URL=https://api.openai.com/v1 # Start python app.py # http://localhost:8000 # auto-reload: uvicorn app:app --reload --port 8000 ``` 交互式 API 文档位于 `/docs`。 ### Docker ``` cp .env.example .env # then edit .env (JWT_SECRET + admin creds are required) docker compose up --build # serves on http://localhost:8000 ``` 如果未设置 `JWT_SECRET`、`INITIAL_ADMIN_EMAIL` 或 `INITIAL_ADMIN_PASSWORD`，compose 文件会快速失败，因此容器永远不会以不安全的默认配置启动。 ## 配置 所有设置均为环境变量；详见 [`.env.example`](.env.example)。核心配置如下： | 变量 | 必填 | 用途 | |---|---|---| | `JWT_SECRET` | ✅ | 签发 access/refresh token。请使用一长串随机字符串。 | | `INITIAL_ADMIN_EMAIL` / `INITIAL_ADMIN_PASSWORD` | ✅ | 首次运行时生成的管理员账号。 | | `LLM_PROVIDER` | — | `anthropic` 或 `openai`；根据设置了哪个 key 自动检测。 | | `ANTHROPIC_API_KEY` / `ANTHROPIC_MODEL` | — | 启用 Claude 增强。 | | `OPENAI_API_KEY` / `OPENAI_MODEL` / `OPENAI_BASE_URL` | — | 启用任何兼容 OpenAI 的模型（包括自托管模型）。 | | `CORS_ORIGINS` | — | 在生产环境中限制允许的来源（默认为 `*`）。 | | `RATE_LIMIT_ENABLED` | — | 基于单 IP 的登录/刷新速率限制（默认开启）。 | 若未配置任何 LLM key ⇒ 应用将以**纯规则**模式运行，并启用完整的方法论引擎。 ## 安全性 - 采用 JWT 身份验证，包含 refresh-token **轮换**（重用已轮换的 token 会被拒绝）以及注销撤销机制。 - 密码使用 bcrypt 哈希处理；登录失败时的**账号锁定**；基于单 IP 的速率限制。 - **默认安全** —— 每个数据 endpoint 都需要会话验证；强制执行角色权限和基于资源的所有权控制（用户无法读取其他用户的模型）。 - 安全 headers（`X-Frame-Options`、`X-Content-Type-Options`、`Referrer-Policy`，以及在 HTTPS 下的 HSTS）；报告是 XSS 安全的（用户提供的名称会被转义，包括内嵌 JSON 中的内容）。 - 全面采用参数化 SQL；针对身份验证和访问决策记录审计日志。 完整的逐项控制设计详见 [`docs/security/SECURITY_ARCHITECTURE.md`](docs/security/SECURITY_ARCHITECTURE.md)， 安全评估（包含发现并修复的问题）详见 [`docs/audit/`](docs/audit/)。请按照 [SECURITY.md](SECURITY.md) 私下报告漏洞。 ## 测试 测试套件在进程内针对真实的应用实例和 SQLite 运行 —— 无需网络。 ``` cd threat-modeler export JWT_SECRET=test INITIAL_ADMIN_EMAIL=admin@corp.io INITIAL_ADMIN_PASSWORD='AdminPass123!' RATE_LIMIT_ENABLED=0 for t in tests/test_*.py; do python3 "$t"; done ``` `tests/test_full_product.py` 是针对整个产品的全面扫描（涵盖 17 个领域的 119 项检查：身份验证、RBAC/IDOR、CRUD、引擎、信任边界/DFD、上传、多 LLM、报告、分享、差异比对、状态、安全，以及一项**默认安全扫描**——以匿名方式调用所有路由以确认无数据泄露）。详情请见 [`TESTING.md`](TESTING.md)。 ## 项目结构 ``` threat-modeler/ app.py FastAPI app — routes, auth wiring, middleware auth/ JWT, dependencies, RBAC permission registry db/ SQLite connection + domain queries threat_engine/ methodologies, scoring, DFD, trust boundaries, diagram extraction, LLM provider layer, reports templates/ static/ server-rendered UI + canvas assets tests/ test suite (7 files) ``` ## 文档 | 文档 | 涵盖内容 | |----------|----------------| | [ARCHITECTURE.md](ARCHITECTURE.md) | 组件、数据流、信任边界、LLM 流程（含图表） | | [CONTRIBUTING.md](CONTRIBUTING.md) | 面向首次贡献者的环境设置、测试、规范与 PR 流程 | | [FAQ.md](FAQ.md) | 为什么使用 AI、支持/本地的 LLM、准确性、数据处理、自托管 | | [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) | 坦诚说明该工具能做和不能做的事 | | [SECURITY.md](SECURITY.md) | 漏洞披露、安全态势、安全加固 | | [docs/security/SECURITY_ARCHITECTURE.md](docs/security/SECURITY_ARCHITECTURE.md) | 逐项控制的安全设计（边界、LLM 流程、prompt 生命周期、威胁假设） | | [SUPPORT.md](SUPPORT.md) | 在哪里提问和报告问题 | | [ROADMAP.md](ROADMAP.md) | 发展方向和计划工作 | | [CHANGELOG.md](CHANGELOG.md) | 重大更新 | | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | 社区准则 | | [docs/audit/](docs/audit/) | 工程审计记录（仓库健康度、安全性） | | [docs/project/](docs/project/) | 工程笔记本 —— 愿景、决策日志、未来构想 | ## 贡献 欢迎您的贡献。请从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始了解环境设置、 规范和 PR 工作流程，并查找带有 [`good first issue`](https://github.com/rootabhi1/ThreatGuard/issues?q=is%3Aopen+label%3A%22good+first+issue%22) 标签的 issue。 请将问题发布在 [讨论区](https://github.com/rootabhi1/ThreatGuard/discussions)； 请按照 [SECURITY.md](SECURITY.md) 的指引私下报告安全问题， 切勿在公开的 issue 中提交。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：AV绕过, FastAPI, LLM集成, Python, 人工智能, 反取证, 威胁建模, 安全评估, 无后门, 用户模式Hook绕过, 请求拦截, 逆向工具