scripts/export_compliance_report.py

#!/usr/bin/env python3
"""CLI tool for compliance officers to generate EU AI Act compliance certificates.

Generates cryptographically signed JSON compliance certificates and structured
Markdown compliance binders for EU AI Act Regulation (EU) 2024/1689 Articles 10-15.

Usage:
    python scripts/export_compliance_report.py \\
      --model-version v2.1.0 \\
      --fl-rounds 25 \\
      --dp-epsilon 2.3 \\
      --dp-delta 1e-5 \\
      --iban-pass-rate 0.9995 \\
      --anomaly-count 1 \\
      --dual-signoff \\
      --model-auc 0.93 \\
      --model-f1 0.88 \\
      --audit-log-sha256 abc123... \\
      --hyperparams-sha256 def456... \\
      --explainability-method SHAP \\
      --consortium-size 5 \\
      --output-dir certs/ \\
      --format json,markdown \\
      --signing-key-env CFI_COMPLIANCE_SIGNING_KEY
"""

from __future__ import annotations

import argparse
import os
import sys
from datetime import UTC, datetime
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent
BACKEND_DIR = REPO_ROOT / "backend"
if str(BACKEND_DIR) not in sys.path:
    sys.path.insert(0, str(BACKEND_DIR))


def _resolve_signing_key(env_var: str, hex_key: str | None) -> bytes:
    """Resolves the HMAC signing key from environment variable or hex CLI argument."""
    if hex_key:
        try:
            return bytes.fromhex(hex_key)
        except ValueError as exc:
            sys.exit(f"Error: --signing-key-hex is not valid hexadecimal: {exc}")

    raw = os.environ.get(env_var, "")
    if raw:
        # Accept both hex-encoded and raw string signing keys from env
        try:
            return bytes.fromhex(raw)
        except ValueError:
            return raw.encode("utf-8")

    # Default insecure dev key — warns loudly
    print(
        "WARNING: No signing key provided via --signing-key-hex or "
        f"${env_var}. Using insecure development key. DO NOT use in production.",
        file=sys.stderr,
    )
    return b"cfi-platform-dev-signing-key-insecure"


def build_parser() -> argparse.ArgumentParser:
    """Builds the CLI argument parser."""
    parser = argparse.ArgumentParser(
        prog="export_compliance_report",
        description=(
            "Generate EU AI Act (EU) 2024/1689 compliance certificates for the "
            "CFI Platform Federated Learning global model."
        ),
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )

    # Model identity
    parser.add_argument(
        "--model-version",
        default="v1.0.0",
        help="Semantic version tag of the assessed FL global model (default: v1.0.0)",
    )

    # FL metrics
    parser.add_argument(
        "--fl-rounds",
        type=int,
        default=10,
        metavar="N",
        help="Number of FL training rounds completed (default: 10)",
    )
    parser.add_argument(
        "--dp-epsilon",
        type=float,
        default=1.0,
        metavar="EPS",
        help="Cumulative DP epsilon budget consumed (default: 1.0)",
    )
    parser.add_argument(
        "--dp-delta",
        type=float,
        default=1e-5,
        metavar="DELTA",
        help="Differential privacy delta parameter (default: 1e-5)",
    )
    parser.add_argument(
        "--iban-pass-rate",
        type=float,
        default=1.0,
        metavar="RATE",
        help="Fraction of transactions passing ISO 13616 IBAN validation (default: 1.0)",
    )
    parser.add_argument(
        "--anomaly-count",
        type=int,
        default=0,
        metavar="N",
        help="Number of Byzantine/spectral anomalies detected (default: 0)",
    )

    # Governance
    parser.add_argument(
        "--dual-signoff",
        action="store_true",
        default=False,
        help="Flag indicating dual-role sign-off (ML Engineer + Compliance Officer) was granted",
    )
    parser.add_argument(
        "--model-auc",
        type=float,
        default=0.0,
        metavar="AUC",
        help="Model Area Under ROC Curve (default: 0.0)",
    )
    parser.add_argument(
        "--model-f1",
        type=float,
        default=0.0,
        metavar="F1",
        help="Model F1 score (default: 0.0)",
    )
    parser.add_argument(
        "--audit-log-sha256",
        default="",
        metavar="HASH",
        help="SHA-256 hex digest of the FL round audit log",
    )
    parser.add_argument(
        "--hyperparams-sha256",
        default="",
        metavar="HASH",
        help="SHA-256 hex digest of training hyperparameters JSON",
    )
    parser.add_argument(
        "--explainability-method",
        default="SHAP",
        help="Explainability method used for model transparency (default: SHAP)",
    )
    parser.add_argument(
        "--consortium-size",
        type=int,
        default=1,
        metavar="N",
        help="Number of participating bank nodes in the consortium (default: 1)",
    )

    # Signing key
    parser.add_argument(
        "--signing-key-env",
        default="CFI_COMPLIANCE_SIGNING_KEY",
        metavar="ENV_VAR",
        help="Environment variable name holding the HMAC signing key (default: CFI_COMPLIANCE_SIGNING_KEY)",
    )
    parser.add_argument(
        "--signing-key-hex",
        default=None,
        metavar="HEX",
        help="HMAC signing key as hex string (overrides --signing-key-env; not recommended for production)",
    )

    # Output
    parser.add_argument(
        "--output-dir",
        default=".",
        metavar="DIR",
        help="Directory to write certificate files to (default: current directory)",
    )
    parser.add_argument(
        "--format",
        default="json,markdown",
        metavar="FMT",
        help="Comma-separated output formats: json, markdown (default: json,markdown)",
    )
    parser.add_argument(
        "--quiet",
        action="store_true",
        default=False,
        help="Suppress stdout output (only write files)",
    )

    return parser


def main(argv: list[str] | None = None) -> int:
    """Entry point for the compliance certificate export CLI.

    Returns:
        0 on success, 1 on compliance failure, 2 on argument/IO error.
    """
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8", errors="replace")

    # Lazy import to allow importability checks in tests
    from app.domain.ai_act_compliance import EUAIActComplianceEngine  # noqa: PLC0415

    parser = build_parser()
    args = parser.parse_args(argv)

    signing_key = _resolve_signing_key(args.signing_key_env, args.signing_key_hex)

    engine = EUAIActComplianceEngine(
        model_version=args.model_version,
        fl_rounds_completed=args.fl_rounds,
        dp_epsilon=args.dp_epsilon,
        dp_delta=args.dp_delta,
        iban_pass_rate=args.iban_pass_rate,
        spectral_anomaly_count=args.anomaly_count,
        dual_signoff_approved=args.dual_signoff,
        model_auc=args.model_auc,
        model_f1=args.model_f1,
        audit_log_sha256=args.audit_log_sha256,
        hyperparams_sha256=args.hyperparams_sha256,
        explainability_method=args.explainability_method,
        consortium_size=args.consortium_size,
    )

    cert = engine.generate_certificate(signing_key)

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)

    timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")
    base_name = f"cfi_compliance_{timestamp}"

    formats = {f.strip().lower() for f in args.format.split(",")}
    written: list[str] = []

    if "json" in formats:
        json_path = output_dir / f"{base_name}.json"
        json_path.write_text(EUAIActComplianceEngine.export_json(cert), encoding="utf-8")
        written.append(str(json_path))

    if "markdown" in formats:
        md_path = output_dir / f"{base_name}.md"
        md_path.write_text(EUAIActComplianceEngine.export_markdown(cert), encoding="utf-8")
        written.append(str(md_path))

    if not args.quiet:
        overall = "COMPLIANT [PASS]" if cert.overall_compliant else "NON-COMPLIANT [FAIL]"
        print(f"Certificate ID  : {cert.cert_id}")
        print(f"Model Version   : {cert.model_version}")
        print(f"Issued At       : {cert.issued_at}")
        print(f"Overall Status  : {overall}")
        print(f"Fingerprint     : {cert.cert_hash}")
        print(f"Files written   : {', '.join(written)}")

    return 0 if cert.overall_compliant else 1


if __name__ == "__main__":
    sys.exit(main())