GurukiranShiv/sentinelgate-incident-commander

# 基于证据把关的事件指挥官助手     一款高级的 SOC/SOAR 风格事件响应助手，能够生成特定事件的调查清单、遏制计划、证据要求、升级摘要、MITRE 风格攻击故事线、审批关卡、回滚指南、案件历史记录以及证据关系图。 本项目被设计为一个**作品集级的网络安全项目**，旨在展示真实的事件响应思维，而不仅仅是展示一个静态的清单生成器。 ## 项目摘要 安全团队通常需要快速响应勒索软件、网络钓鱼、云 IAM 滥用、端点恶意软件、内部威胁和数据泄露等事件。普通的清单可以告诉分析师该做什么，但可能无法解释**在采取有风险的遏制行动之前需要哪些证据**。 本项目通过使用**基于证据把关的响应逻辑**解决了这个问题。 针对每个事件，助手会询问： - 这是哪种类型的事件？ - 已经掌握了哪些证据？ - 哪些资产受到了影响？ - 哪些操作可以安全地自动化？ - 哪些操作需要分析师审批？ - 哪些操作需要 IR 负责人或管理层审批？ - 如果操作错误可能会出现什么问题？ - 需要什么样的回滚计划？ ## 本项目的独特之处 大多数基础的 SOAR 项目会生成如下静态步骤： ``` Isolate host Disable account Block IP Escalate incident ``` 本项目更进一步，生成具有决策意识的操作，例如： ``` Action: Suspend user access Approval Level: Red Status: Missing Evidence - Do Not Execute Yet Verified Evidence: Business continuity plan Missing Evidence: Active exfiltration, HR/legal approval, manager coordination Risk If Wrong: Could create employment/legal risk and disrupt business Rollback: Reinstate least-privilege access after formal decision ``` 这使得本项目更接近真实的 SOC 事件指挥官在活跃事件期间的思考方式。 ## 核心功能 - 动画版 SOC 指挥中心仪表盘 - 带有 Swagger 文档的 FastAPI 后端 - 基于证据把关的 SOAR 决策引擎 - 10 个事件响应剧本 - 调查清单生成 - 遏制计划生成 - 证据列表生成 - 升级摘要生成 - MITRE 风格攻击故事线 - 证据关系图 - 绿/黄/红审批矩阵 - 错误风险与回滚指南 - 案件历史和 SOC 风格搜索 - 异步 SOAR 任务模拟 - SQLite 本地案件存储 - 准备好接入 PostgreSQL / Redis / Celery / Neo4j / OpenSearch 的架构 - 验证脚本和 Pytest 测试 - 可选的 Docker Compose 部署 - 可选的 Next.js 前端启动模板 ## 支持的事件类型 | 事件类型 | 描述 | |---|---| | 网络钓鱼 / BEC | 可疑邮件、凭证收集、商业电子邮件妥协 | | 勒索软件 | 加密活动、勒索信、文件修改、备份目标 | | 凭证泄露 | 账户接管、不可能的旅行、MFA 滥用、可疑登录 | | 端点恶意软件 | 可疑进程、恶意软件行为、端点妥协 | | 云 IAM 滥用 | 未经授权的 API 调用、访问密钥创建、权限提升 | | 数据泄露 | 异常出口流量、敏感数据移动、外部传输 | | Web 应用程序攻击 | WAF 警报、注入尝试、可疑的 Web 活动 | | 横向移动 | 内部侦察、远程执行、凭证重用 | | 内部威胁 | DLP 警报、异常访问、外部共享、HR/法律工作流 | | 漏洞利用 | 公开 CVE 滥用、漏洞利用活动、暴露的服务妥协 | ## 系统接收的输入 分析人员输入： | 输入字段 | 示例 | |---|---| | 事件类型 | 勒索软件 / 大规模加密 | | 严重程度 | 低、中、高、严重 | | 环境 | Windows 企业版 / 文件服务器段 | | 分析师 / 团队 | SOC Analyst、SOC L2、IR Lead | | 受影响资产 | WIN-FILE-01, HR-SHARE, Backup-Repository-01 | | 指标 / 证据 | 勒索信、活动加密、EDR 进程树 | | 分析师备注 | 文件服务器上发现多个文件被加密及勒索信 | ## 输出示例 对于勒索软件事件，助手可以生成： ``` Attack Storyline: Initial Access → Privilege Escalation → Lateral Movement → Backup Targeting → Encryption/Extortion Evidence-Gated Action: Isolate infected endpoint or server Approval: Yellow - Analyst approval required Verified Evidence: Active encryption, ransom note, EDR process tree, mass file modification Missing Evidence: Known ransomware hash Risk If Wrong: Could disconnect critical services or break forensic visibility Rollback: Remove isolation only after IR lead validates eradication and monitoring ``` ## 架构 ``` Dashboard UI ↓ FastAPI API Layer ↓ Evidence-Gated Decision Engine ↓ Case Database: SQLite locally / PostgreSQL in Docker mode ↓ Async Job Layer: Local async simulation / Celery-ready worker ↓ Graph Layer: Inline graph output / Neo4j-ready persistence ↓ Search Layer: Local JSONL search / OpenSearch-ready indexing ↓ Human Approval Log ``` ## 技术栈 | 层级 | 技术 | |---|---| | 后端 API | FastAPI | | 数据验证 | Pydantic | | 数据库 ORM | SQLAlchemy | | 本地数据库 | SQLite | | 高级数据库选项 | PostgreSQL | | 异步任务模拟 | 本地任务队列 | | 高级队列选项 | Redis + Celery | | 图概念 | 证据关系图 | | 高级图选项 | Neo4j | | 搜索概念 | 本地 JSONL 搜索索引 | | 高级搜索选项 | OpenSearch | | 前端 | HTML, CSS, JavaScript | | 可选前端 | Next.js | | 测试 | Pytest | | 部署选项 | Docker Compose | ## 文件夹结构 ``` app/ main.py FastAPI routes schemas.py Request/response models playbooks.py Incident playbooks decision_engine.py Evidence-gated SOAR logic database.py Database setup models.py SQLAlchemy models repository.py Case persistence worker.py Worker task structure services/ commander.py Main report generation service evidence_graph.py Graph builder search_index.py Search indexing job_queue.py Async job queue static/ index.html Dashboard UI styles.css Dashboard styling app.js Frontend logic and API calls scripts/ validate_playbooks.py Validates playbooks and response structure reset_demo_data.py Clears local demo cases and search history tests/ test_playbooks.py Unit tests frontend-next/ Optional Next.js frontend starter Screenshots/ README screenshots ``` ## 本地运行 ### 1. 克隆仓库 ``` git clone https://github.com/YOUR-USERNAME/evidence-gated-incident-commander.git cd evidence-gated-incident-commander ``` 如果您已经下载了项目的 ZIP 文件，请在项目文件夹内打开 PowerShell。 ### 2. 创建虚拟环境 ``` python -m venv venv ``` ### 3. 激活虚拟环境 ``` venv\Scripts\activate ``` ### 4. 安装依赖项 ``` pip install -r requirements.txt ``` ### 5. 验证剧本 ``` python scripts/validate_playbooks.py ``` 预期输出： ``` Validation passed: 10 playbooks include evidence gates, architecture trace, graph output, and SOC-ready response sections. ``` ### 6. 运行测试 ``` pytest ``` 预期输出： ``` 5 passed ``` ### 7. 启动应用程序 ``` uvicorn app.main:app --reload ``` 打开仪表盘： ``` http://127.0.0.1:8000 ``` 打开 FastAPI Swagger 文档： ``` http://127.0.0.1:8000/docs ``` ## 截图前清理演示数据 要删除旧的测试用例并保持案件历史记录整洁： ``` python scripts/reset_demo_data.py ``` 然后重启应用程序： ``` uvicorn app.main:app --reload ``` ## API Endpoints | 方法 | Endpoint | 用途 | |---|---|---| | GET | `/api/health` | 检查应用程序健康状况 | | GET | `/api/incident-types` | 列出支持的事件类型 | | POST | `/api/generate` | 生成指挥官响应计划 | | POST | `/api/jobs` | 启动异步 SOAR 任务模拟 | | GET | `/api/jobs/{job_id}` | 检查异步任务状态 | | GET | `/api/cases` | 查看已存储的案件 | | GET | `/api/cases/{case_id}` | 查看特定案件 | | GET | `/api/search?q=keyword` | 搜索已存储的事件 | | POST | `/api/approvals` | 记录审批决定 | | POST | `/api/report/markdown` | 生成 Markdown 报告 | ## API 请求示例 ``` curl -X POST "http://127.0.0.1:8000/api/generate" ` -H "Content-Type: application/json" ` -d '{"incident_type":"ransomware","severity":"critical","environment":"Windows enterprise / file server segment","affected_assets":["WIN-FILE-01","HR-SHARE","Backup-Repository-01"],"indicators":["ransom note","active encryption","mass file modification","EDR process tree","suspicious admin logon"],"notes":"Multiple shared folders are encrypted and a ransom note was found."}' ``` ## 截图 ### 1. SOC 指挥中心仪表盘  ### 2. 事件输入表单  ### 3. 勒索软件指挥官简报  ### 4. SOAR 生命周期  ### 5. 证据关系图  ### 6. 基于证据把关的遏制行动  ### 7. 审批矩阵与 MITRE 映射  ### 8. 案件历史与 SOC 搜索  ### 9. FastAPI Swagger 文档  ### 10. 验证与测试  ## Docker Compose 运行 使用 Docker 模式以展示更高级的 SOC/SOAR 架构。 ``` docker compose up --build ``` 然后打开： ``` http://127.0.0.1:8000 ``` Neo4j 浏览器： ``` http://127.0.0.1:7474 ``` OpenSearch endpoint： ``` http://127.0.0.1:9200 ``` 停止服务： ``` docker compose down ``` 移除 volumes： ``` docker compose down -v ``` ## 可选的 Next.js 前端 默认仪表盘已由 FastAPI 提供服务。其中包含一个可选的 Next.js 启动模板，用于未来的前端扩展。 ``` cd frontend-next npm install npm run dev ``` 打开： ``` http://127.0.0.1:3000 ``` ## 准确性声明 本项目不应被描述为“具有 98% 的现实世界准确度”。 请改用以下措辞： ``` The system uses a 98%+ playbook confidence target based on playbook coverage, evidence completeness, and response consistency. Real-world accuracy would require validation using historical incidents, analyst review, tabletop exercises, false positives, and false negatives. ``` ## 面试解释说明 使用此解释说明： ``` I built an Evidence-Gated Incident Commander Assistant to simulate how a SOC/SOAR platform supports incident response decisions. Instead of generating static checklists, the system maps each incident type to investigation steps, evidence requirements, containment actions, MITRE-style attack storylines, approval gates, risk-if-wrong notes, rollback guidance, and escalation summaries. The unique part is the evidence-gated decision engine. The tool does not blindly recommend risky containment. For example, collecting logs can be Green and automation-ready, but disabling an account, isolating a production host, or suspending a user can be Yellow or Red depending on the evidence available and the business risk. I used FastAPI for the API layer, SQLAlchemy for case persistence, local async jobs to simulate SOAR background processing, an evidence graph that is Neo4j-ready, and a search index that can work locally or with OpenSearch. The UI is animated, but the main technical value is the backend decision logic and evidence validation process. ``` ## GitHub 仓库描述 ``` Advanced SOC/SOAR Incident Commander Assistant with evidence-gated response logic, investigation checklists, containment plans, MITRE-style attack storylines, approval gates, rollback guidance, case persistence, async job simulation, graph output, and SOC search. ``` ## GitHub 上传注意事项 请勿上传以下这些文件夹/文件： ``` venv/ .pytest_cache/ __pycache__/ Screenshots.zip *.db *.sqlite ``` 保留此文件夹： ``` Screenshots/ ``` 因为 README 中会用到这些图片。 ## 作者 **Gurukiran Shivashankar** 网络安全硕士 SOC Analyst

标签：AV绕过, FastAPI, Python, SOAR, 安全运营, 扫描框架, 搜索引擎查询, 无后门, 测试用例, 版权保护, 逆向工具