MintKangaroo/ThreatGraph
GitHub: MintKangaroo/ThreatGraph
一款基于 STIX 2.1 和 ATT&CK 的证据优先威胁情报图谱平台，将安全事件、IOC 和攻击技术统一关联并为每条关系提供可验证的证据链。
Stars: 0 | Forks: 0
# ThreatGraph
### 证据优先的威胁情报图谱平台
将安全事件与 IOC 连接到一个图谱中，并用可验证的 Evidence 解释所有关系。
[](https://github.com/MintKangaroo/ThreatGraph/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://react.dev/)
[](https://neo4j.com/)
[](https://oasis-open.github.io/cti-documentation/)
[](#质量验证)
[](#当前实现状态)
[](LICENSE)
Workspace overview — metrics, grounded correlation, relationship graph, and Evidence
## ThreatGraph 解决的问题
仅靠分散在 SIEM、EDR、CTI feed 中的观测数据，很难快速说明攻击的整体流程和判断依据。
ThreatGraph 将资产、用户、IOC、恶意软件、事件、ATT&CK Technique 归一化到一个图谱中，
并强制要求每条关系都必须记录 Evidence、可信度和观测时间。
| 关联 | 调查 | 解释 | 隔离 |
| --- | --- | --- | --- |
| 使用决定性 identity 对 STIX 对象和 IOC 去重 | 通过搜索、过滤、时间范围探索攻击路径 | 为每条 edge 连接来源和 Evidence | 所有存储和查询均受 `workspace_id` 限制 |
## 数据流概览
1. **Collect** — 接收 STIX/TAXII、SIEM·EDR 事件、IOC feed 作为输入。
2. **Normalize** — 验证并保留对象，对 IOC 进行 canonicalize、deduplicate 和 mask 处理。
3. **Correlate** — 根据时间窗、共同 IOC/资产/用户、ATT&CK chain 规则查找相关活动。
4. **Investigate** — 通过受限的 Graph API 和基于依据的叙事，同时调查路径和 Evidence。
## 核心功能
### 交互式调查看板
- 事件、资产、IOC、威胁行为者、ATT&CK Technique 关系可视化
- 全局实体搜索和按类型过滤
- Critical path 高亮及 1–72 小时观测范围调节
- 根据节点选择动态更新的属性、关系和 Evidence 面板
- 显示 Evidence 引用数和显式 gap 的 grounded correlation 摘要
- 通过实时节点双击执行基于服务器的 2-hop neighborhood 扩展
- 缩放、重置及导出当前 subgraph JSON
- API 状态显示、离线 demo fallback、响应式布局
- 通过 `VITE_WORKSPACE_ID` 或 `?workspace=
` 查询真实 workspace
- 采用 `?view=critical&entity=` 格式的可共享调查 deep link
Critical path investigation — suspicious edges highlighted with IOC evidence in context
### 证据优先的图核心
- 17 种威胁情报实体和 13 种关系类型
- 基于 `(workspace_id, entity_type, key)` 的 idempotent entity upsert
- 仅当同一 workspace 中存在 source、target 和 Evidence 时才创建关系
- 验证调用者属性，防止其覆盖 identity、workspace、evidence 和 time 字段
- idempotent 初始化 30 个 Neo4j constraint/index
### STIX 2.1 与 IOC pipeline
- STIX 2.1 Bundle 验证、保留原始数据、import/export
- Domain, IPv4/IPv6, URL, SHA 系列 Indicator pattern 映射
- 官方 ATT&CK attack-pattern 中的 Technique/sub-technique、tactic、platform 归一化
- 将 Sigma `attack.t####` 标签映射到相同的 canonical Technique identity
- TAXII 异步输入边界与最大对象数量限制
- IP、domain、URL、hash 的 canonicalization 和稳定的 identity
- 去重及可选的敏感 IOC masking
### 可解释的关联分析与集成
- 在最长 30 天的时间窗内，基于共同 IOC·asset·identity pivot 进行相关分析
- 检测连接到事件的多个 ATT&CK Technique chain
- 输入 facts 相同时生成相同 UUID 的决定性 finding
- 为每个 claim 保留 relationship ID、Evidence ID 和 confidence 的 grounded narrative
- 面向 AI-SOC Dashboard、AutoPentest AI、SentinelFlow 的 versioned export envelope
### 平台基础设施
- FastAPI liveness/readiness、graph exploration、correlation 和 export API
- PostgreSQL metadata store、Neo4j graph store、Redis/Celery runtime
- Docker Compose 服务依赖、healthcheck 和持久化卷
- Python strict typing、100% 后端覆盖率、React 交互测试
## 当前实现状态
| 领域 | 状态 | 实现内容 |
| --- | :---: | --- |
| Platform foundation | ✅ | FastAPI, PostgreSQL, Neo4j, Redis/Celery, React, Compose |
| Graph schema & repository | ✅ | Typed model, Evidence edge, workspace isolation, idempotent upsert |
| STIX 2.1 ingestion | ✅ | Bundle import/export, object mapping, TAXII boundary, raw preservation |
| IOC normalization | ✅ | Canonical identity, deduplication, optional masking |
| ATT&CK knowledge mapping | ✅ | Technique/sub-technique identity, STIX metadata, Sigma tags |
| Correlation engine | ✅ | 时间窗、共同 IOC/asset/identity、ATT&CK technique chain |
| Graph Query API | ✅ | Pagination, time range, neighborhood, incident graph, shortest path, masking |
| Investigation dashboard | ✅ | 搜索、过滤、时间线、关联、服务器扩展、导出、实时/演示 |
| Grounded narratives | ✅ | Relationship/Evidence 引用、confidence、显式 gap |
| Platform adapters | ✅ | AI-SOC Dashboard, AutoPentest AI, SentinelFlow export contracts |
## 快速开始
### Docker Compose
环境要求：Docker Engine 和 Docker Compose v2
```
git clone https://github.com/MintKangaroo/ThreatGraph.git
cd ThreatGraph
cp .env.example .env
docker compose up --build
```
| Service | URL | 作用 |
| --- | --- | --- |
| Dashboard | | 图谱探索和 Evidence 查看 |
| API / OpenAPI | | 状态·图谱·关联分析 API |
| Neo4j Browser | | 本地图谱管理 |
`graph-init` 会在 API 和 worker 启动前安装 constraint 和 index。使用
`docker compose down` 关闭服务。只有在需要连同本地数据一起删除时，
才使用 `docker compose down --volumes`。
### 连接真实 workspace
在 `.env` 中指定要查询的 UUID，然后重启 web 服务。
```
VITE_WORKSPACE_ID=00000000-0000-4000-8000-000000000001
```
如果想进行一次性查看，也可以使用以下 URL。
```
http://localhost:5173/?workspace=00000000-0000-4000-8000-000000000001
```
如果 workspace 中没有节点或 API 查询失败，看板将安全地使用 demo 数据进行
fallback。
### 本地开发
环境要求：Python 3.12+，Node.js 20+
```
python3.12 -m venv .venv
source .venv/bin/activate
make install web-install
make check
```
```
make dev # 전체 스택
make test # Python tests
make web-test # React tests
make web-build # production web build
make graph-schema # Neo4j schema only
```
## API
默认前缀为 `/api/v1`。
| Method | Endpoint | 说明 |
| --- | --- | --- |
| `GET` | `/health/live` | API process liveness |
| `GET` | `/health/ready` | PostgreSQL, Neo4j, Redis readiness |
| `GET` | `/workspaces/{workspace_id}/graph` | 查询 workspace subgraph |
| `GET` | `/workspaces/{workspace_id}/graph/entities/{entity_id}/neighborhood` | bounded neighborhood 扩展 |
| `GET` | `/workspaces/{workspace_id}/graph/paths/shortest` | bounded shortest path |
| `GET` | `/workspaces/{workspace_id}/graph/incidents/{incident_id}` | 以 incident 为中心的 subgraph |
| `GET` | `/workspaces/{workspace_id}/analysis/correlations` | 基于依据的关联分析和叙事 |
| `GET` | `/workspaces/{workspace_id}/analysis/exports/{platform}` | 平台 export envelope |
Graph API 限制了 `limit=1..200`、遍历深度和时间范围。`sensitive=true` 实体的
key、name 和 properties 会在 API 边界处进行 masking。
```
curl "http://localhost:8000/api/v1/workspaces/\
00000000-0000-4000-8000-000000000001/graph?limit=100&offset=0"
```
```
{
"nodes": [],
"relationships": [],
"total_nodes": 0,
"limit": 100,
"offset": 0,
"next_offset": null
}
```
详细的响应和安全行为请参阅 [API 文档](docs/api.md)。
## 图谱模型
```
flowchart LR
A[Asset] -->|observed_on| I[Incident]
U[Identity] -->|authenticated_to| A
F[File / Hash] -->|executed| A
A -->|communicates_with| IP[IP / Domain / URL]
I -->|uses_technique| T[ATT&CK Technique]
M[Malware] -->|related_to| I
TA[Threat Actor] -->|attributed_to| M
E[Evidence] -. grounds every edge .-> I
```
所有 relationship 都必须包含以下字段。
```
source · first_seen · last_seen · confidence · evidence_id · workspace_id
```
完整的 entity identity 和 relationship 规则整理在
[Graph Schema](docs/graph-schema.md) 中。
## 架构
```
flowchart TB
Web[React / Vite Dashboard] -->|REST| API[FastAPI]
API --> PG[(PostgreSQL)]
API --> Neo[(Neo4j)]
API --> Redis[(Redis)]
Worker[Celery Worker] --> Redis
Worker --> Neo
STIX[STIX / TAXII Sources] --> Worker
Init[graph-init] --> Neo
```
- PostgreSQL：workspace、job、integration metadata
- Neo4j：workspace-scoped entities、relationships、Evidence
- Redis/Celery：异步 ingestion 与 correlation 执行边界
- React/Vite：探索 demo 或真实 workspace graph 的运维 UI
更多设计详情请参阅 [Architecture](docs/architecture.md) 和
[Threat Model](docs/threat-model.md)。
## 项目结构
```
threatgraph/
├── src/threatgraph/
│ ├── api/ # FastAPI routes and lifecycle
│ ├── graph/ # typed models, schema, Neo4j repository
│ ├── infrastructure/ # PostgreSQL, Neo4j, Redis resources
│ ├── ioc/ # normalization, identity, masking
│ ├── stix/ # STIX mapping, store, TAXII boundary
│ ├── attack.py # ATT&CK and Sigma technique identity
│ ├── correlation.py # bounded deterministic graph rules
│ ├── narrative.py # Evidence-grounded explanations
│ ├── platforms.py # downstream export contracts
│ └── worker/ # Celery runtime
├── web/src/ # React investigation dashboard
├── tests/unit/ # backend unit tests
├── docs/ # architecture and domain documentation
└── compose.yaml
```
## 质量验证
当前验证标准：
- Backend：**96 个测试**，**100% 语句覆盖率**
- Frontend：**12 个测试**，看板渲染、API fallback、图谱选择/过滤、deep link、全局搜索、neighborhood 和 correlation adapters
- `ruff` lint/format、strict `mypy`、TypeScript 构建
- Docker Compose 配置验证
- GitHub Actions backend/web/compose/graph 集成作业
```
make check
```
## 安全原则
- 所有图谱读写操作均通过 `workspace_id` 进行隔离。
- 没有 Evidence 关联的情况下，不会在同一 workspace 内创建关系。
- Query API 会限制结果大小，并在响应前对敏感实体进行 masking。
- 限制图谱遍历深度和 correlation 时间窗，以阻止过度查询。
- Narrative 和平台 export 会始终保留 relationship/Evidence ID。
- Readiness 错误不会暴露内部 host、credential 或 stack trace。
- Compose 中的默认 secret 仅用于隔离的本地开发。
- 未经授权的目标扫描或攻击行为不属于本项目的范围。
漏洞报告流程请查阅 [SECURITY.md](SECURITY.md)。
## 文档
| 文档 | 内容 |
| --- | --- |
| [Architecture](docs/architecture.md) | 服务与进程边界 |
| [Graph Schema](docs/graph-schema.md) | entity、relationship、identity 规则 |
| [STIX 2.1](docs/stix.md) | import/export 和支持的对象 |
| [IOC Pipeline](docs/ioc.md) | 归一化、去重、masking |
| [ATT&CK Mapping](docs/attack.md) | Technique identity 和 Sigma tag 映射 |
| [Correlation](docs/analysis.md) | 时间窗规则与 Evidence grounding |
| [API](docs/api.md) | health、graph、analysis、export 契约 |
| [Platform Integrations](docs/integrations.md) | downstream envelope 和 event type |
| [Threat Model](docs/threat-model.md) | trust boundary 和滥用案例 |
| [Roadmap](docs/roadmap.md) | 下一步实现计划 |
| [Contributing](CONTRIBUTING.md) | 开发·验证·分支规则 |
## 贡献与许可
贡献前请查阅 [CONTRIBUTING.md](CONTRIBUTING.md) 中的分支与验证规则。
ThreatGraph 基于 [MIT License](LICENSE) 发布。
为可解释、基于证据的安全运营而构建。
标签：AV绕过, FastAPI, React, Syscalls, 威胁情报, 安全运营, 开发者工具, 扫描框架, 搜索引擎查询, 测试用例, 版权保护, 逆向工具