SeifMoussa/offline-alert-triage-lab

# AI 辅助安全告警分诊实验室 防御性离线告警分诊实验室，用于处理合成安全告警，支持确定性 分类、MITRE ATT&CK 映射、事件分组、脱敏以及 Markdown/JSON 报告生成。 ## 安全免责声明 本项目仅用于防御。它处理包含合成告警数据的本地文件，不执行任何网络调用、无实时扫描、无漏洞利用代码、无 攻击自动化、无恶意软件行为，且无外部威胁情报 查询。 “AI 辅助”的标签具有有意且狭义、诚实的范围限制： - 确定性基于规则的引擎。 - 无 LLM。 - 无外部 AI API。 - 无 API 密钥。 - 无随机性输出。 - 每个决策均可通过本地规则、映射和模板进行追踪。 ## 项目目标 该实验室演示了初级安全自动化或蓝队工作流如何 在保持严格安全边界的同时，将原始合成告警 转化为可供分析师直接使用的分诊输出。它专为作品集审查、本地学习和 可重复的质量检查而设计。 目标岗位： - SOC 分析师。 - 网络安全分析师。 - 蓝队分析师。 - 检测工程实习生。 - 事件响应实习生。 - 初级安全自动化岗位。 ## 演示内容 - 安全的本地安全工具设计。 - Schema 验证与结构化错误处理。 - 具有透明规则追踪的确定性严重性分类。 - 无需外部查询的本地 MITRE ATT&CK 映射。 - 无需 LLM 即可生成分析师风格的解释。 - 防御性分诊 playbook 选择。 - 事件分组与严重性汇总。 - 适合报告的脱敏处理与输出验证。 - JSON 与 Markdown 报告生成。 - Python 打包、pytest、覆盖率门控、Ruff、GitHub Actions、CodeQL 和 Dependabot 配置。 ## Pipeline 概览 ``` local synthetic alerts -> alert ingestion -> validation -> severity classification -> MITRE ATT&CK mapping -> analyst-style explanations -> triage playbooks -> incident grouping -> redaction -> Markdown/JSON reports ``` 已实现的阶段： - 从本地 JSON 数组、单个 JSON 对象和简单的 NDJSON 中提取告警。 - Pydantic 验证和结构化的解析错误输出。 - 基于本地 YAML 规则的确定性严重性分类。 - 基于本地静态 YAML 表的 MITRE ATT&CK 映射。 - 基于确定性模板的分析师风格解释。 - 基于本地 playbook 的防御性分诊建议。 - 基于本地确定性关联规则的事件分组。 - 在输出报告前对原始消息、IP、用户名、敏感标记和 疑似凭据的模式进行脱敏。 - 在 `reports/examples` 下生成 Markdown 和 JSON 报告。 ## 安全模型 允许的数据仅限于本地合成告警。示例使用私有实验室 地址段、保留的文档 IP 地址段、`example.com`、`example.org`、 `example.net` 和 `.test` 域名。 应用程序会拒绝 URL 输入、网络路径以及针对 CLI 文件路径的父目录 遍历。它不提供 API 密钥、外部 富化、实时扫描或 SIEM 集成的选项。 报告不包含 `raw_message`、原始源 IP 值、原始目标 IP 值、原始用户名、批准的虚假标记常量或疑似凭据的 赋值。 ## 技术栈 - Python 3.11+。 - Pydantic。 - PyYAML。 - argparse CLI。 - pytest 和 pytest-cov。 - Ruff linting 和格式化。 - 在本地配置的 GitHub Actions 工作流文件。 - 在本地配置的 CodeQL 工作流。 - 在本地配置的 Dependabot。 ## CLI 示例 在仓库根目录下运行。通过可编辑安装，`triage-lab` 也可 作为控制台脚本使用；以下示例使用 `python -m triage_lab` 进行直接的本地执行。 ``` python -m triage_lab --help python -m triage_lab --version python -m triage_lab inventory --input alerts --format json python -m triage_lab validate-alerts --input alerts/sample_alerts.json --format json python -m triage_lab validate-alerts --input alerts/sample_alerts.json --format text python -m triage_lab classify-alerts --input alerts/sample_alerts.json --format json python -m triage_lab classify-alerts --input alerts/sample_alerts.json --format text python -m triage_lab map-mitre --input alerts/sample_alerts.json --format json python -m triage_lab map-mitre --input alerts/sample_alerts.json --format text python -m triage_lab explain-alerts --input alerts/sample_alerts.json --format json python -m triage_lab explain-alerts --input alerts/sample_alerts.json --format text python -m triage_lab group-incidents --input alerts/sample_alerts.json --format json python -m triage_lab group-incidents --input alerts/sample_alerts.json --format text python -m triage_lab redact-check --input alerts/sample_alerts.json --format json python -m triage_lab report --input alerts/sample_alerts.json --output reports/examples --format both python -m triage_lab report --input alerts/sample_alerts.json --output reports/examples --format json python -m triage_lab report --input alerts/sample_alerts.json --output reports/examples --format markdown ``` ## 示例报告 - [JSON 示例报告](reports/examples/security_alert_triage_report.json) - [Markdown 示例报告](reports/examples/security_alert_triage_report.md) 这两份报告均由 `alerts/sample_alerts.json` 生成，仅使用本地合成 数据，包含仅限离线的免责声明，并通过了报告安全 扫描。 ## 测试与质量状态 当前已验证的本地状态： - 256 个测试通过。 - 97.29% 覆盖率。 - 97% 覆盖率门控通过。 - Ruff 检查通过。 - Ruff 格式检查通过。 - 文档安全检查通过。 - CLI 冒烟测试通过。 - 生成的报告及相关 CLI 输出扫描通过。 质量命令： ``` python -m pytest python -m pytest --cov=triage_lab --cov-report=term-missing --cov-fail-under=97 python -m ruff check . python -m ruff format --check . python scripts/check-docs.py python -m py_compile scripts/check-docs.py ``` CI、CodeQL 和 Dependabot 均在本地进行了配置。由于尚未发布仓库，目前尚未验证托管的 GitHub CI 和 CodeQL。 ## 项目结构 ``` alerts/ synthetic alert fixtures config/ local YAML rules, MITRE mappings, playbooks, grouping rules docs/ schema, safety, reporting, testing, and release docs reports/examples/ generated redacted JSON and Markdown reports scripts/check-docs.py documentation and report safety checks src/triage_lab/ application package tests/ pytest suite ``` 关键包区域： - `ingestion`：本地 JSON 加载、清单和路径安全。 - `classification`：严重性规则、修饰符、覆盖和追踪。 - `mitre`：本地静态 ATT&CK 映射。 - `explanations`：确定性的分析师风格文本。 - `triage`：防御性 playbook 选择。 - `grouping`：确定性事件关联。 - `redaction`：适合报告的序列化和验证。 - `reporting`：报告模型、pipeline、渲染器和写入器。 ## 局限性 - 仅作为教学实验室；并非生产级 SOC 平台。 - 仅限合成告警数据。 - 侧重于 JSON 提取；在 v0.1.0 版本中故意将 CSV 提取排除在 范围之外。 - 本地静态 MITRE 示例并非实时的 ATT&CK 数据同步。 - 无 SIEM、EDR、云、工单系统、LLM 或外部威胁情报 集成。 - 在发布之前，托管的 CI、托管的 CodeQL、分支保护、标签和发布验证 仍处于待办状态。 ## 路线图 - 在获得明确批准后发布仓库。 - 在发布后验证托管的 GitHub Actions 和托管的 CodeQL。 - 审查代码扫描、机密扫描和 Dependabot 结果。 - 在存在托管检查后配置分支保护。 - 在最终批准后创建 v0.1.0 标签和 GitHub Release。 - 考虑为作品集展示添加额外的合成测试数据和报告截图。 ## 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。

标签：Cloudflare, MITRE ATT&CK, Python, 云计算, 告警分诊, 安全规则引擎, 安全运营, 恶意代码分类, 扫描框架, 无后门, 规则引擎, 逆向工具