sahillad05/ai-threat-intelligence-assistant
GitHub: sahillad05/ai-threat-intelligence-assistant
一款基于 Google Gemini 与多源情报聚合的 AI 威胁情报分析助手，为安全分析师提供自动化的指标研判与结构化报告生成服务。
Stars: 0 | Forks: 0
# 🛡️ AI 驱动的威胁情报助手
这是一款由 AI 驱动的网络安全工具，用于分析 **IP 地址**、**域名**和 **URL** 的潜在威胁。它从多个威胁情报源收集情报，使用 **Google Gemini AI** 进行分析，并生成结构化且对分析师友好的威胁报告——所有这些都通过专业的 SOC 级仪表板完成。
## 🎯 功能
- **多源情报** — 并发聚合来自 VirusTotal 和 AbuseIPDB 的数据
- **AI 驱动的分析** — Google Gemini 生成带有 JSON schema 验证的结构化威胁评估
- **基于规则的后备机制** — 在 AI 不可用时（如 429/配额超限），自动激活确定性分析引擎
- **对分析师友好的报告** — 包含威胁摘要、风险等级、攻击类型、调查步骤和缓解建议
- **AI 与 VirusTotal 对比** — 将 AI 的分析结果与真实威胁检测数据进行验证的后端服务
- **快速统计** — 直观的 KPI：VT 检测数、滥用评分、历史报告、风险评分
- **专业仪表板** — 企业级 SOC 界面（Splunk/Falcon 风格）
- **颜色编码的严重程度** — 威胁摘要卡片的边框和徽章反映了风险等级
- **会话历史** — 在浏览器会话期间保留带有风险徽章的最近查询记录
## 🖥️ 仪表板预览
该仪表板的设计看起来像一个真实的内部网络安全工具：
- **左侧面板** — 指标输入表单、带有风险徽章的最近查询、数据源状态
- **右侧面板** — 快速统计行、带有严重程度边框的威胁摘要、风险评估、攻击类型、调查步骤、分析师问题、缓解建议，以及一个紧凑的 AI 与 VT 对比表格
## 🏗️ 架构
```
┌─────────────────────────┐
│ Frontend Dashboard │
│ (HTML / CSS / JS) │
└──────────┬──────────────┘
│ POST /api/analyze
┌──────────▼──────────────┐
│ FastAPI Backend │
│ (Validation + CORS) │
└──────────┬──────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ VirusTotal │ │ AbuseIPDB │ │ Gemini AI │
│ API Client │ │ API Client │ │ (or Fallback)│
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
└────────┬───────┘ │
▼ │
┌───────────────┐ │
│ Aggregator │─── compact ────▶│
│ (Risk Score) │ summary │
└───────────────┘ │
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ Comparison │◀───────│ AI Report │
│ Service │ │ (Structured) │
└───────┬───────┘ └───────────────┘
▼
┌───────────────┐
│ Response │
│ (JSON) │
└───────────────┘
```
## 📁 项目结构
```
ai-threat-intelligence-assistant/
│
├── backend/
│ ├── app/
│ │ ├── __init__.py
│ │ ├── main.py # FastAPI entry point + static file serving
│ │ ├── config.py # Environment config with startup validation
│ │ │
│ │ ├── models/
│ │ │ ├── __init__.py
│ │ │ └── schemas.py # Pydantic request/response models
│ │ │
│ │ ├── routes/
│ │ │ ├── __init__.py
│ │ │ └── threat_routes.py # POST /api/analyze + dev/test routes
│ │ │
│ │ ├── services/
│ │ │ ├── __init__.py
│ │ │ ├── virustotal_service.py # VirusTotal API client
│ │ │ ├── abuseipdb_service.py # AbuseIPDB API client
│ │ │ ├── aggregator.py # Multi-source data aggregation + risk scoring
│ │ │ ├── gemini_service.py # Gemini AI analysis + fallback engine
│ │ │ └── comparison_service.py # AI vs VirusTotal alignment comparison
│ │ │
│ │ └── utils/
│ │ └── __init__.py
│ │
│ ├── requirements.txt # Python dependencies
│ ├── .env # API keys (never committed)
│ └── .env.example # Template for .env
│
├── frontend/
│ ├── index.html # Dashboard HTML
│ ├── css/
│ │ └── style.css # Enterprise SOC design system
│ ├── js/
│ │ └── app.js # Frontend logic + API integration
│ └── assets/
│ └── .gitkeep
│
├── .gitignore
└── README.md
```
## 🛠️ 技术栈
| 层级 | 技术 |
| ------------------ | -------------------------- |
| 后端框架 | FastAPI (Python 3.10+) |
| AI 引擎 | Google Gemini 2.5 Flash |
| 威胁情报 | VirusTotal, AbuseIPDB |
| 前端 | HTML5, CSS3, Vanilla JS |
| HTTP Client | httpx (async-capable) |
| 环境管理 | python-dotenv |
| 数据验证 | Pydantic v2 |
## 🚀 快速开始
### 前置条件
- Python 3.10+
- Git
- 用于 Gemini、VirusTotal 和 AbuseIPDB 的 API 密钥（免费版）
### 1. 克隆仓库
```
git clone https://github.com/sahillad05/ai-threat-intelligence-assistant.git
cd ai-threat-intelligence-assistant
```
### 2. 创建虚拟环境
```
cd backend
python -m venv .venv
```
**激活：**
| 操作系统 | 命令 |
| ------------- | ------------------------------ |
| Windows | `.venv\Scripts\activate` |
| macOS / Linux | `source .venv/bin/activate` |
### 3. 安装依赖
```
pip install -r requirements.txt
```
### 4. 配置 API 密钥
```
# 复制 template
cp .env.example .env # (Windows: copy .env.example .env)
# 编辑 .env 并添加你的 API keys
```
| 变量 | 获取途径 |
| ------------------ | ------------------------------------------------- |
| `GEMINI_API_KEY` | https://aistudio.google.com/apikey |
| `VIRUSTOTAL_API_KEY` | https://www.virustotal.com/gui/join-us |
| `ABUSEIPDB_API_KEY` | https://www.abuseipdb.com/account/api |
### 5. 运行服务器
```
uvicorn app.main:app --reload --port 8000
```
### 6. 打开仪表板
| URL | 描述 |
| -------------------------------- | ---------------------------------------- |
| http://localhost:8000 | 仪表板界面 |
| http://localhost:8000/docs | Swagger API 文档 |
| http://localhost:8000/health | 健康检查 |
| http://localhost:8000/config/status | API 密钥状态（安全） |
## 📡 API Endpoint
### 生产环境
| 方法 | Endpoint | 描述 |
| ------ | ---------------- | ------------------------------------------ |
| POST | `/api/analyze` | 完整的威胁分析 pipeline |
**请求体：**
```
{
"indicator": "8.8.8.8",
"type": "ip"
}
```
**支持的类型：** `ip`, `domain`, `url`
### 健康 / 状态
| 方法 | Endpoint | 描述 |
| ------ | ----------------- | -------------------------- |
| GET | `/` | 仪表板界面 |
| GET | `/health` | 健康检查 |
| GET | `/config/status` | API 密钥配置状态 |
| GET | `/docs` | Swagger UI |
### 开发 / 测试
| 方法 | Endpoint | 描述 |
| ------ | ------------------------ | ------------------------------ |
| GET | `/api/test/virustotal` | 测试 VirusTotal 集成 |
| GET | `/api/test/abuseipdb` | 测试 AbuseIPDB 集成 |
## 🔑 环境变量
| 变量 | 描述 | 必需 | 默认值 |
| -------------------- | ------------------------------ | -------- | ----------------- |
| `GEMINI_API_KEY` | Google Gemini API key | ✅ | — |
| `GEMINI_MODEL` | 要使用的 Gemini 模型 | ❌ | `gemini-2.5-flash`|
| `VIRUSTOTAL_API_KEY` | VirusTotal API key | ✅ | — |
| `ABUSEIPDB_API_KEY` | AbuseIPDB API key | ✅ | — |
## 🧠 工作原理
### 分析 Pipeline
1. **输入验证** — Pydantic 验证指标的类型和格式
2. **情报收集** — 并发查询 VirusTotal 和 AbuseIPDB
3. **风险聚合** — 将分数标准化并计算出综合风险判定
4. **AI 分析** — 将精简的数据摘要与结构化的 JSON prompt 一起发送给 Gemini
5. **后备引擎** — 如果 Gemini 返回 429/错误，确定性的基于规则的分析将生成报告
6. **AI 与 VT 对比** — 后端将 AI 风险评估与 VT 检测数据进行对比
7. **响应** — 包含完整报告、原始数据、对比和判定的结构化 JSON
### 弹性设计
- **Gemini 配额超限 (429)？** → 自动回退到基于规则的分析
- **VirusTotal 不可用？** → 仅使用 AbuseIPDB 数据继续生成报告
- **AbuseIPDB 不可用？** → 仅使用 VirusTotal 数据继续生成报告
- **两个 API 均宕机？** → 返回带有明确信息的优雅错误
- **Gemini JSON 无效？** → Schema 验证会捕获它 → 激活后备机制
## 📜 许可证
本项目出于教育和实习目的而构建。
## 🙏 致谢
- [Google Gemini](https://ai.google.dev/) — AI 分析引擎
- [VirusTotal](https://www.virustotal.com/) — 恶意软件和威胁情报
- [AbuseIPDB](https://www.abuseipdb.com/) — IP 滥用报告数据库
- [FastAPI](https://fastapi.tiangolo.com/) — 现代的 Python Web 框架
标签：AI安全分析, DLL 劫持, Web前端, 大语言模型, 威胁情报, 安全运营中心(SOC), 开发者工具, 网络安全, 运行时操纵, 逆向工具, 隐私保护