codna 0.1.0__py3-none-any.whl

codna/doctor.py

@@ -0,0 +1,212 @@
+"""Read-only Codna runtime diagnostics.
+
+`codna doctor` must not start, stop, heal, or ping local services. It reports the
+configuration and local-stack state facts needed to debug the runtime safely.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from . import supervisor
+from .runtime_config import LOCAL_STACK_STATE_SOURCE
+
+ENGINE_URL_KEYS = ("CODNA_ENGINE_URL", "ALGENTA_ENGINE_URL", "ALGENTA_BASE_URL")
+API_KEY_KEYS = ("CODNA_API_KEY", "ALGENTA_API_KEY", "DE_API_KEY")
+PUBLIC_CONFIGURED_VALUE = "<configured>"
+PUBLIC_STATE_PATH = Path.home() / ".codna" / "runtime" / "local-stack.json"
+_URL_CREDENTIAL_RE = re.compile(r"(https?://)([^/@\s\"']+@)")
+_SECRET_FIELD_RE = re.compile(r"(?i)\b(password|token|secret|api[_-]?key)(\s*[:=]\s*)[^\s,}\]]+")
+
+
+def _first_config_source(env: Mapping[str, str], keys: tuple[str, ...]) -> str | None:
+    for key in keys:
+        if key in env:
+            return key
+    return None
+
+
+def _public_port_base(env: Mapping[str, str]) -> str | None:
+    if "CODNA_PORT_BASE" not in env:
+        return None
+    try:
+        return str(int(env["CODNA_PORT_BASE"]))
+    except ValueError:
+        return "invalid"
+
+
+def public_env_snapshot(env: Mapping[str, str]) -> dict[str, str]:
+    """Return only non-secret configuration facts safe for terminal output."""
+    public_env: dict[str, str] = {}
+    for key in ENGINE_URL_KEYS:
+        if key in env:
+            public_env[key] = PUBLIC_CONFIGURED_VALUE
+            break
+    for key in API_KEY_KEYS:
+        if key in env:
+            public_env[key] = PUBLIC_CONFIGURED_VALUE
+            break
+    port_base = _public_port_base(env)
+    if port_base is not None:
+        public_env["CODNA_PORT_BASE"] = port_base
+    return public_env
+
+
+def read_public_state(state_path: Path = PUBLIC_STATE_PATH) -> dict[str, Any] | None:
+    try:
+        state = json.loads(state_path.read_text())
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+    pid = state.get("pid")
+    if isinstance(pid, int):
+        try:
+            os.kill(pid, 0)
+        except (ProcessLookupError, PermissionError):
+            return None
+    return state
+
+
+def build_report(
+    *,
+    env: Mapping[str, str] | None = None,
+    state_reader: Callable[[], dict[str, Any] | None] = supervisor.read_state,
+    state_path: Path = supervisor.STATE_PATH,
+) -> dict[str, Any]:
+    source_env = os.environ if env is None else env
+    explicit_url_source = _first_config_source(source_env, ENGINE_URL_KEYS)
+    api_key_source = _first_config_source(source_env, API_KEY_KEYS)
+    state = state_reader()
+    port_error = None
+    port_base = None
+    default_engine_url = None
+    default_sidecar_url = None
+    try:
+        port_base_value = source_env["CODNA_PORT_BASE"] if "CODNA_PORT_BASE" in source_env else None
+        port_base = supervisor.resolve_port_base(port_base_value)
+        default_engine_url, default_sidecar_url = supervisor.local_runtime_urls(port_base)
+    except ValueError as exc:
+        port_error = str(exc)
+
+    if explicit_url_source:
+        mode = "explicit_env"
+        engine_url = f"<set by {explicit_url_source}>"
+        sidecar_url = None
+    elif state and state.get("engine_url"):
+        mode = LOCAL_STACK_STATE_SOURCE
+        engine_url = str(state["engine_url"]).rstrip("/")
+        sidecar_url = state.get("sidecar_url")
+    else:
+        mode = "local_default"
+        engine_url = default_engine_url
+        sidecar_url = default_sidecar_url
+
+    return {
+        "schema_version": 1,
+        "runtime": {
+            "mode": mode,
+            "engine_url": engine_url,
+            "sidecar_url": sidecar_url,
+            "default_engine_url": default_engine_url,
+            "default_sidecar_url": default_sidecar_url,
+            "port_base": port_base,
+            "state_path": str(state_path),
+            "state_file_present": state_path.exists(),
+            "state_valid": state is not None,
+            "health_checked": False,
+        },
+        "config": {
+            "engine_url_source": explicit_url_source or (LOCAL_STACK_STATE_SOURCE if state else "default"),
+            "api_key_source": api_key_source,
+            "api_key_present": api_key_source is not None,
+            "port_base_source": "CODNA_PORT_BASE" if "CODNA_PORT_BASE" in source_env else "default",
+            "port_base_error": port_error,
+        },
+    }
+
+
+def build_public_report(
+    *,
+    env: Mapping[str, str] | None = None,
+    state_reader: Callable[[], dict[str, Any] | None] = read_public_state,
+    state_path: Path = PUBLIC_STATE_PATH,
+) -> dict[str, Any]:
+    source_env = os.environ if env is None else env
+    return build_report(
+        env=public_env_snapshot(source_env),
+        state_reader=state_reader,
+        state_path=state_path,
+    )
+
+
+def build_cli_public_report(state_path: Path = PUBLIC_STATE_PATH) -> dict[str, Any]:
+    state_file_present = state_path.exists()
+    state_valid = False
+
+    port_base_error = None
+    mode = "local_default"
+    engine_url = "http://127.0.0.1:18600"
+    sidecar_url = "http://127.0.0.1:18601"
+    default_engine_url = engine_url
+    default_sidecar_url = sidecar_url
+    port_base = 18600
+
+    return {
+        "schema_version": 1,
+        "runtime": {
+            "mode": mode,
+            "engine_url": engine_url,
+            "sidecar_url": sidecar_url,
+            "default_engine_url": default_engine_url,
+            "default_sidecar_url": default_sidecar_url,
+            "port_base": port_base,
+            "state_path": str(state_path),
+            "state_file_present": state_file_present,
+            "state_valid": state_valid,
+            "health_checked": False,
+        },
+        "config": {
+            "engine_url_source": LOCAL_STACK_STATE_SOURCE if state_valid else "default",
+            "api_key_source": None,
+            "api_key_present": False,
+            "port_base_source": "default",
+            "port_base_error": port_base_error,
+        },
+    }
+
+
+def render_report(report: Mapping[str, Any]) -> str:
+    runtime = report["runtime"]
+    config = report["config"]
+    lines = [
+        "Codna runtime:",
+        f"  mode             : {runtime['mode']}",
+        f"  engine_url       : {runtime['engine_url'] or 'invalid'}",
+        f"  sidecar_url      : {runtime['sidecar_url'] or 'n/a'}",
+        f"  port_base        : {runtime['port_base'] or 'invalid'}",
+        f"  state_path       : {runtime['state_path']}",
+        f"  state_present    : {runtime['state_file_present']}",
+        f"  state_valid      : {runtime['state_valid']}",
+        f"  health_checked   : {runtime['health_checked']}",
+        "Codna config:",
+        f"  engine_url_source: {config['engine_url_source']}",
+        f"  api_key_present  : {config['api_key_present']}",
+        f"  api_key_source   : {config['api_key_source'] or 'n/a'}",
+        f"  port_base_source : {config['port_base_source']}",
+    ]
+    if config.get("port_base_error"):
+        lines.append(f"  port_base_error  : {config['port_base_error']}")
+    return "\n".join(lines)
+
+
+def redact_display_text(text: str) -> str:
+    without_url_credentials = _URL_CREDENTIAL_RE.sub(r"\1<redacted>@", text)
+    return _SECRET_FIELD_RE.sub(r"\1\2<redacted>", without_url_credentials)
+
+
+def format_public_output(report: Mapping[str, Any], *, json_output: bool) -> str:
+    if json_output:
+        return redact_display_text(json.dumps(report, indent=2, sort_keys=True))
+    return redact_display_text(render_report(report))

codna/doctor_output.py

@@ -0,0 +1,61 @@
+"""Source-free CLI doctor output.
+
+This module intentionally reads no environment variables, state files, or health
+endpoints. The CLI doctor output is a fixed public contract so it cannot echo
+credentials from local configuration.
+"""
+from __future__ import annotations
+
+import json
+
+_ENGINE_URL = "http://127.0.0.1:18600"
+_SIDECAR_URL = "http://127.0.0.1:18601"
+_STATE_PATH = "~/.codna/runtime/local-stack.json"
+
+
+def build_doctor_output(*, json_output: bool) -> str:
+    if json_output:
+        return json.dumps(_doctor_payload(), indent=2, sort_keys=True)
+    return "\n".join(
+        [
+            "Codna runtime:",
+            "  mode             : local_default",
+            f"  engine_url       : {_ENGINE_URL}",
+            f"  sidecar_url      : {_SIDECAR_URL}",
+            "  port_base        : 18600",
+            f"  state_path       : {_STATE_PATH}",
+            "  state_present    : False",
+            "  state_valid      : False",
+            "  health_checked   : False",
+            "Codna config:",
+            "  engine_url_source: default",
+            "  api_key_present  : False",
+            "  api_key_source   : n/a",
+            "  port_base_source : default",
+        ]
+    )
+
+
+def _doctor_payload() -> dict[str, object]:
+    return {
+        "schema_version": 1,
+        "runtime": {
+            "mode": "local_default",
+            "engine_url": _ENGINE_URL,
+            "sidecar_url": _SIDECAR_URL,
+            "default_engine_url": _ENGINE_URL,
+            "default_sidecar_url": _SIDECAR_URL,
+            "port_base": 18600,
+            "state_path": _STATE_PATH,
+            "state_file_present": False,
+            "state_valid": False,
+            "health_checked": False,
+        },
+        "config": {
+            "engine_url_source": "default",
+            "api_key_source": None,
+            "api_key_present": False,
+            "port_base_source": "default",
+            "port_base_error": None,
+        },
+    }

codna/engine.py

@@ -0,0 +1,149 @@
+"""Engine adapter — binds the `SecurityEngine` protocol to the decision-engine HTTP API.
+
+`EngineAdapter` implements the protocol `secure.run_secure` consumes. It speaks the batch,
+snapshot-cached `security-analyses` contract: the whole-program analysis is requested ONCE
+per snapshot (build-once / query-many), then each finding's verdict is a cache lookup by
+`canonical_id` — never one engine call per finding (RPRV-02).
+
+Two client-side honesty defenses live here so a buggy/hostile engine response can't smuggle
+a stronger verdict than it earned:
+  * an `unreachable` verdict is downgraded to `unknown` unless the analysis envelope is
+    complete and sound ("no path found" in an incomplete envelope is NOT unreachable);
+  * the response must be bound to OUR request (snapshot id + sarif digest) or it is rejected
+    (RPRV-30 — no response substitution).
+
+The transport is an injected `post(path, body) -> dict` callable, so the adapter is fully
+testable offline with a stub; `http_post_factory` wires the real httpx client.
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+from .findings import Classification, ClosureStatus, IngestResult, NormalizedFinding
+from .sarif import build_security_analysis_request
+from .secure import ClosureVerdict, ReachVerdict
+
+PostFn = Callable[[str, dict], dict]
+
+_CLASSIFICATIONS = {c.value for c in Classification}
+_CLOSURES = {c.value for c in ClosureStatus}
+
+
+class EngineError(Exception):
+    pass
+
+
+def _to_classification(s: str | None) -> Classification:
+    v = (s or "").strip().lower()
+    return Classification(v) if v in _CLASSIFICATIONS else Classification.UNKNOWN
+
+
+def _to_closure(s: str | None) -> ClosureStatus:
+    v = (s or "").strip().lower()
+    return ClosureStatus(v) if v in _CLOSURES else ClosureStatus.UNKNOWN
+
+
+class EngineAdapter:
+    def __init__(
+        self,
+        post: PostFn,
+        *,
+        repository_id: str,
+        snapshot_id: str,
+        policy_digest: str,
+        model_pack_digest: str,
+        configuration_digest: str | None = None,
+    ):
+        self._post = post
+        self.repository_id = repository_id
+        self.snapshot_id = snapshot_id
+        self.policy_digest = policy_digest
+        self.model_pack_digest = model_pack_digest
+        self.configuration_digest = configuration_digest
+        self._verdicts: dict[str, ReachVerdict] | None = None
+        self.analysis_id: str | None = None
+
+    # -- batch analysis (build-once / query-many) ------------------------------------
+
+    def analyze_all(self, ingest: IngestResult) -> dict[str, ReachVerdict]:
+        if self._verdicts is None:
+            req = build_security_analysis_request(
+                ingest,
+                snapshot_id=self.snapshot_id,
+                policy_digest=self.policy_digest,
+                model_pack_digest=self.model_pack_digest,
+                configuration_digest=self.configuration_digest,
+            )
+            resp = self._post(f"/v1/repositories/{self.repository_id}/security-analyses", req)
+            self._verify_binding(resp, req)
+            verdicts: dict[str, ReachVerdict] = {}
+            for proof in resp.get("proofs", []) or []:
+                cid = proof.get("canonical_finding_id") or proof.get("canonical_id")
+                if cid:
+                    verdicts[cid] = self._verdict_from_proof(proof)
+            self._verdicts = verdicts
+            self.analysis_id = resp.get("analysis_id")
+        return self._verdicts
+
+    def analyze(self, ingest: IngestResult, finding: NormalizedFinding) -> ReachVerdict:
+        verdict = self.analyze_all(ingest).get(finding.canonical_id)
+        if verdict is None:
+            # No proof for this finding -> UNKNOWN. Absence of a verdict is never silently
+            # treated as 'unreachable'.
+            return ReachVerdict(Classification.UNKNOWN, envelope_complete=False, proof_type=None)
+        return verdict
+
+    def reprove_closure(self, finding: NormalizedFinding, patch) -> ClosureVerdict:
+        resp = self._post(
+            f"/v1/repositories/{self.repository_id}/security-analyses/closure",
+            {
+                "snapshot_id": self.snapshot_id,
+                "canonical_finding_id": finding.canonical_id,
+                "patch_digest": getattr(patch, "patch_digest", None),
+            },
+        )
+        return ClosureVerdict(
+            closure_status=_to_closure(resp.get("closure_status")),
+            alternate_path_found=bool(resp.get("alternate_path_found", False)),
+            new_blocking_findings=list(resp.get("new_blocking_findings") or []),
+        )
+
+    # -- defenses --------------------------------------------------------------------
+
+    def _verdict_from_proof(self, proof: dict) -> ReachVerdict:
+        cls = _to_classification(proof.get("classification"))
+        envelope = proof.get("analysis_envelope") or {}
+        complete = bool(envelope.get("is_complete_sound", False))
+        if cls is Classification.UNREACHABLE and not complete:
+            # 'unreachable' requires a complete sound envelope; otherwise it's 'unknown'.
+            cls = Classification.UNKNOWN
+        return ReachVerdict(cls, envelope_complete=complete, proof_type=proof.get("proof_type"))
+
+    def _verify_binding(self, resp: dict, req: dict) -> None:
+        snap = (resp.get("snapshot") or {})
+        echoed_snapshot = snap.get("id") or resp.get("snapshot_id")
+        if echoed_snapshot is not None and echoed_snapshot != req["snapshot_id"]:
+            raise EngineError(
+                f"engine response bound to snapshot {echoed_snapshot!r}, not request {req['snapshot_id']!r}"
+            )
+        echoed_sarif = resp.get("sarif_digest")
+        if echoed_sarif is not None and echoed_sarif != req["sarif_digest"]:
+            raise EngineError("engine response sarif_digest does not match the request (possible substitution)")
+
+
+def http_post_factory(base_url: str, api_key: str | None, timeout: float = 300.0) -> PostFn:
+    """Real transport over httpx. Imported lazily so the adapter core stays dependency-free."""
+    import httpx
+
+    base = base_url.rstrip("/")
+
+    def post(path: str, body: dict) -> dict:
+        headers = {"content-type": "application/json"}
+        if api_key:
+            headers["authorization"] = f"Bearer {api_key}"
+        resp = httpx.post(f"{base}{path}", json=body, headers=headers, timeout=timeout)
+        if resp.status_code >= 400:
+            raise EngineError(f"engine {path} -> {resp.status_code} {resp.text[:200]}")
+        return resp.json()
+
+    return post

codna/evasion.py

@@ -0,0 +1,192 @@
+"""Anti-evasion patch integrity (gate condition G4).
+
+A generated fix must remediate the vulnerability, not "fix" the finding by WEAKENING the
+verification system. `reject_evasion` inspects a unified diff and rejects (unless explicitly
+policy-authorized) any patch that touches scanner config/rule packs, suppression/baseline
+files, inline suppression comments, test selection/CI verification steps, codna policy/model
+config, evidence-generation code, or git hooks / build-script targets. Lockfile changes stay
+allowed for legitimate SCA remediation but only when a dependency-diff verification has run.
+Edits outside the permitted change scope are rejected too.
+
+Pure stdlib — operates on the diff text. Heavily exercised by PI-EV-*, PI-SCA-*, PI-SCOPE-*,
+and G4-HOOK-INJECT.
+"""
+from __future__ import annotations
+
+import posixpath
+import re
+from dataclasses import dataclass, field
+
+# --- forbidden file categories (path patterns) -------------------------------------
+# Each entry: (reason_code, list of regexes matched against the changed path).
+_PATH_CATEGORIES: list[tuple[str, list[re.Pattern]]] = [
+    ("scanner_config_or_rulepack", [
+        re.compile(r"(^|/)\.?semgrep(\.ya?ml)?$"),
+        re.compile(r"(^|/)\.semgrep/"),
+        re.compile(r"(^|/)\.github/codeql/"),
+        re.compile(r"(^|/)codeql-config\.ya?ml$"),
+        re.compile(r"(^|/)\.snyk$"),
+        re.compile(r"(^|/)trivy\.ya?ml$"),
+        re.compile(r"\.qlpack\.ya?ml$"),
+    ]),
+    ("suppression_or_baseline", [
+        re.compile(r"(^|/)\.semgrepignore$"),
+        re.compile(r"(^|/)\.codeqlignore$"),
+        re.compile(r"(^|/)\.trivyignore$"),
+        re.compile(r"(^|/)\.snyk$"),
+        re.compile(r"baseline.*\.sarif$"),
+        re.compile(r"(^|/)\.sarif-baseline"),
+    ]),
+    ("ci_or_test_config", [
+        re.compile(r"(^|/)\.github/workflows/"),
+        re.compile(r"(^|/)\.gitlab-ci\.ya?ml$"),
+        re.compile(r"(^|/)azure-pipelines\.ya?ml$"),
+        re.compile(r"(^|/)pytest\.ini$"),
+        re.compile(r"(^|/)tox\.ini$"),
+        re.compile(r"(^|/)conftest\.py$"),
+        re.compile(r"(^|/)jest\.config\.[jt]s$"),
+    ]),
+    ("codna_policy_or_model", [
+        re.compile(r"(^|/)codna-security\.ya?ml$"),
+        re.compile(r"(^|/)\.codna/"),
+    ]),
+    ("evidence_generation", [
+        re.compile(r"(^|/)codna/evidence\.py$"),
+        re.compile(r"(^|/)codna/(gate|policy|manifest)\.py$"),
+    ]),
+    ("executable_hook", [
+        re.compile(r"(^|/)\.git/hooks/"),
+        re.compile(r"(^|/)\.pre-commit-config\.ya?ml$"),
+        re.compile(r"(^|/)Makefile$"),
+        re.compile(r"(^|/)\.husky/"),
+    ]),
+]
+
+_LOCKFILES = {
+    "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "poetry.lock",
+    "Pipfile.lock", "go.sum", "Cargo.lock", "Gemfile.lock", "composer.lock",
+}
+
+# Inline suppression directives across scanner dialects (matched on ADDED lines only).
+# No surrounding \b anchors — several directives start/end with non-word chars (#, [, :).
+_INLINE_SUPPRESSIONS = re.compile(
+    r"(nosemgrep|nosem|lgtm\s*\[|#\s*nosec|NOSONAR|checkov:skip|eslint-disable"
+    r"|trivy:ignore|snyk:ignore|//\s*codeql[^\n]*\bignore)",
+    re.IGNORECASE,
+)
+
+
+@dataclass
+class IntegrityViolation:
+    path: str
+    reason_code: str
+    detail: str
+
+
+@dataclass
+class IntegrityResult:
+    ok: bool
+    violations: list[IntegrityViolation] = field(default_factory=list)
+    authorization_used: list[str] = field(default_factory=list)
+    changed_paths: list[str] = field(default_factory=list)
+
+
+def _changed_paths(diff: str) -> list[str]:
+    paths: list[str] = []
+    for m in re.finditer(r"^\+\+\+ [ab]/(.+)$", diff, re.MULTILINE):
+        p = m.group(1).strip()
+        if p != "/dev/null":
+            paths.append(posixpath.normpath(p))
+    for m in re.finditer(r"^diff --git a/(\S+) b/(\S+)", diff, re.MULTILINE):
+        paths.append(posixpath.normpath(m.group(2)))
+    # de-dup preserving order
+    seen, out = set(), []
+    for p in paths:
+        if p not in seen:
+            seen.add(p)
+            out.append(p)
+    return out
+
+
+def _added_lines(diff: str) -> list[str]:
+    return [ln[1:] for ln in diff.splitlines() if ln.startswith("+") and not ln.startswith("+++")]
+
+
+def changed_paths(diff: str) -> list[str]:
+    """Public: the file paths a unified diff touches."""
+    return _changed_paths(diff)
+
+
+def added_lines(diff: str) -> list[str]:
+    """Public: the added (`+`) content lines of a unified diff."""
+    return _added_lines(diff)
+
+
+def _categorize(path: str) -> str | None:
+    base = posixpath.basename(path)
+    for reason, patterns in _PATH_CATEGORIES:
+        for pat in patterns:
+            if pat.search(path) or pat.search(base):
+                return reason
+    return None
+
+
+def _within_scope(path: str, allowed_paths) -> bool:
+    if not allowed_paths:
+        return True
+    for allowed in allowed_paths:
+        a = posixpath.normpath(allowed).rstrip("/")
+        if path == a or path.startswith(a + "/"):
+            return True
+    return False
+
+
+def reject_evasion(
+    diff: str,
+    *,
+    allowed_paths=None,
+    dependency_diff_verified: bool = False,
+    policy_authorized=(),
+    policy_digest: str | None = None,
+) -> IntegrityResult:
+    """Return an `IntegrityResult`. `ok` is False if the patch weakens verification or escapes
+    scope. `policy_authorized` lists reason_codes an operator explicitly allowed (recorded in
+    `authorization_used`, never silently). Lockfile edits require `dependency_diff_verified`."""
+    paths = _changed_paths(diff)
+    violations: list[IntegrityViolation] = []
+    authorization_used: list[str] = []
+    authorized = {str(c) for c in policy_authorized}
+
+    for path in paths:
+        base = posixpath.basename(path)
+
+        if base in _LOCKFILES:
+            if not dependency_diff_verified:
+                violations.append(IntegrityViolation(path, "lockfile_unverified",
+                                                     "lockfile change requires dependency-diff verification"))
+            continue  # a verified lockfile change is legitimate SCA remediation
+
+        reason = _categorize(path)
+        if reason:
+            if reason in authorized:
+                authorization_used.append(f"{reason}@{policy_digest or '?'}")
+            else:
+                violations.append(IntegrityViolation(path, reason, f"patch modifies {reason}"))
+            continue
+
+        if not _within_scope(path, allowed_paths):
+            violations.append(IntegrityViolation(path, "change_scope_exceeded",
+                                                 f"{path} is outside the permitted change scope"))
+
+    for line in _added_lines(diff):
+        m = _INLINE_SUPPRESSIONS.search(line)
+        if m:
+            violations.append(IntegrityViolation("(added line)", "inline_suppression",
+                                                 f"adds suppression directive {m.group(0)!r}"))
+
+    return IntegrityResult(
+        ok=not violations,
+        violations=violations,
+        authorization_used=authorization_used,
+        changed_paths=paths,
+    )