leivyfrostbispo1999-commits/sentinela

# Sentinela SOC 5.6 Sentinela SOC 5.6 是一个教育/专业性质的 mini-SIEM，其架构灵感来源于真实的 SOC 环境。 该项目演示了完整的安全 pipeline：事件的生成与收集、通过 Kafka 的摄入、基于 YAML 规则的检测、结合 Redis 状态存储的时序关联、Threat Intelligence、PostgreSQL 持久化、基于 token/JWT 的认证、Prometheus 指标以及实时的 SOC dashboard。 它并不旨在替代 Splunk、Elastic、QRadar、Wazuh 或其他企业级平台。其目标是展示技术成熟度、代码组织能力、默认安全设计以及可扩展能力。 ## 5.6 版本更新内容 - Redis 作为 `rule_engine` 的状态存储，并自动回退到内存模式。 - JWT HMAC-SHA256 认证，同时保持与 `X-SENTINELA-TOKEN` 的兼容性。 - `/auth/token` Endpoint，用于使用旧版 token 签发演示用 JWT。 - 使用 `pytest` 对评分、检测、认证和 `simulated_block` 进行测试。 - 使用 `pytest` 和 `py_compile` 的 GitHub Actions。 - Redis 服务已添加到 Docker Compose 中。 - 教育配置 Profile `kafka-lab`，包含额外的 Kafka broker，且不会破坏单 broker 模式。 - 事件演示模式，包含 `Simular Ataque` 按钮和 `Incident Timeline`。 - 更新 README 以反映 5.6 版本及其技术决策。 ## 架构 ``` simulator / log_collector | v Kafka topic: raw_logs | v rule_engine | +--> Redis state store | fallback: in-memory state | v Kafka topic: security_alerts | v alert_sink | v PostgreSQL | v dashboard_api | v dashboard_web ``` ## 核心功能 - 基于 Kafka 的事件驱动架构。 - 通过 `raw_logs` 摄入原始事件。 - 通过 `security_alerts` 发布丰富化后的告警。 - 可配置的 YAML 检测规则。 - 按照IP、服务、端口和事件类型进行多维度的时序关联。 - 基于 Redis 的关联状态，具备安全的内存回退机制。 - 本地和模拟的外部 Threat Intelligence。 - 基于事件类型、敏感端口、频率、序列和 IOC 匹配的风险评分。 - 使用 `simulated_block` 进行安全的自动化响应。 - PostgreSQL 持久化，具备向后兼容的 schema 演进。 - 具备旧版 token 和 JWT 认证的 REST API。 - 兼容 Prometheus 的 `/metrics` Endpoint。 - 包含过滤器、搜索、排名、分析、攻击地图和 Drill-down 功能的 SOC dashboard。 - 具备受控事件模拟和可视化事件时间线的演示模式。 - 包含测试和 Python 编译检查的 CI pipeline。 ## 服务 | 服务 | 角色 | | --- | --- | | `kafka` | 默认使用的单 broker，用于本地事件流传输。 | | `redis` | 规则引擎关联窗口的状态存储。 | | `db` | 用于告警历史的 PostgreSQL 数据库。 | | `log_collector` | 向 Kafka 生成基准日志事件。 | | `simulator` | 生成正常流量、突发流量、IOC 和攻击序列。 | | `rule_engine` | 应用规则、关联、Threat Intelligence 和风险评分。 | | `alert_sink` | 消费丰富化后的告警并将其持久化到 PostgreSQL 中。 | | `dashboard_api` | 暴露健康检查、认证、告警和指标 Endpoint。 | | `dashboard_web` | 由 Nginx 提供服务的静态 SOC dashboard。 | ## 环境要求 - Docker - Docker Compose - 用于本地测试的 Python 3.11+ ## 本地运行 ``` docker compose up -d --build ``` 检查容器： ``` docker ps ``` 读取最近的日志： ``` docker compose logs --tail=120 ``` 打开 dashboard： ``` http://localhost:8080 ``` ## 接口端点 API 基础 URL： ``` http://localhost:5000 ``` | 接口端点 | 描述 | 认证 | | --- | --- | --- | | `GET /health` | API 和数据库健康检查。 | 无 | | `POST /auth/token` | 使用旧版 token 签发演示用 JWT。 | 旧版 token | | `POST /demo/simulate-attack` | 注册受控的演示事件。 | 是 | | `GET /alertas?range=5m` | 所选时间范围内的告警。 | 是 | | `GET /alertas?range=1h` | 所选时间范围内的告警。 | 是 | | `GET /metrics` | 兼容 Prometheus 的指标。 | 是 | 支持的告警时间范围： - `5m` - `15m` - `1h` - `24h` ## 身份验证 受保护的 Endpoint 接受旧版演示 token： ``` X-SENTINELA-TOKEN: sentinela-demo-token ``` 它们也接受 Bearer 认证： ``` Authorization: Bearer sentinela-demo-token ``` 或者由 `/auth/token` 签发的 JWT： ``` Invoke-RestMethod ` -Method Post ` -Uri "http://localhost:5000/auth/token" ` -Headers @{ "X-SENTINELA-TOKEN" = "sentinela-demo-token" } ``` 相关的环境变量： ``` SENTINELA_API_TOKEN=sentinela-demo-token SENTINELA_JWT_SECRET=sentinela-demo-jwt-secret SENTINELA_JWT_TTL_SECONDS=3600 ``` 为了保持本地演示的兼容性，Dashboard 继续使用旧版 token 头。 ## 演示模式 Sentinela SOC 5.6 包含一个直观的事件演示模式，专为演示和面试官审查而设计。 使用方法： ``` docker compose up -d --build ``` 打开： ``` http://localhost:8080 ``` 点击： ``` Simular Ataque ``` Dashboard 将会： - 高亮显示 `INCIDENTE CRÍTICO EM ANDAMENTO` (正在进行的关键事件)。 - 更新主要卡片。 - 在全局地图上显示动态攻击线。 - 渲染 `Incident Timeline`。 - 展示各个阶段，例如接收到事件、识别可疑 IP、暴力破解检测、YAML 规则匹配、Threat Intelligence 匹配以及 `simulated_block`。 按钮调用的 API Endpoint 为： ``` POST /demo/simulate-attack ``` 它与其他受保护的 Endpoint 需要相同的身份验证，并在 PostgreSQL 中记录演示告警。它不会执行防火墙规则、`iptables` 或任何真实的拦截操作。响应动作仅表示为： ``` simulated_block=true ``` ## 事件时间线 UX 点击 `Simular Ataque` (模拟攻击) 后，Dashboard 会显示一个具有 SOC 风格的调查时间线，包含七个相连的阶段。该视图突出显示了攻击者、检测序列、规则关联以及安全的响应决策。 `Primary Attacker` (主要攻击者) 卡片总结了： - 主要攻击者 IP。 - 初始向量。 - 最高严重级别。 - SOC 响应状态。 `Incident Summary` (事件摘要) 为演示、视频和面试提供了简短的叙述。它说明系统检测到了一次受控攻击，关联规则将事件提升至 `CRITICAL` (严重) 级别，并且系统注册了 `simulated_block`，而未进行真实的拦截。 此功能是用于教育和演示的。它旨在展示检测、关联和响应逻辑，同时保持环境的安全。 ## Redis 状态存储 规则引擎使用 Redis 按 IP 存储关联窗口： ``` REDIS_URL=redis://redis:6379/0 REDIS_STATE_ENABLED=true CORRELATION_WINDOW_SECONDS=300 ``` 如果 Redis 不可用，规则引擎会记录故障并回退到内存状态。这使得演示具有弹性的同时，也展示了预期的生产部署方向。 ## 噪声削减与 SOC 关联 Sentinela SOC 5.6 在不删除历史保留记录的情况下，降低了告警 pipeline 中的噪声。 工作原理： - 具有相同 `ip`、`event_type`、`status`、`port` 和 `threat_category` 的重复告警会被合并。 - 在配置的窗口内多次发出的告警将按 IP 和状态进行速率限制。 - 相关事件在可能的情况下会按 IP 聚合为一个单独的合并告警。 - 告警保留 `first_seen`、`last_seen`、`occurrence_count`、`ports`、`services`、`event_types` 和 `aggregated` 字段。 - Redis 在可用时存储关联状态；如果 Redis 离线，内存回退机制可确保演示继续工作。 重要区别： - 原始事件仍然是 SIEM 历史记录的一部分。 - 合并后的告警是 Dashboard 使用的视图，旨在加快 SOC 分流速度。 - 演示模式可以通过 `mode=demo` 进行隔离，以便展示内容不会与历史噪声混淆。 ## 检测规则 规则配置于： ``` services/rule_engine/rules.yaml ``` 支持的字段： - `name` - `enabled` - `priority` - `description` - `conditions` - `threshold` - `window_seconds` - `min_risk` - `risk` - `status` - `tags` 规则引擎会忽略被禁用的规则，优先应用高优先级的匹配项，并在 YAML 文件无效时使用安全的回退规则集。 ## 模拟拦截 真实的拦截功能仍处于禁用状态： ``` ENABLE_BLOCK=false ``` 不会执行任何防火墙、`iptables` 或主机级别的拦截操作。高风险事件会被标记为： ``` simulated_block=true ``` 这使得项目在用于演示和作品集审查时保持安全，同时又保留了 SOC 响应的概念。 ## 可观测性 API 暴露了 Prometheus 格式的指标： ``` http://localhost:5000/metrics ``` 指标包括： - `sentinela_events_total` - `sentinela_critical_events_total` - `sentinela_ioc_events_total` - `sentinela_events_by_type_total` 参考配置： ``` infra/prometheus/prometheus.yml ``` ## Kafka 多 Broker 实验室 为了在本地演示中保持简单和可靠，默认模式仍然使用单个 Kafka broker。 5.6 版本添加了一个教育性质的 Compose Profile： ``` docker compose --profile kafka-lab up -d --build ``` 这会启动一个额外的 Kafka broker 服务，用于架构讨论和实验。正常的演示流程并不需要它，也不会改变默认的单 broker 行为。 ## 运行测试 安装测试依赖： ``` py -m pip install pytest py -m pip install -r services/rule_engine/requirements.txt py -m pip install -r services/dashboard_api/requirements.txt ``` 运行： ``` py -m pytest -q ``` 编译服务文件： ``` py -m py_compile services\log_collector\main.py services\rule_engine\main.py services\alert-sink\main.py services\dashboard_api\main.py services\simulator\main.py ``` ## CI GitHub Actions 工作流： ``` .github/workflows/ci.yml ``` Pipeline 运行： - 依赖安装 - Python 编译检查 - `pytest` ## 技术栈 - Python - Flask - Kafka - Redis - PostgreSQL - Docker Compose - Nginx - HTML, CSS 和 JavaScript - Chart.js - Prometheus client 库 - 基于 YAML 的规则 - GitHub Actions - Pytest ## 技术决策历史 - **4.0：** 可视化 SOC dashboard、攻击地图、本地 Threat Intelligence 和模拟拦截。 - **5.0：** YAML 规则、时间范围、Prometheus 指标和更丰富的分析。 - **5.5：** 生产成熟度改进，包括 API token 认证、文档、可观测性和仓库清理。 - **5.6：** Redis 状态存储、JWT 兼容性、pytest 覆盖率、CI 工作流以及教育性质的 Kafka 多 broker 配置 Profile。 - **5.6 演示模式：** 带有可视化时间线的受控事件模拟；不执行真实的拦截操作。 ## 仓库结构 ``` services/ alert-sink/ dashboard_api/ dashboard_web/ log_collector/ rule_engine/ simulator/ docs/ infra/ scripts/ tests/ .github/ docker-compose.yml README.md .gitignore ``` ## 诚实的局限性 - Kafka 在默认情况下仍然作为单 broker 运行。 - 额外的 Kafka broker 是出于教育目的，并非完整的生产集群。 - Redis 提高了关联状态的成熟度，但要实现完整的分布式流处理，还需要更强的分区/状态保证。 - 外部 Threat Intelligence 是为了作品集的安全使用而模拟的。 - JWT 经过刻意简化，适用于演示，而非一个完整的身份平台。 - 没有 RBAC、多租户或生产级别的身份提供商。 - 尚未引入 schema registry 或正式的死信队列。 ## 下一步计划 - 添加 schema 验证和死信主题。 - 添加按 IP 或租户的 Kafka 分区策略。 - 添加 Alembic 或其他版本化的迁移工具。 - 为 Kafka lag、Redis 健康状况和处理延迟添加服务级别指标。 - 添加 Grafana Dashboard。 - 添加使用 Docker Compose 的集成测试。

标签：Docker, Docker Compose, GitHub Actions, HTTP/HTTPS抓包, JWT认证, Kafka, PostgreSQL, Python, Redis, SonarQube插件, Splunk替代, URL发现, YAML规则, 事件关联, 事件驱动架构, 云计算, 威胁情报, 安全仪表盘, 安全信息与事件管理, 安全检测, 安全模拟, 安全运营中心, 安全防御评估, 开发者工具, 开源SIEM, 开源框架, 微服务架构, 态势感知, 持续集成, 搜索引擎查询, 搜索引擎爬取, 数据可视化, 无后门, 无线安全, 日志采集, 测试用例, 版权保护, 网络安全, 网络安全教学, 网络映射, 自动化响应, 自动笔记, 自定义请求头, 规则引擎, 逆向工具, 隐私保护