#!/usr/bin/env python3 """ Wazuh agent visibility owner evidence 收件預檢。 本工具只驗證 repo 內 committed snapshot；不查 Wazuh、不 SSH、不讀 secret、不保存 raw log、不重新註冊 agent，也不啟用 active response。 """ from __future__ import annotations import argparse import json import re from pathlib import Path from typing import Any SNAPSHOT_PATH = Path("docs/security/wazuh-agent-visibility-owner-evidence-preflight.snapshot.json") SCHEMA_VERSION = "wazuh_agent_visibility_owner_evidence_preflight_v1" REQUIRED_FIELDS = [ "owner_role", "team", "decision", "decision_reason", "affected_scope", "collection_method", "agent_total", "agent_active", "agent_disconnected", "agent_never_connected", "last_seen_window_start", "last_seen_window_end", "registry_collected_at", "registry_export_scope_aliases", "per_host_registry_matrix", "registry_gap_reason_by_alias", "registry_export_summary_ref", "manager_health_ref", "dashboard_api_status_ref", "dashboard_api_connection_check_status", "dashboard_api_version_check_status", "dashboard_index_pattern_statuses", "dashboard_api_degradation_root_cause", "dashboard_api_repair_postcheck_ref", "redacted_evidence_refs", "followup_owner", "rollback_owner", "postcheck_plan", ] REVIEWER_CHECKS = [ "欄位齊全且皆為脫敏 metadata。", "agent_total 不可小於 active + disconnected + never_connected。", "collection_method 只能是既有唯讀 API 或 manager 端脫敏 CLI 匯出，不可要求 secret 明文。", "registry_export_scope_aliases 必須完整覆蓋 6 個公開節點別名。", "per_host_registry_matrix 每列只能使用公開別名，不得包含內網位址、agent 原名或 raw payload。", "last_seen 時間窗需能覆蓋事故觀察區間。", "manager health ref 與 dashboard API status ref 不可互相替代。", "Dashboard API connection 若仍是 pending / spinning，不得接受為 Wazuh 可用。", "Dashboard API version 必須獨立驗證；index pattern 三綠勾不可替代 API version。", "index pattern 已通過只能代表索引 pattern 可讀，不可替代 manager registry counts。", "Dashboard API 退化根因必須至少分類為 stored API、RBAC / run_as、rate-limit、TLS trust 或 readonly account scope 其中之一。", "dashboard API repair postcheck 必須包含 API connection、API version、manager registry counts 與 IwoooS readback。", "redacted evidence refs 不得包含 raw payload、截圖原文或主機完整輸出。", "owner decision 不可直接授權 active response、host write 或 secret rotation。", "rollback owner 與 postcheck plan 必須存在。", ] OUTCOME_LANES = [ "waiting_owner_evidence", "request_missing_fields", "quarantine_sensitive_payload", "reject_runtime_action_request", "request_dashboard_api_status_supplement", "request_dashboard_api_repair_postcheck", "reject_index_pattern_only_green", "ready_for_reviewer_validation", ] FORBIDDEN_PAYLOADS = [ "raw_wazuh_payload", "raw_log", "full_journal", "unredacted_screenshot", "agent_name", "internal_ip", "authorization_header", "bearer_token", "basic_auth", "password", "token", "cookie", "private_key", "client_keys", "raw_dashboard_request", "dashboard_api_secret", "stored_api_password", "api_token", "active_response_enable", "host_write", "firewall_change", "nginx_reload", ] FORBIDDEN_TEXT_PATTERNS = [ re.compile(r"\b(?:10|127|172\.(?:1[6-9]|2\d|3[01])|192\.168)\.\d{1,3}\.\d{1,3}\b"), re.compile(r"Authorization\s*:", re.IGNORECASE), re.compile(r"Bearer\s+[A-Za-z0-9._-]{10,}", re.IGNORECASE), re.compile(r"Basic\s+[A-Za-z0-9+/=]{10,}", re.IGNORECASE), re.compile(r"password\s*[:=]\s*['\"][^'\"]+['\"]", re.IGNORECASE), re.compile(r"token\s*[:=]\s*['\"][^'\"]+['\"]", re.IGNORECASE), re.compile(r"cookie\s*[:=]\s*['\"][^'\"]+['\"]", re.IGNORECASE), re.compile(r"client\.keys", re.IGNORECASE), re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"), ] REGISTRY_EXPORT_SCOPE_ALIASES = [ "managed_core_node_a", "managed_core_node_b", "managed_dev_node_a", "managed_dev_node_b", "managed_control_node_a", "managed_control_node_b", ] REGISTRY_EXPORT_ALLOWED_COLLECTION_METHODS = [ "wazuh_api_readonly_redacted_counts", "manager_agent_control_redacted_export", ] PER_HOST_REGISTRY_REQUIRED_FIELDS = [ "node_alias", "scope_role", "registry_presence", "agent_status_bucket", "last_seen_state", "manager_group_ref", "agent_id_redacted_ref", "gap_reason", "redacted_evidence_ref", ] REGISTRY_EXPORT_REDACTION_REQUIREMENTS = [ "只允許公開節點別名，不允許內網位址、主機原名或 agent 原名。", "agent id 僅能用不可逆 evidence ref，不得放完整值、雜湊、前後綴或 client key。", "每個缺口必須有 gap reason，不得以 Dashboard 空白或口頭說明補成綠燈。", "Dashboard API connection / version / index pattern 必須分欄呈現，不得合併成單一 healthy。", "Dashboard API 修復證明只能收脫敏 ref，不得收 stored API secret、token、密碼或完整 request。", "只收計數、狀態桶、時間窗與證據 ref，不收 raw API payload、完整 CLI output 或截圖原文。", ] def load_json(path: Path) -> dict[str, Any]: return json.loads(path.read_text(encoding="utf-8")) def assert_equal(label: str, actual: Any, expected: Any) -> None: if actual != expected: raise SystemExit(f"BLOCKED {label}: expected {expected!r}, got {actual!r}") def assert_false(label: str, actual: Any) -> None: assert_equal(label, actual, False) def assert_zero(label: str, actual: Any) -> None: assert_equal(label, actual, 0) def collect_string_values(value: Any) -> list[str]: if isinstance(value, str): return [value] if isinstance(value, list): values: list[str] = [] for item in value: values.extend(collect_string_values(item)) return values if isinstance(value, dict): values = [] for item in value.values(): values.extend(collect_string_values(item)) return values return [] def validate_no_forbidden_text(snapshot: dict[str, Any]) -> None: for text in collect_string_values(snapshot): for pattern in FORBIDDEN_TEXT_PATTERNS: if pattern.search(text): raise SystemExit( "BLOCKED wazuh_agent_visibility_owner_evidence_preflight: " "snapshot contains forbidden sensitive text" ) def build_snapshot() -> dict[str, Any]: return { "schema_version": SCHEMA_VERSION, "status": "owner_evidence_preflight_ready_no_runtime_action", "mode": "redacted_metadata_only_no_secret_no_wazuh_query", "scope": "wazuh_agent_visibility_registry_truth", "required_fields": REQUIRED_FIELDS, "reviewer_checks": REVIEWER_CHECKS, "outcome_lanes": OUTCOME_LANES, "forbidden_payloads": FORBIDDEN_PAYLOADS, "registry_export_contract": { "expected_scope_aliases": REGISTRY_EXPORT_SCOPE_ALIASES, "allowed_collection_methods": REGISTRY_EXPORT_ALLOWED_COLLECTION_METHODS, "per_host_required_fields": PER_HOST_REGISTRY_REQUIRED_FIELDS, "redaction_requirements": REGISTRY_EXPORT_REDACTION_REQUIREMENTS, "registry_export_received_count": 0, "registry_export_accepted_count": 0, }, "summary": { "required_field_count": len(REQUIRED_FIELDS), "reviewer_check_count": len(REVIEWER_CHECKS), "outcome_lane_count": len(OUTCOME_LANES), "forbidden_payload_count": len(FORBIDDEN_PAYLOADS), "expected_scope_alias_count": len(REGISTRY_EXPORT_SCOPE_ALIASES), "per_host_required_field_count": len(PER_HOST_REGISTRY_REQUIRED_FIELDS), "registry_export_received_count": 0, "registry_export_accepted_count": 0, "owner_evidence_received_count": 0, "owner_evidence_accepted_count": 0, "owner_evidence_rejected_count": 0, "owner_evidence_quarantined_count": 0, "runtime_gate_count": 0, "active_response_authorized_count": 0, "host_write_authorized_count": 0, "secret_value_collection_allowed_count": 0, }, "execution_boundaries": { "wazuh_api_live_query_authorized": False, "wazuh_active_response_authorized": False, "host_write_authorized": False, "secret_value_collection_allowed": False, "raw_wazuh_payload_storage_allowed": False, "agent_identity_public_display_allowed": False, "internal_ip_public_display_allowed": False, "runtime_execution_authorized": False, "not_authorization": True, }, "operator_interpretation": [ "這是 Wazuh agent registry 脫敏證據收件前的預檢，不代表已收到或已接受 owner evidence。", "agent service active、TCP 連線存在、Dashboard 可見或口頭宣稱都不可替代 manager registry counts。", "逐主機 registry export 必須使用固定公開節點別名與狀態桶，不能把 agent 原名或內網識別資訊帶到前台。", "若 evidence 夾帶 raw log、未脫敏截圖、內網位址、agent 原名或 secret，必須隔離，不得渲染到前台。", "Dashboard index pattern 三綠勾不可替代 API connection、API version 或 manager registry 驗收。", "任何 active response、host write、firewall、Nginx、Docker、K8s 或 secret 變更都要切獨立人工批准。", ], } def validate(root: Path) -> None: snapshot = load_json(root / SNAPSHOT_PATH) assert_equal("schema_version", snapshot.get("schema_version"), SCHEMA_VERSION) assert_equal( "status", snapshot.get("status"), "owner_evidence_preflight_ready_no_runtime_action", ) assert_equal( "mode", snapshot.get("mode"), "redacted_metadata_only_no_secret_no_wazuh_query", ) assert_equal("required_fields", snapshot.get("required_fields"), REQUIRED_FIELDS) assert_equal("reviewer_checks", snapshot.get("reviewer_checks"), REVIEWER_CHECKS) assert_equal("outcome_lanes", snapshot.get("outcome_lanes"), OUTCOME_LANES) assert_equal("forbidden_payloads", snapshot.get("forbidden_payloads"), FORBIDDEN_PAYLOADS) contract = snapshot.get("registry_export_contract", {}) assert_equal( "registry_export_contract.expected_scope_aliases", contract.get("expected_scope_aliases"), REGISTRY_EXPORT_SCOPE_ALIASES, ) assert_equal( "registry_export_contract.allowed_collection_methods", contract.get("allowed_collection_methods"), REGISTRY_EXPORT_ALLOWED_COLLECTION_METHODS, ) assert_equal( "registry_export_contract.per_host_required_fields", contract.get("per_host_required_fields"), PER_HOST_REGISTRY_REQUIRED_FIELDS, ) assert_equal( "registry_export_contract.redaction_requirements", contract.get("redaction_requirements"), REGISTRY_EXPORT_REDACTION_REQUIREMENTS, ) assert_zero("registry_export_contract.registry_export_received_count", contract.get("registry_export_received_count")) assert_zero("registry_export_contract.registry_export_accepted_count", contract.get("registry_export_accepted_count")) summary = snapshot.get("summary", {}) assert_equal("summary.required_field_count", summary.get("required_field_count"), len(REQUIRED_FIELDS)) assert_equal("summary.reviewer_check_count", summary.get("reviewer_check_count"), len(REVIEWER_CHECKS)) assert_equal("summary.outcome_lane_count", summary.get("outcome_lane_count"), len(OUTCOME_LANES)) assert_equal("summary.forbidden_payload_count", summary.get("forbidden_payload_count"), len(FORBIDDEN_PAYLOADS)) assert_equal( "summary.expected_scope_alias_count", summary.get("expected_scope_alias_count"), len(REGISTRY_EXPORT_SCOPE_ALIASES), ) assert_equal( "summary.per_host_required_field_count", summary.get("per_host_required_field_count"), len(PER_HOST_REGISTRY_REQUIRED_FIELDS), ) for key in [ "registry_export_received_count", "registry_export_accepted_count", "owner_evidence_received_count", "owner_evidence_accepted_count", "owner_evidence_rejected_count", "owner_evidence_quarantined_count", "runtime_gate_count", "active_response_authorized_count", "host_write_authorized_count", "secret_value_collection_allowed_count", ]: assert_zero(f"summary.{key}", summary.get(key)) boundaries = snapshot.get("execution_boundaries", {}) for key, value in boundaries.items(): if key == "not_authorization": assert_equal(f"execution_boundaries.{key}", value, True) else: assert_false(f"execution_boundaries.{key}", value) validate_no_forbidden_text(snapshot) def main() -> None: parser = argparse.ArgumentParser(description="Wazuh agent visibility owner evidence 收件預檢") parser.add_argument("--root", type=Path, default=Path.cwd()) parser.add_argument("--output", type=Path) parser.add_argument("--json", action="store_true") args = parser.parse_args() root = args.root.resolve() if args.output: snapshot = build_snapshot() output = args.output if args.output.is_absolute() else root / args.output output.parent.mkdir(parents=True, exist_ok=True) output.write_text(json.dumps(snapshot, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8") validate(root) snapshot = load_json(root / SNAPSHOT_PATH) if args.json: print(json.dumps(snapshot, ensure_ascii=False, sort_keys=True)) return summary = snapshot["summary"] print( "WAZUH_AGENT_VISIBILITY_OWNER_EVIDENCE_PREFLIGHT_OK " f"fields={summary['required_field_count']} " f"checks={summary['reviewer_check_count']} " f"aliases={summary['expected_scope_alias_count']} " f"export_received={summary['registry_export_received_count']} " f"received={summary['owner_evidence_received_count']} " f"accepted={summary['owner_evidence_accepted_count']} " f"runtime_gate={summary['runtime_gate_count']}" ) if __name__ == "__main__": main()