cc22n/SOC-Assistan
GitHub: cc22n/SOC-Assistan
面向 SOC 分析师的 AI 驱动威胁情报平台，集成 19 个情报 API 和 5 个大模型，实现 IOC 聚合分析、事件管理和专业报告生成的一站式工作流。
Stars: 0 | Forks: 0
# SOC Agent
### 面向 SOC 分析师的 AI 驱动威胁情报平台
*在单一界面中分析 IOC、生成专业报告并管理安全事件。*
[西班牙语版本 / Version en Espanol](README.es.md)
## 什么是 SOC Agent？
SOC Agent 是一个为安全运营中心 (SOC) 分析师设计的基于 Web 的威胁情报平台。它集成了 **19 个威胁情报 API** 和 **5 个 LLM 提供商**，用于分析诸如 IP、域名、哈希和 URL 等威胁指标 (IOC)。
该系统使分析师能够：
- 同时针对多个来源分析 IOC
- 通过自动 LLM 路由获取 AI 驱动的智能分析
- 使用看板和时间线视图管理事件
- 与保持调查上下文的 AI SOC 助手聊天
- 生成 PDF 和 DOCX 格式的专业报告
- 将 IOC 与 MITRE ATT&CK 技术相关联
- 实时监控 API 健康状况、熔断器和性能指标
## 架构
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend │
│ Dashboard │ Analysis │ Chat │ Incidents │ Reports │ Health │
│ (Jinja2 + Tailwind + Chart.js) │
├─────────────────────────────────────────────────────────────┤
│ Flask Backend │
│ ┌──────────┐ ┌──────────┐ ┌────────────────────────┐ │
│ │ Auth │ │ API v2 │ │ Security Middleware │ │
│ │ (RBAC, │ │ Routes │ │ (Anti-SQLi, XSS, │ │
│ │ Audit) │ │ │ │ Prompt Injection) │ │
│ └──────────┘ └──────────┘ └────────────────────────┘ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Services Layer │ │
│ │ LLM Orchestrator (smart routing) │ Session Manager │ │
│ │ Threat Intel + Circuit Breakers │ Report Generator│ │
│ │ IOC Cache (TTL by type & risk) │ Metrics Engine │ │
│ └─────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌────────────────────────────────────┐ │
│ │ PostgreSQL │ │ 19 Threat Intel APIs │ │
│ │ (Users, │ │ VirusTotal, AbuseIPDB, Shodan, │ │
│ │ IOCs, │ │ GreyNoise, OTX, ThreatFox, │ │
│ │ Analyses, │ │ URLhaus, MalwareBazaar, │ │
│ │ Incidents, │ │ SecurityTrails, Pulsedive, ... │ │
│ │ Audit Log, │ └────────────────────────────────────┘ │
│ │ Sessions) │ ┌────────────────────────────────────┐ │
│ └──────────────┘ │ 5 LLM Providers │ │
│ │ xAI · OpenAI · Groq · Gemini │ │
│ │ Anthropic (Claude) │ │
│ └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## 集成 API
### 威胁情报 (19)
| 类别 | API |
|----------|------|
| **信誉** | VirusTotal, AbuseIPDB, GreyNoise, Pulsedive |
| **基础设施** | Shodan, Shodan InternetDB, Criminal IP, SecurityTrails |
| **恶意软件** | ThreatFox, MalwareBazaar, Hybrid Analysis |
| **URL** | URLhaus, URLScan, Google Safe Browsing |
| **情报** | AlienVault OTX |
| **地理位置** | IP-API (免费，无需密钥) |
### LLM 提供商 (5)
| 提供商 | 模型 | 最适用场景 |
|----------|-------|----------|
| **xAI** | Grok-3-mini | 快速分析，默认 |
| **OpenAI** | GPT-4o-mini | 深度分析，哈希 |
| **Groq** | LLaMA 3.3 70B | 速度，免费套餐 |
| **Gemini** | Gemini 2.5 Flash | 长上下文，免费套餐 |
| **Anthropic** | Claude Sonnet 4.6 | 高级推理 |
编排器会根据 IOC 类型和分析深度（例如，IP 使用 Groq，恶意软件哈希使用 OpenAI/Anthropic），自动将每次分析路由到最佳提供商。
## 功能特性
### IOC 分析
- 针对多个 API 同时进行分析
- 自动检测 IOC 类型 (IP, 域名, 哈希, URL)
- 置信度分数和风险级别 (CRITICAL, HIGH, MEDIUM, LOW, CLEAN)
- 自动映射 MITRE ATT&CK 技术
- 智能 LLM 路由：根据 IOC 类型和深度自动选择提供商
- 对所有 API 响应进行 Pydantic 验证 (检测意外的 schema 更改)
### AI SOC 聊天
- 具有持久化上下文的调查助手
- 包含完整历史记录的调查会话
- 自动关联会话中分析过的 IOC
- 会话导出 (JSON, Markdown, PDF, DOCX)
- LLM 提供商选择器 (xAI, OpenAI, Groq, Gemini, Claude)
### 事件管理
- 看板视图 (待处理, 调查中, 已解决, 已关闭)
- 集成时间线与聊天消息
- 每个事件关联多个 IOC (数据透视表)
- 自动生成的工单 ID (SOC-YYYYMMDD-NNN)
- 从分析或聊天中快速创建
- 带所有权验证的分页 API (IDOR 防护)
### 仪表盘
- 带图表的实时统计
- 风险分布、时间趋势
- 近期 IOC 和未解决事件
- 分析次数最多的 IOC
### API 健康仪表盘 (`/api-health`)
- API 配额（已用 / 今日剩余）和熔断器状态的统一视图
- 每个 API 的熔断器：CLOSED / OPEN / HALF-OPEN，包含失败计数和重试计时器
- 按 P95 延迟排名的最慢 5 个 API，配有可视化条形图
- HTTP 端点延迟表 (P50 / P95 / P99 / avg / 错误率)
- 每 30 秒自动刷新
### 报告
- 使用 ReportLab 生成专业的 PDF
- 使用 python-docx 生成可编辑的 DOCX
- 执行摘要、IOC、MITRE ATT&CK、建议
### 安全性
- 使用 Flask-Login + 密码哈希 进行身份验证
- 包含 4 个角色的 RBAC：`viewer`、`analyst`、`senior_analyst`、`admin`
- 所有表单均启用 CSRF 保护
- 按 IP 和端点进行速率限制
- 防注入中间件 (SQLi, XSS, 命令注入, 路径遍历)
- **提示注入保护** — 在发送到 LLM 之前拦截 15 种模式
- 安全标头 (CSP, X-Frame-Options, HSTS 等)
- 会话加固 (HttpOnly, SameSite, 超时)
- **仅追加的审计日志** — 记录每一次登录、分析和访问拒绝
- 请求大小限制 (16 MB)，并配有适当的 413 处理程序
### 可观测性
- **结构化 JSON 日志**，每个请求附带关联 ID
- **内存滑动窗口指标** (P50/P95/P99)，无需外部依赖
- 所有外部 API 的熔断器模式 (CLOSED → OPEN → HALF-OPEN)
- 按 IOC 类型区分的 TTL 缓存 (IP: 1小时, URL: 1小时, 域名: 6小时, 哈希: 24小时)
- 用于高基数查询的复合 PostgreSQL 索引
- 完整的 OpenAPI 规范位于 `/api/v2/openapi.json`
## 安装
### 前置条件
- Python 3.10+
- PostgreSQL 14+
- Git
### 1. 克隆仓库
```
git clone https://github.com/your-username/soc-agent.git
cd soc-agent
```
### 2. 创建虚拟环境
```
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
```
### 3. 安装依赖
```
pip install -r requirements.txt
```
### 4. 配置环境变量
```
cp .env.example .env
# 使用你的 API 密钥和配置编辑 .env
```
### 5. 设置 PostgreSQL
```
CREATE DATABASE soc_agent;
CREATE USER soc_admin WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE soc_agent TO soc_admin;
```
### 6. 初始化数据库
```
flask db upgrade
# 应用 performance 和 audit migrations:
psql -U soc_admin -d soc_agent -f migrations/add_performance_indexes_and_audit.sql
```
### 7. 运行应用
```
# Development
flask run --debug
# Production
gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app
```
### 8. 创建账户
导航到 `http://localhost:5000/auth/register`。第一个注册的用户将成为 **管理员**。
## API 配置
您不需要配置所有的 API 即可使用 SOC Agent。系统可以在您已拥有的任何 API 下正常运行。推荐的入门免费 API：
| API | 免费套餐 | 注册 |
|-----|-----------|---------|
| VirusTotal | 500 次/天 | [virustotal.com](https://www.virustotal.com/gui/join-us) |
| AbuseIPDB | 1000 次/天 | [abuseipdb.com](https://www.abuseipdb.com/register) |
| GreyNoise | 社区版 | [greynoise.io](https://viz.greynoise.io/signup) |
| AlienVault OTX | 不限次数 | [otx.alienvault.com](https://otx.alienvault.com/api) |
| Shodan InternetDB | 无需密钥 | — |
| IP-API | 无需密钥 | — |
| URLhaus | 无需密钥 | — |
| ThreatFox | 无需密钥 | — |
| MalwareBazaar | 无需密钥 | — |
对于 LLM，[Groq](https://console.groq.com/) 提供免费访问。[Anthropic](https://console.anthropic.com/) 和 [OpenAI](https://platform.openai.com/) 为付费服务。
## 项目结构
```
soc-agent/
├── app/
│ ├── __init__.py # Factory pattern, JSON logging, metrics hook
│ ├── config.py # Environment-based config, LLM models
│ ├── middleware/
│ │ └── security.py # Anti-SQLi, XSS, validation
│ ├── models/
│ │ ├── ioc.py # User, IOC, IOCAnalysis, Incident
│ │ ├── session.py # InvestigationSession, SessionIOC
│ │ ├── mitre.py # MITRE ATT&CK mappings
│ │ └── audit.py # AuditEvent, @audit_action decorator
│ ├── routes/
│ │ ├── main.py # Main views + unified API health dashboard
│ │ ├── auth.py # Login, register, profile (with audit log)
│ │ ├── api_v2_routes.py # REST API (analysis, chat, sessions, health)
│ │ ├── incident_routes.py # Incident CRUD with pagination + IDOR checks
│ │ ├── dashboard_routes.py # Dashboard stats API
│ │ ├── report_routes.py # Report generation
│ │ └── mitre_stix_routes.py # MITRE + STIX export (RBAC protected)
│ ├── schemas/
│ │ ├── api.py # Request schemas (Pydantic v2)
│ │ └── api_responses.py # Response schemas for TI APIs
│ ├── services/
│ │ ├── threat_intel.py # API coordinator
│ │ ├── new_api_clients.py # 19 API clients with circuit breakers
│ │ ├── llm_orchestrator.py # Smart LLM routing by IOC type
│ │ ├── llm_service.py # LLM communication (5 providers)
│ │ ├── ioc_cache.py # Cache with TTL by type and risk
│ │ ├── session_manager.py # Chat session management
│ │ ├── report_generator.py # PDF and DOCX
│ │ └── dashboard_stats.py # Statistics
│ ├── templates/ # Jinja2 templates
│ ├── docs/
│ │ └── openapi.py # Full OpenAPI spec
│ └── utils/
│ ├── auth.py # RBAC: @require_role decorator
│ ├── circuit_breaker.py # APICircuitBreaker (CLOSED/OPEN/HALF-OPEN)
│ ├── metrics.py # Sliding window P50/P95/P99 metrics
│ ├── security.py # Prompt injection sanitizer
│ ├── validators.py # IOC validation
│ └── formatters.py # Data formatting
├── migrations/ # SQL migrations
│ └── add_performance_indexes_and_audit.sql
├── tests/
│ └── unit/ # pytest test suite (180+ tests)
├── .env.example # Configuration template
├── requirements.txt # Python dependencies
├── wsgi.py # WSGI entry point
└── README.md
```
## 技术栈
| 层级 | 技术 |
|-------|------------|
| **后端** | Python 3.12, Flask 3.0 |
| **数据库** | PostgreSQL 16 (JSONB, 复合索引) |
| **ORM** | SQLAlchemy 2.x (Flask-SQLAlchemy) |
| **验证** | Pydantic v2 (请求 + API 响应) |
| **前端** | Jinja2, Tailwind CSS (CDN), Chart.js |
| **身份验证** | Flask-Login, Werkzeug, RBAC 角色 |
| **安全** | Flask-WTF (CSRF), Flask-Limiter, 自定义中间件, 审计日志 |
| **弹性** | 熔断器, 按 IOC 类型区分的 TTL 缓存, 请求指标 |
| **报告** | ReportLab (PDF), python-docx (DOCX) |
| **API** | 19 个威胁情报 API |
| **AI** | 5 个具有智能路由的 LLM 提供商 (xAI, OpenAI, Groq, Gemini, Anthropic) |
## 许可证
本项目采用 MIT 许可证授权。详情请参见 [LICENSE](LICENSE)。
## 作者
本项目作为一个作品集构建，展示了以下领域的技能：
- 安全运营 (SOC)
- 威胁情报
- 安全应用开发
- API 和 LLM 集成
- 蓝队 / 防御
SOC Agent — AI 驱动的威胁情报平台
标签：AI, AI助手, API集成, Chart.js, Cloudflare, DLL 劫持, Flask, IOC分析, IP分析, IP 地址批量处理, Jinja2, Kanban看板, LLM, masscan, meg, MITRE ATT&CK, nuclei, PDF报告, PostgreSQL, Python, Sigma 规则, SOC分析师, Tailwind CSS, TIP, Unmanaged PE, URL分析, Word报告, 事件管理, 信息安全, 健康监控, 可观测性, 哈希分析, 域名分析, 大语言模型, 失陷标示器, 威胁情报, 威胁情报平台, 安全运营中心, 实时处理, 密码管理, 开发者工具, 无后门, 智能分析, 测试用例, 熔断器, 网络信息收集, 网络安全, 网络映射, 自动化代码审查, 自动化分析, 自动化响应, 跨站脚本, 逆向工具, 配置审计, 隐私保护