security-platform/backend

AI SOC 分析师后台服务

基于 FastAPI 的智能安全运营中心分析平台后台服务，支持告警数据摄取、实体提取、图分析、风险评分和 LLM 增强分析。

🚀 功能特性

📤 数据摄取

• 支持 JSON/CSV 格式告警文件上传
• 基于 YAML 配置的灵活数据预处理
• JSONPath 表达式和正则转换
• 实体自动提取和标准化

🔍 智能分析

• 图论算法分析实体关系
• 攻击链路径发现
• 风险分数计算和置信度评估
• MITRE ATT&CK 框架映射

🤖 LLM 增强

• OpenAI GPT 集成
• 智能摘要生成
• 威胁洞察分析
• 攻击链分析和事件响应计划

📊 报告生成

• 实体分析报告
• 子图关联分析
• 证据时间线
• 处置建议生成

🛠️ 技术栈

• Web框架: FastAPI + Uvicorn
• 数据库: PostgreSQL + SQLAlchemy (异步)
• 图分析: NetworkX
• 数据处理: JSONPath-ng, Pandas, NumPy
• LLM集成: OpenAI API
• 其他: Pydantic, Loguru, Tenacity

📦 安装部署

环境要求

• Python 3.9+
• PostgreSQL 13+
• Redis (可选)

快速启动

1. 克隆项目

git clone <repository-url>
cd security/backend

2. 安装依赖

pip install -r requirements.txt

3. 配置环境

cp .env.example .env
# 编辑 .env 文件，配置数据库连接等

4. 初始化数据库

# 确保PostgreSQL运行并创建数据库
createdb ai_soc

5. 启动服务

python app/main.py

服务将在 http://localhost:8000 启动

Docker 部署 (推荐)

# 构建镜像
docker build -t ai-soc-backend .

# 使用docker-compose启动
docker-compose up -d

📚 API 文档

启动服务后访问：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

主要 API 端点

数据上传

• GET /api/v1/upload/sources - 获取支持的数据源
• POST /api/v1/upload/ - 上传告警文件
• GET /api/v1/upload/status/{id} - 获取处理状态

分析报告

• GET /api/v1/reports/ - 获取报告列表
• GET /api/v1/reports/{id} - 获取报告详情
• POST /api/v1/reports/generate - 生成新报告
• GET /api/v1/reports/{id}/download - 下载报告

深度分析

• GET /api/v1/analysis/entities/{id}/neighbors - 获取实体邻居
• GET /api/v1/analysis/entities/{id}/graph - 获取实体子图
• GET /api/v1/analysis/attack-chains - 发现攻击链
• POST /api/v1/analysis/llm-insights - LLM 深度洞察

⚙️ 配置说明

数据预处理配置

项目支持基于 YAML 的灵活数据预处理配置，位于 ../configs/ 目录：

meta:
  source_id: splunk_es_alert_json
  display_name: "Splunk ES-style Alerts"
  version: "v1.0.1"

format: json  # 支持 json/csv

inputs:
  event_time: { jsonpath: "$.event_time" }
  alert_type: { jsonpath: "$.alert_type" }
  severity: { jsonpath: "$.severity" }

transforms:
  severity_norm:
    from: severity
    regex_extract:
      pattern: "(?i)^(critical|high|medium|low)$"
      group: 1

expressions:
  ip_all: { expr: 'distinct(concat(source_ips, dest_ips))' }

entities:
  - { name: "host", value: host_names, type: host_id }
  - { name: "ip", value: ip_all, type: ip }

环境变量

变量名	描述	默认值
DATABASE_URL	PostgreSQL连接字符串	-
OPENAI_API_KEY	OpenAI API密钥	-
MAX_UPLOAD_SIZE	最大上传文件大小	10MB
DEFAULT_RISK_THRESHOLD	默认风险阈值	0.7

🔧 开发指南

项目结构

app/
├── api/v1/          # API路由
├── core/            # 核心配置
├── models/          # 数据模型
├── schemas/         # Pydantic模式
├── services/        # 业务逻辑服务
│   ├── config_loader.py    # 配置加载
│   ├── alert_processor.py  # 告警处理
│   ├── entity_extractor.py # 实体提取
│   ├── graph_analyzer.py   # 图分析
│   ├── report_generator.py # 报告生成
│   └── llm_service.py      # LLM服务
└── database.py      # 数据库配置

添加新数据源

1. 在 ../configs/ 目录创建新的 YAML 配置文件
2. 配置字段映射、转换规则和实体提取规则
3. 重启服务或调用配置重载接口

扩展LLM功能

1. 在 services/llm_service.py 中添加新的分析方法
2. 在对应的 API 路由中调用
3. 根据需要调整提示模板和响应处理

📈 性能优化

数据库优化

• 为高频查询字段创建索引
• 使用连接池优化并发性能
• 定期清理历史数据

图分析优化

• 限制图的大小避免内存溢出
• 使用缓存存储计算结果
• 并行处理多个子图分析

LLM调用优化

• 实现请求重试和熔断机制
• 批量处理减少API调用次数
• 缓存常见分析结果

🧪 测试

# 运行单元测试
pytest tests/

# 运行覆盖率测试
pytest --cov=app tests/

# 运行性能测试
pytest tests/performance/

📝 日志

应用使用 Loguru 进行日志记录：

• 默认日志级别：INFO
• 日志格式包含时间、级别、模块信息
• 支持文件轮转和压缩

🚨 监控告警

建议配置以下监控指标：

• API 响应时间和错误率
• 数据库连接池状态
• 文件处理队列长度
• LLM API 调用成功率

🔒 安全考虑

• 输入验证和 SQL 注入防护
• API 速率限制
• 敏感信息脱敏
• 审计日志记录

📋 TODO

• 添加用户认证和权限控制
• 实现实时数据流处理
• 支持更多数据源适配
• 添加机器学习模型集成
• 完善监控和告警机制

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🆘 支持

如有问题或需要帮助，请：

• 提交 Issue
• 查看项目文档
• 联系维护团队

---

🎯 目标: 构建最专业的智能SOC后台分析平台
🚀 愿景: 让威胁检测与响应更加智能化和自动化