From 094d5af05be3cdb5aac536eabbf587a3208b371b Mon Sep 17 00:00:00 2001 From: Your Name Date: Wed, 13 May 2026 15:58:48 +0800 Subject: [PATCH] docs(security): add approval decision record contract [skip ci] --- docs/LOGBOOK.md | 22 ++ ...ty_approval_decision_record_v1.schema.json | 188 ++++++++++++++++++ ...WOOOP-MIRROR-ONLY-CONSUMPTION-CHECKLIST.md | 5 +- ...ECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md | 31 ++- .../SECURITY-APPROVAL-DECISION-RECORD.md | 52 +++++ docs/security/SECURITY-APPROVAL-GATE.md | 3 + docs/security/SECURITY-APPROVAL-QUEUE.md | 4 +- docs/security/SECURITY-MIRROR-ACCEPTANCE.md | 2 +- docs/security/SECURITY-MIRROR-INTAKE-PLAN.md | 9 +- docs/security/SECURITY-MIRROR-READINESS.md | 7 +- docs/security/SECURITY-MIRROR-ROUTE.md | 4 +- .../security/SECURITY-MIRROR-STATUS-ROLLUP.md | 7 +- ...SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md | 3 +- .../SECURITY-SUPPLY-CHAIN-PROGRESS.md | 13 +- ...ity-approval-decision-record.snapshot.json | 46 +++++ .../security-mirror-acceptance.snapshot.json | 8 +- .../security-mirror-dry-run.snapshot.json | 8 +- ...security-mirror-event-sample.snapshot.json | 9 +- .../security-mirror-intake-plan.snapshot.json | 9 +- .../security-mirror-quarantine.snapshot.json | 2 +- .../security-mirror-readiness.snapshot.json | 14 +- .../security-mirror-route.snapshot.json | 10 +- ...ecurity-mirror-status-rollup.snapshot.json | 12 +- ...pply-chain-contract-manifest.snapshot.json | 24 ++- 24 files changed, 434 insertions(+), 58 deletions(-) create mode 100644 docs/schemas/security_approval_decision_record_v1.schema.json create mode 100644 docs/security/SECURITY-APPROVAL-DECISION-RECORD.md create mode 100644 docs/security/security-approval-decision-record.snapshot.json diff --git a/docs/LOGBOOK.md b/docs/LOGBOOK.md index 325209fb..d1ede55a 100644 --- a/docs/LOGBOOK.md +++ b/docs/LOGBOOK.md @@ -1,3 +1,25 @@ +## 2026-05-13 | 資安供應鏈 S3.1：人工決策紀錄契約 + +**背景**：S3.0 已建立 `security_approval_gate_v1`，讓 AwoooP 可顯示人工批准 gate 與 follow-up runtime gate。本輪補上 `security_approval_decision_record_v1`，讓人工 approve / reject / defer / request more evidence / keep blocked 都能被稽核記錄，但不觸發執行。 + +**本次交付**： +- 新增 `docs/schemas/security_approval_decision_record_v1.schema.json`。 +- 新增 `docs/security/security-approval-decision-record.snapshot.json`，目前 0 筆決策紀錄、0 個 runtime action 授權。 +- 新增 `docs/security/SECURITY-APPROVAL-DECISION-RECORD.md`，以繁體中文說明決策紀錄可做 / 不可做與階段定位。 +- 更新資安供應鏈 manifest，contract 數量從 28 增至 29。 +- 更新鏡像 readiness、接收計畫、事件範例、路由矩陣、驗收契約、隔離契約、dry-run、status rollup、approval gate、approval queue、AwoooP mirror-only checklist、AwoooP handoff 與整體進度。 + +**累積狀態**： +- 鏡像 readiness 目前為 29 個 contracts：26 個 ready for mirror、2 個 partial ready、1 個 contract-only、0 個 blocked。 +- Decision records 目前 0 筆；所有決策紀錄都必須維持 `execution_authorized=false`。 +- 批准紀錄仍不得自動執行；任何 runtime action 都需要 follow-up runtime gate。 + +**邊界**： +- 沒有新增 runtime endpoint、DB migration、model 或執行 action。 +- 沒有新增執行按鈕。 +- 沒有啟動 scan、呼叫 Kali `/execute`、建立 repo、修改 visibility、sync refs 或切 GitHub primary。 +- 沒有保存 raw secret、token、cookie、private key 或 exploit payload。 + ## 2026-05-13 | 資安供應鏈 S3.0：人工批准 Gate 契約 **背景**：S2.7 已建立 `security_mirror_status_rollup_v1`，讓 AwoooP 與 Security Supply Chain Session 有共同狀態摘要。本輪開始 S3，但只建立人工批准 gate 的決策語言與稽核格式，不把 approval queue 接成 runner。 diff --git a/docs/schemas/security_approval_decision_record_v1.schema.json b/docs/schemas/security_approval_decision_record_v1.schema.json new file mode 100644 index 00000000..ff44156d --- /dev/null +++ b/docs/schemas/security_approval_decision_record_v1.schema.json @@ -0,0 +1,188 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "urn:awoooi:security-approval-decision-record-v1", + "title": "資安供應鏈人工決策紀錄契約 v1", + "description": "定義 AwoooP 如何保存 Security Supply Chain 人工批准、拒絕、延後、補 evidence 或維持 blocked 的稽核紀錄。此契約不授權 runtime execution。", + "type": "object", + "required": [ + "schema_version", + "status", + "date", + "mode", + "runtime_execution_authorized", + "source_indexes", + "summary", + "decision_records", + "recording_rules", + "forbidden_actions" + ], + "properties": { + "schema_version": { + "const": "security_approval_decision_record_v1" + }, + "status": { + "type": "string", + "enum": ["draft"] + }, + "date": { + "type": "string" + }, + "mode": { + "type": "string", + "enum": ["decision_record_only"] + }, + "runtime_execution_authorized": { + "type": "boolean", + "const": false + }, + "source_indexes": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "summary": { + "type": "object", + "required": [ + "total_decision_records", + "approve_scope_count", + "reject_count", + "defer_count", + "request_more_evidence_count", + "keep_blocked_count", + "pending_runtime_gate_count", + "runtime_actions_authorized", + "raw_secret_storage_authorized" + ], + "properties": { + "total_decision_records": { + "type": "integer", + "minimum": 0 + }, + "approve_scope_count": { + "type": "integer", + "minimum": 0 + }, + "reject_count": { + "type": "integer", + "minimum": 0 + }, + "defer_count": { + "type": "integer", + "minimum": 0 + }, + "request_more_evidence_count": { + "type": "integer", + "minimum": 0 + }, + "keep_blocked_count": { + "type": "integer", + "minimum": 0 + }, + "pending_runtime_gate_count": { + "type": "integer", + "minimum": 0 + }, + "runtime_actions_authorized": { + "type": "boolean", + "const": false + }, + "raw_secret_storage_authorized": { + "type": "boolean", + "const": false + } + }, + "additionalProperties": false + }, + "decision_records": { + "type": "array", + "items": { + "type": "object", + "required": [ + "record_id", + "gate_id", + "source_queue_item_id", + "decision", + "decided_by", + "decided_at", + "approved_scope", + "evidence_refs", + "execution_authorized", + "followup_runtime_gate_required", + "notes" + ], + "properties": { + "record_id": { + "type": "string" + }, + "gate_id": { + "type": "string" + }, + "source_queue_item_id": { + "type": "string" + }, + "decision": { + "type": "string", + "enum": ["approve_scope", "reject", "defer", "request_more_evidence", "keep_blocked"] + }, + "decided_by": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "decided_at": { + "type": "string" + }, + "approved_scope": { + "type": "string", + "enum": [ + "none", + "design_or_draft_only", + "read_only_inventory_only", + "low_noise_scan_scope_only", + "manual_exception_only", + "blocked_by_default" + ] + }, + "evidence_refs": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "execution_authorized": { + "type": "boolean", + "const": false + }, + "followup_runtime_gate_required": { + "type": "boolean", + "const": true + }, + "notes": { + "type": "string" + } + }, + "additionalProperties": false + } + }, + "recording_rules": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "forbidden_actions": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + } + }, + "additionalProperties": false +} diff --git a/docs/security/AWOOOP-MIRROR-ONLY-CONSUMPTION-CHECKLIST.md b/docs/security/AWOOOP-MIRROR-ONLY-CONSUMPTION-CHECKLIST.md index 94d73b23..1525de9d 100644 --- a/docs/security/AWOOOP-MIRROR-ONLY-CONSUMPTION-CHECKLIST.md +++ b/docs/security/AWOOOP-MIRROR-ONLY-CONSUMPTION-CHECKLIST.md @@ -30,6 +30,7 @@ AwoooP 初期不得直接啟動掃描、不得呼叫 Codex patch runner、不得 | `kali_scan_scope_approval_v1` | Kali 112 scan scope、111/168 observe-only、safe/active/credentialed/execute/full-upgrade gates | Approval queue、Operator Console、Audit | approval-only | 只顯示 scope 與 gate，不啟動 scan、不呼叫 `/execute` | | `security_approval_queue_v1` | Security Supply Chain pending approval / block candidate 集中隊列 | Approval queue、Operator Console、Audit | approval-only | 只顯示 review order 與 blocked reason，不執行 queue item | | `security_approval_gate_v1` | S3 人工批准 gate | Approval queue、Operator Console、Audit | approval-only | 只記錄人工決策、批准範圍與 follow-up runtime gate，不執行 gate item | +| `security_approval_decision_record_v1` | S3 人工決策紀錄 | Operator Console、Audit | approval-only | 只保存 approve / reject / defer / request more evidence / keep blocked 的稽核紀錄，不執行決策 | | `security_mirror_readiness_v1` | Security Supply Chain contract mirror readiness index | Operator Console、Runtime State、Channel Event、Audit | mirror-only | 只顯示 ready / partial / contract-only，不執行 mirror item | | `security_mirror_intake_plan_v1` | AwoooP mirror-only intake waves / destinations / acceptance gates | Operator Console、Runtime State、Channel Event、Audit、Approval Queue | mirror-only | 只照 wave 讀取與顯示，不執行 intake item | | `security_mirror_event_v1` | AwoooP mirror-only event envelope | Operator Console、Runtime State、Channel Event、Audit、Approval Queue | mirror-only | 每筆 event 必須 `execution_authorized=false`、`action_buttons_allowed=false` | @@ -89,7 +90,8 @@ AwoooP 初期不得直接啟動掃描、不得呼叫 Codex patch runner、不得 | `kali_scan_scope_approval_v1.status=draft_waiting_approval` | `approve_required` | 顯示 Kali 112、111/168、核心主機、公開網站 scope 與 gate；不得執行 scan | | `security_approval_queue_v1.status=draft` | `approve_required` | 顯示 8 個 queue items、review order 與 blocked reason；不得執行 item | | `security_approval_gate_v1.mode=approval_gate_only` | `approve_required` | 顯示 8 個 gate items、批准範圍與 follow-up runtime gate；批准後不得自動執行 | -| `security_mirror_readiness_v1.status=draft` | `observe` | 顯示 28 個 contracts 的 readiness；不得把 readiness 當 execution authorization | +| `security_approval_decision_record_v1.mode=decision_record_only` | `observe` | 顯示人工決策紀錄；每筆紀錄都必須 `execution_authorized=false` | +| `security_mirror_readiness_v1.status=draft` | `observe` | 顯示 29 個 contracts 的 readiness；不得把 readiness 當 execution authorization | | `security_mirror_intake_plan_v1.status=draft` | `observe` | 顯示 5 個 intake waves 與 4 個 acceptance gates；不得執行 wave | | `security_mirror_event_v1.execution_authorized=false` | `observe` | 只包裝鏡像 payload，明確不授權執行、不顯示執行按鈕 | | `security_mirror_route_v1.status=draft` | `observe` | 顯示 5 個 route groups、channel policy 與 review lane；不得轉成 execution router | @@ -162,6 +164,7 @@ AwoooP 初期不得直接啟動掃描、不得呼叫 Codex patch runner、不得 | Kali scan scope approval package | `docs/security/kali-scan-scope-approval.snapshot.json` / `docs/security/KALI-SCAN-SCOPE-APPROVAL-PACKAGE.md` | | Security approval queue | `docs/security/security-approval-queue.snapshot.json` / `docs/security/SECURITY-APPROVAL-QUEUE.md` | | Security approval gate | `docs/security/security-approval-gate.snapshot.json` / `docs/security/SECURITY-APPROVAL-GATE.md` | +| Security approval decision record | `docs/security/security-approval-decision-record.snapshot.json` / `docs/security/SECURITY-APPROVAL-DECISION-RECORD.md` | | Security mirror readiness | `docs/security/security-mirror-readiness.snapshot.json` / `docs/security/SECURITY-MIRROR-READINESS.md` | | Security mirror intake plan | `docs/security/security-mirror-intake-plan.snapshot.json` / `docs/security/SECURITY-MIRROR-INTAKE-PLAN.md` | | 資安鏡像事件契約 | `docs/security/security-mirror-event-sample.snapshot.json` / `docs/security/SECURITY-MIRROR-EVENT-CONTRACT.md` | diff --git a/docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md b/docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md index 566e6720..0a864abc 100644 --- a/docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md +++ b/docs/security/AWOOOP-SECURITY-SUPPLYCHAIN-INTEGRATION-HANDOFF.md @@ -73,7 +73,7 @@ ```text Kali / Code Review / GitHub / Gitea / Codex -> security_supply_chain_contract_manifest_v1 - -> security_mirror_readiness_v1 / security_mirror_intake_plan_v1 / security_mirror_event_v1 / security_mirror_route_v1 / security_mirror_acceptance_v1 / security_mirror_quarantine_v1 / security_mirror_dry_run_v1 / security_mirror_status_rollup_v1 / security_finding_v1 / kali_scan_scope_approval_v1 / security_approval_queue_v1 / security_approval_gate_v1 / coding_task_v1 / source_control_migration_event_v1 / gitea_repo_inventory_v1 / local_git_remote_inventory_v1 / github_target_probe_v1 / github_target_decision_v1 / github_target_repo_approval_package_v1 / security_rollout_policy_v1 + -> security_mirror_readiness_v1 / security_mirror_intake_plan_v1 / security_mirror_event_v1 / security_mirror_route_v1 / security_mirror_acceptance_v1 / security_mirror_quarantine_v1 / security_mirror_dry_run_v1 / security_mirror_status_rollup_v1 / security_finding_v1 / kali_scan_scope_approval_v1 / security_approval_queue_v1 / security_approval_gate_v1 / security_approval_decision_record_v1 / coding_task_v1 / source_control_migration_event_v1 / gitea_repo_inventory_v1 / local_git_remote_inventory_v1 / github_target_probe_v1 / github_target_decision_v1 / github_target_repo_approval_package_v1 / security_rollout_policy_v1 -> AWOOOI ingestion / asset_inventory / AIOps KPI / AOL -> mirror 到 AwoooP Runtime State / Channel Event / Audit -> AwoooP Policy / Approval / Exception / Operator Console @@ -147,6 +147,18 @@ Snapshot：`docs/security/security-approval-gate.snapshot.json` AwoooP 初期處理方式：只記錄人工決策、audit evidence 與批准範圍；不得把 gate item 接成 runner，不得在批准後自動啟動 scan、repo、refs、deploy 或 secret 類動作。 +### `security_approval_decision_record_v1` + +用途：定義 S3 人工決策紀錄格式，保存 approve / reject / defer / request more evidence / keep blocked 的稽核資料。 + +Schema：`docs/schemas/security_approval_decision_record_v1.schema.json` + +Snapshot：`docs/security/security-approval-decision-record.snapshot.json` + +目前 decision records：0 筆；所有紀錄都必須維持 `execution_authorized=false`，且批准後仍需 follow-up runtime gate。 + +AwoooP 初期處理方式：只保存 reviewer、時間、evidence refs、批准範圍與決策結果；不得把 decision record 當成執行命令。 + ### `security_mirror_readiness_v1` 用途：集中整理 Security Supply Chain contracts 的 mirror readiness，讓 AwoooP 先知道哪些可 mirror、哪些 partial、哪些 contract-only。 @@ -155,7 +167,7 @@ Schema：`docs/schemas/security_mirror_readiness_v1.schema.json` Snapshot：`docs/security/security-mirror-readiness.snapshot.json` -目前 readiness：28 個 contracts，25 個 ready for mirror，2 個 partial ready，1 個 contract-only，0 個 blocked。所有 contract 都是 `execution_allowed=false`。 +目前 readiness：29 個 contracts，26 個 ready for mirror，2 個 partial ready，1 個 contract-only，0 個 blocked。所有 contract 都是 `execution_allowed=false`。 AwoooP 初期處理方式：先 mirror readiness index，再依 readiness 分批 mirror 其他 snapshots；不得把 readiness 當 execution authorization。 @@ -191,7 +203,7 @@ Schema：`docs/schemas/security_mirror_route_v1.schema.json` Snapshot：`docs/security/security-mirror-route.snapshot.json` -目前 route：5 個 route groups，涵蓋 28 個 contracts；所有 route 都是 `runtime_execution_authorized=false`。 +目前 route：5 個 route groups，涵蓋 29 個 contracts；所有 route 都是 `runtime_execution_authorized=false`。 AwoooP 初期處理方式：只依 route group 顯示 Operator Console / Runtime State / Channel Event / Audit / Approval Queue，不把 route 轉成 execution router。 @@ -239,7 +251,7 @@ Schema：`docs/schemas/security_mirror_status_rollup_v1.schema.json` Snapshot：`docs/security/security-mirror-status-rollup.snapshot.json` -目前 rollup：`framework_ready_waiting_approval`；28 個 contracts、25 ready、2 partial、1 contract-only、0 blocked；approval queue 仍為 8 items，其中 7 pending approval、1 block candidate。 +目前 rollup：`framework_ready_waiting_approval`；29 個 contracts、26 ready、2 partial、1 contract-only、0 blocked；approval queue 仍為 8 items，其中 7 pending approval、1 block candidate，decision records 目前 0 筆。 AwoooP 初期處理方式：只顯示階段狀態、下一個 gate 與禁止事項，可寫入 Audit evidence；不得把 rollup 當 runtime authorization。 @@ -275,7 +287,7 @@ Schema：`docs/schemas/security_supply_chain_contract_manifest_v1.schema.json` "schema_version": "security_supply_chain_contract_manifest_v1", "status": "draft", "default_enforcement_level": "mirror_only", - "contract_count": 28 + "contract_count": 29 } ``` @@ -690,7 +702,7 @@ Console 初期不提供高風險執行按鈕。 2026-05-12 contract manifest 追加：已新增 `docs/schemas/security_supply_chain_contract_manifest_v1.schema.json`、`docs/security/security-supply-chain-contract-manifest.snapshot.json` 與 `docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md`。AwoooP 應先讀 manifest 作為 mirror-only contract registry，不把 manifest 當 execution router。 -2026-05-13 mirror route 追加：已新增 `docs/schemas/security_mirror_route_v1.schema.json`、`docs/security/security-mirror-route.snapshot.json` 與 `docs/security/SECURITY-MIRROR-ROUTE.md`。AwoooP 可依 5 個 route groups 將 28 個 contracts 分流到 Operator Console、Runtime State、Channel Event、Audit evidence 與 Approval Queue；route 只決定目的地、channel policy 與 review lane，不是 execution router。 +2026-05-13 mirror route 追加：已新增 `docs/schemas/security_mirror_route_v1.schema.json`、`docs/security/security-mirror-route.snapshot.json` 與 `docs/security/SECURITY-MIRROR-ROUTE.md`。AwoooP 可依 5 個 route groups 將 29 個 contracts 分流到 Operator Console、Runtime State、Channel Event、Audit evidence 與 Approval Queue；route 只決定目的地、channel policy 與 review lane，不是 execution router。 2026-05-13 mirror acceptance 追加：已新增 `docs/schemas/security_mirror_acceptance_v1.schema.json`、`docs/security/security-mirror-acceptance.snapshot.json` 與 `docs/security/SECURITY-MIRROR-ACCEPTANCE.md`。AwoooP 可用 7 個 acceptance checks 驗收 mirror ingestion；blocking checks 只針對 contract count mismatch、缺 event envelope、route coverage 不完整或未脫敏 evidence，不得阻擋 runtime 流程。 @@ -698,10 +710,12 @@ Console 初期不提供高風險執行按鈕。 2026-05-13 mirror dry-run 追加：已新增 `docs/schemas/security_mirror_dry_run_v1.schema.json`、`docs/security/security-mirror-dry-run.snapshot.json` 與 `docs/security/SECURITY-MIRROR-DRY-RUN.md`。AwoooP 未來可用 6 個 dry-run steps 回報接入演練結果；本 snapshot 狀態為 `contract_defined_not_executed`，不得視為 production ingestion 已啟用。 -2026-05-13 mirror status rollup 追加：已新增 `docs/schemas/security_mirror_status_rollup_v1.schema.json`、`docs/security/security-mirror-status-rollup.snapshot.json` 與 `docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md`。AwoooP 與 Security Supply Chain Session 可用同一份 rollup 同步 S0-S4、28 個 contracts、approval queue summary 與下一個安全 gate；本契約不授權任何 runtime action。 +2026-05-13 mirror status rollup 追加：已新增 `docs/schemas/security_mirror_status_rollup_v1.schema.json`、`docs/security/security-mirror-status-rollup.snapshot.json` 與 `docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md`。AwoooP 與 Security Supply Chain Session 可用同一份 rollup 同步 S0-S4、29 個 contracts、approval queue summary 與下一個安全 gate；本契約不授權任何 runtime action。 2026-05-13 S3 approval gate 追加：已新增 `docs/schemas/security_approval_gate_v1.schema.json`、`docs/security/security-approval-gate.snapshot.json` 與 `docs/security/SECURITY-APPROVAL-GATE.md`。AwoooP 可用 8 個 gate items 記錄人工批准、拒絕、延後或補 evidence；批准後仍需 follow-up runtime gate，不得直接執行。 +2026-05-13 S3 decision record 追加：已新增 `docs/schemas/security_approval_decision_record_v1.schema.json`、`docs/security/security-approval-decision-record.snapshot.json` 與 `docs/security/SECURITY-APPROVAL-DECISION-RECORD.md`。AwoooP 可保存人工決策稽核紀錄；目前 0 筆 decision records，所有紀錄都必須 `execution_authorized=false`。 + 2026-05-13 Kali 112 live 整合狀態追加：已在授權下登入 `192.168.0.112` 做 read-only 盤點與低風險更新，並新增 `docs/schemas/kali_integration_status_v1.schema.json`、`docs/security/kali-integration-status.snapshot.json` 與 `docs/security/KALI-INTEGRATION-STATUS.md`。Kali Scanner API `/health` healthy、`kali-scanner.service` active/enabled、node-exporter 與 wg-easy container up；已 targeted update `nmap`、`nikto`、`nuclei`、`curl`、`openssl`、CA 套件，安裝 `jq`，時區改為 `Asia/Taipei`，更新後無 reboot required。AwoooP 可 mirror health / update / gap evidence，但不得直接啟動 scan、credentialed scan 或 `/execute`。 本波仍不做： @@ -756,6 +770,8 @@ Console 初期不提供高風險執行按鈕。 - [security_mirror_status_rollup_v1 snapshot](/Users/ogt/awoooi/docs/security/security-mirror-status-rollup.snapshot.json) - [資安人工批准 Gate 契約](/Users/ogt/awoooi/docs/security/SECURITY-APPROVAL-GATE.md) - [security_approval_gate_v1 snapshot](/Users/ogt/awoooi/docs/security/security-approval-gate.snapshot.json) +- [資安人工決策紀錄契約](/Users/ogt/awoooi/docs/security/SECURITY-APPROVAL-DECISION-RECORD.md) +- [security_approval_decision_record_v1 snapshot](/Users/ogt/awoooi/docs/security/security-approval-decision-record.snapshot.json) - [Source Control ref truth classification](/Users/ogt/awoooi/docs/security/SOURCE-CONTROL-REF-TRUTH-CLASSIFICATION.md) - [source_control_ref_truth_classification_v1 snapshot](/Users/ogt/awoooi/docs/security/source-control-ref-truth-classification.snapshot.json) - [本機 repo canonical lineage snapshot](/Users/ogt/awoooi/docs/security/LOCAL-REPO-CANONICAL-EWOOOC-MOMO-SNAPSHOT.md) @@ -786,6 +802,7 @@ Console 初期不提供高風險執行按鈕。 - [security_supply_chain_contract_manifest_v1 schema](/Users/ogt/awoooi/docs/schemas/security_supply_chain_contract_manifest_v1.schema.json) - [security_mirror_status_rollup_v1 schema](/Users/ogt/awoooi/docs/schemas/security_mirror_status_rollup_v1.schema.json) - [security_approval_gate_v1 schema](/Users/ogt/awoooi/docs/schemas/security_approval_gate_v1.schema.json) +- [security_approval_decision_record_v1 schema](/Users/ogt/awoooi/docs/schemas/security_approval_decision_record_v1.schema.json) - [source_control_ref_truth_classification_v1 schema](/Users/ogt/awoooi/docs/schemas/source_control_ref_truth_classification_v1.schema.json) - [local_repo_canonical_probe_v1 schema](/Users/ogt/awoooi/docs/schemas/local_repo_canonical_probe_v1.schema.json) - [git_remote_refs_probe_v1 schema](/Users/ogt/awoooi/docs/schemas/git_remote_refs_probe_v1.schema.json) diff --git a/docs/security/SECURITY-APPROVAL-DECISION-RECORD.md b/docs/security/SECURITY-APPROVAL-DECISION-RECORD.md new file mode 100644 index 00000000..26d39e24 --- /dev/null +++ b/docs/security/SECURITY-APPROVAL-DECISION-RECORD.md @@ -0,0 +1,52 @@ +# 資安人工決策紀錄契約 + +| 項目 | 內容 | +|------|------| +| 日期 | 2026-05-13 | +| 狀態 | 草案 | +| Schema | `docs/schemas/security_approval_decision_record_v1.schema.json` | +| Snapshot | `docs/security/security-approval-decision-record.snapshot.json` | +| 模式 | `decision_record_only` | +| runtime 執行授權 | `false` | + +## 0. 核心結論 + +`security_approval_decision_record_v1` 是 S3.1 的人工決策稽核格式。 + +它只保存人工決策本身，例如批准範圍、拒絕、延後、要求補 evidence 或維持 blocked。 + +它不是 runner，也不是授權 token。任何決策紀錄都必須維持 `execution_authorized=false`。 + +## 1. 目前狀態 + +| 指標 | 數量 | +|------|------| +| Decision records | 0 | +| Approved scope | 0 | +| Rejected | 0 | +| Deferred | 0 | +| Request more evidence | 0 | +| Keep blocked | 0 | +| Runtime actions authorized | `false` | + +## 2. AwoooP 可做 + +1. 對 `security_approval_gate_v1` 的 gate item 記錄人工決策。 +2. 保存 reviewer、時間、evidence refs 與批准範圍。 +3. 顯示哪些決策仍需要 follow-up runtime gate。 +4. 將決策紀錄寫入 Audit evidence。 +5. 將拒絕、延後或補 evidence 的原因顯示給 Operator。 + +## 3. AwoooP 不可做 + +1. 不把 decision record 當成執行命令。 +2. 不因為 `approve_scope` 就自動執行。 +3. 不啟動 scan、credentialed scan 或 Kali `/execute`。 +4. 不建立 GitHub repo、不改 visibility、不 sync refs、不切 GitHub primary。 +5. 不保存 raw secret、token、cookie、private key、credential value 或 exploit payload。 + +## 4. 階段定位 + +S3.1 只是讓人工決策可追溯。 + +它讓治理面更清楚，但仍然維持低摩擦：沒有 runtime enforcement，沒有自動修復，沒有把 approval queue 接成 runner。 diff --git a/docs/security/SECURITY-APPROVAL-GATE.md b/docs/security/SECURITY-APPROVAL-GATE.md index 55e592e4..c8f72ad7 100644 --- a/docs/security/SECURITY-APPROVAL-GATE.md +++ b/docs/security/SECURITY-APPROVAL-GATE.md @@ -17,6 +17,8 @@ 批准後最多只能進入下一步設計、草案、只讀 inventory、低噪音 scope 或人工 exception；任何真正 runtime action 都還需要後續 runtime gate。 +S3.1 開始，實際人工決策紀錄由 `security_approval_decision_record_v1` 保存。Gate 定義可審項目與批准範圍；Decision Record 保存決策結果與 audit evidence。 + ## 1. 目前 Gate 狀態 | 指標 | 數量 | @@ -49,6 +51,7 @@ 3. 將人工決策寫入 Audit evidence。 4. 顯示批准範圍與仍然禁止事項。 5. 提醒哪些項目需要 follow-up runtime gate。 +6. 將決策結果寫成 `security_approval_decision_record_v1`，但維持 `execution_authorized=false`。 ## 4. AwoooP 不可做 diff --git a/docs/security/SECURITY-APPROVAL-QUEUE.md b/docs/security/SECURITY-APPROVAL-QUEUE.md index cd45689f..6a7cd44e 100644 --- a/docs/security/SECURITY-APPROVAL-QUEUE.md +++ b/docs/security/SECURITY-APPROVAL-QUEUE.md @@ -15,7 +15,7 @@ 它不是授權清單。所有 queue item 都只能顯示、排序、建立 approval candidate，不能直接執行。 -S3.0 開始，實際人工決策格式由 `security_approval_gate_v1` 承接。Queue 負責排序候選；Gate 負責記錄批准範圍、reviewers、決策結果與 follow-up runtime gate。 +S3.0 開始，人工批准範圍由 `security_approval_gate_v1` 承接。S3.1 開始，實際人工決策結果由 `security_approval_decision_record_v1` 保存。Queue 負責排序候選；Gate 負責限制批准範圍；Decision Record 負責稽核紀錄。 目前狀態： @@ -48,7 +48,7 @@ S3.0 開始，實際人工決策格式由 `security_approval_gate_v1` 承接。Q 3. 建立 approval candidate。 4. 保存人工決策結果與 audit evidence。 5. 依 review order 提醒下一個低摩擦 gate。 -6. 將決策寫入 `security_approval_gate_v1`，但不觸發執行。 +6. 將批准範圍對齊 `security_approval_gate_v1`，再把決策結果寫入 `security_approval_decision_record_v1`，但不觸發執行。 ## 3. AwoooP 不可以做 diff --git a/docs/security/SECURITY-MIRROR-ACCEPTANCE.md b/docs/security/SECURITY-MIRROR-ACCEPTANCE.md index 28dd72b1..790379a8 100644 --- a/docs/security/SECURITY-MIRROR-ACCEPTANCE.md +++ b/docs/security/SECURITY-MIRROR-ACCEPTANCE.md @@ -27,7 +27,7 @@ | Check | 目的 | 失敗時是否阻擋鏡像 | |-------|------|--------------------| -| `CONTRACT_COUNT_MATCH` | 確認 manifest、readiness、route coverage 對齊 28 個 contracts | 是 | +| `CONTRACT_COUNT_MATCH` | 確認 manifest、readiness、route coverage 對齊 29 個 contracts | 是 | | `EVENT_ENVELOPE_REQUIRED` | 確認每筆 payload 都不可執行、不可顯示執行按鈕 | 是 | | `ROUTE_GROUP_COVERAGE` | 確認 5 個 route groups 覆蓋所有 contracts | 是 | | `REDACTION_ONLY` | 確認不保存 raw sensitive value | 是 | diff --git a/docs/security/SECURITY-MIRROR-INTAKE-PLAN.md b/docs/security/SECURITY-MIRROR-INTAKE-PLAN.md index e8a1abab..7af7eac8 100644 --- a/docs/security/SECURITY-MIRROR-INTAKE-PLAN.md +++ b/docs/security/SECURITY-MIRROR-INTAKE-PLAN.md @@ -19,10 +19,10 @@ | Wave | 目的 | 主要 contracts | Exit gate | |------|------|----------------|-----------| -| `M0_index_bootstrap` | 先載入 readiness、manifest、低摩擦 policy、鏡像事件信封、鏡像路由矩陣、驗收契約、隔離契約、dry-run 報告格式、status rollup 與 approval gate | readiness / manifest / rollout policy / mirror event / mirror route / acceptance / quarantine / dry-run / status rollup / approval gate | 顯示 28 個 contract 且 `execution_allowed=false` | +| `M0_index_bootstrap` | 先載入 readiness、manifest、低摩擦 policy、鏡像事件信封、鏡像路由矩陣、驗收契約、隔離契約、dry-run 報告格式、status rollup、approval gate 與 decision record | readiness / manifest / rollout policy / mirror event / mirror route / acceptance / quarantine / dry-run / status rollup / approval gate / decision record | 顯示 29 個 contract 且 `execution_allowed=false` | | `M1_kali_visibility` | 顯示 Kali 112、scan scope、approval queue | Kali status / scan scope / approval queue / finding sample | 顯示 5 個 scope groups 與 8 個 queue items，沒有執行按鈕 | | `M2_source_control_visibility` | 顯示 Gitea/GitHub source-control evidence | migration / inventory / refs / approval board | 顯示 blocking reasons，repo/refs actions 全 disabled | -| `M3_approval_candidates` | 顯示 approval candidates、S3 gate 與人工決策留痕 | approval events / approval queue / approval gate / source-control board | 可留痕，不可自動批准或執行 | +| `M3_approval_candidates` | 顯示 approval candidates、S3 gate、decision record 與人工決策留痕 | approval events / approval queue / approval gate / decision record / source-control board | 可留痕，不可自動批准或執行 | | `M4_patch_only_backlog` | 顯示 Codex patch-only backlog lane | coding task | 只顯示 lane，不接 Codex runner action | ## 2. AwoooP 可做 @@ -37,8 +37,9 @@ 8. 將 ready / partial contracts mirror 成 Operator Console / Runtime State / Channel Event / Audit evidence。 9. 將 approval-only contracts mirror 到 Approval Queue。 10. 使用 `security_approval_gate_v1` 顯示批准範圍與 follow-up runtime gate。 -11. 顯示 required reviewers、blocked reason、evidence refs、review order。 -12. 記錄人工決策結果，但不自動執行後續動作。 +11. 使用 `security_approval_decision_record_v1` 保存人工決策紀錄。 +12. 顯示 required reviewers、blocked reason、evidence refs、review order。 +13. 記錄人工決策結果，但不自動執行後續動作。 ## 3. AwoooP 不可做 diff --git a/docs/security/SECURITY-MIRROR-READINESS.md b/docs/security/SECURITY-MIRROR-READINESS.md index 4b661b12..4eb5a0d9 100644 --- a/docs/security/SECURITY-MIRROR-READINESS.md +++ b/docs/security/SECURITY-MIRROR-READINESS.md @@ -23,7 +23,7 @@ | 狀態 | 數量 | 說明 | |------|------|------| -| `ready_for_mirror` | 25 | 可直接 mirror 成 Operator Console / Runtime State / Channel Event / Audit evidence | +| `ready_for_mirror` | 26 | 可直接 mirror 成 Operator Console / Runtime State / Channel Event / Audit evidence | | `partial_ready` | 2 | 可 mirror，但 evidence 仍不完整 | | `contract_only` | 1 | 有 schema / handoff，尚無正式 snapshot | | `blocked` | 0 | 目前沒有禁止 mirror 的 contract | @@ -76,7 +76,8 @@ AwoooP 可以將 ready / partial contracts mirror 到： 8. 再 mirror `security_mirror_intake_plan_v1`，照 wave 執行 read-only intake。 9. 再 mirror `security_approval_queue_v1`，只顯示 review order。 10. 再 mirror `security_approval_gate_v1`，只記錄人工決策與 follow-up runtime gate。 -11. 再 mirror `kali_integration_status_v1` 與 `kali_scan_scope_approval_v1`。 -12. 最後再 mirror source-control 相關 contracts。 +11. 再 mirror `security_approval_decision_record_v1`，只保存人工決策紀錄，不觸發執行。 +12. 再 mirror `kali_integration_status_v1` 與 `kali_scan_scope_approval_v1`。 +13. 最後再 mirror source-control 相關 contracts。 整個 S2 不新增 execution router、不新增執行按鈕、不新增 runtime blocker。 diff --git a/docs/security/SECURITY-MIRROR-ROUTE.md b/docs/security/SECURITY-MIRROR-ROUTE.md index 7665a5a4..ee1884b3 100644 --- a/docs/security/SECURITY-MIRROR-ROUTE.md +++ b/docs/security/SECURITY-MIRROR-ROUTE.md @@ -28,7 +28,7 @@ | `M0_index_bootstrap` | 載入 readiness、manifest、policy、event、intake、route、acceptance、quarantine、dry-run、status rollup | `no_channel_event` | `observe` | | `M1_kali_visibility` | 顯示 Kali 112、111 / 168 scope、approval queue 與 finding sample | `approval_required_only` | `approval_required` | | `M2_source_control_visibility` | 顯示 Gitea / GitHub repo、branch、tag、canonical 差異 | `low_noise_status` | `source_control_review` | -| `M3_approval_candidates` | 顯示人工批准候選、S3 gate 與留痕 | `approval_required_only` | `approval_required` | +| `M3_approval_candidates` | 顯示人工批准候選、S3 gate、decision record 與留痕 | `approval_required_only` | `approval_required` | | `M4_patch_only_backlog` | 顯示 Code Review 後的 Codex patch-only backlog lane | `no_channel_event` | `patch_only` | ## 2. AwoooP 可做 @@ -52,7 +52,7 @@ S2.7 後，AwoooP 主線只需要能讀到： -1. 28 個 contracts。 +1. 29 個 contracts。 2. 5 個 route groups。 3. 所有 route group 都是 `runtime_execution_authorized=false`。 4. Channel Event 初期低噪音。 diff --git a/docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md b/docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md index 261ce2ca..f989a2a4 100644 --- a/docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md +++ b/docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md @@ -19,10 +19,11 @@ | 類型 | 狀態 | |------|------| -| Contract manifest | 28 個 contracts | -| Mirror readiness | 25 ready、2 partial、1 contract-only、0 blocked | +| Contract manifest | 29 個 contracts | +| Mirror readiness | 26 ready、2 partial、1 contract-only、0 blocked | | Approval queue | 8 items：7 pending approval、1 block candidate | | Approval gate | S3.0 已建立；0 approved、7 pending、1 block candidate | +| Decision records | S3.1 已建立；目前 0 筆決策紀錄 | | Dry-run | `contract_defined_not_executed` | | Runtime actions | `false` | | Payload ingestion | `false` | @@ -47,7 +48,7 @@ 下一步仍不是 runtime enforcement。 -建議先讓 AwoooP 主線只讀消費本 rollup 與 `security_approval_gate_v1`，並由人工依序 review： +建議先讓 AwoooP 主線只讀消費本 rollup、`security_approval_gate_v1` 與 `security_approval_decision_record_v1`，並由人工依序 review： 1. redacted finding ingestion adapter。 2. safe web crawl scope。 diff --git a/docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md b/docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md index 5843ca23..0d862bb7 100644 --- a/docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md +++ b/docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md @@ -11,7 +11,7 @@ ## 0. 核心結論 -目前 Security Supply Chain 已有 28 個主要契約可交給 AwoooP 消費。Manifest 的用途是把分散的 schema、snapshot、人讀文件、允許動作與禁止動作收成一份入口，避免不同 Session 各自解讀。 +目前 Security Supply Chain 已有 29 個主要契約可交給 AwoooP 消費。Manifest 的用途是把分散的 schema、snapshot、人讀文件、允許動作與禁止動作收成一份入口，避免不同 Session 各自解讀。 初期預設仍是 `mirror_only`。Manifest 不授權 runtime enforcement、不授權 GitHub/Gitea 主控切換、不授權 repo 建立或 refs sync。 @@ -25,6 +25,7 @@ | `kali_scan_scope_approval_v1` | approval-only | Kali scan scope、111/168 observe-only、active/credentialed/execute gate | `kali-scan-scope-approval.snapshot.json` | | `security_approval_queue_v1` | approval-only | AwoooP 可 mirror 的 Security Supply Chain approval queue | `security-approval-queue.snapshot.json` | | `security_approval_gate_v1` | approval-only | S3 人工批准 gate 與 follow-up runtime gate 邊界 | `security-approval-gate.snapshot.json` | +| `security_approval_decision_record_v1` | approval-only | S3 人工決策稽核紀錄 | `security-approval-decision-record.snapshot.json` | | `security_mirror_readiness_v1` | mirror-only | AwoooP mirror/read-only readiness index | `security-mirror-readiness.snapshot.json` | | `security_mirror_intake_plan_v1` | mirror-only | AwoooP mirror-only intake waves 與 acceptance gates | `security-mirror-intake-plan.snapshot.json` | | `security_mirror_event_v1` | mirror-only | AwoooP mirror event envelope | `security-mirror-event-sample.snapshot.json` | diff --git a/docs/security/SECURITY-SUPPLY-CHAIN-PROGRESS.md b/docs/security/SECURITY-SUPPLY-CHAIN-PROGRESS.md index 5486477a..8482d0ee 100644 --- a/docs/security/SECURITY-SUPPLY-CHAIN-PROGRESS.md +++ b/docs/security/SECURITY-SUPPLY-CHAIN-PROGRESS.md @@ -4,7 +4,7 @@ |------|------| | 日期 | 2026-05-13 | | 狀態 | S0/S1 read-only evidence 建置中 | -| 本階段完成 | 資安供應鏈 contract manifest + Source Control Approval Board + Draft Reconcile Plan + Ref Detail Diff + Ref Truth Classification + Kali 112 live integration status + Security Finding contract + Kali scan scope approval package + Security Approval Queue + S3 人工批准 Gate + 鏡像 readiness index + 鏡像接收計畫 + 鏡像事件信封 + 鏡像路由矩陣 + 鏡像驗收契約 + 鏡像隔離契約 + 鏡像 dry-run 報告契約 + 鏡像狀態彙整契約 | +| 本階段完成 | 資安供應鏈 contract manifest + Source Control Approval Board + Draft Reconcile Plan + Ref Detail Diff + Ref Truth Classification + Kali 112 live integration status + Security Finding contract + Kali scan scope approval package + Security Approval Queue + S3 人工批准 Gate + S3 人工決策紀錄 + 鏡像 readiness index + 鏡像接收計畫 + 鏡像事件信封 + 鏡像路由矩陣 + 鏡像驗收契約 + 鏡像隔離契約 + 鏡像 dry-run 報告契約 + 鏡像狀態彙整契約 | | 原則 | 低摩擦分階段；文件、schema、read-only evidence 優先；不做 runtime enforcement、不切 primary | ## 0. 本階段完成後整體進度 @@ -20,11 +20,11 @@ | S1.2b branch/tag detail diff | 完成草案 | 3 個 refs-blocked mapped repos 已完成 branch/tag 明細 diff；已忽略本 PR 分支避免 evidence 自我污染 | 人工判定真相來源與 deprecated refs | | S1.2c refs 真相來源分類 | 完成草案 | 141 個 ref review items 已分類：4 個真相來源、114 個 drift deprecated 候選、3 個 release tags、20 個 GitHub-only refs | repo owner 單 ref / 單 repo 判定 | | S1.3 低摩擦 rollout policy | 完成草案 | observe-first / mirror-only matrix 已建立 | AwoooP read-only policy 消費 | -| S1.4 契約索引 | 完成草案 | 28 個主要 contract 已集中成 manifest | AwoooP mirror-only contract registry | +| S1.4 契約索引 | 完成草案 | 29 個主要 contract 已集中成 manifest | AwoooP mirror-only contract registry | | S1.5 Kali 112 live 整合狀態 | 完成第一波 | 112 已登入盤點、scanner API healthy、targeted scanner packages updated、Asia/Taipei timezone、no reboot required | scan result ingestion + `/execute` high-risk gate | | S1.6 Kali finding / scan scope approval | 完成草案 | `security_finding_v1` sample snapshot 與 `kali_scan_scope_approval_v1` approval package 已建立；111/168 已納入 observe-only scope | 人工批准 safe crawl / credentialed scan / runtime ingestion / full-upgrade gate | | S1.7 Security approval queue | 完成草案 | 8 個 approval queue items 已集中：7 pending approval、1 block candidate；AwoooP 可 mirror 但不得執行 | 先 review redacted finding ingestion，再 review safe crawl / Gitea inventory | -| S2 AwoooP mirror-only readiness | 完成草案 | `security_mirror_readiness_v1` 已整理 28 個 contracts：25 ready、2 partial、1 contract-only、0 blocked | AwoooP 主線建立只讀入口 | +| S2 AwoooP mirror-only readiness | 完成草案 | `security_mirror_readiness_v1` 已整理 29 個 contracts：26 ready、2 partial、1 contract-only、0 blocked | AwoooP 主線建立只讀入口 | | S2.1 AwoooP mirror-only intake plan | 完成草案 | `security_mirror_intake_plan_v1` 已建立 5 個 intake waves 與 4 個 acceptance gates | AwoooP 主線照 wave mirror，不新增 execution router | | S2.2 AwoooP 鏡像事件信封 | 完成草案 | `security_mirror_event_v1` 已建立，要求每筆鏡像 payload 標示 `execution_authorized=false` 與 `action_buttons_allowed=false` | AwoooP 鏡像 payload 統一信封 | | S2.3 AwoooP 鏡像路由矩陣 | 完成草案 | `security_mirror_route_v1` 已建立 5 個 route groups，定義目的地、channel policy 與 review lane | AwoooP 消費時不猜路由、不新增執行入口 | @@ -34,6 +34,7 @@ | S2.7 AwoooP 鏡像狀態彙整契約 | 完成草案 | `security_mirror_status_rollup_v1` 已建立，彙整 S0-S4、approval queue summary 與下一個安全 gate | 兩個 Session 用同一份 rollup 同步，不誤啟執行面 | | S3 approval gate | 進行中 | `security_approval_gate_v1` 已建立 8 個人工 gate items：7 pending、1 block candidate、0 approved | 不得繞過人工批准；批准後仍需 follow-up runtime gate | | S3.0 人工批准 Gate 契約 | 完成草案 | 定義批准範圍、決策選項、required reviewers、still forbidden 與 follow-up runtime gate | AwoooP 可記錄決策，不可執行 gate item | +| S3.1 人工決策紀錄契約 | 完成草案 | `security_approval_decision_record_v1` 已建立；目前 0 筆 decision records、0 個 runtime action 授權 | AwoooP 可稽核決策，不可把決策當執行 | | S4 migration execution | 未開始 | GitHub primary 長期方向已確認，但 refs / tags / workflow / secret 名稱尚未全量驗證 | SHA/tag/workflow parity 與 rollback ADR | ## 1. 已建立的主要 evidence @@ -72,6 +73,8 @@ | Security approval queue JSON | `docs/security/security-approval-queue.snapshot.json` | | Security approval gate | `docs/security/SECURITY-APPROVAL-GATE.md` | | Security approval gate JSON | `docs/security/security-approval-gate.snapshot.json` | +| Security approval decision record | `docs/security/SECURITY-APPROVAL-DECISION-RECORD.md` | +| Security approval decision record JSON | `docs/security/security-approval-decision-record.snapshot.json` | | Security mirror readiness | `docs/security/SECURITY-MIRROR-READINESS.md` | | Security mirror readiness JSON | `docs/security/security-mirror-readiness.snapshot.json` | | Security mirror intake plan | `docs/security/SECURITY-MIRROR-INTAKE-PLAN.md` | @@ -117,6 +120,6 @@ 3. 依 `SOURCE-CONTROL-REF-TRUTH-CLASSIFICATION.md` 對 `awoooi`、`clawbot-v5`、`wooo-aiops` 做單 repo / 單 ref owner 判定；仍不得 push refs。 4. 對 `ewoooc` / `momo-pro-system` 完成 server-side canonical 判定。 5. 依 `KALI-SCAN-SCOPE-APPROVAL-PACKAGE.md` 取得 safe crawl、credentialed scan、runtime ingestion、full-upgrade / reboot 等 gate 的人工批准；不得直接接 `/execute`。 -6. AwoooP 主線先讀 `security_mirror_readiness_v1`、`security_mirror_intake_plan_v1`、`security_mirror_event_v1`、`security_mirror_route_v1`、`security_mirror_acceptance_v1`、`security_mirror_quarantine_v1`、`security_mirror_dry_run_v1`、`security_mirror_status_rollup_v1` 與 `security_approval_gate_v1`，只建立 mirror-only / read-only policy 入口，不新增執行按鈕。 +6. AwoooP 主線先讀 `security_mirror_readiness_v1`、`security_mirror_intake_plan_v1`、`security_mirror_event_v1`、`security_mirror_route_v1`、`security_mirror_acceptance_v1`、`security_mirror_quarantine_v1`、`security_mirror_dry_run_v1`、`security_mirror_status_rollup_v1`、`security_approval_gate_v1` 與 `security_approval_decision_record_v1`，只建立 mirror-only / read-only policy 入口，不新增執行按鈕。 7. AwoooP 主線消費 `security_rollout_policy_v1` 時，只做 read-only policy，不做 runtime blocking。 -8. AwoooP 主線再讀 `security_approval_queue_v1`、`security_approval_gate_v1` 與 `security_supply_chain_contract_manifest_v1`，顯示 review order、批准範圍與 blocked reason，不新增 execution router。 +8. AwoooP 主線再讀 `security_approval_queue_v1`、`security_approval_gate_v1`、`security_approval_decision_record_v1` 與 `security_supply_chain_contract_manifest_v1`，顯示 review order、批准範圍、決策紀錄與 blocked reason，不新增 execution router。 diff --git a/docs/security/security-approval-decision-record.snapshot.json b/docs/security/security-approval-decision-record.snapshot.json new file mode 100644 index 00000000..4c89ba60 --- /dev/null +++ b/docs/security/security-approval-decision-record.snapshot.json @@ -0,0 +1,46 @@ +{ + "schema_version": "security_approval_decision_record_v1", + "status": "draft", + "date": "2026-05-13", + "mode": "decision_record_only", + "runtime_execution_authorized": false, + "source_indexes": [ + "docs/security/security-approval-gate.snapshot.json", + "docs/security/security-approval-queue.snapshot.json", + "docs/security/security-mirror-status-rollup.snapshot.json" + ], + "summary": { + "total_decision_records": 0, + "approve_scope_count": 0, + "reject_count": 0, + "defer_count": 0, + "request_more_evidence_count": 0, + "keep_blocked_count": 0, + "pending_runtime_gate_count": 0, + "runtime_actions_authorized": false, + "raw_secret_storage_authorized": false + }, + "decision_records": [], + "recording_rules": [ + "每筆人工決策都必須引用 security_approval_gate_v1 的 gate_id 與 source_queue_item_id。", + "approve_scope 只代表批准該 scope 進下一步設計、草案、只讀 inventory、低噪音 scope 或人工 exception；不代表可立即執行。", + "所有 decision record 都必須維持 execution_authorized=false。", + "任何批准後的 scan、/execute、repo、refs、deploy、secret、RBAC、NetworkPolicy、firewall 變更都必須另有 follow-up runtime gate。", + "決策紀錄不得保存 raw secret、token、cookie、private key、credential value 或 exploit payload。" + ], + "forbidden_actions": [ + "execute_decision_record", + "auto_approve", + "execute_after_decision_without_runtime_gate", + "start_kali_scan", + "call_kali_execute_endpoint", + "run_credentialed_scan", + "create_github_repo", + "change_repo_visibility", + "sync_git_refs", + "switch_github_primary", + "auto_merge", + "production_deploy", + "store_secret_token_cookie_private_key_or_exploit_payload" + ] +} diff --git a/docs/security/security-mirror-acceptance.snapshot.json b/docs/security/security-mirror-acceptance.snapshot.json index 69f11f4f..952c6e76 100644 --- a/docs/security/security-mirror-acceptance.snapshot.json +++ b/docs/security/security-mirror-acceptance.snapshot.json @@ -11,8 +11,8 @@ "docs/security/security-mirror-route.snapshot.json" ], "summary": { - "total_contracts": 28, - "ready_for_mirror_count": 25, + "total_contracts": 29, + "ready_for_mirror_count": 26, "route_group_count": 5, "acceptance_check_count": 7, "blocking_check_count": 4 @@ -21,7 +21,7 @@ { "check_id": "CONTRACT_COUNT_MATCH", "title": "契約數量一致", - "expected_result": "AwoooP 讀到 28 個 contracts，且 manifest、readiness、route coverage 的 contract 集合一致。", + "expected_result": "AwoooP 讀到 29 個 contracts，且 manifest、readiness、route coverage 的 contract 集合一致。", "evidence_refs": [ "docs/security/security-supply-chain-contract-manifest.snapshot.json", "docs/security/security-mirror-readiness.snapshot.json", @@ -60,7 +60,7 @@ { "check_id": "ROUTE_GROUP_COVERAGE", "title": "路由群組覆蓋", - "expected_result": "5 個 route groups 合併後涵蓋 manifest 28 個 contracts，且每個 group 都有 destinations、channel_policy 與 review_lane。", + "expected_result": "5 個 route groups 合併後涵蓋 manifest 29 個 contracts，且每個 group 都有 destinations、channel_policy 與 review_lane。", "evidence_refs": [ "docs/security/security-mirror-route.snapshot.json", "docs/security/SECURITY-MIRROR-ROUTE.md" diff --git a/docs/security/security-mirror-dry-run.snapshot.json b/docs/security/security-mirror-dry-run.snapshot.json index 54da74e2..290acc6a 100644 --- a/docs/security/security-mirror-dry-run.snapshot.json +++ b/docs/security/security-mirror-dry-run.snapshot.json @@ -14,8 +14,8 @@ "docs/security/security-mirror-quarantine.snapshot.json" ], "summary": { - "total_contracts": 28, - "ready_for_mirror_count": 25, + "total_contracts": 29, + "ready_for_mirror_count": 26, "route_group_count": 5, "acceptance_check_count": 7, "quarantine_lane_count": 5, @@ -30,7 +30,7 @@ "docs/security/security-supply-chain-contract-manifest.snapshot.json", "docs/security/security-mirror-readiness.snapshot.json" ], - "pass_condition": "看到 28 個 contracts、25 個 ready for mirror，且所有 contract execution_allowed=false。", + "pass_condition": "看到 29 個 contracts、26 個 ready for mirror，且所有 contract execution_allowed=false。", "execution_allowed": false, "blocked_actions": [ "execute_contract", @@ -60,7 +60,7 @@ "docs/security/security-mirror-route.snapshot.json", "docs/security/SECURITY-MIRROR-ROUTE.md" ], - "pass_condition": "route groups 合併後涵蓋 28 個 contracts，沒有未知 execution route。", + "pass_condition": "route groups 合併後涵蓋 29 個 contracts，沒有未知 execution route。", "execution_allowed": false, "blocked_actions": [ "fallback_to_execution_route", diff --git a/docs/security/security-mirror-event-sample.snapshot.json b/docs/security/security-mirror-event-sample.snapshot.json index 70d96e3c..eb120f30 100644 --- a/docs/security/security-mirror-event-sample.snapshot.json +++ b/docs/security/security-mirror-event-sample.snapshot.json @@ -16,8 +16,8 @@ "risk": "LOW", "summary": "AwoooP 可 mirror Security Supply Chain readiness index，但不得把 readiness 視為執行授權。", "payload_summary": { - "total_contracts": 28, - "ready_for_mirror_count": 25, + "total_contracts": 29, + "ready_for_mirror_count": 26, "partial_ready_count": 2, "contract_only_count": 1, "blocked_count": 0, @@ -32,7 +32,8 @@ "docs/security/SECURITY-MIRROR-QUARANTINE.md", "docs/security/SECURITY-MIRROR-DRY-RUN.md", "docs/security/SECURITY-MIRROR-STATUS-ROLLUP.md", - "docs/security/SECURITY-APPROVAL-GATE.md" + "docs/security/SECURITY-APPROVAL-GATE.md", + "docs/security/SECURITY-APPROVAL-DECISION-RECORD.md" ], "blocked_actions": [ "execute_mirror_item", @@ -44,7 +45,7 @@ "store_secret_value" ], "labels": { - "phase": "S3.0", + "phase": "S3.1", "redacted": "true", "action_surface": "none", "mirror_only": "true" diff --git a/docs/security/security-mirror-intake-plan.snapshot.json b/docs/security/security-mirror-intake-plan.snapshot.json index 59a5a01b..02b194d6 100644 --- a/docs/security/security-mirror-intake-plan.snapshot.json +++ b/docs/security/security-mirror-intake-plan.snapshot.json @@ -14,7 +14,8 @@ "docs/security/security-mirror-quarantine.snapshot.json", "docs/security/security-mirror-dry-run.snapshot.json", "docs/security/security-mirror-status-rollup.snapshot.json", - "docs/security/security-approval-gate.snapshot.json" + "docs/security/security-approval-gate.snapshot.json", + "docs/security/security-approval-decision-record.snapshot.json" ], "intake_waves": [ { @@ -52,7 +53,7 @@ "execution_router", "blocking_gate" ], - "exit_gate": "Operator Console 能顯示 28 個 contract、5 個 route groups、7 個 acceptance checks、5 個 quarantine lanes、6 個 dry-run steps、status rollup 與 approval gate，且 mirror event envelope action_buttons_allowed=false。" + "exit_gate": "Operator Console 能顯示 29 個 contract、5 個 route groups、7 個 acceptance checks、5 個 quarantine lanes、6 個 dry-run steps、status rollup、approval gate 與 decision record，且 mirror event envelope action_buttons_allowed=false。" }, { "wave_id": "M1_kali_visibility", @@ -129,6 +130,7 @@ "approval_required_event_v1", "security_approval_queue_v1", "security_approval_gate_v1", + "security_approval_decision_record_v1", "github_target_repo_approval_package_v1", "source_control_approval_board_v1", "kali_scan_scope_approval_v1" @@ -142,6 +144,7 @@ "create_approval_candidate", "record_human_decision", "display_followup_runtime_gate", + "display_decision_record", "display_required_reviewers", "display_blocked_until_approved" ], @@ -150,7 +153,7 @@ "execute_after_approval_without_new_runtime_gate", "store_secret_value" ], - "exit_gate": "Approval candidate 與 S3 approval gate 可顯示與留痕，但任何批准後執行仍需要下一階段 runtime gate。" + "exit_gate": "Approval candidate、S3 approval gate 與 decision record 可顯示與留痕，但任何批准後執行仍需要下一階段 runtime gate。" }, { "wave_id": "M4_patch_only_backlog", diff --git a/docs/security/security-mirror-quarantine.snapshot.json b/docs/security/security-mirror-quarantine.snapshot.json index 1a59216b..2a1563a9 100644 --- a/docs/security/security-mirror-quarantine.snapshot.json +++ b/docs/security/security-mirror-quarantine.snapshot.json @@ -11,7 +11,7 @@ "docs/security/security-supply-chain-contract-manifest.snapshot.json" ], "summary": { - "total_contracts": 28, + "total_contracts": 29, "quarantine_lane_count": 5, "auto_retry_allowed": false, "runtime_blocking_allowed": false diff --git a/docs/security/security-mirror-readiness.snapshot.json b/docs/security/security-mirror-readiness.snapshot.json index d5c2fa5d..640dfb09 100644 --- a/docs/security/security-mirror-readiness.snapshot.json +++ b/docs/security/security-mirror-readiness.snapshot.json @@ -5,8 +5,8 @@ "default_enforcement_level": "mirror_only", "runtime_execution_authorized": false, "summary": { - "total_contracts": 28, - "ready_for_mirror_count": 25, + "total_contracts": 29, + "ready_for_mirror_count": 26, "partial_ready_count": 2, "contract_only_count": 1, "blocked_count": 0 @@ -79,6 +79,16 @@ "human_docs": ["docs/security/SECURITY-APPROVAL-GATE.md"], "notes": "可 mirror S3 人工批准 gate、決策範圍與 follow-up runtime gate；不得執行 gate item。" }, + { + "contract": "security_approval_decision_record_v1", + "readiness": "ready_for_mirror", + "consumption_mode": "approval_only", + "mirror_allowed": true, + "execution_allowed": false, + "snapshot_paths": ["docs/security/security-approval-decision-record.snapshot.json"], + "human_docs": ["docs/security/SECURITY-APPROVAL-DECISION-RECORD.md"], + "notes": "可 mirror S3 人工決策紀錄格式；目前尚無 approved decision record，且 execution_authorized=false。" + }, { "contract": "security_mirror_readiness_v1", "readiness": "ready_for_mirror", diff --git a/docs/security/security-mirror-route.snapshot.json b/docs/security/security-mirror-route.snapshot.json index 5380397e..96ebccc3 100644 --- a/docs/security/security-mirror-route.snapshot.json +++ b/docs/security/security-mirror-route.snapshot.json @@ -11,7 +11,7 @@ "docs/security/security-mirror-event-sample.snapshot.json" ], "summary": { - "total_contracts": 28, + "total_contracts": 29, "route_group_count": 5, "channel_event_policy": "初期只對階段完成、blocked 狀態或需要人工批准的高風險候選發低噪音事件；LOW / MEDIUM observation 不發阻擋事件。", "approval_queue_policy": "只有 approval-only、suggest-only 或 blocked-until-approved 項目可進 approval queue；approval queue 不代表可執行。" @@ -54,7 +54,7 @@ "runtime blocking", "自動批准任何 queue item" ], - "exit_gate": "AwoooP 可顯示 28 個 contract、5 個 route groups、7 個 acceptance checks、5 個 quarantine lanes、6 個 dry-run steps、status rollup 與 approval gate，且所有 route 都維持 runtime_execution_authorized=false。" + "exit_gate": "AwoooP 可顯示 29 個 contract、5 個 route groups、7 個 acceptance checks、5 個 quarantine lanes、6 個 dry-run steps、status rollup、approval gate 與 decision record，且所有 route 都維持 runtime_execution_authorized=false。" }, { "wave_id": "M1_kali_visibility", @@ -137,6 +137,7 @@ "approval_required_event_v1", "security_approval_queue_v1", "security_approval_gate_v1", + "security_approval_decision_record_v1", "github_target_repo_approval_package_v1", "source_control_approval_board_v1", "kali_scan_scope_approval_v1" @@ -151,6 +152,7 @@ "allowed_processing": [ "建立 approval candidate", "顯示 S3 approval gate 與 follow-up runtime gate", + "顯示人工 decision record 與 execution_authorized=false", "顯示 required reviewers", "顯示 blocked_until_approved", "記錄人工決策結果" @@ -161,7 +163,7 @@ "把人工批准記錄轉成 runtime executor", "保存 token 或 secret value" ], - "exit_gate": "Approval candidate 與 S3 approval gate 可顯示與留痕，但批准後執行仍需要下一階段 runtime gate。" + "exit_gate": "Approval candidate、S3 approval gate 與 decision record 可顯示與留痕，但批准後執行仍需要下一階段 runtime gate。" }, { "wave_id": "M4_patch_only_backlog", @@ -193,7 +195,7 @@ "acceptance_gates": [ { "gate_id": "ROUTE_COVERS_ALL_CONTRACTS", - "requirement": "route_groups 合併後必須涵蓋 manifest 的 28 個 contracts。" + "requirement": "route_groups 合併後必須涵蓋 manifest 的 29 個 contracts。" }, { "gate_id": "NO_EXECUTION_SURFACE", diff --git a/docs/security/security-mirror-status-rollup.snapshot.json b/docs/security/security-mirror-status-rollup.snapshot.json index ba7813ff..c69eebf6 100644 --- a/docs/security/security-mirror-status-rollup.snapshot.json +++ b/docs/security/security-mirror-status-rollup.snapshot.json @@ -15,11 +15,12 @@ "docs/security/security-mirror-dry-run.snapshot.json", "docs/security/security-approval-queue.snapshot.json", "docs/security/security-approval-gate.snapshot.json", + "docs/security/security-approval-decision-record.snapshot.json", "docs/security/security-rollout-policy.snapshot.json" ], "summary": { - "total_contracts": 28, - "ready_for_mirror_count": 25, + "total_contracts": 29, + "ready_for_mirror_count": 26, "partial_ready_count": 2, "contract_only_count": 1, "blocked_count": 0, @@ -52,8 +53,8 @@ { "phase_id": "S3_approval_gate", "state": "draft_ready", - "current_result": "Approval queue 已列出 8 個候選，且 security_approval_gate_v1 已定義人工決策、批准範圍與 follow-up runtime gate。", - "next_gate": "先 review redacted finding ingestion、safe crawl 與 Gitea read-only inventory；批准後仍不得自動執行。" + "current_result": "Approval queue 已列出 8 個候選，security_approval_gate_v1 已定義人工 gate，security_approval_decision_record_v1 已定義決策紀錄格式。", + "next_gate": "先 review redacted finding ingestion、safe crawl 與 Gitea read-only inventory；決策紀錄不等於執行授權。" }, { "phase_id": "S4_migration_execution", @@ -86,6 +87,7 @@ "source_contract": "security_approval_queue_v1", "allowed_processing": [ "依 security_approval_gate_v1 人工審查是否可設計 redacted security_finding_v1 ingestion", + "依 security_approval_decision_record_v1 記錄人工決策", "維持只接收摘要與 evidence_ref", "保留 patch-only / review gate" ], @@ -148,7 +150,7 @@ "session_sync_notes": [ "本 rollup 是跨 Session 的共同讀取入口，避免 AwoooP 主線與 Security Supply Chain Session 對進度與 gate 判讀不一致。", "S2/S3 目前仍屬框架期；狀態與人工 gate 可見，不代表 production ingestion、scan、repo migration 或 runtime enforcement 已啟用。", - "S3.0 只新增人工批准 gate 的決策語言；批准後仍需要 follow-up runtime gate，不可直接跳到執行面。" + "S3.1 只新增人工決策紀錄格式；決策紀錄仍維持 execution_authorized=false，不可直接跳到執行面。" ], "forbidden_actions": [ "start_kali_scan", diff --git a/docs/security/security-supply-chain-contract-manifest.snapshot.json b/docs/security/security-supply-chain-contract-manifest.snapshot.json index 7c2ee104..f375b98c 100644 --- a/docs/security/security-supply-chain-contract-manifest.snapshot.json +++ b/docs/security/security-supply-chain-contract-manifest.snapshot.json @@ -2,7 +2,7 @@ "schema_version": "security_supply_chain_contract_manifest_v1", "status": "draft", "default_enforcement_level": "mirror_only", - "contract_count": 28, + "contract_count": 29, "contracts": [ { "contract": "security_rollout_policy_v1", @@ -105,6 +105,26 @@ ], "notes": "定義 S3 人工批准 gate 的決策語言與留痕格式；批准後仍不得自動執行，必須有後續 runtime gate。" }, + { + "contract": "security_approval_decision_record_v1", + "schema_path": "docs/schemas/security_approval_decision_record_v1.schema.json", + "snapshot_paths": ["docs/security/security-approval-decision-record.snapshot.json"], + "human_docs": ["docs/security/SECURITY-APPROVAL-DECISION-RECORD.md"], + "consumer": "AwoooP Audit / Operator Console", + "consumption_mode": "approval_only", + "allowed_actions": ["record_human_decision", "display_decision_scope", "display_followup_runtime_gate"], + "forbidden_actions": [ + "execute_decision_record", + "auto_approve", + "execute_after_decision_without_runtime_gate", + "start_scan", + "call_execute_endpoint", + "create_repo", + "sync_refs", + "store_secret_value" + ], + "notes": "定義 S3 人工決策紀錄格式；記錄 approve/reject/defer/request_more_evidence/keep_blocked，但不授權執行。" + }, { "contract": "security_mirror_readiness_v1", "schema_path": "docs/schemas/security_mirror_readiness_v1.schema.json", @@ -121,7 +141,7 @@ "switch_github_primary", "store_secret_value" ], - "notes": "整理 28 個 Security Supply Chain contracts 的 mirror readiness，供 AwoooP 安全消費。" + "notes": "整理 29 個 Security Supply Chain contracts 的 mirror readiness，供 AwoooP 安全消費。" }, { "contract": "security_mirror_intake_plan_v1",