@0dai-dev/cli 4.3.5 → 4.3.7

package/lib/python/compliance_report.py

@@ -0,0 +1,581 @@
+#!/usr/bin/env python3
+"""0dai Compliance Report - generate SOC 2 / ISO 27001 evidence from audit logs.
+
+Produces structured evidence showing: access controls, change management,
+policy enforcement, and monitoring — derived from ai/ layer data.
+
+Usage:
+    python3 scripts/compliance_report.py --target <path>                    # human-readable
+    python3 scripts/compliance_report.py --target <path> --json             # JSON output
+    python3 scripts/compliance_report.py --target <path> --framework soc2   # SOC 2 focused
+    python3 scripts/compliance_report.py --target <path> --framework iso27001
+    0dai compliance audit-trail --since=DATE [--until=DATE]
+    0dai compliance --target <path>
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import gzip
+import io
+import json
+import pathlib
+import tarfile
+from typing import Any
+
+from json_utils import load_json as _ext_load_json, load_jsonl as _ext_load_jsonl
+
+
+FRAMEWORKS = {
+    "soc2": {
+        "name": "SOC 2 Type II",
+        "controls": [
+            {"id": "CC6.1", "area": "Access Control", "description": "Logical access restrictions to information assets"},
+            {"id": "CC6.2", "area": "Access Control", "description": "User registration and authorization"},
+            {"id": "CC7.2", "area": "Change Management", "description": "Changes are authorized and tested before implementation"},
+            {"id": "CC7.3", "area": "Change Management", "description": "Changes to infrastructure and software are managed"},
+            {"id": "CC7.4", "area": "Monitoring", "description": "Changes are monitored and anomalies investigated"},
+            {"id": "CC8.1", "area": "Risk Assessment", "description": "Risk assessment processes identify threats and vulnerabilities"},
+        ],
+    },
+    "iso27001": {
+        "name": "ISO 27001:2022",
+        "controls": [
+            {"id": "A.5.1", "area": "Policies", "description": "Information security policies defined and approved"},
+            {"id": "A.8.3", "area": "Access Control", "description": "Access to information restricted per policy"},
+            {"id": "A.8.9", "area": "Change Management", "description": "Configuration management applied"},
+            {"id": "A.8.15", "area": "Logging", "description": "Activities, exceptions, and events logged"},
+            {"id": "A.8.25", "area": "Secure Development", "description": "Rules for secure development established"},
+            {"id": "A.8.32", "area": "Change Management", "description": "Changes to development subject to change management"},
+        ],
+    },
+}
+UTC = getattr(dt, "UTC", dt.timezone.utc)
+ADR_SCHEMA = "0dai.adr.v1"
+DATE_ONLY_LENGTH = 10
+NON_CONCRETE_EVIDENCE_KEYS = {
+    "configured",
+    "evidence",
+    "evidence_gaps",
+    "schema_valid",
+}
+PLACEHOLDER_EVIDENCE_TEXT = {
+    "n/a",
+    "na",
+    "none",
+    "no evidence",
+    "not available",
+    "placeholder",
+    "tbd",
+    "todo",
+}
+
+
+def _load_jsonl(path: pathlib.Path) -> list[dict]:
+    return _ext_load_jsonl(path)
+
+
+def _load_json(path: pathlib.Path) -> dict | None:
+    result = _ext_load_json(path)
+    return result or None
+
+
+def _type_name(value: Any) -> str:
+    if value is None:
+        return "null"
+    return type(value).__name__
+
+
+def _is_placeholder_text(value: str) -> bool:
+    normalized = " ".join(value.strip().lower().split())
+    return not normalized or normalized in PLACEHOLDER_EVIDENCE_TEXT
+
+
+def _has_concrete_payload(value: Any) -> bool:
+    has_payload = False
+    if isinstance(value, bool):
+        has_payload = value
+    elif isinstance(value, (int, float)):
+        has_payload = value > 0
+    elif isinstance(value, str):
+        has_payload = not _is_placeholder_text(value)
+    elif isinstance(value, list):
+        has_payload = any(_has_concrete_payload(item) for item in value)
+    elif isinstance(value, dict):
+        has_payload = any(
+            _has_concrete_payload(item)
+            for key, item in value.items()
+            if key not in NON_CONCRETE_EVIDENCE_KEYS
+        )
+    return has_payload
+
+
+def _positive_count(record: dict, key: str) -> bool:
+    try:
+        return int(record.get(key) or 0) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def _string_list_field(raw: Any, field: str, gaps: list[str]) -> list[str]:
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        gaps.append(f"permissions.{field} must be a list, got {_type_name(raw)}")
+        return []
+
+    values: list[str] = []
+    for index, item in enumerate(raw):
+        if not isinstance(item, str) or not item.strip():
+            gaps.append(f"permissions.{field}[{index}] must be a non-empty string")
+            continue
+        values.append(item)
+    return values
+
+
+def _org_policy_pack_names(org_policy: dict) -> list[str]:
+    packs = org_policy.get("packs_applied", [])
+    if not isinstance(packs, list):
+        return []
+
+    names: list[str] = []
+    for item in packs:
+        if isinstance(item, dict):
+            name = str(item.get("name") or "").strip()
+        elif isinstance(item, str):
+            name = item.strip()
+        else:
+            name = ""
+        if name:
+            names.append(name)
+    return names
+
+
+def _normalize_org_permissions(org_policy: dict) -> tuple[dict[str, list[str]], list[str]]:
+    permissions = org_policy.get("permissions", {})
+    if permissions is None:
+        return {"protected_paths": [], "denied_commands": []}, ["permissions must be an object, got null"]
+    if not isinstance(permissions, dict):
+        return (
+            {"protected_paths": [], "denied_commands": []},
+            [f"permissions must be an object, got {_type_name(permissions)}"],
+        )
+
+    gaps: list[str] = []
+    normalized = {
+        "protected_paths": _string_list_field(permissions.get("protected_paths", []), "protected_paths", gaps),
+        "denied_commands": _string_list_field(permissions.get("denied_commands", []), "denied_commands", gaps),
+    }
+    return normalized, gaps
+
+
+def _source_has_failed_evidence(record: Any) -> bool:
+    return (
+        isinstance(record, dict)
+        and (record.get("schema_valid") is False or bool(record.get("evidence_gaps")))
+    )
+
+
+def _source_has_concrete_evidence(source: str, record: Any) -> bool:
+    if not isinstance(record, dict):
+        return _has_concrete_payload(record)
+    if record.get("configured") is False or _source_has_failed_evidence(record):
+        return False
+
+    checks = {
+        "access_control": lambda item: bool(item.get("roles_defined")) and _positive_count(item, "users_assigned"),
+        "audit_log": lambda item: _positive_count(item, "total_entries"),
+        "knowledge_management": lambda item: any(
+            _positive_count(item, key)
+            for key in ("events_captured", "candidates_pending", "knowledge_accepted")
+        ),
+        "licensing": lambda item: item.get("licensed") is True,
+        "prompt_integrity": lambda item: _positive_count(item, "snapshots"),
+        "security_policy": lambda item: bool(item.get("protected_paths") or item.get("denied_commands")),
+        "version_control": lambda item: bool(item.get("ai_version")) and bool(item.get("checksums_present")),
+        "write_ahead_log": lambda item: _positive_count(item, "total_mutations"),
+    }
+
+    check = checks.get(source)
+    return check(record) if check else _has_concrete_payload(record)
+
+
+def generate_evidence(target: pathlib.Path) -> dict:
+    """Collect evidence from all ai/ layer sources."""
+    evidence: dict = {}
+
+    # 1. Audit log — change tracking
+    audit = _load_jsonl(target / "ai" / "manifest" / "audit.jsonl")
+    evidence["audit_log"] = {
+        "total_entries": len(audit),
+        "unique_users": list({e.get("user", "unknown") for e in audit}),
+        "unique_actions": list({e.get("action", "") for e in audit}),
+        "date_range": {
+            "first": audit[0].get("timestamp", "")[:10] if audit else None,
+            "last": audit[-1].get("timestamp", "")[:10] if audit else None,
+        },
+        "evidence": (
+            "All CLI operations logged with timestamp, action, user, and version"
+            if audit
+            else "No audit log entries available"
+        ),
+    }
+
+    # 2. WAL — mutation tracking
+    wal = _load_jsonl(target / "ai" / "manifest" / "wal.jsonl")
+    evidence["write_ahead_log"] = {
+        "total_mutations": len(wal),
+        "undone": sum(1 for e in wal if e.get("undone")),
+        "evidence": (
+            "All MCP write operations recorded with before-state for rollback"
+            if wal
+            else "No MCP write operations recorded"
+        ),
+    }
+
+    # 3. Role policy — access control
+    role_policy = _load_json(target / "ai" / "manifest" / "role-policy.json")
+    if role_policy:
+        evidence["access_control"] = {
+            "roles_defined": list(role_policy.get("roles", {}).keys()),
+            "users_assigned": len(role_policy.get("assignments", {})),
+            "tier_restrictions": {
+                name: r.get("allowed_tiers", [])
+                for name, r in role_policy.get("roles", {}).items()
+            },
+            "evidence": "Role-based access with command tier restrictions enforced per user",
+        }
+    else:
+        evidence["access_control"] = {"configured": False, "evidence": "No role policy configured"}
+
+    # 4. Org policy — security policies
+    org_policy = _load_json(target / "ai" / "manifest" / "org-policy.json")
+    if org_policy:
+        permissions, permission_gaps = _normalize_org_permissions(org_policy)
+        has_enforced_permissions = bool(permissions["protected_paths"] or permissions["denied_commands"])
+        security_policy = {
+            "configured": not permission_gaps and has_enforced_permissions,
+            "schema_valid": not permission_gaps,
+            "packs_applied": _org_policy_pack_names(org_policy),
+            "protected_paths": permissions["protected_paths"],
+            "denied_commands": permissions["denied_commands"],
+            "evidence": (
+                "Organization security policies enforced across all AI agent configurations"
+                if not permission_gaps and has_enforced_permissions
+                else "Organization security policy evidence is incomplete or invalid"
+            ),
+        }
+        if permission_gaps:
+            security_policy["evidence_gaps"] = permission_gaps
+        evidence["security_policy"] = security_policy
+    else:
+        evidence["security_policy"] = {"configured": False, "evidence": "No org policy applied"}
+
+    # 5. License — authorization
+    license_data = _load_json(target / "ai" / "manifest" / "license.json")
+    evidence["licensing"] = {
+        "licensed": license_data is not None,
+        "tier": license_data.get("tier", "free") if license_data else "free",
+        "team": license_data.get("team", "") if license_data else "",
+        "evidence": "License tier controls access to team collaboration features",
+    }
+
+    # 6. Experience pipeline — knowledge management
+    events_dir = target / "ai" / "experience" / "events"
+    candidates_dir = target / "ai" / "experience" / "candidates"
+    accepted_dir = target / "ai" / "experience" / "accepted"
+    evidence["knowledge_management"] = {
+        "events_captured": len(list(events_dir.glob("*.json"))) if events_dir.is_dir() else 0,
+        "candidates_pending": len(list(candidates_dir.glob("*.md"))) if candidates_dir.is_dir() else 0,
+        "knowledge_accepted": sum(1 for _ in accepted_dir.rglob("*.md")) if accepted_dir.is_dir() else 0,
+        "evidence": "Structured knowledge lifecycle: capture → review → promote → distribute",
+    }
+
+    # 7. Version control
+    version_text = None
+    v_path = target / "ai" / "VERSION"
+    if v_path.is_file():
+        version_text = v_path.read_text(encoding="utf-8").strip()
+    lock = _load_json(target / "ai" / "manifest" / "applied-lock.json")
+    evidence["version_control"] = {
+        "ai_version": version_text,
+        "packs_installed": lock.get("packs", {}) if lock else {},
+        "checksums_present": bool(lock and lock.get("generated")),
+        "evidence": "Versioned AI layer with lock files and checksums for integrity verification",
+    }
+
+    # 8. Prompt versioning
+    prompt_history = _load_json(target / "ai" / "prompts" / ".history.json")
+    evidence["prompt_integrity"] = {
+        "snapshots": len(prompt_history.get("snapshots", [])) if prompt_history else 0,
+        "evidence": "System prompt changes tracked with hash-based versioning",
+    }
+
+    return evidence
+
+
+def map_to_framework(evidence: dict, framework: str) -> list[dict]:
+    """Map collected evidence to compliance framework controls."""
+    fw = FRAMEWORKS.get(framework, FRAMEWORKS["soc2"])
+    mappings = []
+
+    evidence_map = {
+        "Access Control": ["access_control", "licensing"],
+        "Change Management": ["audit_log", "write_ahead_log", "version_control"],
+        "Monitoring": ["audit_log", "knowledge_management"],
+        "Logging": ["audit_log", "write_ahead_log"],
+        "Risk Assessment": ["security_policy", "knowledge_management"],
+        "Policies": ["security_policy", "access_control"],
+        "Secure Development": ["prompt_integrity", "version_control"],
+    }
+
+    for control in fw["controls"]:
+        area = control["area"]
+        relevant_keys = evidence_map.get(area, [])
+        relevant_evidence = {k: evidence[k] for k in relevant_keys if k in evidence}
+
+        has_failed_evidence = any(_source_has_failed_evidence(v) for v in relevant_evidence.values())
+        has_data = not has_failed_evidence and any(
+            _source_has_concrete_evidence(key, value)
+            for key, value in relevant_evidence.items()
+        )
+
+        mappings.append({
+            "control_id": control["id"],
+            "area": area,
+            "description": control["description"],
+            "status": "evidenced" if has_data else "gap",
+            "evidence_sources": list(relevant_evidence.keys()),
+        })
+
+    return mappings
+
+
+def cmd_report(target: pathlib.Path, framework: str) -> None:
+    evidence = generate_evidence(target)
+    mappings = map_to_framework(evidence, framework)
+    fw = FRAMEWORKS.get(framework, FRAMEWORKS["soc2"])
+
+    print(f"0dai Compliance Report — {fw['name']}")
+    print(f"Project: {target.resolve().name}")
+    print(f"Generated: {dt.datetime.now(UTC).strftime('%Y-%m-%d %H:%M UTC')}")
+    print(f"AI Layer Version: {evidence.get('version_control', {}).get('ai_version', '?')}")
+    print()
+
+    # Summary
+    evidenced = sum(1 for m in mappings if m["status"] == "evidenced")
+    gaps = sum(1 for m in mappings if m["status"] == "gap")
+    print(f"Controls: {len(mappings)} total, {evidenced} evidenced, {gaps} gap(s)")
+    print()
+
+    # Control mapping
+    print(f"{'Control':<10} {'Area':<20} {'Status':<12} {'Sources':<30} Description")
+    print("-" * 110)
+    for m in mappings:
+        status = "PASS" if m["status"] == "evidenced" else "GAP"
+        sources = ", ".join(m["evidence_sources"][:3])
+        print(f"{m['control_id']:<10} {m['area']:<20} {status:<12} {sources:<30} {m['description'][:35]}")
+
+    # Evidence details
+    print("\nEvidence Details:")
+    for key, val in evidence.items():
+        if isinstance(val, dict) and "evidence" in val:
+            print(f"  {key}: {val['evidence']}")
+
+
+def cmd_json(target: pathlib.Path, framework: str) -> None:
+    evidence = generate_evidence(target)
+    mappings = map_to_framework(evidence, framework)
+    fw = FRAMEWORKS.get(framework, FRAMEWORKS["soc2"])
+    result = {
+        "framework": fw["name"],
+        "project": target.resolve().name,
+        "generated": dt.datetime.now(UTC).isoformat(),
+        "evidence": evidence,
+        "control_mappings": mappings,
+        "summary": {
+            "total_controls": len(mappings),
+            "evidenced": sum(1 for m in mappings if m["status"] == "evidenced"),
+            "gaps": sum(1 for m in mappings if m["status"] == "gap"),
+        },
+    }
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+def _parse_date(value: str) -> dt.datetime:
+    text = value.strip()
+    if not text:
+        raise ValueError("date must not be empty")
+    if len(text) == DATE_ONLY_LENGTH:
+        parsed = dt.datetime.strptime(text, "%Y-%m-%d")
+        return parsed.replace(tzinfo=UTC)
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    parsed = dt.datetime.fromisoformat(text)
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def _end_of_day(value: str) -> dt.datetime:
+    if len(value.strip()) == DATE_ONLY_LENGTH:
+        start = _parse_date(value)
+        return start + dt.timedelta(days=1) - dt.timedelta(microseconds=1)
+    return _parse_date(value)
+
+
+def _record_timestamp(record: dict[str, Any]) -> dt.datetime | None:
+    for key in ("ts_completed", "ts_started"):
+        value = str(record.get(key) or "")
+        if not value:
+            continue
+        try:
+            return _parse_date(value)
+        except ValueError:
+            continue
+    return None
+
+
+def _load_adr_records(target: pathlib.Path) -> list[tuple[pathlib.Path, dict[str, Any]]]:
+    adr_root = target / "ai" / "meta" / "adr"
+    if not adr_root.is_dir():
+        return []
+    records: list[tuple[pathlib.Path, dict[str, Any]]] = []
+    for path in sorted(adr_root.glob("*/*.json")):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(data, dict) and data.get("schema") == ADR_SCHEMA:
+            records.append((path, data))
+    return records
+
+
+def _tar_add_bytes(tar: tarfile.TarFile, name: str, payload: bytes) -> None:
+    info = tarfile.TarInfo(name)
+    info.size = len(payload)
+    info.mtime = 0
+    info.uid = 0
+    info.gid = 0
+    info.uname = ""
+    info.gname = ""
+    tar.addfile(info, io.BytesIO(payload))
+
+
+def export_audit_trail(
+    target: pathlib.Path,
+    *,
+    since: str,
+    until: str | None = None,
+    output: pathlib.Path | None = None,
+) -> dict[str, Any]:
+    since_dt = _parse_date(since)
+    until_dt = _end_of_day(until) if until else dt.datetime.now(UTC)
+    if until_dt < since_dt:
+        raise ValueError("--until must be greater than or equal to --since")
+
+    selected: list[tuple[pathlib.Path, dict[str, Any], dt.datetime]] = []
+    for path, record in _load_adr_records(target):
+        record_ts = _record_timestamp(record)
+        if record_ts is None or record_ts < since_dt or record_ts > until_dt:
+            continue
+        selected.append((path, record, record_ts))
+
+    if output is None:
+        until_label = until or dt.datetime.now(UTC).strftime("%Y-%m-%d")
+        output = (
+            target
+            / "ai"
+            / "meta"
+            / "audit"
+            / f"adr-audit-trail-{since}-to-{until_label}.tar.gz"
+        )
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+
+    manifest = {
+        "schema": "0dai.adr.audit-trail.v1",
+        "generated_at": dt.datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "target": str(target.resolve()),
+        "since": since,
+        "until": until,
+        "record_count": len(selected),
+        "records": [
+            {
+                "session_id": record.get("session_id"),
+                "task_id": record.get("task_id"),
+                "ts_completed": record.get("ts_completed"),
+                "path": str(path.relative_to(target).as_posix()),
+            }
+            for path, record, _record_ts in selected
+        ],
+    }
+
+    with output.open("wb") as raw:
+        with gzip.GzipFile(fileobj=raw, mode="wb", mtime=0) as gz:
+            with tarfile.open(fileobj=gz, mode="w") as tar:
+                _tar_add_bytes(
+                    tar,
+                    "manifest.json",
+                    json.dumps(manifest, indent=2, ensure_ascii=False).encode("utf-8") + b"\n",
+                )
+                for path, _record, _record_ts in selected:
+                    arcname = path.relative_to(target).as_posix()
+                    _tar_add_bytes(tar, arcname, path.read_bytes())
+
+    return {
+        "ok": True,
+        "tarball": str(output),
+        "record_count": len(selected),
+        "since": since,
+        "until": until,
+    }
+
+
+def cmd_audit_trail(args: argparse.Namespace) -> None:
+    result = export_audit_trail(
+        pathlib.Path(args.target).resolve(),
+        since=args.since,
+        until=args.until,
+        output=pathlib.Path(args.output) if args.output else None,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return
+    print(f"0dai ADR audit trail: {result['tarball']}")
+    print(f"Records: {result['record_count']}")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Generate 0dai compliance evidence")
+    subparsers = parser.add_subparsers(dest="command")
+
+    audit_trail = subparsers.add_parser("audit-trail", help="export signed ADR records")
+    audit_trail.add_argument("--target", default=".", help="project root")
+    audit_trail.add_argument("--since", required=True, help="inclusive start date or timestamp")
+    audit_trail.add_argument("--until", default=None, help="inclusive end date or timestamp")
+    audit_trail.add_argument("--output", default="", help="tar.gz output path")
+    audit_trail.add_argument("--json", action="store_true", help="emit JSON")
+
+    parser.add_argument("--target", default=".", help="project root")
+    parser.add_argument("--framework", default="soc2", help="soc2 or iso27001")
+    parser.add_argument("--json", action="store_true", help="emit JSON")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "audit-trail":
+        cmd_audit_trail(args)
+        return
+
+    target = pathlib.Path(args.target).resolve()
+    if args.json:
+        cmd_json(target, args.framework)
+    else:
+        cmd_report(target, args.framework)
+
+
+if __name__ == "__main__":
+    main()