ahmed-raza-shaikh/Kuro-Strike

# Kuro-Strike — Splunk 的 SIEM 告警富化微服务 这是一个生产就绪的 Python 微服务，利用 **VirusTotal**、**Shodan** 和 **AbuseIPDB** 威胁情报实时富化 **Splunk** 安全告警 —— 将分析师的平均分类处理时间从约 8 分钟缩短至每条告警 **90 秒以内**。 ``` Splunk Alert ──POST──► /webhook/splunk │ ┌──────────▼──────────┐ │ EnrichmentService │ │ ───────────────── │ │ Extract IOCs │ │ (IPs/domains/hash) │ └──────────┬──────────┘ │ asyncio.gather() ┌─────────────┼─────────────┐ ▼ ▼ ▼ VirusTotal Shodan AbuseIPDB (malicious (open ports, (abuse score, engines, CVEs, org) reports, TOR) reputation) └─────────────┬─────────────┘ │ ┌──────────▼──────────┐ │ Risk Score 0–100 │ │ Triage Summary │◄─── Redis Cache │ EnrichedAlert │ (TTL 1 hr) └─────────────────────┘ ``` ## 核心成果 - 利用 VirusTotal、Shodan 和 AbuseIPDB 的威胁情报富化 Splunk 告警，支持 SOC 分析师更快速地进行分类处理。 - 采用并发 API 调用和 Redis 缓存，以降低重复 IOC 的延迟并节省威胁情报 API 配额。 ## 功能特性 - **并发富化** — 每个 IOC 并行查询所有三个情报源；延迟约为 `max(source)` 而非 `sum(sources)` - **Redis 缓存** — 重复的 IOC 在 < 5 ms 内从缓存中读取；避免冗余的 API 调用和速率限制消耗 - **自动 IOC 提取** — 从任何 Splunk 结果字段中解析公网 IP、域名以及 MD5/SHA-1/SHA-256 哈希值 - **综合风险评分** — 采用加权算法（0–100），结合 VT 引擎检测数、AbuseIPDB 置信度、Shodan CVE 及可疑端口 - **人类可读的分类摘要** — 即时可用的摘要，包含国家、ISP、CVE 和检测次数 - **双重 Splunk 集成** — 原生 webhook 接收器 + 自定义告警动作脚本 - **Docker 就绪** — 一条 `docker compose up` 命令即可启动服务及 Redis ## 快速开始 ### 1. 获取 API 密钥 | 服务 | 免费额度 | 注册链接 | |---|---|---| | VirusTotal | 4 次请求/分钟 | https://www.virustotal.com/gui/join-us | | Shodan | 100 查询额度 | https://account.shodan.io/register | | AbuseIPDB | 1000 次检查/天 | https://www.abuseipdb.com/register | ### 2. 配置 ``` cp .env.example .env # 编辑 .env — 填入您的三个 API keys ``` ### 3. 运行 ``` # Docker（推荐） make docker-up # 本地（需要 Python 3.12+ 和 Redis） make install make dev ``` 服务监听于 **http://localhost:8000** — 交互式文档位于 **/docs**。 ## API ### `POST /enrich` 接收标准化的 `SplunkAlert` 主体并返回 `EnrichedAlert`。 ``` curl -X POST http://localhost:8000/enrich \ -H "Content-Type: application/json" \ -d '{ "alert_name": "Suspicious Outbound C2 Traffic", "source_ip": "185.220.101.45", "destination_ip": "104.21.14.88", "domain": "malware-c2.xyz", "file_hash": "44d88612fea8a8f36de82e1278abb02f", "result": { "dest_port": "4444", "process": "powershell.exe" } }' ``` **响应** ``` { "risk_level": "CRITICAL", "risk_score": 88, "triage_summary": "🔴 CRITICAL RISK | Score: 88/100\nAlert : Suspicious Outbound C2 Traffic\n\n■ IP: 185.220.101.45\n VirusTotal : 23/90 engines flagged [⚠ MALICIOUS]\n AbuseIPDB : 95% confidence | 847 reports | RU\n ISP : Frantech Solutions\n Shodan ports: [22, 80, 443, 4444]\n CVEs : CVE-2021-44228, CVE-2022-0847\n Org : AS-CHOOPA (Amsterdam NL)\n\n■ Domain: malware-c2.xyz\n VirusTotal : 8/90 engines [⚠ MALICIOUS]\n\n■ Hash: 44d88612fea8a8f...\n VirusTotal : 55/70 engines [⚠ MALICIOUS]", "enrichment_duration_ms": 1247.3, "ip_enrichments": { ... }, "domain_enrichments": { ... }, "hash_enrichments": { ... } } ``` ### `POST /webhook/splunk` 即插即用的 Splunk webhook 接收器 — 接收 Splunk 原生告警 payload 格式。 在 Splunk 中配置：**Alert Actions → Webhook → URL: `http://:8000/webhook/splunk`** ### `GET /health` ``` { "status": "ok", "redis": "connected" } ``` ### `DELETE /cache` 清空 Redis 富化缓存（供管理员/调试使用）。 ## 风险评分 | 来源 | 信号 | 分值 | |---|---|---| | VirusTotal | 恶意引擎数量 | `数量 × 4`（最高 30） | | VirusTotal | 可疑引擎数量 | `数量 × 1`（最高 5） | | VirusTotal | 低信誉度 (< -50) | +5 | | AbuseIPDB | 滥用置信度得分 | `得分 × 0.5`（最高 50） | | AbuseIPDB | TOR 出口节点 | +10 | | AbuseIPDB | > 500 份报告 | +5 | | Shodan | 已知 CVE | `数量 × 8`（最高 20） | | Shodan | 可疑开放端口 | `数量 × 2` | | VirusTotal (哈希) | 恶意引擎数量 | `数量 × 6`（最高 80） | | 风险等级 | 分数 | |---|---| | 🟢 低风险 | 0 – 24 | | 🟡 中风险 | 25 – 49 | | 🟠 高风险 | 50 – 74 | | 🔴 严重风险 | 75 – 100 | ## 项目结构 ``` siem-alert-enrichment/ ├── src/ │ ├── main.py # FastAPI app factory │ ├── config.py # pydantic-settings config │ ├── models/ │ │ ├── alert.py # SplunkAlert, IOCBundle, SplunkWebhookPayload │ │ └── enrichment.py # VirusTotalResult, ShodanResult, AbuseIPDBResult, EnrichedAlert │ ├── enrichers/ │ │ ├── base.py # Abstract base enricher │ │ ├── virustotal.py # VT API v3 (IPs, domains, hashes) │ │ ├── shodan.py # Shodan host lookup │ │ └── abuseipdb.py # AbuseIPDB check endpoint │ ├── services/ │ │ ├── enrichment_service.py # Orchestration, scoring, triage summary │ │ └── cache_service.py # Redis async cache │ └── api/ │ └── routes.py # FastAPI routes ├── tests/ │ ├── conftest.py # Shared fixtures & mocks │ ├── test_enrichers.py # Enricher unit tests (respx mocks) │ ├── test_api.py # API & service integration tests │ └── fixtures/ │ └── sample_alert.json # Sample Splunk alert payload ├── splunk/ │ ├── alert_action.py # Splunk custom alert action script │ └── README.md # Splunk integration guide ├── Dockerfile ├── docker-compose.yml ├── Makefile ├── requirements.txt └── .env.example ``` ## 开发 ``` make test # pytest with coverage report make lint # ruff linter make docker-up # full stack ``` ## 安全与隐私 - 仅将 VirusTotal、Shodan、AbuseIPDB 以及可选的 Splunk webhook 凭据存储在环境变量或托管密钥库中——严禁将其提交到代码仓库。 - 将告警 payload 和富化结果视为安全敏感的运营数据；部署时应配备适当的访问控制、日志保留策略和 TLS 终端。 - API 速率限制和第三方威胁情报的覆盖范围可能会影响富化的完整性；请通过您的事件响应流程验证结果。 ## 环境变量 | 变量 | 默认值 | 描述 | |---|---|---| | `VIRUSTOTAL_API_KEY` | — | **必填** | | `SHODAN_API_KEY` | — | **必填** | | `ABUSEIPDB_API_KEY` | — | **必填** | | `REDIS_URL` | `redis://localhost:6379/0` | Redis 连接 | | `CACHE_TTL_SECONDS` | `3600` | IOC 缓存生命周期 | | `ENRICHMENT_TIMEOUT_SECONDS` | `10` | 单个情报源请求超时时间 | | `SPLUNK_WEBHOOK_TOKEN` | *(空)* | 可选 webhook 认证 token | | `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` | ## 技术栈 - **FastAPI** — 异步 REST 框架 - **httpx** — 用于所有三个 TI API 的异步 HTTP 客户端 - **redis[asyncio]** — 用于缓存的异步 Redis 客户端 - **pydantic v2** — 数据验证与序列化 - **pytest + respx** — 单元测试与集成测试 ## 许可证 本项目基于 [MIT 许可证](LICENSE) 发布。 版权所有 (c) 2026 Ahmed Raza Shaikh。 有关规范的许可条款，请参阅 [开源促进会 MIT 许可证](https://opensource.org/license/mit/)。

标签：AV绕过, FastAPI, Python, 威胁情报, 安全规则引擎, 开发者工具, 搜索引擎查询, 无后门, 请求拦截, 运行时操纵, 逆向工具