agentspm 0.1.1__py3-none-any.whl

agentspm/__init__.py

@@ -0,0 +1,6 @@
+"""agentspm — Agent Security Posture Management blueprint (v0.1, in development).
+
+Posture, not enforcement: finds, documents, and maps — never enforces.
+"""
+
+__version__ = "0.1.1"

agentspm/canonical.py

@@ -0,0 +1,63 @@
+"""Canonical serialization and deterministic hashing (FR-10).
+
+Every hash in this repository is computed over the *canonical JSON form*:
+sorted keys, no whitespace, UTF-8, no NaN. Two runs over the same graph must
+produce byte-identical hashes, so nothing in this module may consult the
+clock, the environment, or any random source.
+
+Timestamp fields are volatile run metadata, not graph content: they are
+stripped before hashing (``strip_timestamps``) so that re-collecting an
+unchanged graph yields the same ``graph_hash`` (AK-08 / TC-16).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+# Volatile timestamp keys excluded from content/graph hashes (FR-10).
+TIMESTAMP_KEYS = frozenset(
+    {
+        "collected_at",
+        "last_seen",
+        "entitlement_review_at",
+        "evaluated_at",
+    }
+)
+
+
+def canonical_json(value: Any) -> str:
+    """Serialize ``value`` to canonical JSON (sorted keys, compact, UTF-8)."""
+    return json.dumps(
+        value,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        allow_nan=False,
+    )
+
+
+def strip_timestamps(value: Any) -> Any:
+    """Recursively remove volatile timestamp keys; used for hashing only."""
+    if isinstance(value, dict):
+        return {
+            key: strip_timestamps(item)
+            for key, item in value.items()
+            if key not in TIMESTAMP_KEYS
+        }
+    if isinstance(value, list):
+        return [strip_timestamps(item) for item in value]
+    return value
+
+
+def sha256_hex(data: bytes | str) -> str:
+    """Hex SHA-256 of raw bytes (strings are encoded as UTF-8)."""
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+def content_hash(document: Any) -> str:
+    """Deterministic content hash of one document (timestamps excluded)."""
+    return sha256_hex(canonical_json(strip_timestamps(document)))

agentspm/cli.py

@@ -0,0 +1,624 @@
+"""agentspm CLI (AK-06): scan -> evaluate -> report, plus export and doctor.
+
+Pipeline (ADR-0001): **collect -> validate -> merge -> derive** (``scan``) ->
+**evaluate** (pinned OPA, hard fail on any engine problem) -> **report**
+(redacted by default; the full profile never leaves the evidence store).
+
+Exit codes:
+
+* ``scan``: non-zero ONLY for a configuration error (2), an empty graph
+  after the scan (1), or ``--strict`` with a degraded run (1). A failing
+  collector alone degrades to a partial scan — the previous snapshot stays
+  and the report shows the staleness.
+* ``evaluate``: any OPA problem is a hard fail (1) — never default results.
+* ``report``: refusing to write a full profile outside the evidence store,
+  or failing the redaction gate, exits 1.
+* ``export``: fewer than two age recipients is refused (1).
+* ``doctor``: any failing check exits 1 with a readable list.
+
+Everything tenant-specific comes from the deployment YAML + ``AGENTSPM_*``
+environment variables (FR-D5); this module never hard-codes tenant state.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tarfile
+import tempfile
+import uuid
+from collections.abc import Mapping
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Any
+
+import structlog
+import typer
+
+from agentspm.collectors import (
+    Collector,
+    CollectorConfigError,
+    build_enabled_collectors,
+    collector_registry,
+    load_config,
+    run_collectors,
+)
+from agentspm.doctor import (
+    MIN_AGE_RECIPIENTS,
+    age_recipients_from_config,
+    has_failures,
+    resolve_age_path,
+    run_doctor,
+)
+from agentspm.evaluate import EvaluateError, find_policies_dir, run_evaluate
+from agentspm.graph.derive import derive
+from agentspm.graph.store import GraphStore
+from agentspm.report import (
+    META_DROPPED_DOCUMENTS,
+    META_SCAN_COLLECTORS,
+    META_SCAN_ID,
+    META_SCAN_TIME,
+    META_SYNTHETIC_DATA,
+    REPORT_FORMATS,
+    REPORT_PROFILES,
+    ReportError,
+    active_retention,
+    build_report,
+    load_controls,
+    resolve_evidence_store,
+)
+from agentspm.report.json import render_json
+from agentspm.report.md import render_md
+from agentspm.report.redact import (
+    Pseudonymizer,
+    RedactionError,
+    assert_no_personal_identifiers,
+    configure_logging,
+    load_or_create_key,
+    redact_structure,
+    resolve_pseudo_key_path,
+)
+from agentspm.report.sarif import render_sarif
+
+log = structlog.get_logger(__name__)
+
+ENV_CONFIG = "AGENTSPM_CONFIG"
+ENV_DB = "AGENTSPM_DB"
+
+DEFAULT_DB = "agentspm.sqlite"
+_CONFIG_FALLBACKS = ("agentspm.yaml", "deploy/agentspm.example.yaml")
+#: Ten z fallbacku, ktery je soucasti repa a nikdy neni provozni konfiguraci.
+_EXAMPLE_CONFIG = "deploy/agentspm.example.yaml"
+
+EXIT_ERROR = 1
+EXIT_CONFIG = 2
+
+MOCK_COLLECTOR = "mock-gateway"
+
+app = typer.Typer(
+    name="agentspm",
+    help="Agent security posture: collect, evaluate against the policy pack, report.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--config",
+        envvar=ENV_CONFIG,
+        help="Deployment YAML (default: ./agentspm.yaml, then the example config).",
+    ),
+]
+DbOption = Annotated[
+    Path | None,
+    typer.Option("--db", envvar=ENV_DB, help="SQLite graph database path."),
+]
+
+
+def _fail(message: str, exit_code: int = EXIT_ERROR) -> typer.Exit:
+    typer.echo(f"error: {message}", err=True)
+    return typer.Exit(exit_code)
+
+
+def _load_cli_config(config_opt: Path | None) -> tuple[dict[str, Any], Path | None]:
+    """Resolve and load the deployment config; a missing default is fine."""
+    path: Path | None
+    if config_opt is not None:
+        if not config_opt.is_file():
+            raise _fail(f"config file not found: {config_opt}", EXIT_CONFIG)
+        path = config_opt
+    else:
+        path = next(
+            (Path(c) for c in _CONFIG_FALLBACKS if Path(c).is_file()), None
+        )
+    if path is None:
+        return {}, None
+    try:
+        return load_config(path), path
+    except (CollectorConfigError, OSError, ValueError) as exc:
+        raise _fail(f"cannot load config {path}: {exc}", EXIT_CONFIG) from exc
+
+
+def _db_path(db_opt: Path | None, config: Mapping[str, Any]) -> Path:
+    if db_opt is not None:
+        return db_opt
+    configured = config.get("database")
+    if isinstance(configured, str) and configured:
+        return Path(configured)
+    return Path(DEFAULT_DB)
+
+
+def _freshness_path(db_path: Path) -> Path:
+    return db_path.with_suffix(".freshness.json")
+
+
+@app.callback()
+def _main() -> None:
+    configure_logging()
+
+
+# -- scan ---------------------------------------------------------------------
+
+
+def _build_selected_collectors(
+    names: list[str], config: Mapping[str, Any]
+) -> list[Collector]:
+    registry = collector_registry()
+    sections_raw = config.get("collectors")
+    sections = sections_raw if isinstance(sections_raw, Mapping) else {}
+    collectors: list[Collector] = []
+    for name in names:
+        factory = registry.get(name)
+        if factory is None:
+            raise _fail(
+                f"unknown collector {name!r}; registered: "
+                f"{', '.join(sorted(registry))}",
+                EXIT_CONFIG,
+            )
+        section_raw = sections.get(name)
+        section = dict(section_raw) if isinstance(section_raw, Mapping) else {}
+        try:
+            collectors.append(factory(section, dict(os.environ)))
+        except CollectorConfigError as exc:
+            raise _fail(str(exc), EXIT_CONFIG) from exc
+    return collectors
+
+
+@app.command()
+def scan(
+    collector: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--collector",
+            help="Run only this collector (repeatable); default: all enabled in the config.",
+        ),
+    ] = None,
+    config: ConfigOption = None,
+    db: DbOption = None,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Exit non-zero when any collector failed, degraded to partial, "
+            "or dropped documents.",
+        ),
+    ] = False,
+) -> None:
+    """Collect -> validate -> merge -> derive into the SQLite graph."""
+    cfg, _ = _load_cli_config(config)
+    database = _db_path(db, cfg)
+    store = GraphStore(database)
+
+    if collector:
+        collectors = _build_selected_collectors(list(collector), cfg)
+    else:
+        try:
+            collectors = build_enabled_collectors(cfg)
+        except CollectorConfigError as exc:
+            raise _fail(str(exc), EXIT_CONFIG) from exc
+        if not collectors:
+            typer.echo(
+                "no collectors enabled in the config and none selected via "
+                "--collector; nothing was collected",
+                err=True,
+            )
+
+    outcomes = run_collectors(store, collectors)
+    events = [event for outcome in outcomes for event in outcome.events]
+    derive_result = derive(store, events)
+
+    scan_id = str(uuid.uuid4())
+    scan_time = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    collectors_meta = {
+        outcome.collector: {
+            "status": outcome.status,
+            "documents": outcome.documents,
+            "dropped": outcome.dropped,
+            "warnings": list(outcome.warnings),
+        }
+        for outcome in outcomes
+    }
+    dropped_total = sum(outcome.dropped for outcome in outcomes)
+    dropped_by_collector = {
+        outcome.collector: outcome.dropped for outcome in outcomes if outcome.dropped
+    }
+    synthetic = MOCK_COLLECTOR in {c.name for c in collectors} or (
+        MOCK_COLLECTOR in store.collectors_with_contributions()
+    )
+
+    store.set_meta(META_SCAN_ID, scan_id)
+    store.set_meta(META_SCAN_TIME, scan_time)
+    store.set_meta_json(META_SCAN_COLLECTORS, collectors_meta)
+    store.set_meta_json(
+        META_DROPPED_DOCUMENTS,
+        {"total": dropped_total, "by_collector": dropped_by_collector},
+    )
+    store.set_meta(META_SYNTHETIC_DATA, "true" if synthetic else "false")
+
+    freshness = {
+        "scan_id": scan_id,
+        "scan_time": scan_time,
+        "graph_hash": derive_result.graph_hash,
+        "collectors": collectors_meta,
+    }
+    freshness_path = _freshness_path(database)
+    freshness_path.write_text(
+        json.dumps(freshness, indent=2, sort_keys=True) + "\n", encoding="utf-8"
+    )
+
+    assets_total = len(store.list_asset_rows())
+    for outcome in outcomes:
+        typer.echo(
+            f"collector {outcome.collector}: {outcome.status} "
+            f"({outcome.documents} documents, {outcome.dropped} dropped)"
+        )
+    typer.echo(
+        f"scan {scan_id}: {assets_total} assets in graph, "
+        f"graph_hash {derive_result.graph_hash[:16]}…, freshness {freshness_path}"
+    )
+
+    if assets_total == 0:
+        raise _fail("scan produced an empty graph (0 assets)")
+    if strict:
+        degraded = [
+            outcome.collector
+            for outcome in outcomes
+            if outcome.status in ("failed", "partial") or outcome.dropped
+        ]
+        if degraded:
+            raise _fail(
+                "--strict: degraded collectors: " + ", ".join(sorted(degraded))
+            )
+
+
+# -- evaluate -------------------------------------------------------------------
+
+
+@app.command()
+def evaluate(
+    config: ConfigOption = None,
+    db: DbOption = None,
+) -> None:
+    """Evaluate the graph with the pinned OPA binary (hard fail on any error)."""
+    cfg, _ = _load_cli_config(config)
+    store = GraphStore(_db_path(db, cfg))
+    try:
+        result = run_evaluate(store, cfg)
+    except EvaluateError as exc:
+        raise _fail(str(exc)) from exc
+    typer.echo(
+        f"evaluate: {result.findings_stored} findings stored "
+        f"({result.findings_dropped} dropped by validation), "
+        f"policy pack {result.policy_pack_version}, opa {result.opa_path}"
+    )
+
+
+# -- report ---------------------------------------------------------------------
+
+
+def _render(
+    report_model: dict[str, Any],
+    fmt: str,
+    controls: list[dict[str, Any]] | None,
+) -> str:
+    if fmt == "md":
+        return render_md(report_model, controls)
+    if fmt == "json":
+        return render_json(report_model)
+    if controls is None:
+        raise _fail("SARIF output needs controls.yaml (policy pack not found)")
+    return render_sarif(report_model, controls)
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return False
+    return True
+
+
+@app.command()
+def report(
+    fmt: Annotated[
+        str, typer.Option("--format", help="Output format: md, json or sarif.")
+    ] = "md",
+    profile: Annotated[
+        str,
+        typer.Option(
+            "--profile",
+            help="redacted (default, pseudonymized) or full (evidence store only).",
+        ),
+    ] = "redacted",
+    out: Annotated[Path | None, typer.Option("--out", help="Output path.")] = None,
+    config: ConfigOption = None,
+    db: DbOption = None,
+) -> None:
+    """Render the posture report (redacted by default)."""
+    if fmt not in REPORT_FORMATS:
+        raise _fail(f"unknown format {fmt!r} (use md, json or sarif)", EXIT_CONFIG)
+    if profile not in REPORT_PROFILES:
+        raise _fail(f"unknown profile {profile!r} (use redacted or full)", EXIT_CONFIG)
+    cfg, _ = _load_cli_config(config)
+    store = GraphStore(_db_path(db, cfg))
+    try:
+        report_model = build_report(store, cfg, profile=profile)
+    except ReportError as exc:
+        raise _fail(str(exc)) from exc
+
+    controls: list[dict[str, Any]] | None
+    try:
+        controls = load_controls(find_policies_dir(cfg))
+    except (EvaluateError, ReportError) as exc:
+        if fmt == "sarif":
+            raise _fail(f"SARIF needs the policy pack metadata: {exc}") from exc
+        controls = None
+
+    evidence_store = resolve_evidence_store(cfg)
+    extension = {"md": "md", "json": "json", "sarif": "sarif"}[fmt]
+
+    if profile == "full":
+        # The full profile NEVER leaves the evidence store (GAP-GDPR-03).
+        if evidence_store is None:
+            raise _fail(
+                "full profile requires an evidence store (set evidence_store "
+                "in the config or AGENTSPM_EVIDENCE_STORE)"
+            )
+        target = (
+            out
+            if out is not None
+            else evidence_store / "reports" / f"agentspm-report-full.{extension}"
+        )
+        if not _is_within(target, evidence_store):
+            raise _fail(
+                f"refusing to write a full-profile report outside the evidence "
+                f"store ({evidence_store}); target was {target}"
+            )
+        rendered = _render(report_model, fmt, controls)
+    else:
+        target = out if out is not None else Path(f"agentspm-report.{extension}")
+        key_path = resolve_pseudo_key_path(evidence_store)
+        if key_path is None:
+            raise _fail(
+                "redacted profile needs the pseudonymization key: set "
+                "AGENTSPM_PSEUDO_KEY_PATH or configure the evidence store "
+                "(evidence_store / AGENTSPM_EVIDENCE_STORE)"
+            )
+        pseudo = Pseudonymizer(load_or_create_key(key_path))
+        report_model = redact_structure(report_model, pseudo)
+        rendered = _render(report_model, fmt, controls)
+        try:
+            assert_no_personal_identifiers(rendered)
+        except RedactionError as exc:
+            raise _fail(str(exc)) from exc
+        # alias -> value mapping is personal data: evidence store only (RP-05).
+        pseudo.write_mapping(key_path.parent)
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(rendered, encoding="utf-8")
+    if profile == "full":
+        target.parent.chmod(0o700)
+        target.chmod(0o600)
+    typer.echo(f"report written: {target} (format {fmt}, profile {profile})")
+
+
+# -- export ---------------------------------------------------------------------
+
+
+@app.command()
+def export(
+    encrypt: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--encrypt",
+            help="age recipient as age:<recipient> (repeatable; >= 2 required).",
+        ),
+    ] = None,
+    out: Annotated[
+        Path | None, typer.Option("--out", help="Output path for the .tar.age snapshot.")
+    ] = None,
+    config: ConfigOption = None,
+    db: DbOption = None,
+) -> None:
+    """Write an age-encrypted snapshot (database + reports) — >= 2 recipients."""
+    cfg, _ = _load_cli_config(config)
+    recipients: list[str] = []
+    for entry in encrypt or []:
+        if not entry.startswith("age:"):
+            raise _fail(
+                f"--encrypt expects age:<recipient>, got {entry!r}", EXIT_CONFIG
+            )
+        value = entry[len("age:") :]
+        if value and value not in recipients:
+            recipients.append(value)
+    for value in age_recipients_from_config(cfg):
+        if value not in recipients:
+            recipients.append(value)
+    if len(recipients) < MIN_AGE_RECIPIENTS:
+        raise _fail(
+            f"export refused: {len(recipients)} age recipient(s) provided, "
+            f"at least {MIN_AGE_RECIPIENTS} required (a single lost key must "
+            "not strand the evidence)"
+        )
+
+    age_path = resolve_age_path(dict(os.environ))
+    if age_path is None:
+        raise _fail(
+            "age binary not found (ASSUM-08: the export uses the system age "
+            "binary — install age or set AGENTSPM_AGE_PATH)"
+        )
+
+    database = _db_path(db, cfg)
+    if not database.is_file():
+        raise _fail(f"database not found: {database} — run `agentspm scan` first")
+    evidence_store = resolve_evidence_store(cfg)
+    if out is not None:
+        target = out
+    elif evidence_store is not None:
+        target = evidence_store / "exports" / "agentspm-export.tar.age"
+    else:
+        raise _fail(
+            "no --out given and no evidence store configured for the default "
+            "export location"
+        )
+
+    members: list[tuple[Path, str]] = [(database, f"db/{database.name}")]
+    freshness_path = _freshness_path(database)
+    if freshness_path.is_file():
+        members.append((freshness_path, f"db/{freshness_path.name}"))
+    if evidence_store is not None:
+        reports_dir = evidence_store / "reports"
+        if reports_dir.is_dir():
+            members.extend(
+                (path, f"reports/{path.relative_to(reports_dir)}")
+                for path in sorted(reports_dir.rglob("*"))
+                if path.is_file()
+            )
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if evidence_store is not None and _is_within(target, evidence_store):
+        target.parent.chmod(0o700)
+    with tempfile.TemporaryDirectory(prefix="agentspm-export-") as tmp:
+        tar_path = Path(tmp) / "snapshot.tar"
+        with tarfile.open(tar_path, "w") as archive:
+            for source, arcname in members:
+                archive.add(source, arcname=arcname)
+        argv = [str(age_path)]
+        for recipient in recipients:
+            argv += ["-r", recipient]
+        argv += ["-o", str(target), str(tar_path)]
+        completed = subprocess.run(argv, capture_output=True, text=True)  # no shell
+        if completed.returncode != 0:
+            raise _fail(f"age encryption failed: {completed.stderr.strip()}")
+    target.chmod(0o600)
+    typer.echo(
+        f"export written: {target} ({len(members)} file(s), "
+        f"{len(recipients)} age recipients)"
+    )
+
+
+# -- doctor ---------------------------------------------------------------------
+
+
+# -- purge ----------------------------------------------------------------------
+
+
+def _parse_older_than(value: str) -> int:
+    """``90d`` / ``90`` -> days; anything else is a config error."""
+    text = value.strip().lower()
+    if text.endswith("d"):
+        text = text[:-1]
+    if not text.isdigit():
+        raise _fail(
+            f"invalid --older-than {value!r}: use a day count like 90 or 90d",
+            EXIT_CONFIG,
+        )
+    return int(text)
+
+
+@app.command()
+def purge(
+    older_than: Annotated[
+        str | None,
+        typer.Option(
+            "--older-than",
+            help="Age threshold in days (e.g. 90d). Default: retention.raw_days "
+            "from the config (the same number the report header prints).",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Count what would be deleted; delete nothing."),
+    ] = False,
+    config: ConfigOption = None,
+    db: DbOption = None,
+) -> None:
+    """Enforce the declared retention: delete graph rows and full-profile
+    reports older than the threshold (GAP-GDPR-08).
+
+    Scope: the graph database and ``<evidence_store>/reports/``. NOT covered:
+    redacted reports written outside the evidence store (the tool cannot know
+    where they live) and the pseudonymization key/mapping (deleting the mapping
+    would break linkability of reports still within retention). Rows without a
+    parseable timestamp are never deleted. A real purge writes an enforcement
+    marker into ``meta`` (key ``purge:last``).
+    """
+    from agentspm.purge import (
+        purge_report_files,
+        purge_store,
+        write_purge_marker,
+    )
+
+    cfg, _ = _load_cli_config(config)
+    retention = active_retention(cfg)
+    days = _parse_older_than(older_than) if older_than is not None else retention["raw_days"]
+    cutoff = datetime.now(tz=UTC) - timedelta(days=days)
+
+    store = GraphStore(_db_path(db, cfg))
+    result = purge_store(store, cutoff, dry_run=dry_run)
+    result.report_files = purge_report_files(
+        resolve_evidence_store(cfg), cutoff, dry_run=dry_run
+    )
+
+    verb = "would delete" if dry_run else "deleted"
+    typer.echo(
+        f"purge ({'dry run, ' if dry_run else ''}older than {days}d, "
+        f"cutoff {result.cutoff}):"
+    )
+    typer.echo(
+        f"  rows {verb}: assets={result.assets} contributions={result.contributions} "
+        f"edges={result.edges} provenance={result.provenance} findings={result.findings}"
+    )
+    typer.echo(f"  report files {verb}: {len(result.report_files)}")
+    for path in result.report_files:
+        typer.echo(f"    {path}")
+    if not dry_run:
+        write_purge_marker(store, result)
+        typer.echo("  enforcement marker written (meta key purge:last)")
+
+
+@app.command()
+def doctor(config: ConfigOption = None) -> None:
+    """Preflight checks: OPA pin, capabilities, permissions, age, credentials."""
+    cfg, config_path = _load_cli_config(config)
+    is_example = config is None and config_path is not None and (
+        config_path.as_posix() == _EXAMPLE_CONFIG
+    )
+    results = run_doctor(cfg, config_path=config_path, config_is_example=is_example)
+    for result in results:
+        typer.echo(str(result))
+    failures = [result for result in results if result.status == "fail"]
+    if has_failures(results):
+        typer.echo(
+            f"doctor: {len(failures)} check(s) failed "
+            f"({', '.join(result.name for result in failures)})",
+            err=True,
+        )
+        raise typer.Exit(EXIT_ERROR)
+    typer.echo("doctor: all checks passed")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()