#!/usr/bin/env python3 """GitHub 私有備援 evidence gate。 此工具只讀既有 GitHub target decision / owner response / approval package snapshot，產生「私有備援是否可進入執行」的 fail-closed gate。它不呼叫 GitHub / Gitea API、不建立 repo、不修改 visibility、不同步 refs、不讀取 或保存任何 secret value。 """ from __future__ import annotations import argparse import json from datetime import datetime, timezone from pathlib import Path from typing import Any SCHEMA_VERSION = "github_target_private_backup_evidence_gate_v1" FORBIDDEN_ACTIONS = [ "create_github_repo", "change_repo_visibility", "push_refs", "delete_refs", "force_push", "mirror_sync", "switch_github_primary", "disable_gitea", "workflow_modification", "workflow_trigger", "secret_value_collection", "private_clone_url_collection", ] def load_json(path: Path) -> dict[str, Any]: with path.open(encoding="utf-8") as handle: payload = json.load(handle) if not isinstance(payload, dict): raise ValueError(f"{path}: expected JSON object") return payload def build_target_gate(decision: dict[str, Any]) -> dict[str, Any]: approval_required = bool(decision.get("approval_required")) probe_status = str(decision.get("probe_status") or "unknown") github_repo = str(decision.get("github_repo") or "") if not approval_required: visibility_status = "external_scope_not_backup_target" blockers = ["external_scope_review_only"] elif probe_status.startswith("exists"): visibility_status = "blocked_public_probe_visible_private_evidence_required" blockers = [ "github_target_publicly_readable_by_unauthenticated_probe", "private_visibility_owner_evidence_missing", "safe_credential_metadata_missing", "refs_sync_not_authorized", ] elif probe_status == "not_found_or_private": visibility_status = "blocked_private_or_absent_not_verified" blockers = [ "not_found_or_private_is_not_private_verification", "private_visibility_owner_evidence_missing", "safe_credential_metadata_missing", "refs_sync_not_authorized", ] else: visibility_status = "blocked_probe_status_unknown" blockers = [ "github_target_probe_status_unknown", "private_visibility_owner_evidence_missing", "safe_credential_metadata_missing", "refs_sync_not_authorized", ] return { "github_repo": github_repo, "source_key": decision.get("source_key"), "approval_required": approval_required, "probe_status": probe_status, "target_state": decision.get("target_state"), "risk": decision.get("risk"), "visibility_evidence_status": visibility_status, "private_backup_verified": False, "private_visibility_owner_evidence_ref": None, "safe_credential_evidence_status": ( "not_required_external_scope" if not approval_required else "missing_safe_credential_metadata" ), "safe_credential_evidence_ref": None, "owner_response_accepted": False, "refs_sync_ready": False, "execution_ready": False, "blockers": blockers, "evidence_refs": decision.get("evidence_refs", []), "forbidden_actions": FORBIDDEN_ACTIONS, "repo_creation_authorized": False, "visibility_change_authorized": False, "refs_sync_authorized": False, "github_primary_switch_authorized": False, "secret_values_collected": False, } def count_targets(targets: list[dict[str, Any]], predicate) -> int: return sum(1 for target in targets if predicate(target)) def build_payload( decision_snapshot: dict[str, Any], owner_response_snapshot: dict[str, Any], approval_package_snapshot: dict[str, Any], ) -> dict[str, Any]: decisions = decision_snapshot.get("decisions") or [] if not isinstance(decisions, list): raise ValueError("github target decision snapshot missing decisions") targets = [build_target_gate(decision) for decision in decisions if isinstance(decision, dict)] approval_targets = [target for target in targets if target["approval_required"]] public_visible_targets = [ target for target in approval_targets if str(target["probe_status"]).startswith("exists") ] unknown_private_targets = [ target for target in approval_targets if target["probe_status"] == "not_found_or_private" ] owner_summary = owner_response_snapshot.get("summary") or {} package_items = approval_package_snapshot.get("approval_items") or [] received_count = int(owner_summary.get("received_response_count", 0) or 0) accepted_count = int(owner_summary.get("accepted_response_count", 0) or 0) status = "blocked_public_visibility_and_safe_credential_evidence_required" if not public_visible_targets: status = "blocked_private_visibility_and_safe_credential_evidence_required" summary = { "target_decision_count": len(targets), "approval_required_target_count": len(approval_targets), "approval_package_item_count": len(package_items), "public_probe_visible_target_count": len(public_visible_targets), "not_found_or_private_target_count": len(unknown_private_targets), "private_backup_verified_count": 0, "private_visibility_evidence_missing_count": len(approval_targets), "safe_credential_required_count": len(approval_targets), "safe_credential_accepted_evidence_count": 0, "owner_response_received_count": received_count, "owner_response_accepted_count": accepted_count, "execution_ready_count": 0, "blocked_target_count": len(approval_targets), "external_scope_target_count": count_targets(targets, lambda target: not target["approval_required"]), "forbidden_action_count": len(FORBIDDEN_ACTIONS), "repo_creation_authorized": False, "visibility_change_authorized": False, "refs_sync_authorized": False, "github_primary_switch_authorized": False, "workflow_modification_authorized": False, "workflow_trigger_authorized": False, "secret_value_collection_allowed": False, "private_clone_url_collection_allowed": False, "not_found_or_private_as_absent_allowed": False, "public_repo_allowed": False, } return { "schema_version": SCHEMA_VERSION, "generated_at": datetime.now(timezone.utc).isoformat(), "status": status, "mode": "read_only_private_backup_evidence_gate", "source_reviews": { "github_target_decision": "docs/security/github-target-decision.snapshot.json", "github_target_owner_decision_response": "docs/security/github-target-owner-decision-response.snapshot.json", "github_target_repo_approval_package": "docs/security/github-target-repo-approval-package.snapshot.json", }, "summary": summary, "targets": targets, "acceptance_requirements": [ "每個 approval-required GitHub target 必須有 private visibility owner evidence ref。", "公開 probe 可讀的 target 不得被視為符合私有備援要求。", "`not_found_or_private` 只代表未授權只讀 probe 看不到，不得當成 private verified 或 repo absent。", "safe credential evidence 只允許 credential storage / owner / scope / rotation metadata，不得收 token value。", "owner response accepted count 在 reviewer acceptance 前必須維持 0。", "private evidence 與 safe credential evidence 完整前不得建立 repo、改 visibility、push refs 或切 GitHub primary。", ], "rejection_rules": [ "任何 public repo 或 unauthenticated readable target 均不得標示 private_backup_verified=true。", "任何 token、PAT、private key、cookie、session、private clone credential 或 partial secret 必須拒收。", "任何 repo creation、visibility change、refs sync、force push、tag rewrite、workflow trigger 或 primary switch request 必須拒收。", "任何把 `not_found_or_private` 解讀為 repo 不存在或可建立新 repo 的 response 必須拒收。", ], "operation_boundaries": { "read_only_api_allowed": True, "github_api_write_allowed": False, "gitea_api_write_allowed": False, "repo_creation_allowed": False, "visibility_change_allowed": False, "refs_sync_allowed": False, "workflow_modification_allowed": False, "workflow_trigger_allowed": False, "github_primary_switch_allowed": False, "secret_value_collection_allowed": False, "private_clone_url_collection_allowed": False, }, "authorization_flags": { "runtime_execution_authorized": False, "repo_creation_authorized": False, "visibility_change_authorized": False, "refs_sync_authorized": False, "workflow_modification_authorized": False, "workflow_trigger_authorized": False, "github_primary_switch_authorized": False, "secret_values_collected": False, }, } def write_markdown(payload: dict[str, Any], path: Path) -> None: summary = payload["summary"] lines = [ "# GitHub Target Private Backup Evidence Gate", "", "| 項目 | 值 |", "|------|----|", f"| 狀態 | `{payload['status']}` |", f"| approval-required targets | `{summary['approval_required_target_count']}` |", f"| public probe visible | `{summary['public_probe_visible_target_count']}` |", f"| not_found_or_private | `{summary['not_found_or_private_target_count']}` |", f"| private backup verified | `{summary['private_backup_verified_count']}` |", f"| safe credential evidence | `{summary['safe_credential_accepted_evidence_count']}/{summary['safe_credential_required_count']}` |", f"| execution ready | `{summary['execution_ready_count']}` |", "", "## Target Gate", "", "| GitHub target | probe | visibility evidence | private verified | blockers |", "|---------------|-------|---------------------|------------------|----------|", ] for target in payload["targets"]: if not target["approval_required"]: continue lines.append( "| " + " | ".join( [ f"`{target['github_repo']}`", f"`{target['probe_status']}`", f"`{target['visibility_evidence_status']}`", f"`{str(target['private_backup_verified']).lower()}`", f"`{len(target['blockers'])}`", ] ) + " |" ) lines.extend( [ "", "## 不可誤讀", "", "- 本 gate 不是 GitHub repo creation / visibility change / refs sync 授權。", "- 公開 probe 可讀的 target 需要 private visibility owner evidence，不能標綠。", "- `not_found_or_private` 不能當成已 private，也不能當成 repo 不存在。", "- safe credential evidence 只收 metadata，不收 secret value。", "", ] ) path.write_text("\n".join(lines), encoding="utf-8") def main() -> int: parser = argparse.ArgumentParser() parser.add_argument("--root", default=".") parser.add_argument("--output-json", default="docs/security/github-target-private-backup-evidence-gate.snapshot.json") parser.add_argument("--output-md", default="docs/security/GITHUB-TARGET-PRIVATE-BACKUP-EVIDENCE-GATE.md") args = parser.parse_args() root = Path(args.root) payload = build_payload( load_json(root / "docs/security/github-target-decision.snapshot.json"), load_json(root / "docs/security/github-target-owner-decision-response.snapshot.json"), load_json(root / "docs/security/github-target-repo-approval-package.snapshot.json"), ) output_json = root / args.output_json output_md = root / args.output_md output_json.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") write_markdown(payload, output_md) summary = payload["summary"] print( "GITHUB_TARGET_PRIVATE_BACKUP_EVIDENCE_GATE_BLOCKED " f"targets={summary['approval_required_target_count']} " f"public_visible={summary['public_probe_visible_target_count']} " f"private_verified={summary['private_backup_verified_count']} " f"credential={summary['safe_credential_accepted_evidence_count']}/{summary['safe_credential_required_count']} " f"refs_sync={summary['refs_sync_authorized']}" ) return 0 if __name__ == "__main__": raise SystemExit(main())