causal-memory-layer 0.4.0__py3-none-any.whl

cli/audit.py

@@ -0,0 +1,83 @@
+"""
+CLI audit adapter — thin shim over ``cml.audit.AuditEngine``.
+
+This module previously contained a parallel re-implementation of rules
+R1–R4 which kept drifting from the SDK engine (cf. the duplicate-finding
+bug fixed in PR #57 and the SAST report at
+docs/reviews/sast-report-2026-04-24.md).
+
+Now it just converts ``list[dict]`` ↔ the CLI's expected output shape
+and delegates rule evaluation to the SDK so there is exactly one source
+of truth for audit semantics.
+"""
+from __future__ import annotations
+
+from cml.audit import AuditConfig, AuditEngine, Severity
+from cml.record import CausalRecord
+
+
+def _code_to_rule(code: str) -> str:
+    # "CML-AUDIT-R1-MISSING_PARENT" -> "R1"; falls back to "?" for unknown codes
+    parts = code.split("-")
+    return parts[2] if len(parts) >= 3 else "?"
+
+
+def audit(records: list[dict], _config: dict | None = None) -> dict:
+    """Run R1–R4 audit on raw record dicts.
+
+    Returns the dict shape ``cli/main.py`` expects:
+        {"summary": {total, ok, warn, fail, passed}, "findings": [...]}
+    Each finding has ``rule``, ``code``, ``severity``, ``record_id``,
+    ``line``, and ``message``. Records that produce no findings are
+    represented by a single synthetic ``"rule": "OK"`` entry so the CLI
+    can render a per-record status.
+    """
+    cml_records: list[CausalRecord] = []
+    id_to_line: dict[str, int] = {}
+    for i, raw in enumerate(records):
+        rid = raw.get("id")
+        if rid:
+            id_to_line[rid] = i + 1
+        cml_records.append(CausalRecord.from_dict(raw))
+
+    result = AuditEngine(AuditConfig()).run(cml_records)
+
+    findings_by_record: dict[str, list[dict]] = {}
+    for f in result.findings:
+        findings_by_record.setdefault(f.record_id, []).append({
+            "rule": _code_to_rule(f.code),
+            "code": f.code,
+            "severity": f.severity,
+            "record_id": f.record_id,
+            "line": id_to_line.get(f.record_id),
+            "message": f.message,
+        })
+
+    findings: list[dict] = []
+    for rec in cml_records:
+        per_rec = findings_by_record.get(rec.id)
+        if per_rec:
+            findings.extend(per_rec)
+        else:
+            findings.append({
+                "rule": "OK",
+                "code": "OK",
+                "severity": Severity.OK,
+                "record_id": rec.id,
+                "line": id_to_line.get(rec.id),
+                "message": "All rules passed",
+            })
+
+    fail = sum(1 for f in findings if f["severity"] == Severity.FAIL)
+    warn = sum(1 for f in findings if f["severity"] == Severity.WARN)
+    ok = sum(1 for f in findings if f["severity"] == Severity.OK)
+    return {
+        "summary": {
+            "total": len(findings),
+            "ok": ok,
+            "warn": warn,
+            "fail": fail,
+            "passed": fail == 0,
+        },
+        "findings": findings,
+    }

cli/chain.py

@@ -0,0 +1,113 @@
+"""
+Causal chain reconstruction.
+Given a record ID and a log, follows parent_cause links to the root.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def reconstruct_chain(records: list[dict], target_id: str) -> dict:
+    """
+    Reconstruct the causal chain ending at target_id.
+
+    Returns a dict with:
+      target_id: str
+      chain: list of records from root to target (in order)
+      has_gap: bool — True when the chain terminates with a gap (not a root_event)
+      gap_note: str | None
+      r3_context: dict | None — filled when a SECRET access is NOT in the chain
+        but shares the same PID as the target
+    """
+    ROOT_PREFIX = "root_event:"
+    id_to_record: dict[str, Any] = {
+        rec.get("id"): rec for rec in records if rec.get("id")
+    }
+
+    if target_id not in id_to_record:
+        return {
+            "target_id": target_id,
+            "chain": [],
+            "has_gap": True,
+            "gap_note": f"Record '{target_id}' not found in log",
+            "r3_context": None,
+        }
+
+    # Walk backwards from target to root
+    chain_reversed: list[dict] = []
+    visited: set[str] = set()
+    current_id: str | None = target_id
+    has_gap = False
+    gap_note: str | None = None
+
+    while current_id:
+        if current_id in visited:
+            gap_note = f"Cycle detected at '{current_id}' — chain truncated"
+            has_gap = True
+            break
+        visited.add(current_id)
+        rec = id_to_record.get(current_id)
+        if not rec:
+            gap_note = f"Record '{current_id}' referenced by parent_cause is missing from log"
+            has_gap = True
+            break
+        chain_reversed.append(rec)
+        parent_cause = rec.get("parent_cause")
+        if parent_cause is None:
+            permitted_by = rec.get("permitted_by", "")
+            if not (isinstance(permitted_by, str) and permitted_by.startswith(ROOT_PREFIX)):
+                has_gap = True
+                if permitted_by == "unobserved_parent":
+                    gap_note = (
+                        f"Chain has a gap at '{current_id}': "
+                        "parent is unobserved (permitted_by: unobserved_parent)"
+                    )
+                else:
+                    gap_note = (
+                        f"Chain terminates at '{current_id}' with parent_cause=null "
+                        f"(permitted_by: '{permitted_by}') — neither a root nor a marked gap"
+                    )
+            break
+        current_id = parent_cause
+
+    chain = list(reversed(chain_reversed))
+    chain_ids = {r.get("id") for r in chain}
+
+    # Check for R3 context: SECRET access by the same process not in chain
+    target_rec = id_to_record[target_id]
+    target_action = target_rec.get("action", "")
+    target_pid = target_rec.get("actor", {}).get("pid")
+    r3_context: dict | None = None
+
+    if target_action in ("connect", "send") and target_pid is not None:
+        for rec in records:
+            if rec.get("actor", {}).get("pid") != target_pid:
+                continue
+            rec_action = rec.get("action", "")
+            rec_obj = rec.get("object")
+            is_secret = (
+                isinstance(rec_obj, dict)
+                and (
+                    rec_obj.get("classification") == "SECRET"
+                    or str(rec_obj.get("path", "")).startswith("/secrets/")
+                )
+            )
+            if rec_action in ("open", "read") and is_secret:
+                if rec.get("id") not in chain_ids:
+                    r3_context = {
+                        "secret_record": rec,
+                        "note": (
+                            f"SECRET access ({rec.get('id')} {rec_action} "
+                            f"{rec_obj.get('path', '?') if isinstance(rec_obj, dict) else rec_obj})"
+                            " by same process is NOT causally linked to this NET_OUT record"
+                        ),
+                    }
+                    break
+
+    return {
+        "target_id": target_id,
+        "chain": chain,
+        "has_gap": has_gap,
+        "gap_note": gap_note,
+        "r3_context": r3_context,
+    }

cli/main.py

@@ -0,0 +1,141 @@
+"""
+CML CLI entry point.
+
+Usage:
+  python -m cli.main audit <file.jsonl> [--format json|text]
+  python -m cli.main chain <file.jsonl> <record_id>
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _is_strict_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _validate_raw_record(raw: dict, line_no: int) -> None:
+    required = ("id", "timestamp", "actor", "action", "object", "permitted_by")
+    missing = [key for key in required if key not in raw]
+    if missing:
+        raise ValueError(f"Line {line_no}: missing required keys: {missing}")
+    if not isinstance(raw["id"], str) or not raw["id"].strip():
+        raise ValueError(f"Line {line_no}: field 'id' must be a non-empty string")
+    if not _is_strict_int(raw["timestamp"]):
+        raise ValueError(f"Line {line_no}: field 'timestamp' must be a strict integer")
+    if not isinstance(raw["action"], str) or not raw["action"].strip():
+        raise ValueError(f"Line {line_no}: field 'action' must be a non-empty string")
+    if not isinstance(raw["permitted_by"], str) or not raw["permitted_by"].strip():
+        raise ValueError(f"Line {line_no}: field 'permitted_by' must be a non-empty string")
+    actor = raw["actor"]
+    if not isinstance(actor, dict):
+        raise ValueError(f"Line {line_no}: field 'actor' must be an object")
+    if not _is_strict_int(actor.get("pid")) or not _is_strict_int(actor.get("uid")):
+        raise ValueError(f"Line {line_no}: actor.pid and actor.uid must be strict integers")
+    parent = raw.get("parent_cause")
+    if parent is not None and (not isinstance(parent, str) or not parent.strip()):
+        raise ValueError(f"Line {line_no}: field 'parent_cause' must be a non-empty string or null")
+
+
+def _load_jsonl(file_path: str) -> list[dict]:
+    records = []
+    with open(file_path, encoding="utf-8") as fh:
+        for line_no, line in enumerate(fh, start=1):
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                raw = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"Line {line_no}: invalid JSON ({exc})") from exc
+            if not isinstance(raw, dict):
+                raise ValueError(f"Line {line_no}: each JSONL entry must be an object")
+            _validate_raw_record(raw, line_no)
+            records.append(raw)
+    return records
+
+
+def _cmd_audit(args: argparse.Namespace) -> None:
+    from cli.audit import audit
+
+    file_path = args.file
+    if not Path(file_path).exists():
+        print(f"[ERROR] File not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        records = _load_jsonl(file_path)
+    except ValueError as exc:
+        print(f"[ERROR] Failed to parse log: {exc}", file=sys.stderr)
+        sys.exit(1)
+    result = audit(records)
+    result["file"] = file_path
+
+    if args.format == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        s = result["summary"]
+        status = "PASSED" if s["passed"] else "FAILED"
+        print(f"CML Audit: {status}")
+        print(f"  File : {file_path}")
+        print(f"  Total: {s['total']}  OK: {s['ok']}  WARN: {s['warn']}  FAIL: {s['fail']}")
+        for f in result["findings"]:
+            if f["severity"] != "OK":
+                loc = f"line {f['line']}" if f.get("line") else "?"
+                print(f"  [{f['severity']}] {f['code']} @ {f['record_id']} ({loc})")
+                print(f"        {f['message']}")
+
+
+def _cmd_chain(args: argparse.Namespace) -> None:
+    from cli.chain import reconstruct_chain
+
+    file_path = args.file
+    if not Path(file_path).exists():
+        print(f"[ERROR] File not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        records = _load_jsonl(file_path)
+    except ValueError as exc:
+        print(f"[ERROR] Failed to parse log: {exc}", file=sys.stderr)
+        sys.exit(1)
+    result = reconstruct_chain(records, args.record_id)
+    print(json.dumps(result, indent=2))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="cml",
+        description="Causal Memory Layer CLI — audit and chain inspection",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    audit_p = sub.add_parser("audit", help="Audit a JSONL causal log against CML rules")
+    audit_p.add_argument("file", help="Path to .jsonl causal log")
+    audit_p.add_argument(
+        "--format",
+        choices=["json", "text"],
+        default="text",
+        help="Output format (default: text)",
+    )
+
+    chain_p = sub.add_parser("chain", help="Reconstruct causal chain for a record")
+    chain_p.add_argument("file", help="Path to .jsonl causal log")
+    chain_p.add_argument("record_id", help="ID of the record to trace")
+
+    args = parser.parse_args()
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "audit":
+        _cmd_audit(args)
+    elif args.command == "chain":
+        _cmd_chain(args)
+
+
+if __name__ == "__main__":
+    main()

cml/__init__.py

@@ -0,0 +1,50 @@
+"""
+cml — Causal Memory Layer Python SDK
+
+Core package for recording, computing, and auditing causal chains.
+
+Modules:
+    record  — CausalRecord, Actor, load_jsonl
+    ctag    — CTAG 16-bit computation (DOM, CLASS, GEN, LHINT, SEAL)
+    chain   — Chain reconstruction and path queries
+    audit   — Audit engine (R1–R4)
+    report  — Report generation (Markdown, JSON, text)
+
+Quick start:
+
+    from cml import load_jsonl, AuditEngine, AuditConfig
+
+    records = load_jsonl("causal.jsonl")
+    engine  = AuditEngine()
+    result  = engine.run(records)
+    print(result.passed(), result.findings)
+"""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("causal-memory-layer")
+except PackageNotFoundError:  # not installed (editable source checkout)
+    __version__ = "0.0.0+unknown"
+
+from .record import CausalRecord, Actor, Action, load_jsonl, records_to_index
+from .ctag   import (
+    DOM, CLASS, CTAGState,
+    compute_ctag, decode_ctag, compute_lhint,
+)
+from .chain  import reconstruct_chain, has_path, find_root, group_by_pid
+from .audit  import AuditEngine, AuditConfig, AuditResult, Finding, Severity, CustomRule
+from .report import to_markdown, to_json, to_text
+
+__all__ = [
+    # record
+    "CausalRecord", "Actor", "Action", "load_jsonl", "records_to_index",
+    # ctag
+    "DOM", "CLASS", "CTAGState", "compute_ctag", "decode_ctag", "compute_lhint",
+    # chain
+    "reconstruct_chain", "has_path", "find_root", "group_by_pid",
+    # audit
+    "AuditEngine", "AuditConfig", "AuditResult", "Finding", "Severity", "CustomRule",
+    # report
+    "to_markdown", "to_json", "to_text",
+]