#!/usr/bin/env python3 """ IwoooS public gateway 變更前置 Gate 只讀清冊。 本工具只讀取已提交的 Nginx drift snapshot 與 DNS / TLS snapshot，整理 public gateway reload / route change 前必備的 owner、diff、nginx -t、 route smoke、rollback 與維護窗口欄位。它不 SSH、不讀 live 主機、不執行 nginx -t、不 reload、不做 DNS / TLS probe，也不收 secret value。 """ from __future__ import annotations import argparse import json import subprocess import sys from datetime import datetime, timedelta, timezone from pathlib import Path from typing import Any TAIPEI = timezone(timedelta(hours=8)) REQUIRED_PREFLIGHT_GATES = [ { "gate_id": "PG1", "label": "source-of-truth hash", "required_evidence": "repo_source_raw_and_normalized_sha256", "owner_acceptance_required": False, "repo_only_ready": True, }, { "gate_id": "PG2", "label": "affected route list", "required_evidence": "domain_route_upstream_tls_admin_websocket_acme_inventory", "owner_acceptance_required": False, "repo_only_ready": True, }, { "gate_id": "PG3", "label": "owner response", "required_evidence": "owner role/team, decision, reason, affected scope, redacted refs, followup owner", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG4", "label": "owner-provided live config", "required_evidence": "redacted live conf export or owner statement", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG5", "label": "rendered diff", "required_evidence": "source-to-live rendered diff with redaction", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG6", "label": "nginx -t evidence", "required_evidence": "syntax test output captured by approved maintainer", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG7", "label": "public route smoke", "required_evidence": "public route smoke plan and result for affected domains", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG8", "label": "admin route smoke", "required_evidence": "admin/auth route smoke when admin path is affected", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG9", "label": "WebSocket / API smoke", "required_evidence": "WebSocket or API smoke when upstream or upgrade header is affected", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG10", "label": "ACME / TLS owner check", "required_evidence": "certificate path, SAN/wildcard/shared-cert statement, ACME impact", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG11", "label": "maintenance window", "required_evidence": "approved window and notification scope", "owner_acceptance_required": True, "repo_only_ready": False, }, { "gate_id": "PG12", "label": "rollback owner and ref", "required_evidence": "rollback owner, rollback file/ref, post-rollback smoke", "owner_acceptance_required": True, "repo_only_ready": False, }, ] EXECUTION_BOUNDARIES = { "runtime_execution_authorized": False, "host_live_conf_read_authorized": False, "ssh_read_authorized": False, "ssh_write_authorized": False, "host_write_authorized": False, "nginx_test_authorized": False, "nginx_test_executed": False, "nginx_reload_authorized": False, "nginx_reload_executed": False, "public_gateway_reload_authorized": False, "public_route_change_authorized": False, "admin_route_change_authorized": False, "websocket_route_change_authorized": False, "acme_challenge_change_authorized": False, "dns_query_executed": False, "live_tls_probe_executed": False, "certbot_renew_authorized": False, "certbot_renew_executed": False, "route_smoke_authorized": False, "route_smoke_executed": False, "rollback_executed": False, "secret_value_collection_allowed": False, "action_buttons_allowed": False, } def git_short_sha(root: Path) -> str: try: result = subprocess.run( ["git", "rev-parse", "--short", "HEAD"], cwd=root, check=True, capture_output=True, text=True, ) return result.stdout.strip() except Exception: return "unknown" def load_json(path: Path) -> dict[str, Any]: return json.loads(path.read_text(encoding="utf-8")) def unique_upstreams(domains: list[dict[str, Any]]) -> list[str]: return sorted({upstream for item in domains for upstream in item.get("upstreams", [])}) def build_config_rows(nginx_report: dict[str, Any]) -> list[dict[str, Any]]: rows: list[dict[str, Any]] = [] for config in nginx_report.get("configs", []): parsed = config.get("repo_source", {}).get("parsed", {}) rows.append( { "config_id": config["config_id"], "host": config["host"], "role": config["role"], "control_tier": config["control_tier"], "owner_gate": config["owner_gate"], "repo_source_path": config["repo_source_path"], "live_path": config["live_path"], "server_block_count": parsed.get("server_block_count", 0), "server_name_count": len(parsed.get("server_names", [])), "upstream_count": len(parsed.get("proxy_passes", [])), "tls_certificate_path_count": len(parsed.get("ssl_certificates", [])), "admin_route_count": len(parsed.get("admin_routes", [])), "acme_route_count": len(parsed.get("acme_routes", [])), "websocket_route_count": len(parsed.get("websocket_routes", [])), "repo_source_hash_ready": True, "owner_response_received": False, "owner_response_accepted": False, "live_conf_evidence_received": False, "rendered_diff_ready": False, "nginx_test_evidence_received": False, "route_smoke_evidence_received": False, "maintenance_window_accepted": False, "rollback_owner_accepted": False, "runtime_gate_open": False, } ) return rows def build_route_impacts(domains: list[dict[str, Any]]) -> list[dict[str, Any]]: impacts: list[dict[str, Any]] = [] for item in domains: impacts.append( { "domain": item["domain"], "hosts": item.get("hosts", []), "config_ids": item.get("config_ids", []), "control_tier": item.get("control_tier", "C3"), "upstream_count": len(item.get("upstreams", [])), "has_tls_certificate_path": item.get("tls_certificate_path_present", False), "certificate_owner_confirmation_required": item.get( "certificate_owner_confirmation_required", False, ), "acme_challenge_present": item.get("acme_challenge_present", False), "admin_route_count": item.get("admin_route_count", 0), "websocket_route_count": item.get("websocket_route_count", 0), "public_route_smoke_required": True, "admin_route_smoke_required": item.get("admin_route_count", 0) > 0, "websocket_or_api_smoke_required": item.get("websocket_route_count", 0) > 0 or len(item.get("upstreams", [])) > 0, "tls_owner_check_required": item.get("certificate_owner_confirmation_required", False), "owner_response_accepted": False, "route_smoke_accepted": False, } ) return impacts def build_report( root: Path, nginx_report: dict[str, Any], domain_tls_report: dict[str, Any], generated_at: str | None, ) -> dict[str, Any]: report_time = generated_at or datetime.now(TAIPEI).isoformat(timespec="seconds") managed_domains = domain_tls_report.get("managed_domains", []) config_rows = build_config_rows(nginx_report) route_impacts = build_route_impacts(managed_domains) upstreams = unique_upstreams(managed_domains) repo_only_ready_count = sum(1 for gate in REQUIRED_PREFLIGHT_GATES if gate["repo_only_ready"]) owner_required_count = sum(1 for gate in REQUIRED_PREFLIGHT_GATES if gate["owner_acceptance_required"]) summary = { "source_config_count": len(config_rows), "c0_source_config_count": sum(1 for item in config_rows if item["control_tier"] == "C0"), "managed_domain_count": len(managed_domains), "route_impact_count": len(route_impacts), "unique_upstream_count": len(upstreams), "tls_certificate_path_count": domain_tls_report.get("summary", {}).get( "unique_certificate_path_count", 0, ), "certificate_owner_confirmation_required_count": domain_tls_report.get("summary", {}).get( "certificate_owner_confirmation_required_count", 0, ), "admin_route_domain_count": domain_tls_report.get("summary", {}).get("admin_route_domain_count", 0), "websocket_route_domain_count": domain_tls_report.get("summary", {}).get( "websocket_route_domain_count", 0, ), "acme_challenge_domain_count": domain_tls_report.get("summary", {}).get( "acme_challenge_domain_count", 0, ), "preflight_gate_count": len(REQUIRED_PREFLIGHT_GATES), "repo_only_preflight_ready_count": repo_only_ready_count, "owner_acceptance_required_gate_count": owner_required_count, "preflight_gate_accepted_count": 0, "owner_response_received_count": 0, "owner_response_accepted_count": 0, "owner_provided_live_conf_received_count": 0, "rendered_diff_ready_count": 0, "nginx_test_evidence_count": 0, "route_smoke_evidence_count": 0, "maintenance_window_accepted_count": 0, "rollback_owner_accepted_count": 0, "runtime_gate_count": 0, "action_button_count": 0, "coverage_percent_before_preflight": 78, "coverage_percent_after_preflight": 84, } return { "schema_version": "public_gateway_preflight_inventory_v1", "generated_at": report_time, "status": "repo_only_preflight_contract_ready", "source_scope": "committed_nginx_and_domain_tls_snapshots_only", "git_commit": git_short_sha(root), "source_reports": [ "docs/security/nginx-config-drift-repo.snapshot.json", "docs/security/domain-tls-certbot-inventory.snapshot.json", ], "summary": summary, "execution_boundaries": EXECUTION_BOUNDARIES, "required_preflight_gates": REQUIRED_PREFLIGHT_GATES, "config_preflight_rows": config_rows, "route_impacts": route_impacts, "unique_upstreams": upstreams, "required_owner_fields": [ "owner_role_or_team", "decision", "decision_reason", "affected_scope", "redacted_evidence_refs", "followup_owner", "rollback_owner", "maintenance_window", "validation_plan", "nginx_test_evidence_ref", "route_smoke_evidence_ref", ], "next_collection_order": [ "public_gateway_owner_response", "owner_provided_live_conf_export", "source_to_live_rendered_diff", "nginx_t_evidence", "affected_public_route_smoke", "admin_route_smoke_if_affected", "websocket_or_api_smoke_if_affected", "tls_certificate_owner_confirmation", "maintenance_window", "rollback_owner_and_ref", ], "operator_interpretation": [ "這是 Nginx public gateway 變更前置控管清冊，不是 reload 授權。", "repo-only ready 只代表 source hash 與 affected route list 已能重跑產生。", "owner response、live conf、rendered diff、nginx -t、route smoke、maintenance window 與 rollback owner 全部仍為 0。", "若未來發現 live drift，只能建立 evidence 與 owner decision，不得自動覆寫 live。", ], } def main() -> int: parser = argparse.ArgumentParser(description="IwoooS public gateway 變更前置 Gate 只讀清冊") parser.add_argument("--root", default=".", help="repo root") parser.add_argument( "--nginx-report", default="docs/security/nginx-config-drift-repo.snapshot.json", help="Nginx repo-only drift detector snapshot", ) parser.add_argument( "--domain-tls-report", default="docs/security/domain-tls-certbot-inventory.snapshot.json", help="DNS / TLS / certbot repo-only inventory snapshot", ) parser.add_argument("--output", help="寫出 JSON 報告") parser.add_argument("--generated-at", help="固定報告時間，供 committed snapshot 使用") args = parser.parse_args() root = Path(args.root).resolve() report = build_report( root, load_json(root / args.nginx_report), load_json(root / args.domain_tls_report), args.generated_at, ) payload = json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) if args.output: output = Path(args.output) output.parent.mkdir(parents=True, exist_ok=True) output.write_text(payload + "\n", encoding="utf-8") else: print(payload) summary = report["summary"] print( "PUBLIC_GATEWAY_PREFLIGHT_INVENTORY_OK " f"configs={summary['source_config_count']} " f"routes={summary['route_impact_count']} " f"gates={summary['preflight_gate_count']} " f"runtime_gate={summary['runtime_gate_count']}", file=sys.stderr, ) return 0 if __name__ == "__main__": sys.exit(main())