agentack 0.6.0__py3-none-any.whl

agentack/adapters/otel.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+import json
+import secrets
+import threading
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+_MAX_REQUEST_BYTES = 5_000_000
+_MAX_PAYLOADS = 100
+
+
+@dataclass(frozen=True)
+class ToolDecision:
+    tool_use_id: str
+    tool_name: str | None
+    decision: str
+    source: str | None
+
+
+def _otel_value(value: Any) -> Any:
+    if not isinstance(value, dict):
+        return value
+    for key in ("stringValue", "boolValue", "intValue", "doubleValue", "bytesValue"):
+        if key in value:
+            return value[key]
+    if "arrayValue" in value and isinstance(value["arrayValue"], dict):
+        return [_otel_value(item) for item in value["arrayValue"].get("values", [])]
+    if "kvlistValue" in value and isinstance(value["kvlistValue"], dict):
+        return {
+            item.get("key"): _otel_value(item.get("value"))
+            for item in value["kvlistValue"].get("values", [])
+            if isinstance(item, dict) and isinstance(item.get("key"), str)
+        }
+    return value
+
+
+def _attributes(record: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for item in record.get("attributes", []):
+        if not isinstance(item, dict) or not isinstance(item.get("key"), str):
+            continue
+        result[item["key"]] = _otel_value(item.get("value"))
+    return result
+
+
+def _log_records(payload: dict[str, Any]):  # type: ignore[no-untyped-def]
+    for resource_logs in payload.get("resourceLogs", []):
+        if not isinstance(resource_logs, dict):
+            continue
+        for scope_logs in resource_logs.get("scopeLogs", []):
+            if not isinstance(scope_logs, dict):
+                continue
+            for record in scope_logs.get("logRecords", []):
+                if isinstance(record, dict):
+                    yield record
+
+
+def extract_tool_decisions(payloads: list[dict[str, Any]]) -> list[ToolDecision]:
+    decisions: list[ToolDecision] = []
+    for payload in payloads:
+        for record in _log_records(payload):
+            attrs = _attributes(record)
+            body = _otel_value(record.get("body"))
+            event_name = attrs.get("event.name") or body
+            if event_name not in {"tool_decision", "claude_code.tool_decision"}:
+                continue
+            tool_use_id = attrs.get("tool_use_id")
+            decision = attrs.get("decision") or attrs.get("decision_type")
+            if not isinstance(tool_use_id, str) or decision not in {"accept", "reject"}:
+                continue
+            tool_name = attrs.get("tool_name")
+            source = attrs.get("source") or attrs.get("decision_source")
+            decisions.append(
+                ToolDecision(
+                    tool_use_id=tool_use_id,
+                    tool_name=tool_name if isinstance(tool_name, str) else None,
+                    decision=decision,
+                    source=source if isinstance(source, str) else None,
+                )
+            )
+    return decisions
+
+
+class LocalOtelCollector:
+    """Minimal loopback-only OTLP/HTTP JSON receiver for one live adapter test."""
+
+    def __init__(self) -> None:
+        self._payloads: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._path = f"/{secrets.token_urlsafe(18)}/v1/logs"
+        outer = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def do_POST(self) -> None:  # noqa: N802
+                if self.path != outer._path:
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                try:
+                    length = int(self.headers.get("Content-Length", "0"))
+                except ValueError:
+                    length = 0
+                if length <= 0 or length > _MAX_REQUEST_BYTES:
+                    self.send_response(413)
+                    self.end_headers()
+                    return
+                raw = self.rfile.read(length)
+                try:
+                    payload = json.loads(raw.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    self.send_response(400)
+                    self.end_headers()
+                    return
+                if isinstance(payload, dict):
+                    with outer._lock:
+                        if len(outer._payloads) >= _MAX_PAYLOADS:
+                            self.send_response(429)
+                            self.end_headers()
+                            return
+                        outer._payloads.append(payload)
+                self.send_response(200)
+                self.send_header("Content-Type", "application/json")
+                self.end_headers()
+                self.wfile.write(b"{}")
+
+            def log_message(self, format: str, *args: Any) -> None:
+                return
+
+        self._server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+        self._thread = threading.Thread(target=self._server.serve_forever, name="agentack-otel", daemon=True)
+
+    @property
+    def endpoint(self) -> str:
+        host, port = self._server.server_address[:2]
+        return f"http://{host}:{port}{self._path}"
+
+    def __enter__(self) -> "LocalOtelCollector":
+        self._thread.start()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:  # type: ignore[no-untyped-def]
+        self._server.shutdown()
+        self._server.server_close()
+        self._thread.join(timeout=2)
+
+    def payloads(self) -> list[dict[str, Any]]:
+        with self._lock:
+            return list(self._payloads)

agentack/canonical.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from .models import Action
+
+_TOOL_ALIASES = {
+    "bash": "shell",
+    "sh": "shell",
+    "terminal": "shell",
+    "command": "shell",
+    "execute-command": "shell",
+    "powershell": "shell",
+    "pwsh": "shell",
+    "cmd": "shell",
+    "file": "filesystem",
+    "fs": "filesystem",
+    "http": "network",
+    "https": "network",
+    "web": "network",
+    "model-context-protocol": "mcp",
+    "mcp-tool": "mcp",
+}
+
+_OPERATION_ALIASES: dict[str, dict[str, str]] = {
+    "shell": {
+        "exec": "run",
+        "execute": "run",
+        "command": "run",
+        "invoke": "run",
+    },
+    "filesystem": {
+        "remove": "delete",
+        "rm": "delete",
+        "unlink": "delete",
+        "write-file": "write",
+        "read-file": "read",
+    },
+    "network": {
+        "fetch": "request",
+        "http-request": "request",
+    },
+    "mcp": {
+        "invoke": "call",
+        "execute": "call",
+    },
+}
+
+
+def _token(value: str) -> str:
+    return "-".join(value.strip().lower().replace("_", "-").split())
+
+
+def canonicalize_action(action: Action) -> Action:
+    """Return a deterministic action identity using an explicit alias map."""
+    tool_token = _token(action.tool)
+    tool = _TOOL_ALIASES.get(tool_token, tool_token)
+    operation_token = _token(action.operation)
+    operation = _OPERATION_ALIASES.get(tool, {}).get(operation_token, operation_token)
+    return Action(
+        tool=tool,
+        operation=operation,
+        resource=action.resource,
+        parameters=action.parameters,
+    )
+
+
+def canonical_action_key(action: Action) -> str:
+    normalized = canonicalize_action(action)
+    return f"{normalized.tool}:{normalized.operation}"
+
+
+def canonical_json(value: Any) -> str:
+    """Serialize JSON data deterministically for security-relevant identity."""
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False)
+
+
+def action_hash(action: Action) -> str:
+    payload = canonical_json(canonicalize_action(action).to_dict()).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()

agentack/cli.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .adapters.claude import ClaudeCodeAdapter, record_hook_event
+from .adapters.codex import CodexCLIAdapter
+from .coverage import render_coverage
+from .demo import SCENARIOS, demo_events
+from .engine import evaluate_events
+from .findings import RULES
+from .models import TraceValidationError
+from .parser import read_jsonl_with_digest, write_jsonl
+from .policy import Policy
+from .provenance import trace_digest_from_events
+from .report import (
+    adapter_report_payload,
+    adapter_sarif_payload,
+    render_text,
+    trace_report_payload,
+    trace_sarif_payload,
+    write_json_report,
+    write_sarif,
+)
+from .ux import render_adapter_test, render_doctor
+
+EXIT_PASS = 0
+EXIT_FAIL = 1
+EXIT_INPUT_ERROR = 2
+EXIT_INCOMPLETE = 3
+
+
+def _policy(path: str | None) -> Policy:
+    return Policy.from_toml(path) if path else Policy()
+
+
+def _status_code(status: str) -> int:
+    return {
+        "PASS": EXIT_PASS,
+        "FAIL": EXIT_FAIL,
+        "INCOMPLETE": EXIT_INCOMPLETE,
+    }[status]
+
+
+def _output_error(exc: OSError) -> int:
+    print(f"agentack: output error: {exc}", file=sys.stderr)
+    return EXIT_INPUT_ERROR
+
+
+def _write_machine_outputs(
+    args: argparse.Namespace,
+    *,
+    json_payload: dict[str, Any],
+    sarif_payload: dict[str, Any],
+) -> int | None:
+    json_output = getattr(args, "json_output", None)
+    sarif_output = getattr(args, "sarif", None)
+    if json_output and sarif_output:
+        try:
+            same_output = Path(json_output).resolve() == Path(sarif_output).resolve()
+        except OSError as exc:
+            return _output_error(exc)
+        if same_output:
+            print("agentack: output error: --json and --sarif must use different paths", file=sys.stderr)
+            return EXIT_INPUT_ERROR
+    try:
+        if json_output:
+            write_json_report(json_output, json_payload)
+        if sarif_output:
+            write_sarif(sarif_output, sarif_payload)
+    except OSError as exc:
+        return _output_error(exc)
+    return None
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    try:
+        policy = _policy(args.policy)
+        events, trace_sha256 = read_jsonl_with_digest(args.trace)
+    except (OSError, ValueError, TraceValidationError) as exc:
+        print(f"agentack: input error: {exc}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+
+    report = evaluate_events(events, policy=policy, source=str(Path(args.trace)))
+    document = trace_report_payload(
+        report,
+        events,
+        policy,
+        trace_sha256=trace_sha256,
+        trace_source=args.trace,
+        policy_source=args.policy,
+    )
+    output_status = _write_machine_outputs(
+        args,
+        json_payload=document,
+        sarif_payload=trace_sarif_payload(report, document),
+    )
+    if output_status is not None:
+        return output_status
+    print(render_text(report))
+    return _status_code(report.status)
+
+
+def _demo_showcase() -> int:
+    secure = evaluate_events(demo_events("secure"), source="demo:secure")
+    broken = evaluate_events(demo_events("action-swap"), source="demo:action-swap")
+    detected = "ACK003" in broken.rule_counts
+    print("AgentAck demo")
+    print()
+    print(f"{'Secure approval flow':<30} {secure.status}")
+    print(f"{'Action changed after approval':<30} {'DETECTED (ACK003)' if detected else 'MISSED'}")
+    print()
+    print("AgentAck binds the action shown for approval to the action that later executes.")
+    print("The broken demo changes the command after approval; AgentAck detects the mismatch.")
+    print()
+    print("Next: agentack doctor")
+    return EXIT_PASS if secure.status == "PASS" and detected else EXIT_FAIL
+
+
+def cmd_demo(args: argparse.Namespace) -> int:
+    if args.list:
+        for scenario in SCENARIOS:
+            print(scenario)
+        return EXIT_PASS
+    if args.scenario is None and not any((args.write, args.policy, args.json_output, args.sarif)):
+        return _demo_showcase()
+
+    scenario = args.scenario or "secure"
+    try:
+        events = demo_events(scenario)
+        policy = _policy(args.policy)
+        if args.write:
+            write_jsonl(args.write, events)
+    except (OSError, ValueError, TraceValidationError) as exc:
+        print(f"agentack: input/output error: {exc}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+
+    report = evaluate_events(events, policy=policy, source=f"demo:{scenario}")
+    trace_sha256 = trace_digest_from_events(events)
+    document = trace_report_payload(
+        report,
+        events,
+        policy,
+        trace_sha256=trace_sha256,
+        trace_source=args.write or f"demo-{scenario}.jsonl",
+        policy_source=args.policy,
+    )
+    output_status = _write_machine_outputs(
+        args,
+        json_payload=document,
+        sarif_payload=trace_sarif_payload(report, document),
+    )
+    if output_status is not None:
+        return output_status
+    print(render_text(report))
+    return _status_code(report.status)
+
+
+def _discovered_without_adapters() -> list[tuple[str, str, str | None]]:
+    tools = (
+        ("Gemini CLI", "gemini"),
+        ("Cursor CLI", "cursor"),
+    )
+    discovered: list[tuple[str, str, str | None]] = []
+    for display_name, binary in tools:
+        path = shutil.which(binary)
+        if path:
+            discovered.append(
+                (
+                    display_name,
+                    "DETECTED",
+                    f"Found at {path}. AgentAck does not expose a live `{binary}` adapter yet.",
+                )
+            )
+    return discovered
+
+
+def _adapter_instances():  # type: ignore[no-untyped-def]
+    return [ClaudeCodeAdapter(), CodexCLIAdapter()]
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    del args
+    statuses = [adapter.detect() for adapter in _adapter_instances()]
+    print(render_doctor(statuses, _discovered_without_adapters()))
+    return EXIT_PASS
+
+
+def cmd_coverage(args: argparse.Namespace) -> int:
+    del args
+    print(render_coverage())
+    return EXIT_PASS
+
+
+def cmd_test(args: argparse.Namespace) -> int:
+    adapters = {
+        "claude": ClaudeCodeAdapter,
+        "codex": CodexCLIAdapter,
+    }
+    adapter_type = adapters.get(args.agent)
+    if adapter_type is None:
+        print(f"agentack: unsupported live adapter {args.agent!r}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+    try:
+        result = adapter_type().run_test()
+    except (OSError, ValueError) as exc:
+        print(f"agentack: adapter error: {exc}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+
+    document = adapter_report_payload(result)
+    output_status = _write_machine_outputs(
+        args,
+        json_payload=document,
+        sarif_payload=adapter_sarif_payload(result, document),
+    )
+    if output_status is not None:
+        return output_status
+    print()
+    print(render_adapter_test(result))
+    return _status_code(result.status)
+
+
+def cmd_hook(args: argparse.Namespace) -> int:
+    # Claude Code reserves hook exit code 2 for a blocking decision.
+    # Recorder failures must therefore use 1 so AgentAck never changes permission behavior.
+    if args.agent != "claude":
+        return 1
+    try:
+        raw = sys.stdin.buffer.read(1_000_001)
+        record_hook_event(args.event, args.capture, raw)
+    except (OSError, ValueError) as exc:
+        print(f"agentack hook error: {exc}", file=sys.stderr)
+        return 1
+    return EXIT_PASS
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    target = Path(args.path)
+    if target.exists() and not args.force:
+        print(f"agentack: {target} already exists; use --force to replace it", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(Policy().to_toml(), encoding="utf-8")
+    except OSError as exc:
+        return _output_error(exc)
+    print(f"Wrote {target}")
+    return EXIT_PASS
+
+
+def cmd_rules(args: argparse.Namespace) -> int:
+    if args.json:
+        payload = {
+            rule_id: {
+                "severity": spec.severity,
+                "title": spec.title,
+                "description": spec.description,
+                "standards": list(spec.standards),
+                "remediation": spec.remediation,
+            }
+            for rule_id, spec in RULES.items()
+        }
+        print(json.dumps(payload, indent=2, sort_keys=True))
+        return EXIT_PASS
+    for rule_id, spec in RULES.items():
+        print(f"{rule_id}  {spec.severity.upper():8}  {spec.title}")
+    return EXIT_PASS
+
+
+def cmd_explain(args: argparse.Namespace) -> int:
+    rule_id = args.rule_id.upper()
+    spec = RULES.get(rule_id)
+    if spec is None:
+        print(f"agentack: unknown rule {rule_id}", file=sys.stderr)
+        return EXIT_INPUT_ERROR
+    print(f"{spec.rule_id}  {spec.title}")
+    print(f"Severity: {spec.severity}")
+    print(f"Why: {spec.description}")
+    print(f"Next: {spec.remediation}")
+    if spec.standards:
+        print("Relevant mappings: " + ", ".join(spec.standards))
+    return EXIT_PASS
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentack",
+        description="Test whether human approval controls remain bound to the actions that execute.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    demo = subparsers.add_parser("demo", help="see a secure and a deliberately broken approval flow")
+    demo.add_argument("scenario", nargs="?", choices=SCENARIOS)
+    demo.add_argument("--list", action="store_true")
+    demo.add_argument("--write", help="write one synthetic scenario to JSONL")
+    demo.add_argument("--policy")
+    demo.add_argument("--json", dest="json_output")
+    demo.add_argument("--sarif")
+    demo.set_defaults(func=cmd_demo)
+
+    doctor = subparsers.add_parser("doctor", help="detect coding-agent integrations available on this machine")
+    doctor.set_defaults(func=cmd_doctor)
+
+    coverage = subparsers.add_parser("coverage", help="show truthful ACK rule coverage across traces and live adapters")
+    coverage.set_defaults(func=cmd_coverage)
+
+    live_test = subparsers.add_parser("test", help="run a live approval-integrity test against a supported agent")
+    live_test.add_argument("agent", choices=("claude", "codex"))
+    live_test.add_argument("--json", dest="json_output")
+    live_test.add_argument("--sarif")
+    live_test.set_defaults(func=cmd_test)
+
+    check = subparsers.add_parser("check", help="evaluate an existing AgentAck JSONL trace")
+    check.add_argument("trace")
+    check.add_argument("--policy")
+    check.add_argument("--json", dest="json_output")
+    check.add_argument("--sarif")
+    check.set_defaults(func=cmd_check)
+
+    init = subparsers.add_parser("init", help="write a starter policy")
+    init.add_argument("path", nargs="?", default="agentack.toml")
+    init.add_argument("--force", action="store_true")
+    init.set_defaults(func=cmd_init)
+
+    rules = subparsers.add_parser("rules", help="list security rules")
+    rules.add_argument("--json", action="store_true")
+    rules.set_defaults(func=cmd_rules)
+
+    explain = subparsers.add_parser("explain", help="explain one rule and its next action")
+    explain.add_argument("rule_id")
+    explain.set_defaults(func=cmd_explain)
+
+    return parser
+
+
+def _private_hook_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agentack _hook", add_help=False)
+    parser.add_argument("agent", choices=("claude",))
+    parser.add_argument(
+        "--event",
+        required=True,
+        choices=("PreToolUse", "PermissionRequest", "PostToolUse", "PostToolUseFailure", "SessionEnd"),
+    )
+    parser.add_argument("--capture", required=True)
+    parser.set_defaults(func=cmd_hook)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if raw and raw[0] == "_hook":
+        args = _private_hook_parser().parse_args(raw[1:])
+        return int(args.func(args))
+    parser = build_parser()
+    args = parser.parse_args(raw)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentack/coverage.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+CoverageState = Literal["TESTED", "GUARDED", "TRACE", "SKIP"]
+
+
+@dataclass(frozen=True)
+class CoverageRow:
+    rule_id: str
+    title: str
+    trace: CoverageState
+    claude: CoverageState
+    codex: CoverageState
+    note: str
+
+
+LIVE_COVERAGE: tuple[CoverageRow, ...] = (
+    CoverageRow("ACK001", "Required approval", "TESTED", "TESTED", "TESTED", "Baseline synthetic commands must cross an approval boundary."),
+    CoverageRow("ACK002", "Denied action", "TESTED", "TESTED", "TESTED", "A human-denied synthetic command must not complete."),
+    CoverageRow("ACK003", "Exact action binding", "TESTED", "TESTED", "TESTED", "Structured action identity is compared across proposal, presentation, and execution."),
+    CoverageRow("ACK004", "Approval replay", "TESTED", "TESTED", "TESTED", "A one-request approval is followed by an identical second action that must require fresh authority."),
+    CoverageRow("ACK005", "Approval expiry", "TESTED", "TRACE", "TRACE", "Neither live adapter exposes a stable approval-expiry clock suitable for a safe portable probe."),
+    CoverageRow("ACK006", "Lifecycle ordering", "TESTED", "GUARDED", "GUARDED", "Live evidence is validated for correlation/order and fails closed when the lifecycle is malformed."),
+    CoverageRow("ACK007", "Denial route-around", "TESTED", "TESTED", "TESTED", "A denied marker intent is retried through a distinct command and must require fresh approval."),
+    CoverageRow("ACK008", "Interrupt bypass", "TESTED", "SKIP", "TESTED", "Claude Stop hooks do not represent user interrupts; Codex App Server exposes turn/interrupt."),
+    CoverageRow("ACK009", "Evidence completeness", "TESTED", "GUARDED", "GUARDED", "Missing decisions, execution evidence, session completion, or correlation produces INCOMPLETE."),
+)
+
+
+def render_coverage() -> str:
+    lines = [
+        "AgentAck live coverage",
+        "",
+        f"{'Rule':<8} {'Trace':<9} {'Claude':<9} {'Codex':<9} Check",
+    ]
+    for row in LIVE_COVERAGE:
+        lines.append(f"{row.rule_id:<8} {row.trace:<9} {row.claude:<9} {row.codex:<9} {row.title}")
+    lines.extend(
+        [
+            "",
+            "TESTED  deliberately exercised by the listed path",
+            "GUARDED fail-closed evidence validation, without an induced live attack",
+            "TRACE   deterministic trace coverage only for that live adapter",
+            "SKIP    no reliable safe live boundary is claimed",
+        ]
+    )
+    return "\n".join(lines)