lumen-maximus/soc_triage_bot
GitHub: lumen-maximus/soc_triage_bot
一个异步、与SIEM无关的SOC分诊代理，用于自动化安全警报分析与响应建议生成。
Stars: 0 | Forks: 0
# SOC分诊机器人
一个异步的、与SIEM无关的安全运营中心（SOC）分诊代理服务，用于自动化安全警报分析与响应建议生成。
## 功能特性
- **信号摄入与规范化**：接收多种信号类型（SIEM警报、IOC、CVE、威胁狩猎发现、用户报告），并将其规范化为通用模式
- **并发增强**：使用适配器并行运行增强处理：
- SIEM（历史上下文、警报频率）
- EDR（端点数据、进程树）
- 威胁情报（信誉、攻击活动）
- 漏洞数据库（CVE详情、补丁状态）
- CMDB（资产关键性、所有权）
- **ETS预测**：多时域指数平滑预测，支持滚动回测与异常检测
- **相似案例检索**：基于TF-IDF的相似性搜索，查找相关历史案例
- **确定性分类**：使用增强数据和历史模式，基于规则的TP/FP分类
- **操作建议**：生成、去重和排序操作建议，来源包括：
- 预定义模板
- 案例学习到的模式
- 基于动态上下文的生成
- **Jinja Markdown报告**：专业、易读的分诊报告
- **双重接口**：同时提供CLI和REST API
## 安装说明
```
# 克隆仓库
git clone https://github.com/lumen-maximus/soc_triage_bot.git
cd soc_triage_bot
# 安装依赖项
pip install -e .
# 用于开发（包括测试依赖项）
pip install -e ".[dev]"
```
## 快速开始
### CLI使用方法
```
# 启动 REST API 服务器
soc-agent serve --host 0.0.0.0 --port 8000
# 从 JSON 文件分类信号
soc-agent triage examples/siem_alert.json -o report.md
# 使用历史数据进行分类以预测
soc-agent triage examples/siem_alert.json \
--historical-data examples/historical_data.json \
-o report.md
# 交互式创建和分类信号
soc-agent create --type siem_alert
# 验证信号文件
soc-agent validate examples/siem_alert.json
# 检查适配器健康状况
soc-agent health
```
### REST API使用方法
启动服务器：
```
soc-agent serve
```
或直接使用uvicorn：
```
uvicorn soc_triage_bot.api:app --host 0.0.0.0 --port 8000
```
API调用示例：
```
# 健康检查
curl http://localhost:8000/health
# 分类信号
curl -X POST http://localhost:8000/triage \
-H "Content-Type: application/json" \
-d @examples/siem_alert.json
# 获取分类结果
curl http://localhost:8000/triage/{triage_id}
# 获取 Markdown 报告
curl http://localhost:8000/triage/{triage_id}/report
# 获取行动提案
curl http://localhost:8000/triage/{triage_id}/actions
# 标准化原始信号
curl -X POST http://localhost:8000/signals/normalize \
-H "Content-Type: application/json" \
-d '{"type":"siem_alert","title":"Test","description":"Test alert","severity":"high"}'
```
## 信号格式
信号遵循规范化模式：
```
{
"signal_id": "sig-20251214-001",
"signal_type": "siem_alert",
"timestamp": "2025-12-14T19:00:00Z",
"source": {
"system": "splunk",
"rule_id": "rule-001",
"rule_name": "Suspicious PowerShell"
},
"title": "Suspicious PowerShell Execution",
"description": "PowerShell with encoded command detected",
"severity": "high",
"entities": {
"hostname": ["workstation-01"],
"user": ["admin"],
"ip": ["192.0.2.15"]
},
"tags": ["malware", "powershell"],
"raw_data": {},
"metadata": {}
}
```
### 信号类型
- `siem_alert`：来自SIEM系统的警报
- `ioc`：威胁指标匹配
- `cve`：漏洞报告
- `hunt`：威胁狩猎发现
- `user_report`：用户提交的安全问题
## 架构设计
### 组件
1. **模型**：用于信号、增强、分类和操作的Pydantic模型
2. **适配器**：可插拔的外部系统适配器（SIEM、EDR、TI、Vuln、CMDB）
3. **服务**：
- `EnrichmentService`：编排并发增强处理
- `ForecastingService`：支持滚动回测的ETS预测
- `SimilarityService`：基于TF-IDF的相似案例检索
- `ClassificationService`：确定性TP/FP分类
- `ActionProposalService`：模板、学习和生成的操作建议
- `ReportService`：基于Jinja2的报告生成
- `TriageService`：完整工作流程的主编排器
### 工作流程
1. **摄入**：接收多种格式的信号
2. **规范化**：转换为通用模式
3. **增强**：通过适配器运行并发增强
4. **预测**：分析时间序列模式（如果提供历史数据）
5. **检索**：查找相似历史案例
6. **分类**：确定TP/FP/未知，并计算置信度分数
7. **建议**：生成排序后的操作建议
8. **报告**：渲染全面的Markdown报告
## 配置说明
系统设计为与SIEM无关，支持可插拔适配器。要集成到您的环境中：
1. **实现自定义适配器**：为您的特定系统扩展 `BaseAdapter`
2. **配置端点**：在适配器配置中设置API端点和凭据
3. **调整分类**：在 `ClassificationService` 中调整置信度阈值
4. **添加模板**：在 `ActionProposalService` 中扩展操作模板
自定义适配器示例：
```
from soc_triage_bot.adapters import BaseAdapter
from soc_triage_bot.models import Signal, EnrichmentResult, EnrichmentStatus
class MySIEMAdapter(BaseAdapter):
async def enrich(self, signal: Signal) -> EnrichmentResult:
# Query your SIEM
data = await query_my_siem(signal)
return EnrichmentResult(
adapter=self.name,
status=EnrichmentStatus.SUCCESS,
data=data
)
```
## 开发指南
### 运行测试
```
# 安装开发依赖项
pip install -e ".[dev]"
# 运行测试
pytest
# 运行覆盖率
pytest --cov=soc_triage_bot --cov-report=html
```
### 项目结构
```
soc_triage_bot/
├── soc_triage_bot/
│ ├── __init__.py
│ ├── models/ # Pydantic data models
│ │ ├── signal.py
│ │ ├── enrichment.py
│ │ ├── classification.py
│ │ └── action.py
│ ├── adapters/ # Enrichment adapters
│ │ ├── base.py
│ │ ├── siem.py
│ │ ├── edr.py
│ │ ├── threat_intel.py
│ │ ├── vulnerability.py
│ │ └── cmdb.py
│ ├── services/ # Core services
│ │ ├── enrichment.py
│ │ ├── forecasting.py
│ │ ├── similarity.py
│ │ ├── classification.py
│ │ ├── action_proposal.py
│ │ ├── report.py
│ │ └── triage.py
│ ├── api.py # FastAPI REST API
│ └── cli.py # Click CLI
├── tests/ # Test suite
├── examples/ # Example signals
└── pyproject.toml # Project configuration
```
## API文档
当服务器运行时，请访问：
- Swagger UI：http://localhost:8000/docs
- ReDoc：http://localhost:8000/redoc
## 系统扩展
### 添加新信号类型
1. 在 `models/signal.py` 的 `SignalType` 枚举中添加
2. 更新 `api.py` 或 `cli.py` 中的规范化逻辑
3. 在 `examples/` 中添加示例
### 添加新适配器
1. 在 `adapters/` 中创建新适配器
2. 扩展 `BaseAdapter`
3. 实现 `enrich()` 方法
4. 在 `api.py` 和 `cli.py` 中注册
### 添加操作模板
编辑 `services/action_proposal.py` 中的 `ActionProposalService._load_templates()` 方法
## 许可协议
MIT License - 详见LICENSE文件
## 贡献指南
欢迎贡献！请：
1. Fork本仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求
## 支持渠道
如有问题、疑问或贡献，请在GitHub上提交issue。
标签：GPT, Markdown报告生成, Python开发, REST API, TF-IDF相似度搜索, 事件分类, 动作推荐, 占用监测, 命令行接口, 响应推荐, 威胁分类, 威胁情报集成, 安全运营中心, 并发增强, 异步处理, 时间序列预测, 漏洞管理, 监控工具, 网络映射, 自动化安全分析, 规则分类, 警报管理, 资产管理, 逆向工具, 预测分析