lucashgrifoni/App-Suite-Modeling
GitHub: lucashgrifoni/App-Suite-Modeling
以版本化 YAML 模型为核心的威胁建模即代码工具包，支持多方法论分析、工程工件导入与 CI 集成，让威胁建模贴近代码仓库并可重复执行。
Stars: 0 | Forks: 0
# App Suite 建模
**面向软件交付团队的威胁建模即代码。**
在**版本化的 YAML 模型**中一次性定义架构，运行**多方法论分析**，并将输出接入**代码评审、流水线和审计工具**——无需在图表和电子表格中重复逻辑。
[](LICENSE)
[](https://www.python.org/)
[](https://nodejs.org/)
## 这是什么？
**App Suite 建模**是一个开源的**威胁建模**工具包，围绕**规范文档**（`.otm.yaml` / JSON）构建：包含组件、信任边界、数据流和资产。同一份文档支持：
- 用于自动化的 **CLI**（`otm`），
- 用于集成的 **REST API**（[FastAPI](https://fastapi.tiangolo.com/)），
- 以及用于向导化建模和可视化的 **Web UI**（React + Vite）。
**威胁引擎**会验证模型并生成**建议的威胁**、**结构化的可解释性说明**、**修复样式的待办事项提示**以及**导出内容**（Markdown、JSON、Mermaid、可选的 PDF）。您可以**导入**来自真实工程工件（OpenAPI、Kubernetes manifest、Terraform、Helm）的草稿，并对两个模型版本进行**差异对比**，以便进行 PR 样式的代码评审。
它面向那些希望让模型**贴近代码仓库**、**在 Git 中可评审**且**在 CI 中可重复执行**的 **AppSec**、**DevSecOps** 和**软件架构师**。
## 为什么会有这个项目
传统的威胁建模通常**无法**随着交付节奏进行**扩展**：
- 图表和电子表格会与真实系统发生**偏离**。
- 启发式逻辑存在于**单一**供应商工具或某位分析师的脑海中。
- 产出结果**难以进行版本控制**、难以进行差异对比，且在**Pull Request**或**工单**中使用十分笨拙。
本项目将威胁模型视为**类代码数据**：一套 schema，多种展现形式。您可以从终端或 API **验证**并**分析**同一个文件，将与证据友好的工件附加到评审中，并在架构发生变化时**重新运行**分析——无需在每个客户端中重新实现 STRIDE（或其他视角）。
## 核心能力
| 领域 | 您将获得 |
|------|----------------|
| **模型即代码** | 基于 [`otm_core_schema`](packages/core-schema) 验证的规范化 `.otm.yaml` / JSON；契合 Git 和代码评审。 |
| **多方法论引擎** | STRIDE、LINDDUN、PASTA、NIST Data-Centric、OCTAVE Allegro、CIA-DIE、**PLOT4ai**（AI/LLM 系统）。 |
| **可解释性** | 伴随启发式逻辑的结构化解释记录——而不仅仅是纯文本的项目符号。 |
| **语义差异对比** | 比较 models（及丰富比较），用于 **PR**、审计和发布门禁。 |
| **工件导入** | 从 **OpenAPI/Swagger**、**Kubernetes YAML**、**Terraform**、**Helm** 生成草稿种子（请务必检查结果）。 |
| **导出** | JSON、Markdown、Mermaid、bundles；在浏览器中为 Web UI 路径生成 **PDF**；通过可选附加组件提供高级报告路径。 |
| **CI / 自动化** | 通过 **CLI** 或 **REST** 实现相同的操作（`validate`、`analyze`、`export`、`diff`、模板、导入）。 |
详细信息：[方法论矩阵](docs/features/MULTI_ENGINE_ARCHITECTURE.md) · [工件导入](docs/features/ARTIFACT_IMPORT.md) · [导出器](docs/features/EXPORTERS.md) · [差异对比](docs/features/THREAT_MODEL_DIFF.md)
## 工作原理（概述）
```
Author model (.otm.yaml) → validate → analyze (methodology / auto-recommend)
→ review threats + explanations + backlog hints → export artifacts → diff versions
```
可选：**导入** OpenAPI/K8s/Terraform/Helm 以初始化草稿，然后在**向导**或编辑器中进行**增量式**完善，并通过 **API** 或 **CLI** 进行共享。
## 架构概览（简述）
| 层级 | 职责 |
|--------|------|
| **CLI** (`apps/cli`, Typer) | 本地和 CI 工作流：`otm validate`、`analyze`、`report`、`diff`、`import`、模板。 |
| **API** (`apps/api`, FastAPI) | 通过 HTTP 访问相同功能；OpenAPI 契约已在 CI 中检查。 |
| **Web UI** (`apps/web`) | 向导化流程、React Flow 图表、分析、导出，历史记录保存在**浏览器存储**中（默认不使用服务端会话数据库）。 |
| **威胁引擎** (`packages/threat-engine`) | 方法论视角、启发式逻辑、PLOT4ai 信号、评分——**不**依赖 FastAPI/React。 |
| **Schema** (`packages/core-schema`) | 有效 **OTM** 文档的唯一事实来源。 |
| **导出器 / 图表 / 扩展包** | `packages/exporters`、`diagram-engine`、`industry-packs`、`framework-mappings` 等。 |
更深度的说明：[MONOREPO.md](docs/MONOREPO.md) · [REPOSITORY_LAYOUT.md](docs/REPOSITORY_LAYOUT.md) · [ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)
## 快速开始
**前置条件**
- **Python 3.11+**
- 如果您要开发 Web UI，则需要 **Node 20+**（与 CI 匹配）
- 在 Linux 上，包含 PDF 处理栈的完整**开发环境**安装可能需要 **Cairo** 开发包（参见 [CONTRIBUTING.md](CONTRIBUTING.md)）
**安装（CLI + API + 开发工具，推荐贡献者使用）**
```
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -e ".[dev,cli,api]"
```
请使用 **`[dev,cli,api]`**，以便本地运行与 CI 保持一致（API 测试需要 `slowapi` 等）。最小化的仅 CLI 安装：`pip install -e ".[cli]"`。
**自动化引导**（在 `apps/web` 中进行 venv + 可编辑安装 + `npm install`）：
```
python scripts/setup_dev.py
```
**同时运行 API + Web**（设置完成后）：
```
python scripts/run_dev.py
```
- API: `http://127.0.0.1:8000` · OpenAPI UI: `/docs`
- Web: `http://127.0.0.1:5173`
**最小化 CLI 会话**
```
otm validate examples/minimal.otm.yaml
otm analyze examples/minimal.otm.yaml --methodology stride
otm report examples/minimal.otm.yaml -o REPORT.md
```
## 示例（真实场景）
**输入** — 摘自 [`examples/minimal.otm.yaml`](examples/minimal.otm.yaml)（包含用户、API、worker、DB 的订单 API）：
```
model:
schema_version: "1.1.0"
system_type: web_application
industry_sector: saas
metadata:
title: "Exemplo — API de pedidos"
summary: "Serviço REST com fila e banco."
components:
- id: user
name: "Usuário"
kind: user
in_trust_boundary: internet
- id: api
name: "API"
kind: process
in_trust_boundary: vpc
# … trust_boundaries, data_flows, assets (see full file in repo)
```
**命令**
```
otm validate examples/minimal.otm.yaml
otm analyze examples/minimal.otm.yaml --methodology stride
```
**输出（精简版）** — 分析总结了方法论、交叉点和启发式计数（确切数字取决于引擎版本）：
```
| Exemplo — API de pedidos |
| Framework refs: ISO/IEC 27001 … · NIST CSF … · OWASP … |
| Structural warnings: 0 |
| Methodology: stride |
| Cross-boundary flows: 1 |
| Base heuristics: N new · 0 already covered |
| Highest score (L×I): … |
```
`otm report … -o REPORT.md` 会生成一份 **Markdown 报告**，您可以将其附加到 PR 或证据包中。
## 截图
| 产品概述 | 分析输出 |
|---|---|
| [](docs/screenshots/home.png) | [](docs/screenshots/analysis.png) |
| 首页：主视觉 + 主要 CTA（新模型、导入、模板）。 | 方法论选择、模型指标，以及带有“可能性 × 影响”评分的建议威胁。 |
其他截图（向导步骤、导出/PDF 操作以及 CLI 会话）将在制作完成后发布在 [`docs/screenshots/`](docs/screenshots/README.md) 下。构图指南：[`docs/features/SCREENSHOT_GUIDE.md`](docs/features/SCREENSHOT_GUIDE.md)。
## 使用场景
- **AppSec 计划** — 可重复的模型、用于评审的导出内容、可追溯的解释。
- **DevSecOps** — 在流水线中使用 `otm`；为工单和门禁提供 JSON/Markdown 工件。
- **架构与设计评审** — 跨架构版本进行语义**差异对比**。
- **PR 规范** — 附加或基于团队修改的同一文件生成工件。
- **审计** — 结构化输出和方法论对齐（参见框架映射文档）。
- **AI/LLM 系统** — 用于模型/prompt/RAG/agent 问题的 PLOT4ai 视角。
## 成熟度与局限性
**明确说明本项目的定位：** 它**不是**一个具备内置组织账户、集中式模型历史记录或特定云端托管的全功能**多租户 SaaS**。
| 主题 | 预期情况 |
|--------|-------------|
| **核心 Schema 与引擎** | **稳定**且经过充分测试；**STRIDE** 是最成熟的视角；其他视角则各有不同（参见[发布范围](docs/internal/decisions/RELEASE_SCOPE_FREEZE.md)）。 |
| **CLI / OpenAPI** | 面向自动化的**稳定**契约；破坏性变更应进行版本控制并记录在 [CHANGELOG](CHANGELOG.md) 中。 |
| **Web UI** | **成熟的 MVP**：包含完整流程 + 图表 + 导出；默认情况下**持久化是以浏览器/会话为中心的**——默认技术栈中没有服务端用户数据库。 |
| **生产环境中的 API** | 提供可选的 **API 密钥**和**速率限制**；**面向互联网的**部署仍需您自行配置**网关、身份验证和系统加固**（[部署说明](docs/architecture/DEPLOYMENT_INVARIANTS.md)）。 |
| **导入** | 生成的是**草稿**——必须由人工来核对信任边界和敏感数据。 |
| **分析** | **启发式/辅助性**——并非对完整性保证或形式化证明。 |
完整细节：[KNOWN_LIMITATIONS.md](docs/KNOWN_LIMITATIONS.md)
测试套件（参考）：安装 `.[dev,cli,api]` 后，CI 中包含 **400+** 个 Python 测试——参见 [CI 工作流](.github/workflows/github-ci-cd.yml)。
## 项目结构（指引）
- 布局与打包：[docs/MONOREPO.md](docs/MONOREPO.md)
- 各层与 `otm_*` 包：[docs/REPOSITORY_LAYOUT.md](docs/REPOSITORY_LAYOUT.md)
- 文档组织方式：[docs/DOCUMENTATION_STRUCTURE.md](docs/DOCUMENTATION_STRUCTURE.md)
## 文档
| 文档 | 用途 |
|-----|---------|
| [docs/README.md](docs/README.md) | 文档中心与新手指南（包含面向 PT-BR 的指南） |
| [docs/features/CLI.md](docs/features/CLI.md) | CLI 参考 |
| [docs/features/API.md](docs/features/API.md) | REST API 与可选边界 |
| [docs/features/UI.md](docs/features/UI.md) | Web 应用流程 |
| [docs/features/MULTI_ENGINE_ARCHITECTURE.md](docs/features/MULTI_ENGINE_ARCHITECTURE.md) | 方法论矩阵 |
| [docs/features/CHOOSE_METHODOLOGY.md](docs/features/CHOOSE_METHODOLOGY.md) | 选择视角 |
| [docs/features/PLOT4AI_AI_SYSTEM.md](docs/features/PLOT4AI_AI_SYSTEM.md) | PLOT4ai / AI 建模 |
| [docs/features/ARTIFACT_IMPORT.md](docs/features/ARTIFACT_IMPORT.md) | 导入 OpenAPI、K8s、Terraform、Helm |
| [docs/features/THREAT_MODEL_DIFF.md](docs/features/THREAT_MODEL_DIFF.md) | 模型差异对比 |
| [docs/features/EXPORTERS.md](docs/features/EXPORTERS.md) | 导出格式 |
| [docs/CI_AND_SECURITY_EVIDENCE.md](docs/CI_AND_SECURITY_EVIDENCE.md) | 安全工具与 CI 门禁 |
| [docs/features/PRODUCT_POSITIONING.md](docs/features/PRODUCT_POSITIONING.md) | 定位叙述 |
| [docs/features/BRANDING.md](docs/features/BRANDING.md) | 面向维护者的品牌标识、色调和视觉系统 |
| [docs/PROJECT_DEEP_DIVE.md](docs/PROJECT_DEEP_DIVE.md) | 深度的产品与工程概述 |
发布评估（面向维护者）：[FINAL_GO_NO_GO_RELEASE_ASSESSMENT.md](docs/internal/reports/FINAL_GO_NO_GO_RELEASE_ASSESSMENT.md)
## 安全
请**不要**提交包含可利用漏洞细节的公开 issue。请使用 [SECURITY.md](SECURITY.md) 中的流程（例如 GitHub Security Advisories）。
## 版本控制
包版本记录在 `pyproject.toml` 中（目前为 **7.6.4**，与 `apps/web/package.json` 保持一致）。标签、RC 版本以及它们与历史里程碑（例如已记录的 `v0.1.0` 范围）的关系在 [docs/VERSIONING_AND_TAGS.md](docs/VERSIONING_AND_TAGS.md) 中进行了说明。发布历史：[CHANGELOG.md](CHANGELOG.md)。
## 许可证
[MIT](LICENSE)
## 商标
*App Suite Modeling* 是本项目名称。STRIDE、LINDDUN、PASTA、NIST、PLOT4ai 及其他名称归其各自所有者所有，此处引用它们是为了描述**支持的视角**，而非表示归属关系。
标签：AV绕过, DevSecOps, FastAPI, MITM代理, Python, React, Syscalls, 上游代理, 威胁建模, 安全工程, 无后门, 网络测绘, 逆向工具