suwa-sh/shared-infra-incident-readiness
GitHub: suwa-sh/shared-infra-incident-readiness
一款面向共享基础设施事件的诊断 CLI 工具，用于自动化检查责任边界、DPA 条款合规性、通知 SLA 时间线，并支持生成 runbook 与 Tabletop 演练计划。
Stars: 0 | Forks: 0
# shared-infra-incident-readiness
[](https://github.com/suwa-sh/shared-infra-incident-readiness/actions/workflows/ci.yml)
[](LICENSE)
一款诊断工具和可扩展框架，专为**共享基础设施事件发生后的前 30 分钟**设计：明确责任人、检查缺失的 DPA 条款、评估通知时间线是否符合 SLA，以及如何开展 Tabletop 演练。本工具提炼自针对一起共享邮件平台事件（由六家 ISP 共享的 OEM 平台）的**公开分析**。
核心功能：
1. **诊断你的事件准备情况** — 自动化检查责任边界、合同（DPA）条款以及通知 SLA，并返回确定性的结论。
2. **机器可读的单一事实来源** — 责任表、RACI、DPA 条款、通知义务和场景均作为定义文件维护，方便 AI agent 和 CI 直接读取。
3. **无需 fork 即可扩展** — 每家公司都可以通过 overlay 添加自己的角色、条目、条款、义务和场景。
## 快速开始（3 分钟）
无需任何环境配置——拉取已发布的镜像并运行。内置的示例开箱即用：
```
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 --version
# 1. 为已填写的 responsibility-boundary matrix 评分
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
check-responsibility examples/responsibility/sample-oem-mail.yaml
# 2. 检查 DPA clause 覆盖范围
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
check-dpa examples/dpa/sample-dpa-answers.yaml
# 3. 验证 incident record 及其 notification SLA timeline
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
validate-record examples/records/sample-incident.json --level extended
# 4. 生成 3 阶段 runbook（responsibility table -> runbook -> comms tree）
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
render-runbook examples/responsibility/sample-oem-mail.yaml --scenario rce-6brand
# 5. 生成 Tabletop 演练计划
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
tabletop --scenario rce-6brand examples/responsibility/sample-oem-mail.yaml
# 6. 验证 overlay（仅添加/增强）并检查定义
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 \
check-overlay examples/overlays/sample-company/extra-clauses.yaml
docker run --rm ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 list-definitions
```
`--version` 会打印应用版本及内置的 overlay 引擎版本，例如 `siir 0.2.0 (overlay-scoring-skeleton 0.1.0)`。
每个命令都会返回一个确定性的退出码，方便你将其作为 CI 的拦截条件：
**0** ok · **1** partial（黄色：警告、暂缓项、尚未发送的通知）· **2** block（缺口、缺失条款、违反 SLA、overlay 被拒绝）· **3** input 错误（文件缺失 / 解析错误）。
## 使用流程
这些命令针对的是*你的*数据。请将存放你文件的目录挂载到容器中。为了保持本指南后续内容的简洁，我们可以定义一个 shell 函数：
```
siir() { docker run --rm -v "$PWD:/data" -w /data \
ghcr.io/suwa-sh/shared-infra-incident-readiness:v0.2.0 "$@"; }
```
从 [`examples/`](examples/) 中获取一个示例作为模板，填入你自己的值，然后按照从日常准备到事件期间验证的顺序依次运行以下命令。
1. **准备** — 从示例开始创建你自己的输入文件（`my-responsibility.yaml`、`my-dpa.yaml`）。
2. **检查责任（日常）** — 在 `matrix` 中填入你自己的 R/A/C/I（如果尚未决定，可以填写 `tbd`），然后运行 `siir check-responsibility my-responsibility.yaml`。优先修复 `BLOCK` 行，然后再处理 `REVISE` 灰色地带。
3. **检查合同（日常）** — 复制 `examples/dpa/sample-dpa-answers.yaml`，将每个条款标记为 `present` / `partial` / `missing`，然后运行 `siir check-dpa my-dpa.yaml`。
4. **准备 runbook 与演练** — 生成确定性的 3 阶段 runbook 及 Tabletop 计划：
`siir render-runbook my-responsibility.yaml --scenario rce-6brand` 和 `siir tabletop --scenario rce-6brand my-responsibility.yaml`（使用 `siir list-definitions` 列出所有场景 ID）。
5. **事件期间验证** — 根据 `examples/records/sample-incident.json` 构建真实的事件记录，并检查通知时间线：`siir validate-record my-incident.json --level extended`。
6. **扩展（可选）** — 通过 overlay 添加你自己的角色 / 条款 / 场景，使用 `siir check-overlay ` 进行验证，并通过 `--overlay ` 应用。
示例输出（`check-responsibility`）— 每行标记为 `[OK]` ok / `[..]` revise / `[NG]` block，最后是总体结论：
```
Target: 共用メール基盤 (6 ISP OEM)
Responsibility readiness: 83%
[OK] RB01 利用者向け窓口・本人通知: OK (ok)
[..] RB04 プレスリリース (共同 / 個別の決定): REVISE (accountability_deferred)
gray (tbd): oem_operator
[NG] RB12 平時 / 事故時の合同演習主催: BLOCK (unassigned)
Conclusion: BLOCK
```
请参阅 [`README.ja.md`](README.ja.md#使い方想定ワークフロー) 获取工作流中每个命令的示例输出。
## 适用人群
| 如果你是... | 请从...开始 |
|---|---|
| OEM / 共享平台运营商的 **PMO / 安全负责人** | [`docs/01_responsibility_boundary.md`](docs/01_responsibility_boundary.md) — 填写你的矩阵，运行 `check-responsibility` |
| 外包合同中的 **法务 / 采购** 负责人 | [`docs/03_dpa_clauses.md`](docs/03_dpa_clauses.md) — 检查 10 项强制要求的 DPA 条款 |
| 负责接入事件记录 pipeline 的 **工程师 / SRE** | [`schemas/incident-record.schema.json`](schemas/incident-record.schema.json) + [`docs/02_incident_raci_and_sla.md`](docs/02_incident_raci_and_sla.md) |
| **顾问 / 方案撰写人** | 所有 `docs/` 及 overlay 模型 — 克隆后私下进行 overlay，展示针对客户定制的评分 |
## 本仓库包含的内容
```
shared-infra-incident-readiness/
├── definitions/ # Machine-readable canonical framework (YAML)
│ ├── responsibility-matrix.yaml # 12 items x 4 roles (R/A/C/I)
│ ├── incident-raci.yaml # 15 activities x 5 roles (refs obligations/clauses)
│ ├── dpa-clauses.yaml # 10 DPA clauses (contractual SLA source of truth)
│ ├── notification-obligations.yaml # statutory notification clocks
│ └── scenarios.yaml # Tabletop scenarios
├── schemas/incident-record.schema.json # incident record + notification timeline
├── bin/siir + src/siir/ # the CLI
├── examples/ # sample inputs, overlays, worked example, agent skills
├── docs/ # design docs (C4, concept model, scoring)
└── tests/ # overlay / scoring / SLA / runbook boundary conditions
```
## overlay 模型
overlay 允许公司无需 fork 即可扩展该框架。仅允许两种操作，它们需在 `extension_points` 中按定义进行声明：
- **`add`** — 追加新的角色 / 条目 / 条款 / 义务 / 场景（需使用新的 `id`）。覆盖或删除现有条目的操作会被拒绝。
- **`strengthen`** — 仅允许将声明的数值字段向更严格的方向调整（例如将 SLA 从 24 小时缩短至 12 小时）。放宽要求会被拒绝。
`siir check-overlay `（使用[使用流程](#usage-workflow)中定义的 `siir` shell 函数）会在你应用 overlay 之前对其进行验证。
## 开发
```
pytest tests/ # boundary conditions, exit codes
bin/siir --help # CLI smoke
npx md-mermaid-lint docs/*.md # diagram syntax
```
## License
MIT — 详见 [LICENSE](LICENSE)。
标签：Docker, IT运维, SLA管理, Socks5代理, Tabletop演练, 安全规则引擎, 安全防御评估, 请求拦截, 逆向工具