awoooi/docs/security/HOST-SERVICE-CHANGE-EVIDENCE-ACCEPTANCE.md

IwoooS Docker / systemd / 主機服務變更證據驗收

項目	內容
日期	2026-06-15
狀態	change_evidence_acceptance_ready_no_runtime_action
工具	scripts/security/host-service-change-evidence-acceptance.py
輸入	docs/security/host-service-owner-response-acceptance.snapshot.json
Snapshot	docs/security/host-service-change-evidence-acceptance.snapshot.json
runtime gate	0

1. 目的

Docker / systemd / host service 事故不能只看「服務又起來了」。主機重啟、Docker daemon starting、compose stack 退出、systemd failed unit、repair-bot / runner 競爭、cold-start recovery 或 port binding 漂移，都可能讓公開 route 短暫恢復但根因仍未驗收。

本文件只定義變更 / 事故證據如何收件、補證、隔離、拒收與進 reviewer review。它不是 live host read、不是 SSH、不是 Docker / systemd 操作、不是 repair-bot、不是 Ansible、不是 route smoke，也不是 production write 或 runtime gate 授權。

2. 摘要

指標	值	說明
change evidence candidate count	9	對應 9 個 host service surface
write-capable candidate count	3	Ansible role、110 repair-bot、188 repair-bot
live evidence required candidate count	8	local dev compose 之外都需 owner-provided live metadata
change evidence field count	45	每份 candidate 的 metadata-only 欄位
required evidence field count	25	actor、before / after、daemon、compose、systemd、port、dependency、route、post-check 等
reviewer check count	26	actor、service state、daemon、compose、systemd、dependency、route recovery、no-false-green 等
outcome lane count	10	waiting、quarantine、reject、supplement、incident backfill、no-false-green supplement、review、maintenance、runtime gate
blocked action count	39	SSH、Docker、systemctl、repair-bot、Ansible、route smoke、raw log storage、runtime gate 等
change evidence received / accepted	0 / 0	尚未收到，尚未驗收
runtime gate / action button	0 / 0	未開啟

3. 驗收候選

Candidate	Host scope	類型	變更證據焦點
host_service_change_evidence:local_dev_compose	local_dev_only	Docker Compose	dev-only disposition、不得誤用 production、secret placeholder policy
host_service_change_evidence:monitoring_110_compose	host_110	Docker Compose	Docker daemon、compose stack、route recovery、Alertmanager / Prometheus 影響
host_service_change_evidence:monitoring_exporters_188_compose	host_188	Docker Compose	exporter state、DB / Redis dependency、compose recovery 與 post-check
host_service_change_evidence:sentry_110_reference_compose	host_110	reference compose	source-of-truth、official revision、backup / rollback path
host_service_change_evidence:langfuse_110_compose	host_110	Docker Compose	compose state、secret placeholder disposition、route recovery
host_service_change_evidence:ansible_docker_compose_service_role	multi_host	Ansible executor role	check-mode、allowed service_dir、人工 gate、rollback owner
host_service_change_evidence:repair_bot_110_whitelist	host_110	repair whitelist	actor、disable switch、audit log ref、post-check、runner contention
host_service_change_evidence:repair_bot_188_whitelist	host_188	repair whitelist	systemd restart approval gate、sudoers boundary、route smoke plan
host_service_change_evidence:config_backup_host_capture	host_cluster	config backup capture	latest backup status、restore drill owner、secret handling proof

上表使用 host alias，不把內網位址放進前台產品文案。Snapshot 內若保留既有 repo-only scope，仍不得把它當成可公開文案或 live host 授權。

4. 必填證據欄位

欄位	規則
change_or_incident_ref	可追溯 change / incident / ticket ref
actor_role_or_team	只填角色或團隊，不填私人聯絡資料或 credential
decision / decision_reason	說明 confirm、defer、reject 或 request_more_evidence 的理由
affected_scope	明確列出 host alias、service scope、route / agent / monitoring 影響
boot_or_restart_window_ref	boot、restart、kill、cold-start 或 recovery 時間 ref
before_service_state_ref / after_service_state_ref	變更前後服務狀態 ref，不能只寫「已恢復」
docker_daemon_state_ref	Docker daemon active / starting / failed / socket / contention metadata ref
compose_stack_state_ref	compose stack / container state 摘要 ref，不保存 raw docker ps dump
systemd_unit_state_ref	systemd unit、failed unit 或 degraded state 摘要 ref
failed_unit_review_ref	failed unit 是否與事故或恢復相關的 review ref
port_binding_state_ref	host port、container port、proxy、gateway / firewall exposure 摘要 ref
dependency_impact_ref	上游、下游、資料庫、queue、registry、AI provider 與 public route 依賴 ref
cold_start_sequence_ref	Docker daemon、compose stack、systemd unit、runner 與 post-check 順序 ref
runner_or_repair_bot_contention_ref	runner、repair-bot、backup job、iptables / xtables 或 compose action 競爭 ref
public_route_recovery_refs / admin_route_recovery_refs	route 恢復 ref；無影響需說明不適用
agent_provider_health_refs	AI provider、agent、webhook 或 proxy 健康 ref
monitoring_alert_refs	alert / incident / monitoring ref，避免人工觀察 false green
operator_notification_refs / cross_project_sync_ref	跨產品 / Session / owner 同步 ref
restoration_time_ref	已恢復事故的恢復時間；未恢復則提供 still-degraded ref
rollback_owner / rollback_plan_ref	回復責任與 plan
postcheck_evidence_refs	service、route、agent、queue、monitoring 與 rollback stop condition

5. Reviewer checks

Check	說明
change_ref_present	必須有可追溯 change / incident ref
actor_role_traceable	不接受匿名 restart、kill、compose action 或 daemon 操作
decision_reason_present	decision 與 reason 必須同時存在
affected_scope_matches_surface	affected scope 必須能對回 host service surface
boot_or_restart_window_present	重啟、cold-start 或恢復需有時間 ref
before_after_service_state_present	需有 before / after service state ref
docker_daemon_state_present	Docker daemon state 必須有脫敏 metadata ref
compose_stack_state_present	compose / container state 不保存 raw dump
systemd_unit_state_present	systemd unit / failed unit / degraded state 必須可追溯
failed_unit_review_present	failed unit 是否相關必須 review
port_binding_state_present	port / proxy / gateway / firewall exposure 必須一致性 review
dependency_impact_present	必須列上游、下游、queue、registry、AI provider、public route 與 monitoring 影響
cold_start_sequence_present	必須提供 cold-start / recovery sequence ref
runner_repair_bot_contention_present	必須確認 runner、repair-bot、backup job 或 xtables 競爭
route_recovery_evidence_present	route 受影響時需有恢復 ref
agent_provider_health_present	AI provider、agent 或 webhook 受影響時需有健康 ref
monitoring_alert_ref_present	需列 monitoring / alert / incident ref
operator_notification_present	需提供已通知受影響 owner / Session 的脫敏 ref
cross_project_sync_present	跨專案影響需有同步 ref
restoration_time_present	已恢復事故需提供恢復時間或 still-degraded ref
rollback_owner_present	rollback owner 與 rollback plan 必須存在
postcheck_evidence_present	post-check 必須覆蓋 service、route、agent、queue、monitoring 與 stop condition
secret_or_raw_payload_absent	不得包含 secret、env dump、raw docker logs、raw journal、private key 或 cookie
no_false_green_service_health	不得把 healthy、route 200、container up 或 dashboard up 當成驗收完成
no_runtime_authorization	證據驗收不授權 SSH、Docker、systemctl、repair-bot、Ansible 或 host write
counts_transition_safe	只有 reviewer record 可更新 accepted count，且不得開 runtime gate

6. 禁止事項

1. 不 SSH read / write。
2. 不讀 live host、live Docker、live systemd 或 live journal。
3. 不執行 docker compose up/down/pull、docker restart、docker kill。
4. 不執行 systemctl restart/reload/kill。
5. 不呼叫 repair-bot，不跑 Ansible apply。
6. 不做 sudo action、host file write、firewall / port change 或 route smoke。
7. 不保存 raw live config、raw docker log、raw journal、raw env dump、secret value 或 private key。
8. 不把服務 healthy、route 200、container up 或 dashboard up 當成 recovery / config 已驗收。
9. 不跳過 source-of-truth、依賴圖、port binding、cold-start sequence 或 daemon / runner contention review。
10. 不開 runtime gate，不建立 action button。

7. 指令

產生 committed snapshot：

python3 scripts/security/host-service-change-evidence-acceptance.py \
  --root . \
  --owner-response-report docs/security/host-service-owner-response-acceptance.snapshot.json \
  --output docs/security/host-service-change-evidence-acceptance.snapshot.json \
  --generated-at 2026-06-15T18:50:00+08:00

驗證 guard：

python3 scripts/security/security-mirror-progress-guard.py --root .

8. 完成度

工作	完成度	說明
host service change evidence acceptance artifact	100%	產生器、snapshot 與文件已固定
Docker / systemd / host service 只讀治理成熟度	58% -> 62%	事故 / 變更證據、重啟 actor、before / after、daemon、compose、systemd、port、dependency、route recovery、operator notice 與 no-false-green 已納入
change evidence received / accepted	0%	尚未收到，尚未驗收
live host read / SSH	0%	尚未批准且未執行
Docker / systemd / repair-bot / Ansible	0%	尚未批准且未執行
runtime gate / host write	0%	未授權且未執行