bertdavies/Diamond-Modeller
GitHub: bertdavies/Diamond-Modeller
一款交互式的网络威胁情报钻石模型建模与可视化工作台，支持 AI 代理编排和 OpenAI 驱动的归因分析。
Stars: 0 | Forks: 0
# Diamond Modeller v1.1
**作者：** Albert Davies
**许可协议：** CC BY-NC-SA 4.0 — 对 CTI 社区免费，商业使用需获得许可
Diamond Modeller 是一款交互式 Web 应用程序，用于构建、可视化和分析网络威胁情报 (CTI) 的 [Diamond Model](https://www.activeresponse.org/wp-content/uploads/2013/07/diamond.pdf) 图谱。
## 为什么选择 Diamond Modeller？
Diamond Modeller 的真正威力在于它是一个**代理编排系统 (agentic orchestration systems) 的后端**。包含的 **Agent Skill** (`diamond-modeller-skill/`) 通过 REST API 赋予任何 AI 代理对 Diamond Model 图谱的完整 CRUD 访问权限。这意味着自主代理可以摄取威胁情报报告，将其分解为映射到 Kill Chain 阶段或 MITRE ATT&CK 战术的 Diamond Model，构建连接图谱，并生成归属假设 —— 所有这些都是程序化、大规模且无需人工交互完成的。
也就是说，Diamond Modeller 设计为在三个层面上工作：
### 1. 代理集成（推荐）
将包含的 Skill 安装到您的编排框架中。AI 代理随后可以：
- 将原始威胁情报转换为结构化的 Diamond Model
- 为每个 Kill Chain 阶段（`KC1`–`KC7`）或 MITRE ATT&CK 战术（`TA0001`–`TA0043`）创建一个 Diamond
- 用指标和丰富的上下文注释填充所有四个顶点
- 自动连接共享指标的 Diamond
- 以 JSON 格式导出/导入整个分析
- 触发由 OpenAI 驱动的归属假设生成
有关完整说明，请参阅 `diamond-modeller-skill/SKILL.md`，Python 客户端请参阅 `diamond-modeller-skill/scripts/diamond_modeller.py`。
### 2. 带 OpenAI 归属的独立模式
将 Diamond Modeller 作为独立的 Web 应用程序运行。通过 UI 手动构建图谱，然后点击 **Generate hypotheses** 将完整的 Diamond 集发送到由 OpenAI 驱动的分析管道。它会生成一份可下载的 PDF 报告，其中包含排名的归属假设、置信度水平和支持证据。需要 OpenAI API 密钥（通过 UI 或 `.env` 设置）。
### 3. 工作台模式（无需 API 密钥）
将 Diamond Modeller 纯粹用作 Diamond 建模工作台。创建 Diamond，用指标填充顶点，并让应用程序在指标重叠处自动生成链接。将您的分析导出为 JSON 或 PNG。不需要 OpenAI 密钥 —— 归属分析完全是可选的。
## 工作原理
每个 **diamond** 代表一个入侵活动单元，具有四个顶点：
| 顶点 | 捕获内容 |
|---|---|
| **Adversary** | 威胁行为者名称、别名、动机 |
| **Victimology** | 目标、组织、行业、地理位置 |
| **Capability** | 工具、恶意软件家族、TTP |
| **Infrastructure** | IP、域名、电子邮件地址、C2 服务器 |
Diamond 被放置在交互式 Cytoscape 图谱上。当两个 Diamond 共享一个或多个指标时，应用程序会自动在它们之间绘制标记边缘，使重叠立即可见。
## 示例：使用 Kill Chain 阶段对入侵进行建模
一种常见的模式是为每个 Kill Chain 阶段创建一个 Diamond，并用在该阶段观察到的指标填充每个 Diamond：
| Diamond (标签) | Adversary | Capability | Infrastructure | Victimology |
|---|---|---|---|---|
| **KC1 UNC4736** | UNC4736 | LinkedIn 抓取, Google dorking | cdn-update[.]com | ACME Corp |
| **KC3 UNC4736** | UNC4736 | 鱼叉式钓鱼, 宏 DOCX | cdn-update[.]com, 198.51.100.12 | ACME Corp |
| **KC4 UNC4736** | UNC4736 | CVE-2024-1234, PowerShell 释放器 | 198.51.100.12 | ACME Corp |
| **KC6 UNC4736** | UNC4736 | Cobalt Strike 信标 | 203.0.113.45, cdn-update[.]com | ACME Corp |
| **KC7 UNC4736** | UNC4736 | Mimikatz, HTTPS 渗出 | 203.0.113.45, exfil-drop[.]net | ACME Corp |
由于 Diamond 共享指标（例如 `cdn-update[.]com`, `198.51.100.12`, `UNC4736`, `ACME Corp`），图谱会自动链接它们，生成连接的 Kill Chain 可视化。
同样的方法也适用于 MITRE ATT&CK 战术 —— 将 Diamond 标记为 `TA0043 UNC4736`, `TA0001 UNC4736` 等。
### 生成归属假设
填充 Diamond 后，在控制面板中点击 **Generate hypotheses**。这会将完整的 Diamond 集发送到由 OpenAI 驱动的分析管道，该管道将：
1. 聚合所有 Diamond 的指标。
2. 交叉引用已知的威胁行为者档案、TTP 和基础设施模式。
3. 生成一份 PDF 报告，其中包含排名的归属假设、置信度水平和支持证据。
PDF 将直接在浏览器中下载。
## 功能特性
- **创建和编辑 Diamond**，具有四个顶点（对手、受害者特征、能力、基础设施）
- **自动链接生成**，当 Diamond 共享指标时
- **交互式图谱**（平移、缩放、拖动），由 Cytoscape.js 驱动
- **智能布局** —— Kill Chain (`KC1`–`KC7`) 和 MITRE ATT&CK (`TA0001`–`TA0043`) Diamond 按阶段/战术顺序从上到下自动排列；重叠计数影响间距
- **共享指标徽章** —— Diamond 之间的边缘汇总为可点击的徽章；点击以展开共享指标的完整列表；可以同时展开多个徽章
- **彩色边缘高亮** —— 展开徽章会使用链接 Diamond 的颜色（不同时混合）为连接线着色；徽章和列表边框颜色匹配
- **隐藏/显示 Diamond** —— 从现有 Diamond 列表中切换单个 Diamond 的可见性，而无需删除它们
- **图谱注释** —— 图谱画布上的便签，用于注释
- **深色模式** 切换，位于导航栏中
- **导出 PNG** —— 图谱的高分辨率截图，包括所有覆盖层（徽章、展开列表、注释）
- **导出/导入图谱** —— 以 JSON 文件形式分享分析
- **生成假设** —— 由 OpenAI 驱动的归属分析，可下载 PDF
- **Agent Skill** —— 用于代理编排的完整 REST API 客户端
- **关于页面** —— 在浏览器中渲染此 README
## Agent Skill
`diamond-modeller-skill/` 目录包含 AI 代理与 Diamond Modeller 交互所需的一切：
```
diamond-modeller-skill/
├── SKILL.md # Skill definition and usage instructions
├── scripts/
│ └── diamond_modeller.py # Python client (DiamondModellerClient)
└── references/
└── API_REFERENCE.md # Full REST API endpoint reference
```
Python 客户端为 Kill Chain (`create_kill_chain_diamonds`) 和 MITRE ATT&CK (`create_mitre_tactic_diamonds`) 工作流提供了专门的方法，并内置了阶段/战术代码映射和标签格式化。
## UI 指南
### 导航栏
| 元素 | 描述 |
|---|---|
| **Diamond Modeller** | 应用程序标题（左侧） |
| **About** | 打开渲染为 HTML 的此 README |
| **Moon/Sun icon** | 切换深色模式 |
### 左侧面板（滑出式抽屉）
| 部分 | 描述 |
|---|---|
| **Create New Diamond** | 表单：标签、注释、颜色和可折叠的顶点部分。每个顶点每行接受一个指标。 |
| **Existing Diamonds** | 已保存 Diamond 的列表。点击编辑，弹出查看详情，X 删除。 |
| **Create New Note** | 向图谱画布添加可拖动的便签。 |
| **Controls** | 见下文。 |
### 控制项
| 按钮 | 动作 |
|---|---|
| **Set OpenAI API Key** | 在当前会话中将密钥存储在 `.env` 中 |
| **Export PNG** | 下载图谱的高分辨率 PNG |
| **Export graph** | 下载完整的 JSON 分析 |
| **Import graph** | 上传之前导出的 JSON，替换当前数据 |
| **Generate hypotheses** | 运行 OpenAI 归属分析并下载 PDF 报告 |
| **Clear all** | 删除所有 Diamond、边缘和图谱注释 |
### 现有 Diamond
| 图标 | 动作 |
|---|---|
| **Eye** | 在图谱上隐藏/显示 Diamond（切换可见性而不删除） |
| **Pop-out** | 在弹出窗口中查看完整的 Diamond 详情 |
| **X** | 永久删除该 Diamond |
### 图谱交互
- **点击 Diamond** —— 打开一个详细信息弹出窗口，按顶点分组显示指标
- **悬停在 Diamond 上** —— 显示“Click to expand”（点击展开）工具提示
- **点击共享指标徽章** —— 展开以显示两个 Diamond 之间所有共享的指标；连接线变成彩色以匹配链接的 Diamond
- **点击另一个徽章** —— 独立展开（以前的徽章保持打开状态）
- **再次点击展开的徽章** —— 折叠它并重置线条颜色
- **拖动 Diamond** —— 在画布上重新定位它
- **平移** —— 点击并拖动背景
- **缩放** —— 滚动滚轮，或使用 +/- 按钮
## 示例
项目中附带了一个 Scattered Spider Kill Chain 分析示例，位于 `examples/scattered_spider.json`。通过 UI（Controls -> Import graph）或 API 导入它，可以看到涵盖侦察、交付、安装和行动目标的四个链接 Diamond。
## 快速开始
```
git clone https://github.com/bertdavies/Diamond-Modeller.git
cd diamond-modeller
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # Optional: add your OpenAI key for attribution
python run.py
```
然后打开 http://localhost:8000。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `DATABASE_URL` | 否 | `sqlite:///./diamond_modeller.db` | SQLite 连接字符串 |
| `OPENAI_API_KEY` | 仅用于假设生成 | — | 通过 `.env` 或 UI 设置 (Controls -> Set OpenAI API Key) |
## REST API 参考
### 页面
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/` | 重定向到 `/graph/` |
| `GET` | `/graph/` | 图谱 UI 页面 |
| `GET` | `/about` | 渲染为 HTML 的 README |
### Diamond
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/create-diamond` | 创建一个 Diamond (表单数据: label, notes, colour, indicators) |
| `GET` | `/diamonds/` | 列出/搜索 Diamond (可选 `?query=`) |
| `GET` | `/diamonds/{id}` | Diamond 摘要 JSON |
| `GET` | `/diamonds/{id}/details` | 完整的 Diamond 详情 JSON (包括每个顶点的指标) |
| `GET` | `/diamonds/{id}/edit` | 预填充用于编辑的 Diamond 数据 |
| `PUT` | `/diamonds/{id}` | 更新一个 Diamond (表单数据) |
| `DELETE` | `/diamonds/{id}` | 删除单个 Diamond |
| `DELETE` | `/diamonds/remove-all/` | 删除所有 Diamond、顶点、指标和边缘 |
### 图谱与链接
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/graph` | 用于 Cytoscape 的图谱 JSON (`{ elements: { nodes, edges } }`) |
| `POST` | `/links/` | 创建手动链接 (`{ src_diamond_id, dst_diamond_id, reason }`) |
| `POST` | `/regenerate-links` | 从指标重叠重建所有自动链接 |
### 导出/导入
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/api/export-analysis` | 将完整分析导出为 JSON |
| `POST` | `/api/import-analysis` | 从 JSON 导入分析 (替换当前数据) |
### 归属
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/conduct-attribution` | 运行假设生成。成功时返回 PDF，失败时返回 JSON。 |
### 设置
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/api/settings/openai-api-key` | 设置 OpenAI API 密钥 (`{ "api_key": "sk-..." }`) |
| `GET` | `/api/settings/openai-api-key` | 检查密钥是否已配置 (`{ "set": true/false }`) |
## 技术栈
- **后端:** FastAPI, SQLModel, SQLite, Alembic
- **前端:** Jinja2 templates, JavaScript, Cytoscape.js
- **UI 主题 [Star Admin 2](https://github.com/BootstrapDash/star-admin2-free-admin-template) 由 [BootstrapDash](https://www.bootstrapdash.com/) 提供 (MIT License)
- **归属分析:** OpenAI SDK, ReportLab
- **Agent Skill:** Python `requests` 客户端
## 数据库表
| 表 | 用途 |
|---|---|
| `diamond` | 核心 Diamond 记录 (标签、注释、颜色、时间戳) |
| `vertex` | 每个 Diamond 的每种顶点类型一个 |
| `indicator` | 带有类型分类的标准化指标值 |
| `vertexindicator` | 顶点和指标之间的多对多连接 |
| `edge` | Diamond 之间的链接（自动或手动） |
## 开发
### 迁移
```
alembic upgrade head
alembic revision --autogenerate -m "describe change"
```
### 项目布局
```
.
├── app/ # FastAPI backend
│ ├── main.py # Routes and endpoints
│ ├── models.py # SQLModel / Pydantic models
│ ├── database.py # Engine and session
│ ├── services.py # Business logic
│ └── indicators.py # Indicator normalisation
├── attribution/ # OpenAI-powered hypothesis generation
├── diamond-modeller-skill/ # Agent skill for agentic integration
│ ├── SKILL.md # Skill definition
│ ├── scripts/ # Python API client
│ └── references/ # API documentation
├── templates/ # Jinja2 HTML templates
├── examples/ # Example analysis JSON files
├── static/ # Static assets
├── alembic/ # Database migrations
├── run.py # Dev server entry point
├── requirements.txt
└── README.md
```
## 贡献
欢迎贡献。请提交 Issue 或 Pull Request。
## 许可证
本项目采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可。您可以自由地出于非商业目的共享和改编它，但需注明出处并在相同许可下发布。商业用途需获得作者的事先书面许可。详情请参阅 [LICENSE](LICENSE)。
## 快速开始
```
git clone https://github.com/bertdavies/Diamond-Modeller.git
cd diamond-modeller
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # Optional: add your OpenAI key for attribution
python run.py
```
然后打开 http://localhost:8000。
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `DATABASE_URL` | 否 | `sqlite:///./diamond_modeller.db` | SQLite 连接字符串 |
| `OPENAI_API_KEY` | 仅用于假设生成 | — | 通过 `.env` 或 UI 设置 (Controls -> Set OpenAI API Key) |
## REST API 参考
### 页面
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/` | 重定向到 `/graph/` |
| `GET` | `/graph/` | 图谱 UI 页面 |
| `GET` | `/about` | 渲染为 HTML 的 README |
### Diamond
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/create-diamond` | 创建一个 Diamond (表单数据: label, notes, colour, indicators) |
| `GET` | `/diamonds/` | 列出/搜索 Diamond (可选 `?query=`) |
| `GET` | `/diamonds/{id}` | Diamond 摘要 JSON |
| `GET` | `/diamonds/{id}/details` | 完整的 Diamond 详情 JSON (包括每个顶点的指标) |
| `GET` | `/diamonds/{id}/edit` | 预填充用于编辑的 Diamond 数据 |
| `PUT` | `/diamonds/{id}` | 更新一个 Diamond (表单数据) |
| `DELETE` | `/diamonds/{id}` | 删除单个 Diamond |
| `DELETE` | `/diamonds/remove-all/` | 删除所有 Diamond、顶点、指标和边缘 |
### 图谱与链接
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/graph` | 用于 Cytoscape 的图谱 JSON (`{ elements: { nodes, edges } }`) |
| `POST` | `/links/` | 创建手动链接 (`{ src_diamond_id, dst_diamond_id, reason }`) |
| `POST` | `/regenerate-links` | 从指标重叠重建所有自动链接 |
### 导出/导入
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/api/export-analysis` | 将完整分析导出为 JSON |
| `POST` | `/api/import-analysis` | 从 JSON 导入分析 (替换当前数据) |
### 归属
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/conduct-attribution` | 运行假设生成。成功时返回 PDF，失败时返回 JSON。 |
### 设置
| 方法 | 路径 | 描述 |
|---|---|---|
| `POST` | `/api/settings/openai-api-key` | 设置 OpenAI API 密钥 (`{ "api_key": "sk-..." }`) |
| `GET` | `/api/settings/openai-api-key` | 检查密钥是否已配置 (`{ "set": true/false }`) |
## 技术栈
- **后端:** FastAPI, SQLModel, SQLite, Alembic
- **前端:** Jinja2 templates, JavaScript, Cytoscape.js
- **UI 主题 [Star Admin 2](https://github.com/BootstrapDash/star-admin2-free-admin-template) 由 [BootstrapDash](https://www.bootstrapdash.com/) 提供 (MIT License)
- **归属分析:** OpenAI SDK, ReportLab
- **Agent Skill:** Python `requests` 客户端
## 数据库表
| 表 | 用途 |
|---|---|
| `diamond` | 核心 Diamond 记录 (标签、注释、颜色、时间戳) |
| `vertex` | 每个 Diamond 的每种顶点类型一个 |
| `indicator` | 带有类型分类的标准化指标值 |
| `vertexindicator` | 顶点和指标之间的多对多连接 |
| `edge` | Diamond 之间的链接（自动或手动） |
## 开发
### 迁移
```
alembic upgrade head
alembic revision --autogenerate -m "describe change"
```
### 项目布局
```
.
├── app/ # FastAPI backend
│ ├── main.py # Routes and endpoints
│ ├── models.py # SQLModel / Pydantic models
│ ├── database.py # Engine and session
│ ├── services.py # Business logic
│ └── indicators.py # Indicator normalisation
├── attribution/ # OpenAI-powered hypothesis generation
├── diamond-modeller-skill/ # Agent skill for agentic integration
│ ├── SKILL.md # Skill definition
│ ├── scripts/ # Python API client
│ └── references/ # API documentation
├── templates/ # Jinja2 HTML templates
├── examples/ # Example analysis JSON files
├── static/ # Static assets
├── alembic/ # Database migrations
├── run.py # Dev server entry point
├── requirements.txt
└── README.md
```
## 贡献
欢迎贡献。请提交 Issue 或 Pull Request。
## 许可证
本项目采用 [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可。您可以自由地出于非商业目的共享和改编它，但需注明出处并在相同许可下发布。商业用途需获得作者的事先书面许可。详情请参阅 [LICENSE](LICENSE)。标签：Kill Chain, LLM, Mutation, OpenAI, PDF报告生成, Python, REST API, Unmanaged PE, 入侵分析, 内存规避, 可视化, 后端开发, 威胁情报, 安全运营, 开发者工具, 归因分析, 扫描框架, 攻击溯源, 数据可视化, 无后门, 杀伤链, 结构化分析, 编排框架, 网络安全, 网络测绘, 自动化分析, 跨站脚本, 逆向工具, 钻石模型, 隐私保护