diff_gate.py

#!/usr/bin/env python3
"""The CI gate, in Python: does a change introduce a NEW route to a critical
terminal?

`bastion diff <base> <candidate>` is the recommended way to adopt Bastion — it
fails a pull request only for paths the change *introduces*, so an existing
backlog does not block every merge. This shows the same logic through the API.

Here the "base" is the hardened manifest and the "candidate" is the vulnerable
one, so the diff surfaces the ci-runner → secrets path as newly introduced and
the gate fails (exit 1), exactly as it would on a real PR.

Run:
    python examples/diff_gate.py ; echo "exit code: $?"
"""

from __future__ import annotations

import pathlib
import sys

from bastion.core import diff, engine
from bastion.rules.context import AnalysisOptions

HERE = pathlib.Path(__file__).parent


def _scan(manifest: pathlib.Path):
    return engine.scan(
        engine.ScanOptions(
            target=manifest,
            analysis=AnalysisOptions(include_system=False),
            timestamp="2026-01-01T00:00:00Z",
        )
    ).report


def main() -> int:
    base = _scan(HERE / "manifests" / "hardened.yaml")
    candidate = _scan(HERE / "manifests" / "vulnerable.yaml")

    result = diff.compare(base, candidate, timestamp="2026-01-01T00:00:00Z")

    new_critical = result.introduced_critical_paths
    print(f"Newly introduced findings: {len(result.introduced_findings)}")
    print(f"Newly introduced paths to a critical terminal: {len(new_critical)}\n")
    for path in new_critical:
        print(f"  NEW: {path.source.name} → {path.terminal.name} "
              f"({path.length} hop, {path.confidence.name})")

    # Fail the gate if the change introduces any new critical path.
    if new_critical:
        print("\nGate: FAIL — this change introduces a new route to a critical terminal.")
        return 1
    print("\nGate: PASS — no new critical routes introduced.")
    return 0


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