bertdavies/Diamond-Modeler
GitHub: bertdavies/Diamond-Modeler
一个基于 Diamond Model 的网络威胁情报分析与可视化工作台，支持 AI 智能体集成和自动化归因假设生成。
Stars: 0 | Forks: 0
# Diamond Modeler
**作者：** Albert Davies
**许可协议：** CC BY-NC-SA 4.0 — 对 CTI 社区免费，商业使用需获许可
Diamond Modeler 是一个交互式 Web 应用程序，用于为网络威胁情报 (CTI) 构建、可视化和分析 [Diamond Model](https://www.activeresponse.org/wp-content/uploads/2013/07/diamond.pdf) 图。
## 为什么选择 Diamond Modeler？
Diamond Modeler 的真正威力在于它是一个**智能体编排系统 (agentic orchestration systems) 的后端**。包含的 **Agent Skill** (`diamond-modeler-skill/`) 通过 REST API 赋予任何 AI Agent 对 Diamond Model 图的完整 CRUD 访问权限。这意味着自主 Agent 可以摄取威胁情报报告，将其分解为映射到 Kill Chain 阶段或 MITRE ATT&CK 战术的 Diamond Model，构建连接图，并生成归因假设 —— 所有这些都可以在规模化条件下通过编程实现，无需人工干预。
也就是说，Diamond Modeler 旨在三个层面上工作：
### 1. 智能体集成 (推荐)
将包含的技能安装到您的编排框架中。AI Agent 随后可以：
- 将原始威胁情报转换为结构化的 Diamond Model
- 为每个 Kill Chain 阶段 (`KC1`–`KC7`) 或 MITRE ATT&CK 战术 (`TA0001`–`TA0043`) 创建一个 Diamond
- 用指标和丰富的上下文注释填充所有四个顶点
- 自动链接共享指标的 Diamond
- 以 JSON 格式导出/导入整个分析
- 触发由 OpenAI 驱动的归因假设生成
有关完整说明，请参阅 `diamond-modeler-skill/SKILL.md`，Python 客户端请参阅 `diamond-modeler-skill/scripts/diamond_modeler.py`。
### 2. 独立模式与 OpenAI 归因
将 Diamond Modeler 作为独立的 Web 应用程序运行。通过 UI 手动构建您的图，然后点击 **Generate hypotheses** 将完整的 Diamond 集发送到由 OpenAI 驱动的分析流水线。它会生成一份可下载的 PDF 报告，其中包含排名的归因假设、置信度水平和支持证据。需要 OpenAI API 密钥（通过 UI 或 `.env` 设置）。
### 3. 工作台模式 (无需 API 密钥)
将 Diamond Modeler 纯粹用作 Diamond 建模工作台。创建 Diamond，用指标填充顶点，并让应用程序在指标重叠处自动生成链接。将您的分析导出为 JSON 或 PNG。无需 OpenAI 密钥 —— 归因完全是可选的。
## 工作原理
每个 **Diamond** 代表一个入侵活动单元，具有四个顶点：
| Vertex | 捕获内容 |
|---|---|
| **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**，具有四个顶点 (Adversary, Victimology, Capability, Infrastructure)
- 当 Diamond 共享指标时**自动生成链接**
- 由 Cytoscape.js 驱动的**交互式图** (平移、缩放、拖动)
- **图注释** —— 图画布上的便利贴，用于批注
- 导航栏中的**深色模式**切换
- **导出 PNG** —— 图的高分辨率截图
- **导出 / 导入图** —— 以 JSON 文件形式分享分析
- **生成假设** —— 由 OpenAI 驱动的归因分析，可下载 PDF
- **Agent Skill** —— 用于智能体编排的完整 REST API 客户端
- **关于页面** —— 在浏览器中渲染此 README
## Agent Skill
`diamond-modeler-skill/` 目录包含 AI Agent 与 Diamond Modeler 交互所需的一切：
```
diamond-modeler-skill/
├── SKILL.md # Skill definition and usage instructions
├── scripts/
│ └── diamond_modeler.py # Python client (DiamondModelerClient)
└── 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 Modeler** | 应用程序标题 (左侧) |
| **About** | 打开渲染为 HTML 的此 README |
| **月亮/太阳图标** | 切换深色模式 |
### 左侧面板 (滑出式抽屉)
| 部分 | 描述 |
|---|---|
| **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** —— 打开一个详细弹出窗口，其中指标按顶点分组
- **悬停在 Diamond 上** —— 显示 "Click to expand" 工具提示
- **点击共享指标徽章** —— 展开以显示两个 Diamond 之间的所有共享指标
- **拖动 Diamond** —— 在画布上重新定位
- **平移** —— 点击并拖动背景
- **缩放** —— 滚动轮，或使用 +/- 按钮
## 示例
项目中附带了一个 Scattered Spider Kill Chain 分析示例，位于 `examples/scattered_spider.json`。通过 UI (Controls -> Import graph) 或 API 导入它，可以看到涵盖侦察、交付、安装和目标行动的四个链接 Diamond。
## 快速开始
```
git clone https://github.com/your-username/diamond-modeler.git
cd diamond-modeler
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_modeler.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 主题：** [BootstrapDash](https://www.bootstrapdash.com/) 的 [Star Admin 2](https://github.com/BootstrapDash/star-admin2-free-admin-template) (MIT License)
- **归因：** OpenAI SDK, ReportLab
- **Agent Skill：** Python `requests` 客户端
## 数据库表
| 表 | 用途 |
|---|---|
| `diamond` | 核心 Diamond 记录 (label, notes, colour, timestamps) |
| `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-modeler-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/your-username/diamond-modeler.git
cd diamond-modeler
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_modeler.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 主题：** [BootstrapDash](https://www.bootstrapdash.com/) 的 [Star Admin 2](https://github.com/BootstrapDash/star-admin2-free-admin-template) (MIT License)
- **归因：** OpenAI SDK, ReportLab
- **Agent Skill：** Python `requests` 客户端
## 数据库表
| 表 | 用途 |
|---|---|
| `diamond` | 核心 Diamond 记录 (label, notes, colour, timestamps) |
| `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-modeler-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)。标签：CRUD, FTP漏洞扫描, JSON, LLM, Mutation, OpenAI, PDF报告生成, Python, REST API, Unmanaged PE, 入侵分析, 内存规避, 可视化, 后端开发, 威胁情报, 安全编排, 开发者工具, 归因分析, 情报分析工具, 技能, 数据可视化, 无后门, 杀伤链, 网络安全, 网络调试, 自动化, 逆向工具, 钻石模型, 隐私保护