finnholzgrabe/secops-automation-workbench

# SecOps 自动化工作台  一个面向安全自动化工程的 .NET 优先小型工作台：告警标准化、MITRE ATT&CK 风格映射、确定性 playbook 选择、富化存根以及安全的模拟响应动作。 本仓库的定位严格限制为工程工作台，而非生产级的 SOAR/SIEM/EDR 产品。 ## 此项目演示的内容 - 安全告警标准化与分诊流程设计 - 面向 API 和 playbook 的自动化思维 - 检测/响应术语，且不夸大 SOC 生产经验 - 清晰的 .NET 架构、确定性测试以及对 CI 友好的命令行工具 ## 此项目不是什么 - 不是生产级的事件响应平台 - 不是经过验证的 SOAR、SIEM 或 EDR 系统 - 不能替代安全监控、案例管理或分析师审查 - 默认情况下，未连接到真实的客户、身份、端点或防火墙系统 ## 快速开始 ``` dotnet restore dotnet build --no-restore dotnet run --project src/SecOps.Workbench.Cli -- --help dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json dotnet test ``` 测试使用 xUnit 并通过 `dotnet test` 运行。`Core` 中的领域逻辑没有外部依赖，因此其关键行为可以快速且确定性地进行验证。 ### 报告输出格式 `triage` 命令默认渲染 Markdown 报告，并且可以输出确定性的 JSON。使用 `--out` 可将其写入文件而非标准输出： ``` # Markdown 输出到 stdout（默认） dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json # JSON 输出到 stdout dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json --format json # JSON 写入文件（artifacts/ 下生成的报告被 git-ignored） dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json --format json --out artifacts/triage.json ``` JSON 报告具有稳定的顶层结构（`alertId`、`severity`、`techniqueIds`、`recommendedPlaybook`、`recommendedActions`、`rationale`、`dryRun`）。未知的 `--format` 会以非零状态退出。每份报告都会保留 `dryRun: true`，这反映了默认安全的响应模型。 `--format html` 会渲染一个独立、无依赖的 HTML 报告（所有动态值都经过了 HTML 编码）。这就是已发布的演示页面所展示的内容。 ``` dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json --format html --out artifacts/report.html ``` 添加 `--attack-layer ` 还可以为映射的技术写入一个 [ATT&CK Navigator](https://mitre-attack.github.io/attack-navigator/) 层（v4.5）。该文件可直接加载到 Navigator 中进行可视化；技术计数将转换为热力图分数。 ``` dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json --attack-layer artifacts/layer.json ``` ### Playbook 推荐由 [`playbooks/`](playbooks) 下的本地 playbook 定义驱动。每个 playbook 声明 `id`、`title`、`description`、`category`、`techniques`、`recommendedActions` 和 `dryRunOnly`。分诊会根据类别和技术重叠度选择最合适的 playbook；当目录不存在时，它会回退到内置目录，因此分诊在干净的检出状态下也能工作。 ``` # 列出可用的 playbooks dotnet run --project src/SecOps.Workbench.Cli -- playbooks list # 验证 playbook 目录（遇到任何无效文件时以非零状态退出） dotnet run --project src/SecOps.Workbench.Cli -- playbooks validate ``` 验证强制执行安全模型：每个 playbook 必须设置 `dryRunOnly: true`，技术 ID 必须是 ATT&CK 风格，且必须存在必填字段。无效的 playbook 会失败并显示可读的逐字段错误信息。 ### 富化（合成） 分诊在三个接口背后附加了富化上下文 —— `IIdentityContextProvider`、`IAssetContextProvider` 和 `IReputationProvider`。默认的提供程序是合成 mock：它们不进行网络调用，不读取真实系统，并且是完全确定性的（使用稳定的 FNV 哈希代替每个进程随机化的 `string.GetHashCode`）。富化为每份报告添加了主体风险提示、资产关键性和每个 observable 的上下文，并在输出中清晰地标记为 `synthetic`（合成）。 这些接口是真实适配器的切入点。作为一个具体的离线示例，`--ioc-file` 会切换为一个**基于文件的信誉提供程序**，该程序读取本地 IOC 列表，并对未列出的任何内容回退到 mock： ``` dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/endpoint-suspicious-process.json --ioc-file samples/reputation/iocs.json --format json ``` `suspicious_process` 从 `unknown`（mock）变为 `malicious`（来自 IOC 文件）—— 相同的分诊 pipeline，不同的提供程序，无需更改代码。真实的身份提供程序、CMDB 或联网的威胁情报集成仍然不在范围内，且在设计上是可选项。 ### 分析师案例笔记 添加 `--case-note` 以输出 Markdown 案例笔记而非报告。它汇集了摘要、observable、映射的技术（附名称）、推荐的 playbook、分析师清单、试运行响应计划以及明确的限制部分： ``` dotnet run --project src/SecOps.Workbench.Cli -- triage samples/alerts/suspicious-login.json --case-note ``` 案例笔记仅为 Markdown 格式，并且与所有输出一样，是由合成数据生成的，且所有响应步骤均被设定为试运行建议。 ### 场景模拟 对一系列有序的合成告警运行分诊，以观察入侵如何随时间升级。这是**以合成数据形式进行的对手模拟** —— 不会执行任何实际操作。输出是一个事件时间轴以及汇总的 ATT&CK 技术覆盖范围。 ``` dotnet run --project src/SecOps.Workbench.Cli -- simulate samples/scenarios/identity-mfa-fatigue.json dotnet run --project src/SecOps.Workbench.Cli -- simulate samples/scenarios/identity-mfa-fatigue.json --attack-layer artifacts/incident-layer.json ``` 场景文件包含一个 `name`、一个 `description` 和一个有序的 `alerts` 数组（每个条目使用与单个告警相同的结构）。模拟器按时间戳对时间轴进行排序，报告最高严重性，并统计整个事件中的技术出现频率。 ### 批量分诊和指标 对目录中的每个告警进行分诊，并以 JSON 或 CSV 格式输出汇总指标 —— 严重性计数、技术出现频率和 playbook 分布： ``` dotnet run --project src/SecOps.Workbench.Cli -- batch samples/alerts --format json dotnet run --project src/SecOps.Workbench.Cli -- batch samples/alerts --format csv --out artifacts/triage-summary.csv ``` 解析失败的文件会在 stderr 上报告并跳过；该命令仍会对成功解析的告警进行汇总。 ### 检测内容 linting [`detections/`](detections) 文件夹包含**受 Sigma 启发的示例规则**（而非生产级检测）。一个无依赖的内容 linter 会检查每个规则是否具备使其能够被审查的字段：`title`、有效的 Sigma `status`、至少一个 ATT&CK 技术标签（`attack.tNNNN`）、有意义的 `falsepositives` 说明，以及必须指向现有 fixture 文件的 `testFixture` 引用。 ``` dotnet run --project src/SecOps.Workbench.Cli -- detections lint ``` 如果任何规则缺少必填字段、使用了无效的状态，或者引用了缺失的 fixture，linter 将以非零状态退出。它对规则文本执行结构检查，而不是解析完整的 YAML，这使得核心部分保持无依赖；它是一个内容质量门控，而不是 Sigma 执行引擎。 `detections test` 更进一步，针对其 fixture 事件实际**评估**每个规则，并将结果与 fixture 预期的 `shouldMatch` 结果进行比较： ``` dotnet run --project src/SecOps.Workbench.Cli -- detections test ``` 评估器支持一小部分有文档说明的 Sigma 风格条件 —— ` | count() by > N`，可选地加上 `and ` 用于共存事件 —— 这足以对内置示例进行端到端测试。超出该子集的规则将被报告为已跳过，而不会失败。 ## 安装 CLI 打包为 .NET 全局工具： ``` dotnet pack src/SecOps.Workbench.Cli -c Release -o artifacts dotnet tool install --global --add-source ./artifacts SecOps.Workbench.Cli secops-workbench triage samples/alerts/suspicious-login.json ``` 标记的发布版本（`v*`）还会附带 linux-x64、win-x64 和 osx-arm64 的独立单文件二进制文件 —— 无需 .NET runtime —— 由[发布工作流](.github/workflows/release.yml)构建。 ## HTTP API 相同的分诊 pipeline 也作为一个小型的无状态 ASP.NET Core 最小化 API（`src/SecOps.Workbench.Api`）公开。富化提供程序和 `TriageEngine` 注册在 DI 中；默认值是合成 mock，在配置中设置 `Reputation:IocFile` 会切换为基于文件的信誉提供程序，无需任何代码更改。每个响应都保持试运行状态。 ``` dotnet run --project src/SecOps.Workbench.Api # 在另一个 shell 中： curl -s localhost:5000/healthz curl -s -X POST localhost:5000/triage -H 'Content-Type: application/json' \ --data-binary @samples/alerts/suspicious-login.json ``` - `GET /healthz` —— 存活探针。 - `POST /triage` —— body 是一个告警 JSON 文档；响应是确定性的分诊报告。无效的告警将返回 `400` 并附带问题详情。 这些 endpoint 由使用 `WebApplicationFactory` 的集成测试所覆盖。 ## 当前切片 版本 0.1 从一个微小但可用的垂直切片开始： 1. 加载告警 JSON 文件。 2. 将其标准化为类型化的领域模型。 3. 将选定的信号映射到 ATT&CK 风格的技术 ID。 4. 附加合成富化（身份、资产、observable 上下文）。 5. 选择安全的 playbook 推荐。 6. 打印确定性的面向分析师的分诊摘要，或完整的案例笔记。 ## 架构 ``` src/SecOps.Workbench.Core Domain model, parser, triage logic, playbook selection src/SecOps.Workbench.Cli File IO, command parsing, user-facing output tests/SecOps.Workbench.Tests xUnit regression tests for parsing, mapping, triage, and output contracts docs/ Architecture, threat model, roadmap, and scope notes samples/alerts/ Tiny synthetic alerts only playbooks/ Local JSON playbook definitions detections/ Sigma-inspired example rules and test fixtures artifacts/ Generated outputs; heavy or local outputs are ignored ``` ## 演示 请参阅 [docs/demo.md](docs/demo.md) 了解可复现的单次运行，并在 [docs/examples/](docs/examples) 下查看捕获的示例输出。架构（包括图表）在 [docs/architecture.md](docs/architecture.md) 中，值得注意的权衡取舍写在 [docs/design-decisions.md](docs/design-decisions.md) 中。 交互式演示位于 [docs/index.html](docs/index.html) —— 选择一个合成告警或入侵场景，浏览由 CLI 生成的分诊报告、案例笔记、JSON 和 ATT&CK 覆盖范围。在 `docs/` 文件夹上启用 GitHub Pages 即可将其发布为可浏览的网站。 ## 路线图 - 具备试运行和回滚语义的安全响应模拟器 - 用于本地 Wazuh/Shuffle 实验环境的可选适配器，默认情况下从不启用 ## 安全性 所有样本都是合成的。响应动作默认必须是试运行。切勿提交真实的告警、凭据、客户数据、内部日志或个人安全事件。

标签：Cloudflare, MITRE ATT&CK, 单元测试, 告警分诊, 多人体追踪, 安全运营, 扫描框架