ahmedgheyas72/IOC-Enrichment-Threat-Intelligence-API

# IOC 增强与威胁情报 API      一个生产级别的 REST API，接受妥协指标（IP、域名、URL、文件哈希），同时针对多个威胁情报来源进行增强，评估其风险等级，并返回结构化调查准备好的输出——旨在复制 Tier 1 SOC 分析师分级工作流程。 ## 它能做什么 SOC 分析师在调查警报时通常必须手动检查每个可疑 IP 的 VirusTotal、AbuseIPDB 和 AlienVault OTX——一次一个标签页。此 API 自动化此过程： 1. 通过一次 API 调用提交 IOC 2. 三种威胁情报来源同时查询（通过异步 I/O） 3. 一个加权评分算法返回带有来源归因原因的 `CLEAN / SUSPICIOUS / MALICIOUS` 判决 4. 结果被存储并链接到调查案例 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Azure App Service │ │ │ │ ┌──────────────┐ ┌───────────────┐ ┌─────────────┐ │ │ │ FastAPI │────▶│ Redis Cache │ │ Key Vault │ │ │ │ + Pydantic │ │ (1hr TTL) │ │ API keys │ │ │ └──────┬───────┘ └───────────────┘ └─────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ │ │ │ PostgreSQL │ ◀── Flexible Server (private VNet) │ │ │ Flex Server │ │ │ └──────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ │ asyncio.gather() — all 3 fire simultaneously ├──────────────────┬──────────────────┐ ▼ ▼ ▼ [VirusTotal] [AbuseIPDB] [AlienVault OTX] AV detections Abuse confidence Threat actor pulses ``` ## 技术栈 | 层 | 技术 | 为什么 | |---|---|---| | API 框架 | FastAPI | 异步原生，自动生成 Swagger UI，内置 Pydantic 验证 | | 验证 | Pydantic v2 | 在任何 API 调用触发之前拒绝格式错误的输入 | | HTTP 客户端 | httpx（异步） | 非阻塞——同时运行 VT、AbuseIPDB、OTX | | 缓存 | Redis | 内存查找返回时间小于 10ms，而实时调用约为 800ms | | 数据库 | PostgreSQL（asyncpg） | 持久性案例管理和增强历史记录 | | 容器化 | Docker + Compose | 一条命令本地设置，相同的镜像部署到 Azure | | 云 | Azure App Service | 带有 VNet 隔离的 PostgreSQL 的容器部署 | | 机密 | Azure Key Vault | API 密钥永远不会在 `.env` 文件或源代码中 | | CI/CD | GitHub Actions | 在将 `main` 推送到 `main` 时自动部署到 Azure | | 监控 | Azure Application Insights | 请求跟踪、延迟、错误跟踪 | ## 快速入门（本地） **先决条件：** Docker Desktop、免费的 [VirusTotal API 密钥](https://virustotal.com）、免费的 [AbuseIPDB API 密钥](https://abuseipdb.com). ``` git clone https://github.com/[your-handle]/ioc-enrichment-api cd ioc-enrichment-api # 复制并填写您的API密钥 cp .env.example .env # 启动一切（FastAPI + PostgreSQL + Redis） docker compose up --build ``` API 可在 `http://localhost:8000` 上使用 Swagger UI 在 `http://localhost:8000/docs` ## API 参考 ### 增强一个 IOC ``` POST /ioc/enrich Content-Type: application/json { "value": "185.220.101.5", "ioc_type": "ip" } ``` **响应：** ``` { "id": "3f7a1c2e-84b0-4d9a-a3f1-0e6b2c1d4e5f", "value": "185.220.101.5", "ioc_type": "ip", "verdict": "MALICIOUS", "score": 70, "reasons": [ "VirusTotal: 8 malicious engine detections", "AbuseIPDB: 73% abuse confidence score", "AlienVault OTX: found in 3 threat actor pulses" ], "sources": { "virustotal": { "malicious": 8, "suspicious": 2, "harmless": 62 }, "abuseipdb": { "confidence": 73, "total_reports": 41 }, "otx": { "pulse_count": 3 } }, "cached": false, "created_at": "2025-07-01T14:23:01Z" } ``` **支持的 IOC 类型：** `ip`、`domain`、`url`、`hash` ### 检索过去的增强 ``` GET /ioc/3f7a1c2e-84b0-4d9a-a3f1-0e6b2c1d4e5f ``` ### 搜索增强历史记录 ``` GET /ioc/search?value=185.220.101.5 ``` ### 创建一个调查案例 ``` POST /cases Content-Type: application/json { "title": "Suspicious outbound traffic — Ticket #4821", "description": "Multiple endpoints beaconing to the same external IP" } ``` **响应：** ``` { "id": "case-uuid", "title": "Suspicious outbound traffic — Ticket #4821", "status": "open", "ioc_count": 0, "created_at": "2025-07-01T14:23:01Z" } ``` ### 将 IOC 附带到案例中 ``` POST /cases/{case_id}/iocs Content-Type: application/json { "ioc_id": "3f7a1c2e-84b0-4d9a-a3f1-0e6b2c1d4e5f" } ``` ### 检索完整的案例摘要 ``` GET /cases/{case_id} ``` 返回包含所有附加 IOC、它们的判决、分数和来源数据的案例——分析师编写事件报告所需的一切。 ### 关闭案例 ``` DELETE /cases/{case_id} ``` ### 健康检查 ``` GET /health ``` ``` { "status": "ok", "version": "1.0.0" } ``` ## 评分算法 大多数 IOC 工具返回原始 API 数据，并将解释留给分析师。此 API 添加了一个评分层，将来自所有三个来源的信号组合成一个可操作的判决。 ``` def score_ioc(vt_result, abuseipdb_result, otx_result) -> dict: score = 0 reasons = [] # VirusTotal: how many AV engines flagged it malicious = vt_result["last_analysis_stats"]["malicious"] if malicious > 3: score += 40 reasons.append(f"VirusTotal: {malicious} malicious engine detections") # AbuseIPDB: community-reported abuse confidence confidence = abuseipdb_result["abuseConfidenceScore"] if confidence > 50: score += 30 reasons.append(f"AbuseIPDB: {confidence}% abuse confidence score") # AlienVault OTX: threat actor attribution pulses = otx_result["pulse_info"]["count"] if pulses > 0: score += 20 reasons.append(f"AlienVault OTX: found in {pulses} threat actor pulses") verdict = "MALICIOUS" if score >= 60 else "SUSPICIOUS" if score >= 30 else "CLEAN" return {"score": score, "verdict": verdict, "reasons": reasons} ``` | 分数 | 判决 | 含义 | |---|---|---| | 0–29 | `CLEAN` | 没有来自来源的任何有意义信号 | | 30–59 | `SUSPICIOUS` | 一些信号——需要分析师审查 | | 60–100 | `MALICIOUS` | 强大的多来源确认 | **设计决策：** VirusTotal 权重最高（40 分），因为它聚合了 70 多个 AV 引擎。AbuseIPDB（30 分）依赖于社区报告，可能存在误报，因此单独携带的权重较小。OTX（20 分）对于威胁行为者归因最有价值——即使一个脉冲也很重要。未来的改进将是添加近期加权：2019 年的 VirusTotal 检测应该比上周的检测分数低。 ## 项目结构 ``` ioc-enrichment-api/ ├── app/ │ ├── main.py # FastAPI app instance, startup events │ ├── database.py # Async SQLAlchemy engine + session factory │ ├── models/ │ │ ├── ioc.py # IOCRecord SQLAlchemy model │ │ └── case.py # Case + CaseIOC junction table │ ├── schemas/ │ │ ├── ioc.py # Pydantic request/response schemas │ │ └── case.py │ ├── routers/ │ │ ├── ioc.py # /ioc/* endpoints │ │ └── cases.py # /cases/* endpoints │ └── services/ │ ├── virustotal.py # VirusTotal async client │ ├── abuseipdb.py # AbuseIPDB async client │ ├── otx.py # AlienVault OTX async client │ ├── scoring.py # Weighted scoring algorithm │ └── cache.py # Redis get/set with TTL ├── tests/ │ ├── test_enrich.py │ └── test_scoring.py ├── .github/ │ └── workflows/ │ └── deploy.yml # GitHub Actions → Azure ├── Dockerfile ├── docker-compose.yml ├── .env.example └── README.md ``` ## 环境变量 ``` # 数据库 DATABASE_URL=postgresql+asyncpg://user:password@localhost/iocdb # Redis REDIS_URL=redis://localhost:6379 # 威胁情报API（在生产中使用Azure Key Vault） VT_API_KEY=your_virustotal_key ABUSEIPDB_API_KEY=your_abuseipdb_key OTX_API_KEY=your_otx_key # Azure（仅限生产） AZURE_KEY_VAULT_URL=https://your-vault.vault.azure.net ``` 在生产中，所有 API 密钥都存储在 Azure Key Vault 中。`.env` 文件仅用于本地开发，并排除在源代码控制之外。 ## 我接下来会构建什么 - **Slack webhook 集成**——自动将 `MALICIOUS` 判决发布到 SOC Slack 频道，这样分析师就不需要轮询 API - **STIX/TAXII 导出**——标准化的威胁情报导出格式，允许与 MISP 或 ThreatConnect 等商业 TIP 平台集成 - **评分中的近期加权**——3 年前的 VirusTotal 检测应该比上个月的检测分数低；评分算法目前将所有检测同等对待 - **批量增强端点**——`POST /ioc/enrich/bulk` 接受最多 100 个 IOC，以流的形式返回结果；对于处理完整的警报 IOC 列表很有用 - **Shodan 集成**——为 IP 添加端口/服务暴露数据；没有先前滥用历史的 IP 运行端口 4444 比运行端口 443 的 IP 更可疑 ## 作者 **Ahmed [Last Name**] 美国沙迦大学计算机科学毕业生 针对阿联酋的蓝队/SOC 分析师职位 [LinkedIn](https://linkedin.com/in/[handle]) · [GitHub](https://github.com/[handle])

标签：搜索引擎查询, 测试用例, 请求拦截, 逆向工具