RohithJoginpelly/ai-soc-copilot

# AI SOC Copilot [](https://github.com/RohithJoginpelly/python-cloud-soc-triage-engine/actions/workflows/test.yml)       ## 概述 AI SOC Copilot 是一个多源、基于证据的安全调查平台，专为蓝队和 SOC 分析师工作流而构建。 该平台摄取并标准化 AWS CloudTrail、Wazuh 和 Snort 遥测数据；关联相关活动；计算确定性风险；将发现映射到 MITRE ATT&CK；生成经过验证的 Copilot 辅助内容；并在安全的案例管理工作流中存储调查记录。 该项目在本地运行，包含脱敏的示例遥测数据和确定性后备 Copilot 提供程序，因此审查者无需 AWS 账户、付费服务或外部 AI 凭证即可重现完整的工作流。 ## 项目影响 | 功能 | 验证结果 | |---|---| | 遥测源 | AWS CloudTrail、Wazuh 和 Snort | | 多源演示事件 | 5 个标准化事件 | | 跨源关联 | 1 个 SSH 入侵发现 | | 风险优先级 | P1 紧急，100/100 | | MITRE ATT&CK 覆盖范围 | T1595、T1110.001 和 T1078 | | 持久化案例工作流 | 状态、分配、笔记和审计追踪 | | Copilot 行为 | 基于证据的输出，带有明确的不确定性 | | 自动化测试 | 413 个通过的测试 | | 部署 | 加固的非 root Docker 容器 | | 运行时模型 | 默认离线后备；可选外部提供程序 | ## SOC 工作流 1. 摄取 CloudTrail、Wazuh 和 Snort 遥测数据。 2. 验证事件并将其标准化为通用 schema。 3. 关联相关的端点、身份验证和网络活动。 4. 计算确定性的严重性和风险。 5. 将证据映射到 MITRE ATT&CK 技术。 6. 构建基于证据的分诊包。 7. 生成经过验证的 Copilot 总结、调查步骤和草稿笔记。 8. 将事件存储在 SQLite 中，并保留仅追加的审计历史。 9. 对分析师进行身份验证并实施基于角色的访问控制。 10. 通过 FastAPI 仪表板分配、调查、更新、解决和关闭案例。 ## 本项目的突出之处 本项目超越了单纯的告警生成。它展示了 SOC 平台如何在一个可重现的系统中，将检测工程、跨源关联、可解释的风险评分、MITRE ATT&CK、AI 安全、分析师工作流、可审计性、API 安全性、自动化测试以及加固部署结合在一起。 Copilot 不会自动控制威胁，也不会将不受信任的日志内容视为指令。分析师仍然负责验证和响应决策。 ## 平台截图 ### 安全案例队列  ### 关联事件与 MITRE ATT&CK 映射  ### 基于证据的 Copilot 评估  ### 仅追加的审计时间线  ## 演示视频 观看完整的 AI SOC Copilot V2 演示： [查看 AI SOC Copilot v2.0.1 演示](https://github.com/RohithJoginpelly/ai-soc-copilot/releases/tag/v2.0.1) 此演示涵盖了多源事件关联、确定性风险评分、MITRE ATT&CK 映射、基于证据的 Copilot 辅助、案例管理和审计历史。 ## 架构 ``` CloudTrail, Wazuh, and Snort telemetry | v Input validation and normalization | v Cross-source correlation | v Deterministic risk scoring and MITRE ATT&CK mapping | v Evidence-grounded Copilot assistance | v Persistent SOC case management and audit trail | v Authenticated FastAPI analyst dashboard ``` ## 核心功能 * 解析 AWS CloudTrail 风格的 JSON 日志 * 检测可疑的 IAM、root、S3、CloudTrail 和安全组活动 * 使用关联逻辑检测多步云入侵行为 * 将检测结果映射到 MITRE ATT&CK 战术和技术 * 通过用户和 IP 上下文文件添加本地信息丰富 * 分配严重性和风险评分 * 将事件存储在本地 SQLite 案例数据库中 * 提供经过身份验证的、基于角色的 FastAPI 仪表板用于 SOC 分诊 * 支持分析师案例状态更新和笔记 * 生成 Markdown 事件报告 * 包含 SOC 操作手册 * 包含自动化 pytest 覆盖率 * 支持基于 Docker 的本地执行 * 完全离线运行，无云成本 ## 检测覆盖范围 | 规则 ID | 检测内容 | 严重性 | | ------------ | ------------------------------------------ | -------- | | AWS-AUTH-001 | 多次登录失败后成功 | High | | AWS-IAM-001 | 创建了新的 IAM 访问密钥 | Medium | | AWS-IAM-002 | 疑似 IAM 权限提升 | High | | AWS-LOG-001 | CloudTrail 日志记录被修改或禁用 | Critical | | AWS-ROOT-001 | 检测到 root 账户控制台登录 | Critical | | AWS-S3-001 | 疑似公开的 S3 存储桶暴露 | High | | AWS-NET-001 | 安全组对互联网开放 | High | | AWS-CORR-001 | 疑似云账户入侵链 | Critical | ## 关联检测 本项目包含一个高级关联规则，用于检测可能的云账户入侵链。 示例攻击链： * 控制台登录活动 * 访问密钥创建 * IAM 权限更改 * CloudTrail 日志记录被修改 当在短时间窗口内检测到此序列时，引擎会创建： AWS-CORR-001 疑似云账户入侵链 这展示了超越简单单事件匹配的检测逻辑。 ## MITRE ATT&CK 映射 | 规则 ID | MITRE 技术 | | ------------ | ----------------------------------------- | | AWS-AUTH-001 | T1110 Brute Force | | AWS-IAM-001 | T1098 Account Manipulation | | AWS-IAM-002 | T1098 Account Manipulation | | AWS-LOG-001 | T1562.008 Disable or Modify Cloud Logs | | AWS-ROOT-001 | T1078 Valid Accounts | | AWS-S3-001 | T1530 Data from Cloud Storage | | AWS-NET-001 | T1578 Modify Cloud Compute Infrastructure | | AWS-CORR-001 | T1078 / T1098 / T1562.008 | ## 本地信息丰富 引擎使用本地上下文文件对告警进行信息丰富： * `data/context/known_ips.csv` * `data/context/users.csv` 信息丰富字段包括： * IP 类型 * IP 标签 * IP 信誉 * 工作时间上下文 * 正常的 AWS 区域 * 异常区域标志 * 用户风险 * 本地风险备注 示例： CloudTrail 日志记录被来自可疑 IP 地址的关键用户修改。 ## 案例管理仪表板 V2 分析师仪表板提供经过身份验证的案例管理、所有权分配、笔记、状态转换、审计历史以及基于角色的管理控制。 仪表板功能包括： * 告警指标 * 严重性过滤 * 状态过滤 * 用户过滤 * IP 信誉过滤 * 事件队列 * 事件详情视图 * MITRE ATT&CK 部分 * 本地信息丰富部分 * 证据视图 * 推荐的分析师操作 * 案例状态更新 * 分析师笔记 支持的案例状态： * Open (打开) * Investigating (调查中) * Escalated (已升级) * Closed (已关闭) * False Positive (误报) ## 事件报告 本项目为每个案例生成 Markdown 事件报告。 生成的报告在运行时写入： ``` reports/generated/ ``` 生成的报告会被排除在 Git 之外；该目录通过 `.gitkeep` 占位符保留。 每份报告包括： * 执行摘要 * 检测详情 * 实体上下文 * 本地信息丰富 * MITRE ATT&CK 映射 * 证据 * 推荐的分析师操作 * 分析师笔记 * 案例时间线 * 关闭指南 ## 项目结构 ``` .github/workflows/ test.yml # CI validation data/ test_events/ # Sanitized Snort and Wazuh demo telemetry cases/ # Runtime SQLite case storage normalized/ # Normalized event output alerts/ # Runtime-generated alert queue (Git-ignored) vulnerabilities/ # Vulnerability-enrichment data deploy/ run-production-container.sh # Hardened production launcher docs/ demo_walkthrough.md # Verified end-to-end V2 demo CONFIGURATION.md # Runtime settings DEPLOYMENT.md # Container deployment OPERATIONS.md # Health, readiness, and metrics RELEASE_NOTES_V2.md # v2 release notes images/ # Portfolio screenshots legacy/ v1/ dashboard/ # Archived V1 Streamlit dashboard data/raw/ # Archived sanitized AWS CloudTrail sample reports/ # Archived V1 report example screenshots/ # Archived V1 Cloud SOC screenshots playbooks/ # SOC investigation and response guidance src/ api/ # FastAPI app, dashboard, security, health, metrics cases/ # Persistent case models and SQLite store copilot/ # Prompting, providers, validation, and service layer correlation_engine/ # Cross-source SSH correlation identity/ # Analyst accounts, RBAC, passwords, and sessions ingestion/ # Snort and Wazuh loaders mitre/ # MITRE ATT&CK models and mappings normalization/ # CloudTrail, Snort, and Wazuh normalization orchestration/ # End-to-end SOC pipeline risk/ # Deterministic risk scoring storage/ # Normalized-event persistence triage/ # Evidence-backed triage packet construction v2_cli.py # V2 command-line entry point tests/ # 413 automated tests across platform components ``` 为了保持历史兼容性，仓库还保留了部分选定的根级 V1 模块和旧版的 `dashboard/` 目录。主要的发布版本是位于 `src/api/` 下的 V2 FastAPI 平台。 ## 本地运行 创建并激活虚拟环境： ``` python3 -m venv venv source venv/bin/activate ``` 安装依赖项： ``` python -m pip install -r requirements.txt ``` 创建一次性跨源演示案例： ``` rm -f /tmp/ai-soc-v2-demo.db python -m src.v2_cli \ run-ssh-case \ --snort data/test_events/sample_snort_ssh_recon.json \ --wazuh data/test_events/sample_wazuh_ssh_compromise.json \ --database /tmp/ai-soc-v2-demo.db \ --provider fallback ``` 创建管理员账户： ``` python -m src.identity.cli \ --database /tmp/ai-soc-v2-demo.db \ create \ --email analyst@example.com \ --name "SOC Administrator" \ --role admin ``` 配置临时本地设置： ``` export SOC_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')" export SOC_SESSION_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(64))')" export SOC_CASE_DATABASE=/tmp/ai-soc-v2-demo.db export SOC_INPUT_ROOT=data/test_events export SOC_DEPLOYMENT_MODE=development export SOC_SESSION_HTTPS_ONLY=false export SOC_ENABLE_HSTS=false export SOC_LOG_FORMAT=text export SOC_LOG_LEVEL=INFO ``` 启动 FastAPI 应用程序： ``` python -m uvicorn src.api.main:app \ --host 127.0.0.1 \ --port 8000 ``` 打开分析师仪表板： ``` http://127.0.0.1:8000/dashboard ``` 有关完整的演示和清理工作流，请参阅 [`docs/demo_walkthrough.md`](docs/demo_walkthrough.md)。 ## 使用 Docker 运行 V2 API 构建加固的生产镜像： ``` sudo docker build -t ai-soc-copilot:v2-production . ``` 创建被忽略的生产环境文件： ``` cp .env.production.example .env.production chmod 600 .env.production ``` 为 `SOC_API_KEY` 和 `SOC_SESSION_SECRET` 配置独立的值，然后启动容器： ``` ./deploy/run-production-container.sh ``` V2 API 在本地可通过以下地址访问： ``` http://127.0.0.1:8000 ``` 操作检查： ``` curl -i http://127.0.0.1:8000/health/live curl -i http://127.0.0.1:8000/health/ready ``` 启动器使用非 root 用户、只读根文件系统、降权（dropped capabilities）、资源限制、持久化 SQLite 存储以及仅限本地主机的端口绑定。 有关生产环境的指导，请参阅 `docs/DEPLOYMENT.md` 和 `docs/CONFIGURATION.md`。 ## 运行测试 运行自动化测试套件： ``` python -m pytest -v ``` 预期结果： ``` 413 passed ``` 测试验证以下内容： * 解析器加载 CloudTrail 风格的事件 * 标准化事件包含必填字段 * 检测规则生成预期的告警 * 关联引擎生成入侵链告警 * 完整的流水线生成 8 个告警 * 添加了 MITRE 映射 * 添加了本地信息丰富 * 关联告警具有紧急风险评分 * 报告生成器创建 Markdown 内容 ## SOC 操作手册 本项目包含以下场景的响应操作手册： * 多次登录失败后成功 * 创建新的 IAM 访问密钥 * IAM 权限提升 * CloudTrail 日志记录篡改 * 使用 root 账户 * 公开 S3 存储桶暴露 * 安全组对互联网开放 每份操作手册都包括调查步骤、需要审查的证据、控制指导和关闭标准。 ## 展示的技能 * AWS CloudTrail 日志分析 * 云安全监控 * IAM 威胁检测 * 云错误配置检测 * SOC 告警分诊 * 检测工程 * 关联逻辑 * MITRE ATT&CK 映射 * 本地告警信息丰富 * 风险评分 * SQLite 案例管理 * 安全的 FastAPI 分析师仪表板开发 * 事件响应文档编写 * Python 自动化 * Pytest 验证 * Docker 打包 * Git 和 GitHub 工作流 ## 成本设计 本项目专为离线运行而设计。 主版本不需要 AWS 账户。 不需要付费的云服务。 示例的 CloudTrail 风格日志允许完整的检测、分诊、报告和仪表板工作流在本地运行。 ## 当前发布 — v2.0.1 AI SOC Copilot `v2.0.1` 是当前稳定的版本。它包含多源遥测处理、确定性关联和风险评分、MITRE ATT&CK 映射、基于证据的 Copilot 辅助、经过身份验证的分析师工作流、仅追加审计、运营可观测性以及加固的容器部署。 - 发布说明：[`docs/RELEASE_NOTES_V2.md`](docs/RELEASE_NOTES_V2.md) - 可重现的演示：[`docs/demo_walkthrough.md`](docs/demo_walkthrough.md) - 部署指南：[`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) ## 旧版 V1 兼容性 为了保持历史兼容性，仓库在 `legacy/v1/` 下保留了部分选定的 V1 CloudTrail 检测、报告、通知和 Streamlit 组件。主要维护的平台是位于 `src/api/`、`src/correlation_engine/`、`src/copilot/`、`src/identity/` 以及上述记录的其他 V 包下的模块化 V2 实现。 ## 未来改进 - OpenVAS 漏洞信息丰富以及资产与发现的关联 - 共享的 PostgreSQL 和 Redis 服务以实现水平扩展 - 企业 SSO 和 MFA - 外部 SIEM 转发和 OpenTelemetry 导出 - 额外的遥测连接器和关联规则 - 正式的 Copilot 准确性和不受支持声明的评估 - Kubernetes 部署和灾难恢复工作流 - PDF/JSON 案例导出以及更丰富的分析师可视化 ## 文档 - [`docs/demo_walkthrough.md`](docs/demo_walkthrough.md) — 端到端的本地演示 - [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — 运行时设置 - [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — 加固的容器部署 - [`docs/OPERATIONS.md`](docs/OPERATIONS.md) — 健康、就绪和指标 - [`docs/V2_ROADMAP.md`](docs/V2_ROADMAP.md) — 架构和路线图 - [`docs/RELEASE_NOTES_V2.md`](docs/RELEASE_NOTES_V2.md) — 发布详情

标签：AI辅助分析, AMSI绕过, Python, 威胁检测, 安全编排自动化与响应(SOAR), 安全规则引擎, 安全运营中心(SOC), 密码管理, 无后门, 请求拦截, 逆向工具