abdalmegedalfiky-ops/PhantomGuard

# PhantomGuard [](https://github.com/abdalmegied/PhantomGuard/actions/workflows/ci.yml/badge.svg) [](LICENSE) [](https://www.python.org/) AI 驱动的 SOAR pipeline 集成了 Claude API 与 Elasticsearch (ELK Stack)，用于快速检测 alerts、进行分析并采取适当的响应决策 —— 采用 safety-first design（默认 dry-run）。 ## 架构 ``` Elasticsearch (Kibana Security alerts) │ ▼ Collector (elastic_collector.py) │ normalize alert fields [FIX: nested field lookup] ▼ Enrichment (mitre_mapper.py) │ map keywords -> MITRE ATT&CK [EXPANDED: +20 techniques] ▼ AI Triage Engine (triage_engine.py) │ Claude API -> severity, classification, confidence, recommended_actions ▼ Decision Engine (decision_engine.py) │ AUTO_EXECUTE | ESCALATE_TO_ANALYST | NO_ACTION ▼ Notifications (notifications.py) [NEW] │ Slack webhook لما يحصل ESCALATE_TO_ANALYST (اختياري) ▼ Action Executor (executor.py) │ playbook YAML -> dry-run log (أو تنفيذ حقيقي لو فعّلته) ▼ Report Generator (report_generator.py) │ Markdown + JSON report لكل alert -> output_reports/ ▼ State Store (state_store.py) SQLite + INDEX على processed_at + pruning دوري [FIX] ``` ## 设计理念 - **基于置信度门控的自动化**：任何敏感 action（block_ip / isolate_host / disable_user）都不会自动执行，除非 AI confidence ≥ 0.85、severity 为 high/critical 且 classification 为 true_positive。否则，将转交由 Analyst review。 - **默认 DRY_RUN=true**：首次运行项目时，所有的 actions 仅会被记录到 log 中，而不会对任何真实系统执行实际操作。 - **审计追踪**：每个 alert 都会生成 Markdown + JSON 报告，其中包含 MITRE mapping、完整的 AI 分析、决策以及任何执行步骤。 - **Slack 通知**：当发生 ESCALATE_TO_ANALYST 时，系统会发送一条包含所有详细信息（severity, confidence, MITRE, reasoning, suggested actions）的 Slack message。 ## 设置 ``` pip install -r requirements.txt cp .env.example .env # 在 .env 中填充 ANTHROPIC_API_KEY 和 ES_API_KEY (或 ES_USERNAME/ES_PASSWORD) # 可选：添加 SLACK_WEBHOOK_URL 以用于 escalation notifications ``` ## 用法 ``` # 确保设置正确 python -m soar_ai.cli check-config # 运行一次循环（拉取最近 15 分钟） python -m soar_ai.cli run # 按照 POLL_INTERVAL_SECONDS 持续运行 python -m soar_ai.cli run --loop # 想在没有真实 ES/Claude 的情况下快速试用 UI？ python -m soar_ai.cli seed-demo # 在 http://localhost:5000 上运行 SOC console (Flask dashboard) python -m soar_ai.cli serve # Tests pytest tests/ -v pytest tests/ -v --cov=soar_ai --cov-report=term-missing ``` ## 控制台 (PhantomGuard Console) - **过滤/搜索**：支持按 severity 和 decision outcome 进行即时过滤，以及无需任何服务器往返的纯文本搜索。 - **告警详情**：完整的 AI 分析（summary + reasoning + classification），MITRE ATT&CK chips，decision rationale，以及终端风格的 execution log。 - **API endpoints**：`/api/metrics` 和 `/api/alerts` 返回用于 monitoring 的 JSON。 - 目前没有 auth — 被设计为供单用户使用的个人 MVP。 ## Bug 修复 (v1.1) | # | 文件 | 问题 | 解决方案 | |---|-------|---------|------| | 1 | `elastic_collector.py` | `src.get("kibana.alert.rule.name")` 总是返回 None（点号 key 而非嵌套查找） | 在所有字段替换为 `_dig()` + flat key fallback | | 2 | `seed_demo.py` | AUTO_EXECUTE execution_logs 是硬编码的字符串，而非真实的 playbook steps | 替换为实际的 `execute_action()` | | 3 | `cli.py` | already_processed alerts 被静默忽略，没有计数器 | 在 summary 中添加 `skipped_count` | | 4 | `cli.py` | `execute_action result.success` 未被监控 | 在表格中添加 "Exec OK" 列 + 记录失败情况 | | 5 | `seed_demo.py` | alert_id 总是 demo-001..005 → 重新运行会覆盖原 reports | 在每次运行时使用 timestamp 前缀 | | 6 | `config.py` | 没有 Slack 配置 | 添加 `SLACK_WEBHOOK_URL` | | 7 | `notifications.py` | 不存在 | 新文件：Slack webhook 集成 | | 8 | `mitre_mapper.py` | keywords 缺失（C2, mimikatz, DLL injection 等） | 添加了 +20 种 technique | | 9 | `webapp/app.py` | 没有 500 error handler | 添加 handler + `/api/metrics` + `/api/alerts` | | 10 | `requirements.txt` | 未添加 pytest | 添加 pytest + pytest-cov | | 11 | `state_store.py` | processed_at 上没有 index + 数据库会无限增大 | 添加 INDEX + `prune_old_records()` | ## 路线图（后续计划） - [ ] 将 `_REAL_HANDLERS` 与真实的 integrations 连接（Firewall API / EDR / IdP） - [ ] 为 Flask dashboard 提供 Basic auth - [ ] 除 Elasticsearch 外，支持 multi-index sources（Splunk, custom webhook） - [ ] 反馈循环：如果 Analyst 修改了 AI 的决策，则将其记录为 training signal - [ ] 在 dashboard 中加入 MTTD / MTTR 指标 ## 安全说明 这是一个防御性（blue-team 自动化）的 SOAR 项目。所有的 playbooks （`soar_ai/playbooks/*.yaml`）均为遏制响应措施 —— 项目中不包含任何攻击性代码或 exploit。

标签：DLL 劫持, Elasticsearch, Flask, PB级数据处理, SOAR, 大语言模型, 安全运维, 安全运营中心, 网络映射, 自动化响应, 逆向工具