Lightweight SOAR Platform

轻量化安全编排自动化与响应平台 V1，面向中小企业的私有化单实例部署方案。

---

核心能力

告警采集 → 归一化 → 智能降噪 → 事件关联 → 自动化响应 → 审批审计

能力	说明
多源采集	Webhook / Syslog（RFC 3164/5424 + CEF）/ Windows Event，支持 FortiGate、MDE、Palo Alto 等厂商适配器
智能降噪	白名单、去重，时间窗聚合，噪声压制，严重度重算；内置 20+ 基线规则，支持热更新
事件关联	correlation_key + 攻击链模式识别（侦察 → 利用 → 提权 → 横移 → 外传）
自动响应	防火墙封禁 / EDR 处置 / 邮件通知 / Webhook 回调；支持影响范围评估与自动回滚
审批流	高风险动作需人工审批，支持批量审批、审批模板、自动降级
试运行模式	默认启用，规则验证后再切生产；所有动作强制审计留痕
可观测性	Prometheus 指标 / Grafana 看板 / 结构化日志 / trace_id 全链路追踪

---

快速开始

前置要求

• Docker Engine ≥ 20.10、Docker Compose ≥ 2.0
• Linux（Ubuntu 20.04+ / CentOS 8+ / Debian 11+）或 macOS
• CPU 4 核 / 内存 8GB / 磁盘 100GB

1. 克隆与配置

git clone https://github.com/example/soar.git lightweight-soar-agent
cd lightweight-soar-agent

# 复制环境变量模板并编辑
cp .env.example .env
# 至少设置：
#   POSTGRES_PASSWORD（数据库密码）
#   JWT_SECRET_KEY（≥32 字节，推荐 `openssl rand -hex 32`）

2. 启动完整服务

docker compose up -d

# 检查服务状态
docker compose ps

# 健康检查
curl http://localhost:8000/health

服务列表：soar-app（API）、soar-syslog（采集器）、soar-db（PostgreSQL 14）、soar-redis（Redis 7）。

3. 访问

入口	地址
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc
Prometheus	http://localhost:9090 （需启用 with-monitoring profile）
Grafana	http://localhost:3000 （需启用 with-monitoring profile）

默认账号：admin，初始密码在容器启动日志或 /data/initial_password.txt 中。

---

开发环境

依赖服务（Docker）

docker compose -f docker-compose.dev.yml up -d db redis

安装依赖

python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

配置

确保 .env 中数据库连接指向 Docker 映射端口（默认 localhost:5433 和 localhost:6380）。

运行迁移

python -m alembic upgrade head

启动服务

# API 服务（热重载）
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Syslog 采集器（单独终端）
python -m connectors.syslog

代码质量

# 格式化
black .

# Lint
ruff check . && flake8 .

# 类型检查
mypy core/ app/ connectors/ executors/

# 预提交钩子
pre-commit install

---

测试

# 全量测试
pytest tests/unit/ tests/integration/ -v

# 单文件
pytest tests/unit/test_denoise.py -v

# 带覆盖率
pytest --cov=app --cov=core --cov-report=term-missing

覆盖率要求：整体 ≥ 80%，denoise / response / audit 模块 ≥ 90%。

---

架构

数据流

外部告警 → connectors/ → ingest → normalize → denoise → incident → response → executors/
                  ↓            ↓           ↓            ↓           ↓
              raw_alerts  normalized  rule_metrics  incidents  approval_tasks + audit_logs

核心模块

目录	职责
core/	配置（pydantic-settings）、数据库（SQLAlchemy 2.0 async）、ORM 模型、认证、日志、指标、中间件
app/	业务逻辑层：ingest、normalize、denoise（5 级降噪管道）、incident、response（审批 + 执行 + 回滚）、audit
connectors/	告警源适配器（webhook、syslog、厂商解析器）
executors/	响应执行器（firewall、EDR、notification、webhook）；基于注册表模式
web/	Vue.js 3 + Element Plus 静态前端（独立部署时由 Nginx 服务）
deploy/	Docker 配置、PostgreSQL 初始化脚本、Nginx 配置、健康检查脚本
migrations/	Alembic 数据库迁移脚本

关键设计

• 异步优先：SQLAlchemy 2.0 async + httpx async client
• Pydantic v2：所有数据模型均使用 Pydantic v2 进行验证
• 注册表模式：执行器 @register_executor / 适配器 @register_adapter
• 中间件栈：TraceId → SecurityHeaders → RateLimit → Prometheus → CORS
• ** Append-only 审计**：audit_logs 表受数据库触发器保护（禁止 UPDATE/DELETE/TRUNCATE）
• 单实例部署：不依赖外部 LLM、消息队列、微服务

---

API 概览

所有接口遵循统一响应格式 {code, msg, data, trace_id}，路由前缀为 /api/v1/。

领域	主要端点
认证	POST /api/v1/auth/login
告警	POST /api/v1/ingest/webhook/{source}、GET /api/v1/alerts
降噪规则	GET /api/v1/denoise/rules、POST /api/v1/denoise/reload
事件	GET /api/v1/incidents、POST /api/v1/incidents/{id}/close
响应	POST /api/v1/response/dispatch、POST /api/v1/response/approve/{task_id}
审计	GET /api/v1/audit/logs、GET /api/v1/audit/export
看板	GET /api/v1/dashboard/summary、GET /api/v1/dashboard/trend

完整 API 文档见 http://localhost:8000/docs（服务启动后）。

---

配置参考

关键环境变量（.env）：

变量	默认值	说明
APP_ENV	production	production / development / test
DATABASE_URL	—	postgresql+asyncpg://user:pass@host:5432/db
REDIS_URL	redis://redis:6379/0	Redis 连接串
JWT_SECRET_KEY	—	JWT 签名密钥，必须 ≥ 32 字节
SOAR_DRY_RUN	true	默认试运行模式，所有响应动作仅记录不执行
SOAR_ROLLBACK_ENABLED	true	是否启用自动回滚
RATE_LIMIT_PER_MINUTE	100	每 IP 每分钟请求上限
RETENTION_AUDIT_LOG_DAYS	365	审计日志保留天数

---

部署拓扑

                            ┌──────────────┐
                         →  │   Nginx      │  (可选，反向代理 + HTTPS)
                            │  (:80/:443)  │
                            └──────┬───────┘
                                   │ :8000
                            ┌──────▼───────┐
                            │  soar-app    │  FastAPI + APScheduler
                            │  uvicorn     │
                            └──────┬───────┘
                                   │
               ┌───────────────────┼───────────────────┐
               │                   │                    │
        ┌──────▼───────┐   ┌───────▼──────┐   ┌───────▼──────┐
        │  soar-db     │   │  soar-redis  │   │  soar-syslog │
        │  PostgreSQL  │   │  Redis 7     │   │  UDP/TCP 514 │
        │  5432        │   │  6379        │   │              │
        └──────────────┘   └──────────────┘   └──────────────┘

可选监控栈（docker compose --profile with-monitoring up -d）：Prometheus + Grafana。

---

文档索引

类型	文档
需求规格	docs/01-需求规格说明书SRS.md
工程规范	docs/02-驾驭工程强制规范.md
架构设计	docs/design/01-系统架构设计.md
数据库设计	docs/design/02-数据库设计.md
接口契约	docs/design/03-接口契约规范.md
采集归一化	docs/design/04-采集归一化.md
降噪关联	docs/design/05-降噪关联.md
自动化处置	docs/design/06-自动化处置.md
Web UI	docs/design/07-WebUI.md
开发文档	docs/dev/开发文档.md
用户手册	docs/user/用户手册.md
排查手册	docs/ops/问题排查手册.md

---

版本历史

详见 CHANGELOG.md。

---

许可证

Apache License 2.0，详见 LICENSE。