amirzyazid/threat-intel-api
GitHub: amirzyazid/threat-intel-api
一款面向 SOC 的轻量级威胁情报富化 API，聚合多源情报并提供标准化风险评分与 MITRE ATT&CK 映射。
Stars: 0 | Forks: 0
# SOC 威胁情报富化 API
一个用于通过威胁情报、风险评分和 MITRE ATT&CK 技术映射来富化可观测数据（IP、域名、URL）的 API。该工具聚合来自多个威胁情报源的数据，以提供全面的安全风险评估。
## 功能
- **IP 地址分析** - 分析 IPv4 地址的恶意活动
- **URL 和域名分析** - 提交完整的 URL 或域名以提取并分析域名
- **风险评分** - 从多个来源聚合威胁情报，并提供标准化的 0-100 风险评分
- **MITRE ATT&CK 映射** - 将威胁映射到 MITRE ATT&CK 技术和战术
- **威胁行为者归属** - 识别相关的威胁行为者及其所在国家/地区
- **多源情报** - 聚合来自 VirusTotal、AlienVault 和 APT 数据库的数据
## 快速开始
### 前置条件
- Python 3.8+
- pip (Python 包管理器)
### 安装
1. 克隆仓库：
```
git clone
cd threat-intel-api
```
2. 安装依赖：
```
pip install -r requirements.txt
```
### 运行 API
启动开发服务器：
```
python -m app.main
```
API 将在 `http://localhost:8000` 处可用
**交互式 API 文档：** 访问 `http://localhost:8000/docs` 查看 Swagger UI
## API 端点
### 1. 分析 IP 地址
分析 IPv4 地址的恶意活动和威胁指标。
**端点：** `GET /api/v1/analyze/ip/{ip_address}`
**参数：**
- `ip_address` (路径参数)：有效的 IPv4 地址（例如，`192.168.1.1`）
**请求示例：**
```
curl http://localhost:8000/api/v1/analyze/ip/8.8.8.8
```
**响应示例：**
```
{
"observable": "8.8.8.8",
"observable_type": "ip",
"overall_risk_score": 0,
"severity": "Low",
"sources": [
{
"source_name": "VirusTotal",
"malicious_votes": 0,
"total_votes": 10,
"tags": []
}
],
"mitre_ttps": [],
"associated_actors": [],
"summary": "IP address appears to be safe based on current threat intelligence."
}
```
### 2. 分析 URL 或域名
分析 URL 或域名的恶意活动。API 会自动从完整的 URL 中提取域名。
**端点：** `GET /api/v1/analyze/url/{url:path}`
**参数：**
- `url` (路径参数)：完整的 URL（例如，`https://example.com/path`）或域名（例如，`example.com`）
**请求示例：**
```
# 分析完整 URL
curl http://localhost:8000/api/v1/analyze/url/https://example.com/path/to/resource
# 直接分析域名
curl http://localhost:8000/api/v1/analyze/url/example.com
```
**响应示例：**
```
{
"observable": "example.com",
"observable_type": "domain",
"overall_risk_score": 15,
"severity": "Low",
"sources": [
{
"source_name": "VirusTotal",
"malicious_votes": 2,
"total_votes": 45,
"tags": ["phishing", "malware-distribution"]
}
],
"mitre_ttps": [
{
"id": "T1566.002",
"name": "Phishing: Spearphishing Link",
"url": "https://attack.mitre.org/techniques/T1566/002/"
}
],
"associated_actors": [
{
"name": "Lazarus Group",
"country": "North Korea",
"description": "Suspected state-sponsored APT group"
}
],
"summary": "Domain has been associated with phishing campaigns. Low to medium risk."
}
```
## 响应结构
所有威胁分析端点都返回一个 `RiskReport` 对象：
```
{
"observable": "string - The IP, domain, or URL analyzed",
"observable_type": "string - Type: 'ip', 'domain', or 'hash'",
"overall_risk_score": "integer - Risk score from 0 (Safe) to 100 (Critical)",
"severity": "string - One of: 'Low', 'Medium', 'High', 'Critical'",
"sources": [
{
"source_name": "string - Name of threat intelligence source",
"malicious_votes": "integer - Number of sources flagging as malicious",
"total_votes": "integer - Total sources voting on this observable",
"tags": ["string - Tags or categories (e.g., 'malware', 'phishing')"]
}
],
"mitre_ttps": [
{
"id": "string - MITRE ATT&CK technique ID (e.g., 'T1566.002')",
"name": "string - Technique name",
"url": "string - Link to MITRE ATT&CK page"
}
],
"associated_actors": [
{
"name": "string - Threat actor name",
"country": "string - Country of origin",
"description": "string - Description of the actor"
}
],
"summary": "string - Human-readable summary of the threat assessment"
}
```
## 风险评分解释
API 使用标准化的 0-100 风险评分：
| 评分范围 | 严重性 | 解释 |
|-------------|----------|-----------------|
| 0-25 | 低 | 安全，风险极低 |
| 26-50 | 中 | 检测到可疑活动 |
| 51-75 | 高 | 存在明确的入侵指标 |
| 76-100 | 严重 | 已确认为恶意，建议立即采取行动 |
## 风险评分算法
总体风险评分通过聚合来自多个威胁情报源的数据来计算：
1. **VirusTotal** - 根据检测率最高计 60 分
2. **AlienVault OTX** - 根据 pulse 数据最高计 30 分
3. **APT 威胁行为者** - 如果与已知 APT 组织相关，最高计 10 分
4. **最终得分** - 上限为 100（最高风险）
## 已知安全 IP
以下 IP 被识别为安全，并返回风险评分 0：
- `8.8.8.8` (Google DNS)
- `1.1.1.1` (Cloudflare DNS)
- `8.8.4.4` (Google DNS 备用)
## 已知恶意 IP
以下 IP 被标记为恶意：
- `185.159.231.1`
- `103.149.208.57`
- `94.156.71.115`
## 架构
该 API 使用 FastAPI 构建，并遵循分层架构：
```
app/
├── main.py # API routes and endpoint definitions
├── models/
│ └── schemas.py # Pydantic data models and enums
└── services/
├── analyzer.py # Core threat analysis logic
├── utils.py # Utility functions (URL parsing, domain extraction)
└── integrations/
└── dummy_intel.py # Mock threat intelligence data sources
```
### 关键组件
- **analyzer.py**：包含 `analyze_ip()` 和 `analyze_url()` 函数，用于协调威胁情报聚合
- **utils.py**：实用函数，包括用于解析 URL 的 `extract_domain_from_url()`
- **dummy_intel.py**：带有确定性数据的模拟威胁情报源，用于测试和开发
- **schemas.py**：定义 API 请求/响应结构的 Pydantic 模型
## 错误处理
API 返回相应的 HTTP 状态码：
| 状态码 | 含义 |
|------------|---------|
| 200 | 成功 - 可观测数据成功分析 |
| 400 | 错误请求 - 无效的可观测数据格式 |
| 500 | 内部服务器错误 |
**错误响应示例：**
```
{
"detail": "Invalid IPv4 address format."
}
```
## 开发
### 项目结构
```
threat-intel-api/
├── README.md # This file
├── requirements.txt # Python dependencies
├── .gitignore # Git ignore rules
└── app/
├── __init__.py
├── main.py
├── models/
│ └── schemas.py
└── services/
├── analyzer.py
├── utils.py
└── integrations/
└── dummy_intel.py
```
### 运行测试
目前，该项目包含用于开发的模拟威胁情报数据。可以使用以下命令运行测试：
```
# 注意：正式的 test suite 即将推出
python -m pytest
```
## 未来增强计划
- [ ] 域名到 IP 地址的 DNS 解析
- [ ] 特定域名的威胁情报
- [ ] 哈希分析 (MD5, SHA-1, SHA-256)
- [ ] 真实威胁情报源集成 (VirusTotal API, AlienVault OTX API)
- [ ] 用于性能优化的缓存层
- [ ] 速率限制和身份验证
- [ ] 历史趋势分析
- [ ] 告警生成和 Webhook
## 依赖项
- **fastapi** (0.111.0) - 用于构建 API 的现代 Web 框架
- **uvicorn** (0.30.1) - 用于运行 FastAPI 应用的 ASGI 服务器
- **pydantic** (2.7.4) - 数据验证和序列化
- **httpx** (0.27.0) - 用于异步请求的 HTTP 客户端
## CORS 配置
该 API 为开发环境启用了宽松设置的 CORS。在生产环境中，请更新 `app/main.py` 中的 `CORSMiddleware` 配置，以限制允许的来源。
## 许可证
[在此处添加您的许可证信息]
## 贡献
[在此处添加贡献指南]
## 支持
如有问题或功能请求，请在 GitHub 仓库中开启一个 issue。
标签：AES-256, AlienVault, API, Ask搜索, Cloudflare, HTTP/HTTPS抓包, IP分析, MITRE ATT&CK, Python, Sigma 规则, Swagger, URL分析, VirusTotal, 域名分析, 威胁情报, 威胁情报丰富, 威胁指标, 安全运营中心, 开发者工具, 态势感知, 情报聚合, 攻击归因, 无后门, 漏洞评估, 网络安全, 网络映射, 运行时操纵, 逆向工具, 隐私保护, 风险评分