codna 0.1.0__py3-none-any.whl

codna/evidence.py

@@ -0,0 +1,163 @@
+"""Evidence attestation — the signed, replay-resistant handoff between the analysis worker
+and the PR writer (gate condition G9).
+
+The worker binds the original commit, patch digest, resulting tree, scanner outputs, proof
+results, test logs, Mojo verdict, and policy decision into one payload, stamps a single-use
+nonce, and signs it. The writer (which cannot execute repo code) re-verifies the signature,
+checks every required field is present, and consumes the nonce so a prior valid attestation
+cannot be replayed against a moved base or an already-opened PR (ATT-REPLAY).
+
+The signer is pluggable (`Signer` protocol). `HmacSigner` (stdlib `hmac`) is used for tests
+and self-hosted runs; a production deployment can swap an ed25519/KMS/Sigstore signer — the
+verify/binding/replay logic is identical. Key custody for the real signer is out of scope
+here (see the plan's residual-risks section).
+"""
+from __future__ import annotations
+
+import hmac
+import json
+import os
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Protocol
+
+from .findings import stable_json
+
+REQUIRED_FIELDS = (
+    "original_commit",
+    "patch_digest",
+    "resulting_tree",
+    "scanner_outputs",
+    "proof_results",
+    "test_logs",
+    "mojo_verdict",
+    "policy_decision",
+    "nonce",
+)
+
+
+class AttestationError(Exception):
+    pass
+
+
+class Signer(Protocol):
+    @property
+    def key_id(self) -> str: ...
+    def sign(self, data: bytes) -> str: ...
+    def verify(self, data: bytes, signature: str) -> bool: ...
+
+
+class HmacSigner:
+    """Deterministic keyed-MAC signer (stdlib). Same payload + key -> same signature."""
+
+    def __init__(self, key: bytes, key_id: str = "worker-key"):
+        self._key = key
+        self._key_id = key_id
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    def sign(self, data: bytes) -> str:
+        return hmac.new(self._key, data, sha256).hexdigest()
+
+    def verify(self, data: bytes, signature: str) -> bool:
+        return hmac.compare_digest(self.sign(data), signature or "")
+
+
+def new_nonce() -> str:
+    """Fresh single-use nonce. Injected explicitly in tests for determinism."""
+    return os.urandom(16).hex()
+
+
+@dataclass(frozen=True)
+class Attestation:
+    payload: dict
+    signature: str
+    signer_id: str
+
+    def to_dict(self) -> dict:
+        return {"payload": self.payload, "signature": self.signature, "signer_id": self.signer_id}
+
+
+def _signing_bytes(payload: dict) -> bytes:
+    # Canonical (sorted-key) serialization -> order-independent, deterministic (ATT-05).
+    return stable_json(payload).encode("utf-8")
+
+
+def build_attestation(signer: Signer, *, nonce: str, **fields) -> Attestation:
+    missing = [f for f in REQUIRED_FIELDS if f != "nonce" and f not in fields]
+    if missing:
+        raise AttestationError(f"cannot build attestation, missing fields: {missing}")
+    payload = {**fields, "nonce": nonce}
+    return Attestation(payload, signer.sign(_signing_bytes(payload)), signer.key_id)
+
+
+class NonceStore:
+    """Single-use enforcement. `use` returns False if the nonce was already consumed."""
+
+    def __init__(self):
+        self._seen: set[str] = set()
+
+    def use(self, nonce: str) -> bool:
+        if nonce in self._seen:
+            return False
+        self._seen.add(nonce)
+        return True
+
+
+def attestation_from_dict(d: dict) -> Attestation:
+    return Attestation(d["payload"], d["signature"], d["signer_id"])
+
+
+def write_evidence(evidence_dir: str, *, attestation: Attestation, patch_diff: str, finding=None) -> None:
+    """Persist the worker's signed handoff so a separate, unprivileged writer job can consume
+    it: the attestation, the patch, and a minimal finding descriptor (identity for the branch)."""
+    os.makedirs(evidence_dir, exist_ok=True)
+    with open(os.path.join(evidence_dir, "attestation.json"), "w", encoding="utf-8") as fh:
+        fh.write(stable_json(attestation.to_dict()))
+    with open(os.path.join(evidence_dir, "patch.diff"), "w", encoding="utf-8") as fh:
+        fh.write(patch_diff)
+    if finding is not None:
+        with open(os.path.join(evidence_dir, "finding.json"), "w", encoding="utf-8") as fh:
+            fh.write(stable_json({
+                "canonical_id": finding.canonical_id,
+                "rule_id": finding.rule_id,
+                "finding_kind": finding.finding_kind.value,
+            }))
+
+
+def read_evidence(evidence_dir: str) -> tuple[Attestation, str, dict]:
+    """Inverse of `write_evidence`: (attestation, patch_diff, finding_descriptor)."""
+    with open(os.path.join(evidence_dir, "attestation.json"), encoding="utf-8") as fh:
+        att = attestation_from_dict(json.load(fh))
+    with open(os.path.join(evidence_dir, "patch.diff"), encoding="utf-8") as fh:
+        diff = fh.read()
+    descriptor: dict = {}
+    fpath = os.path.join(evidence_dir, "finding.json")
+    if os.path.exists(fpath):
+        with open(fpath, encoding="utf-8") as fh:
+            descriptor = json.load(fh)
+    return att, diff, descriptor
+
+
+def verify_attestation(
+    att: Attestation,
+    *,
+    trusted_signers: dict[str, Signer],
+    nonce_store: NonceStore | None = None,
+) -> tuple[bool, str]:
+    """Verify an attestation before the writer acts on it. Checks: all required fields
+    present, signer is trusted, signature valid over the canonical payload, and (if a
+    nonce store is given) the nonce is fresh. Returns (ok, reason)."""
+    for f in REQUIRED_FIELDS:
+        if f not in att.payload:
+            return False, f"missing required field {f!r}"
+    signer = trusted_signers.get(att.signer_id)
+    if signer is None:
+        return False, f"untrusted signer {att.signer_id!r}"
+    if not signer.verify(_signing_bytes(att.payload), att.signature):
+        return False, "signature invalid (payload tampered or wrong key)"
+    if nonce_store is not None and not nonce_store.use(att.payload["nonce"]):
+        return False, "attestation replayed / nonce already used"
+    return True, "ok"

codna/findings.py

@@ -0,0 +1,272 @@
+"""Data models for codna's security-proof pipeline.
+
+`NormalizedFinding` is the canonical, scanner-agnostic representation produced by
+`codna.sarif.ingest_sarif`. Everything downstream (reachability proof, remediation,
+the PR-open gate) keys off `canonical_id` — a deterministic content hash over a
+finding's SEMANTIC identity (rule + sink + dataflow paths), NEVER over volatile fields
+(result/run order, message text, tool fingerprints, column offsets). See the A–Z test
+plan (SAR-*, RPRV-*) for the contract these models must satisfy.
+
+Pure stdlib, no engine/http/llm imports — this module is the bottom of the dependency
+graph and stays trivially testable offline.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+def stable_json(obj: Any) -> str:
+    """The ONE canonical serialization used for every digest/id: sorted keys, compact,
+    UTF-8 preserved. Same input -> byte-identical output, so runs are reproducible."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def digest_of(obj: Any) -> str:
+    """sha256: over the canonical JSON of `obj`."""
+    return "sha256:" + sha256_hex(stable_json(obj).encode("utf-8"))
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+    UNKNOWN = "unknown"
+
+
+_SEV_ORDER = {
+    Severity.UNKNOWN: -1,
+    Severity.INFO: 0,
+    Severity.LOW: 1,
+    Severity.MEDIUM: 2,
+    Severity.HIGH: 3,
+    Severity.CRITICAL: 4,
+}
+
+
+def severity_at_least(a: Severity, b: Severity) -> bool:
+    """True if band `a` is >= band `b`. UNKNOWN is below everything (never gates on
+    severity alone — it must be surfaced, not silently treated as low)."""
+    return _SEV_ORDER[a] >= _SEV_ORDER[b]
+
+
+class FindingKind(str, Enum):
+    TAINT = "taint"
+    SCA = "sca"
+    CONTROL_FLOW = "control_flow"
+    CONFIG = "config"
+    SECRET = "secret"
+    UNSUPPORTED = "unsupported"
+
+
+class Classification(str, Enum):
+    """Pre-patch reachability verdict for the ORIGINAL finding. `EXPLOITABLE` requires a
+    validated source→sink dataflow; `UNREACHABLE` requires a *complete* analysis envelope —
+    "no path found" in an incomplete envelope is `UNKNOWN`, never `UNREACHABLE`."""
+
+    EXPLOITABLE = "exploitable"
+    PRODUCTION_REACHABLE = "production-reachable"
+    UNREACHABLE = "unreachable"
+    UNKNOWN = "unknown"
+
+
+class ClosureStatus(str, Enum):
+    """Post-patch verdict — a SEPARATE judgment from reachability. `CLOSED` means the
+    original semantic proof obligation is no longer violated (a sanitizer/barrier can close
+    it even while the operation stays production-reachable) and no alternate path was found."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class Location:
+    """A physical/logical code location. `start_column` is deliberately EXCLUDED from
+    identity (`key()`) — it is too volatile across scanner versions."""
+
+    uri: str
+    start_line: int | None = None
+    start_column: int | None = None
+    logical: str | None = None  # logicalLocation fullyQualifiedName / symbol
+
+    def key(self) -> dict:
+        return {"uri": self.uri, "line": self.start_line, "logical": self.logical}
+
+    def to_dict(self) -> dict:
+        return {
+            "uri": self.uri,
+            "start_line": self.start_line,
+            "start_column": self.start_column,
+            "logical": self.logical,
+        }
+
+
+def compute_canonical_id(
+    rule_id: str,
+    kind: "FindingKind | str",
+    primary: Location | None,
+    code_flows: list[list[Location]],
+) -> str:
+    """Deterministic semantic identity. Two byte-identical findings collapse to the same
+    id (dedupe); two findings sharing a sink but with DISTINCT dataflows get DIFFERENT
+    ids (so distinct flows are never merged away — SAR-21/SAR-22). Volatile fields are
+    excluded so the id is stable under result/run reordering (SAR-25/SAR-26)."""
+    flows = sorted(
+        ([loc.key() for loc in flow] for flow in code_flows),
+        key=stable_json,
+    )
+    ident = {
+        "rule_id": rule_id,
+        "kind": kind.value if isinstance(kind, FindingKind) else kind,
+        "primary": primary.key() if primary else None,
+        "flows": flows,
+    }
+    return digest_of(ident)
+
+
+@dataclass
+class NormalizedFinding:
+    rule_id: str
+    message: str
+    scanner: str
+    finding_kind: FindingKind
+    severity: Severity
+    original_severity: str | None
+    severity_rationale: str
+    primary_location: Location | None
+    locations: list[Location] = field(default_factory=list)
+    related_locations: list[Location] = field(default_factory=list)
+    code_flows: list[list[Location]] = field(default_factory=list)
+    fingerprints: dict = field(default_factory=dict)
+    partial_fingerprints: dict = field(default_factory=dict)
+    suppressions: list = field(default_factory=list)
+    baseline_state: str | None = None
+    logical_locations: list = field(default_factory=list)
+    properties: dict = field(default_factory=dict)
+    run_index: int = 0
+    occurrence_count: int = 1
+    quarantined: bool = False
+    quarantine_reason: str | None = None
+    canonical_id: str = ""
+
+    @classmethod
+    def minimal(cls, *, canonical_id: str, rule_id: str, finding_kind: "FindingKind | str") -> "NormalizedFinding":
+        """Reconstruct a lightweight finding from an evidence descriptor (the writer only needs
+        identity + rule + kind to name the branch/PR; the full finding lives in the attestation)."""
+        kind = finding_kind if isinstance(finding_kind, FindingKind) else FindingKind(str(finding_kind))
+        f = cls(
+            rule_id=rule_id, message="", scanner="", finding_kind=kind,
+            severity=Severity.UNKNOWN, original_severity=None, severity_rationale="",
+            primary_location=None,
+        )
+        f.canonical_id = canonical_id
+        return f
+
+    @property
+    def is_actively_suppressed(self) -> bool:
+        """SARIF suppression is "active" unless explicitly rejected. An unsuppressed
+        occurrence must never be shadowed by a suppressed duplicate (SAR-23/24)."""
+        if not self.suppressions:
+            return False
+        for s in self.suppressions:
+            status = s.get("status") if isinstance(s, dict) else None
+            if status in (None, "accepted"):
+                return True
+        return False
+
+    def to_dict(self) -> dict:
+        return {
+            "canonical_id": self.canonical_id,
+            "rule_id": self.rule_id,
+            "message": self.message,
+            "scanner": self.scanner,
+            "finding_kind": self.finding_kind.value,
+            "severity": self.severity.value,
+            "original_severity": self.original_severity,
+            "severity_rationale": self.severity_rationale,
+            "primary_location": self.primary_location.to_dict() if self.primary_location else None,
+            "locations": [loc.to_dict() for loc in self.locations],
+            "related_locations": [loc.to_dict() for loc in self.related_locations],
+            "code_flows": [[loc.to_dict() for loc in flow] for flow in self.code_flows],
+            "fingerprints": self.fingerprints,
+            "partial_fingerprints": self.partial_fingerprints,
+            "suppressions": self.suppressions,
+            "baseline_state": self.baseline_state,
+            "logical_locations": self.logical_locations,
+            "properties": self.properties,
+            "run_index": self.run_index,
+            "occurrence_count": self.occurrence_count,
+            "quarantined": self.quarantined,
+            "quarantine_reason": self.quarantine_reason,
+        }
+
+
+@dataclass
+class ScannerIdentity:
+    name: str  # canonical: codeql|semgrep|snyk|trivy|...
+    raw_name: str
+    version: str | None
+    guid: str | None
+    rules_count: int
+    rules_digest: str
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "raw_name": self.raw_name,
+            "version": self.version,
+            "guid": self.guid,
+            "rules_count": self.rules_count,
+            "rules_digest": self.rules_digest,
+        }
+
+
+@dataclass
+class IngestResult:
+    schema_version: str
+    sarif_digest: str
+    scanner: ScannerIdentity
+    findings: list[NormalizedFinding]
+    provenance_valid: bool
+    provenance_errors: list[str]
+    commit: str | None
+    tree_digest: str | None
+    repo_uri: str | None
+    scanner_self_report: dict
+    # Scanner-reported success (exitCode/executionSuccessful) is NEVER authoritative —
+    # codna reruns the scanner itself under a pinned manifest (G2/G6). Always False.
+    scanner_self_report_trusted: bool
+    quarantined_artifacts: list[dict]
+    raw_result_count: int
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": self.schema_version,
+            "sarif_digest": self.sarif_digest,
+            "scanner": self.scanner.to_dict(),
+            "findings": [f.to_dict() for f in self.findings],
+            "provenance_valid": self.provenance_valid,
+            "provenance_errors": list(self.provenance_errors),
+            "commit": self.commit,
+            "tree_digest": self.tree_digest,
+            "repo_uri": self.repo_uri,
+            "scanner_self_report": self.scanner_self_report,
+            "scanner_self_report_trusted": self.scanner_self_report_trusted,
+            "quarantined_artifacts": self.quarantined_artifacts,
+            "raw_result_count": self.raw_result_count,
+        }
+
+    def to_canonical_json(self) -> str:
+        """Byte-reproducible serialization — no clock/uuid/random leak (SAR-35,
+        INFRA-DETERMINISM)."""
+        return stable_json(self.to_dict())

codna/gate.py

@@ -0,0 +1,132 @@
+"""The PR-open gate — the nine conditions that must ALL hold before codna opens a draft PR.
+
+This is the decision core: pure logic that composes already-computed verdicts (provenance,
+baseline reproduction, reachability classification, patch integrity, regression safety,
+scanner confirmation, closure, alternate/new findings, attestation) into one auditable
+`GateDecision`. A PR opens only on a logical-AND of every condition; a single failure blocks
+it and the failing condition is named (BRCP-38/39).
+
+Note the separation the spec insists on: G6 (scanner confirmation, non-degraded) is about
+the scan; G7 (closure) requires `closure_status == CLOSED` and is satisfied by a sanitizer
+even when the operation stays production-reachable — closure is NOT "all reachability gone".
+
+Pure stdlib, no engine/http/subprocess — the gate is decided from inputs, never by executing
+anything. Producing those inputs is the worker's job (a different privilege domain).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .findings import Classification, ClosureStatus
+from .policy import Policy
+
+GATE_ORDER = ("G1", "G2", "G3", "G4", "G5", "G6", "G7", "G8", "G9")
+
+
+@dataclass
+class GateInput:
+    # G1 immutable provenance (all digests bound, commit pinned)
+    provenance_valid: bool
+    # G2 baseline reproduction on the exact unpatched snapshot
+    baseline_reproduced: bool
+    # G3 policy-eligible proof
+    classification: Classification
+    # G4 patch integrity (no verification-evasion, within change scope)
+    patch_integrity_ok: bool
+    # G5 regression safety
+    build_passed: bool
+    tests_passed: bool
+    mojo_ok: bool
+    # G6 scanner confirmation under an identical, non-degraded config
+    scanner_confirms_gone: bool
+    scan_not_degraded: bool
+    # G7 independent closure proof
+    closure_status: ClosureStatus
+    # G8 no alternate / newly-introduced vulnerability
+    alternate_path_found: bool
+    new_blocking_findings: list = field(default_factory=list)
+    # G9 attested handoff (signature/digests verified) + base unchanged at open time
+    attestation_ok: bool = False
+    base_unchanged: bool = False
+
+
+@dataclass
+class ConditionResult:
+    gate: str
+    passed: bool
+    reason: str
+
+
+@dataclass
+class GateDecision:
+    conditions: list[ConditionResult]
+    should_open_pr: bool
+
+    @property
+    def failed(self) -> list[str]:
+        return [c.gate for c in self.conditions if not c.passed]
+
+    def reason_for(self, gate: str) -> str:
+        for c in self.conditions:
+            if c.gate == gate:
+                return c.reason
+        raise KeyError(gate)
+
+
+def _cond(gate: str, passed: bool, ok_reason: str, fail_reason: str) -> ConditionResult:
+    return ConditionResult(gate, passed, ok_reason if passed else fail_reason)
+
+
+def evaluate_gate(inp: GateInput, policy: Policy) -> GateDecision:
+    """Evaluate all nine conditions. `should_open_pr` is the logical-AND — every condition
+    must pass; otherwise the PR is blocked and `.failed` lists the offending gate(s)."""
+    eligible, elig_reason = policy.is_autofix_eligible(inp.classification)
+
+    g5 = inp.build_passed and inp.tests_passed and inp.mojo_ok
+    g5_fail = "; ".join(
+        r
+        for r, ok in (
+            ("build failed", inp.build_passed),
+            ("tests failed", inp.tests_passed),
+            ("Mojo verdict below threshold", inp.mojo_ok),
+        )
+        if not ok
+    )
+
+    g6 = inp.scanner_confirms_gone and inp.scan_not_degraded
+    g6_fail = (
+        "originating scanner still reports the finding"
+        if not inp.scanner_confirms_gone
+        else "patched scan is degraded vs baseline (fewer rules/files/queries)"
+    )
+
+    g8 = (not inp.alternate_path_found) and (not inp.new_blocking_findings)
+    g8_fail = (
+        "an equivalent alternate violating path remains"
+        if inp.alternate_path_found
+        else f"patch introduces {len(inp.new_blocking_findings)} new policy-blocking finding(s)"
+    )
+
+    g9 = inp.attestation_ok and inp.base_unchanged
+    g9_fail = (
+        "evidence attestation failed verification"
+        if not inp.attestation_ok
+        else "base commit changed before PR open (proof bound to a stale tree)"
+    )
+
+    conditions = [
+        _cond("G1", inp.provenance_valid, "provenance digest-bound", "incomplete/unbound provenance"),
+        _cond("G2", inp.baseline_reproduced, "baseline reproduced on unpatched snapshot",
+              "could not reproduce a semantically-equivalent finding on the unpatched snapshot"),
+        _cond("G3", eligible, elig_reason, elig_reason),
+        _cond("G4", inp.patch_integrity_ok, "patch integrity ok",
+              "patch weakens verification or escapes the permitted change scope"),
+        _cond("G5", g5, "build/tests pass and Mojo meets threshold", g5_fail),
+        _cond("G6", g6, "scanner confirms finding gone under identical config", g6_fail),
+        _cond("G7", inp.closure_status == ClosureStatus.CLOSED,
+              "obligation closed (sanitizer/barrier or path removed)",
+              f"closure_status is {inp.closure_status.value} (need 'closed')"),
+        _cond("G8", g8, "no alternate path and no new blocking findings", g8_fail),
+        _cond("G9", g9, "attested handoff verified and base unchanged", g9_fail),
+    ]
+    return GateDecision(conditions, should_open_pr=all(c.passed for c in conditions))

codna/gitpush.py

@@ -0,0 +1,57 @@
+"""Git push backend — turns a verified patch into a pushed branch for the PR writer.
+
+The writer (GitHubWriter) opens the PR via the API; the actual "branch from diff" is this
+backend's job: from a clean checkout it creates the branch at the base, applies the unified
+diff, commits, and pushes. Kept separate from writer.py so the writer's "executes no
+repository code" property stays clear — this runs only git plumbing (never the project's
+build/test/scanner code), and is exercised offline against a local bare remote in tests.
+"""
+from __future__ import annotations
+
+import subprocess
+
+
+class GitPushError(Exception):
+    pass
+
+
+def _git(repo_dir: str, *args: str, stdin: str | None = None) -> str:
+    proc = subprocess.run(
+        ["git", "-C", repo_dir, *args],
+        input=stdin, capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        raise GitPushError(f"git {' '.join(args)} -> {proc.returncode}: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+class GitBranchBuilder:
+    def __init__(self, repo_dir: str, remote: str = "origin"):
+        self.repo_dir = repo_dir
+        self.remote = remote
+
+    def build_and_push(
+        self,
+        *,
+        branch: str,
+        base: str,
+        patch_diff: str,
+        commit_message: str,
+        push_url: str | None = None,
+    ) -> str:
+        """Create `branch` at `base`, apply `patch_diff`, commit, and push. `push_url` (with an
+        embedded token) overrides the named remote. Returns the branch name."""
+        if not patch_diff.strip():
+            raise GitPushError("empty patch")
+        base_sha = _git(self.repo_dir, "rev-parse", base).strip()
+        _git(self.repo_dir, "checkout", "-B", branch, base_sha)
+        apply = subprocess.run(
+            ["git", "-C", self.repo_dir, "apply", "--index", "--whitespace=nowarn", "-"],
+            input=patch_diff, capture_output=True, text=True,
+        )
+        if apply.returncode != 0:
+            raise GitPushError(f"git apply failed: {apply.stderr.strip()}")
+        _git(self.repo_dir, "-c", "user.email=codna@codna.ai", "-c", "user.name=codna",
+             "commit", "-m", commit_message)
+        _git(self.repo_dir, "push", push_url or self.remote, f"HEAD:refs/heads/{branch}")
+        return branch