abbas-babayev/ioc-investigation-platform
GitHub: abbas-babayev/ioc-investigation-platform
面向 SOC 分析师的开源 IOC 富化平台，通过 VirusTotal API 实现失陷指标的自动检测、风险评分和处置建议。
Stars: 2 | Forks: 1
# 🔍 IOC 调查平台
## 📌 描述
**IOC 调查平台** 是一个为 SOC 分析师和威胁情报工作流程构建的基于 Web 的安全工具。它通过查询 VirusTotal API 并提供带有风险评估的结构化结果，实现 IOC (Indicator of Compromise) 的自动化富化。
构建时注重简洁性 —— 无需复杂的基础设施，只需一个 FastAPI 后端和一个具有暗色终端美感的纯 HTML/CSS/JS 前端。
## ✨ 特性
- 🔎 IOC 类型的**自动检测**：IP、Domain、URL、Hash (MD5/SHA1/SHA256)
- 📡 **VirusTotal API v3** 集成 —— 实时威胁情报
- 📊 **检测统计**：恶意、可疑、无害、未检测到的数量
- 🚦 **风险评分**：低 / 中 / 高 / 严重
- 💬 基于检测数量的**分析师建议**
- 🌑 **暗色终端 UI** —— 整洁且专注
- 🐳 **Docker 支持**，便于本地部署
- 🔐 **默认安全** —— 通过 `.env` 提供 API 密钥，绝不硬编码
## 🏗️ 架构
```
Browser (Frontend)
│
│ POST /api/lookup { "ioc": "..." }
▼
FastAPI Backend
├── detector.py → Identifies IOC type
├── virustotal.py → Queries VirusTotal API
└── scoring.py → Calculates risk + recommendation
│
│ JSON response
▼
Browser renders result
```
有关完整文档，请参见 [docs/architecture.md](docs/architecture.md)。
## 🛠️ 技术栈
| 层级 | 技术 |
|----------|-----------------------------|
| Backend | Python 3.11, FastAPI |
| HTTP | httpx (异步) |
| Config | python-dotenv |
| Frontend | HTML5, CSS3, Vanilla JS |
| Server | Uvicorn |
| Deploy | Docker, Docker Compose |
| API | VirusTotal API v3 |
## 📁 项目结构
```
ioc-investigation-platform/
├── backend/
│ ├── app/
│ │ ├── main.py # FastAPI app, endpoint /api/lookup
│ │ ├── detector.py # IOC type detection (regex)
│ │ ├── virustotal.py # VirusTotal API integration
│ │ └── scoring.py # Risk scoring logic
│ ├── requirements.txt
│ ├── Dockerfile
│ └── .env.example # Environment variable template
│
├── frontend/
│ ├── index.html # Main UI
│ ├── style.css # Dark theme styles
│ └── app.js # fetch() logic, DOM updates
│
├── docs/
│ └── architecture.md # Technical documentation
│
├── docker-compose.yml
├── .gitignore
├── README.md
└── LICENSE
```
## ⚙️ 安装说明
### 前置条件
- Python 3.11+
- [VirusTotal API key](https://www.virustotal.com/gui/sign-in) (提供免费套餐)
- Docker & Docker Compose (可选)
### 选项 A: 不使用 Docker 运行 (推荐用于开发)
**1. 克隆仓库**
```
git clone https://github.com/YOUR_USERNAME/ioc-investigation-platform.git
cd ioc-investigation-platform
```
**2. 配置 Python 虚拟环境**
```
cd backend
python -m venv venv
# 在 macOS/Linux 上：
source venv/bin/activate
# 在 Windows 上：
venv\Scripts\activate
```
**3. 安装依赖**
```
pip install -r requirements.txt
```
**4. 配置你的 API 密钥**
```
cp .env.example .env
# 打开 .env 并替换：VT_API_KEY=your_virustotal_api_key_here
```
**5. 启动后端**
```
uvicorn app.main:app --reload
# Server 运行于 http://localhost:8000
```
**6. 打开前端**
只需在浏览器中打开 `frontend/index.html`。
无需构建步骤 —— 它是纯 HTML。
### 选项 B: 使用 Docker 运行
**1. 配置环境**
```
cd backend
cp .env.example .env
# 编辑 .env 并添加你的 VirusTotal API key
```
**2. 启动所有服务**
```
# 在项目根目录下：
docker-compose up --build
```
**3. 访问平台**
- Frontend: http://localhost:80
- Backend API: http://localhost:8000
## 🔑 环境变量
| 变量 | 描述 | 必填 |
|-------------|--------------------------------|----------|
| `VT_API_KEY` | VirusTotal API 密钥 | ✅ 是 |
在此获取你的免费 API 密钥：https://www.virustotal.com/gui/sign-in
## 🚀 使用说明
1. 在浏览器中打开平台
2. 输入以下任意内容：
- **IP 地址**：`8.8.8.8`, `185.220.101.1`
- **域名**：`malware.example.com`, `phishing-site.ru`
- **URL**：`http://evil.com/payload.exe`
- **文件哈希**：`44d88612fea8a8f36de82e1238abc123` (MD5/SHA1/SHA256)
3. 点击 **INVESTIGATE** 或按 **Enter**
4. 查看结果：检测统计、风险级别和分析师建议
## 📡 API 参考
### `POST /api/lookup`
**请求：**
```
{
"ioc": "8.8.8.8"
}
```
**响应：**
```
{
"ioc": "8.8.8.8",
"ioc_type": "ip",
"stats": {
"malicious": 0,
"suspicious": 0,
"harmless": 79,
"undetected": 14
},
"risk_level": "Low",
"recommendation": "No threats detected. IOC appears clean...",
"error": null
}
```
**健康检查：**
```
GET /
→ { "status": "ok", "message": "IOC Investigation Platform is running" }
```
## 📸 截图
## 🗺️ 路线图
- [ ] AbuseIPDB 集成 (IP 信誉)
- [ ] 域名 WHOIS 查询
- [ ] DNS 解析 (A, MX, NS 记录)
- [ ] Shodan 集成 (开放端口)
- [ ] PDF 调查报告导出
- [ ] SQLite 历史日志
- [ ] 批量 IOC 查询 (CSV 上传)
- [ ] API 认证 (API 密钥中间件)
- [ ] OpenCTI / MISP 集成
- [ ] MITRE ATT&CK 映射
## ⚠️ 免责声明
本工具仅供**授权的安全研究和调查使用**。
- 请勿使用本工具调查你没有权限分析的系统上的 IOC
- 请勿主动连接、探测恶意 URL 或 IP，或与之交互
- VirusTotal 免费 API 存在限制：每分钟 4 次请求，每天 500 次请求
- 本工具提供威胁情报数据 —— 不构成法律或取证建议
## 📄 许可证
MIT License — 详见 [LICENSE](LICENSE)。
## 致谢
由 [@abbas-babayev](https://github.com/abbas-babayev) 和 [@nugetts](https://github.com/nugetts) 构建
标签：AMSI绕过, API集成, Ask搜索, AV绕过, CMS安全, CSS, Docker, FastAPI, Hash查询, HTML, httpx, IOC丰富化, IP 地址批量处理, IP查询, JavaScript, Python, SOC工具, URL查询, Uvicorn, VirusTotal, 可观测性, 域名查询, 失陷标示, 威胁情报, 威胁检测, 安全运营中心, 安全防御评估, 容器化部署, 开发者工具, 异步HTTP, 无后门, 暗色主题, 漏洞发现, 版权保护, 网络信息收集, 网络映射, 请求拦截, 运行时操纵