handcuff 0.2.0__py3-none-any.whl

handcuff/capture/tree.py

@@ -0,0 +1,43 @@
+"""Process-tree tracker (AL-022).
+
+Maintains the live set of PIDs descended from a root PID by polling
+`psutil`. Short-lived processes that spawn and exit between polls are
+inherently missable with this approach (documented limitation) — the
+capture backend built on top of this is expected to emit `LOSS` for
+detected gaps.
+"""
+
+from __future__ import annotations
+
+import psutil
+
+
+class ProcessTreeTracker:
+    def __init__(self, root_pid: int) -> None:
+        self.root_pid = root_pid
+        self._pids: set[int] = set()
+
+    @property
+    def pids(self) -> set[int]:
+        return set(self._pids)
+
+    def refresh(self) -> tuple[set[int], set[int]]:
+        """Poll the system for descendants of root_pid. Returns
+        (added, removed) PID sets relative to the previous snapshot."""
+        current: set[int] = set()
+        if psutil.pid_exists(self.root_pid):
+            current.add(self.root_pid)
+            try:
+                root = psutil.Process(self.root_pid)
+                for child in root.children(recursive=True):
+                    current.add(child.pid)
+            except psutil.NoSuchProcess:
+                pass
+
+        added = current - self._pids
+        removed = self._pids - current
+        self._pids = current
+        return added, removed
+
+    def contains(self, pid: int) -> bool:
+        return pid in self._pids

handcuff/cli.py

@@ -0,0 +1,362 @@
+"""Handcuff CLI (Typer app). AL-001/AL-024.
+
+Commands implemented for the vertical slice: `watch`, `sessions`.
+Remaining commands are placeholders so `--help` lists the full surface
+described in the PRD/TRD; they raise NotImplementedError until their
+tickets land.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import UTC, datetime
+from pathlib import Path
+
+import typer
+
+from handcuff.banner import print_banner, should_show_banner
+from handcuff.config import DEFAULT_DB_PATH
+from handcuff.export.json_export import export_session_json
+from handcuff.runner import list_sessions, watch_command
+from handcuff.storage.db import connect
+
+app = typer.Typer(help="A dashcam for your AI agents.")
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    no_banner: bool = typer.Option(
+        False, "--no-banner", help="Skip the startup banner for this invocation."
+    ),
+) -> None:
+    """A dashcam for your AI agents."""
+    # The full welcome panel is a startup/session-entry thing (like
+    # Claude Code's splash), not something that should reprint on every
+    # one-shot command — showing it for `handcuff sessions`, `export`,
+    # etc. every single time floods the terminal with a large repeated
+    # panel (confirmed directly from a real screenshot: back-to-back
+    # invocations produced stacked, overlapping panel text). Only show
+    # it when entering the interactive dashboard (`tui`) or when
+    # `handcuff` is run bare with no subcommand.
+    show_for = {"tui", None}
+    if not no_banner and ctx.invoked_subcommand in show_for:
+        print_banner()
+
+
+@app.command()
+def watch(
+    command: list[str] = typer.Argument(..., help="Command to run and record, e.g. -- bash -c ..."),
+    label: str = typer.Option(None, help="Human-readable label for this session"),
+    quiet: bool = typer.Option(False, "--quiet", help="Headless: record with no UI"),
+    watch_path: list[str] = typer.Option(
+        None,
+        "--watch-path",
+        help="Directory to watch for file events (repeatable). Default: cwd + home.",
+    ),
+    enforce: bool = typer.Option(
+        False,
+        "--enforce",
+        help=(
+            "Real OS-level blocking: deny-ACL sensitive files under watch paths "
+            "(no admin needed) and, if elevated, block outbound network via "
+            "Windows Firewall except --allow-domain. See `handcuff doctor` for "
+            "what's actually active."
+        ),
+    ),
+    protect_path: list[str] = typer.Option(
+        None, "--protect-path", help="Extra path to scan for sensitive files under --enforce."
+    ),
+    allow_domain: list[str] = typer.Option(
+        None, "--allow-domain", help="Domain allowed through the firewall block (repeatable)."
+    ),
+    webhook_url: str = typer.Option(
+        None,
+        "--webhook-url",
+        help="Post a content-light JSON payload here when a critical alert fires. "
+        "HTTPS required (plain HTTP only allowed to localhost).",
+    ),
+    hash_content: bool = typer.Option(
+        False,
+        "--hash-content",
+        help="Record a SHA-256 of written file contents (files up to 1 MiB). "
+        "Only the hash is stored, never the content.",
+    ),
+) -> None:
+    """Launch COMMAND under observation; record process activity to a session."""
+    paths = [Path(p) for p in watch_path] if watch_path else None
+    protected = [Path(p) for p in protect_path] if protect_path else None
+    session_id = asyncio.run(
+        watch_command(
+            list(command),
+            label=label,
+            watch_paths=paths,
+            enforce=enforce,
+            protected_paths=protected,
+            allowed_domains=list(allow_domain) if allow_domain else None,
+            webhook_url=webhook_url,
+            hash_content=hash_content,
+        )
+    )
+    typer.echo(f"session {session_id} closed")
+    if enforce:
+        conn = connect(DEFAULT_DB_PATH)
+        marks = conn.execute(
+            "SELECT payload_json FROM events WHERE session_id=? AND kind='MARK'", (session_id,)
+        ).fetchall()
+        for m in marks:
+            typer.echo(f"  [enforce] {m['payload_json']}")
+
+
+@app.command()
+def sessions() -> None:
+    """List recorded sessions."""
+    rows = list_sessions()
+    if not rows:
+        typer.echo("no sessions recorded yet")
+        raise typer.Exit()
+    for row in rows:
+        started = datetime.fromtimestamp(row["started_at"] / 1000, tz=UTC).isoformat()
+        typer.echo(
+            f"{row['id']}  {row['status']:<24} {started}  {row['label'] or ''}  {row['target_cmd']}"
+        )
+
+
+@app.command()
+def attach(
+    pid: int,
+    label: str = typer.Option(None, help="Human-readable label for this session"),
+    duration: float = typer.Option(
+        None, "--duration", help="Stop recording after this many seconds (default: until pid exits)"
+    ),
+) -> None:
+    """Attach to an already-running process tree and record it until it exits."""
+    from handcuff.runner import attach_command
+
+    session_id = asyncio.run(attach_command(pid, label=label, duration_s=duration))
+    typer.echo(f"session {session_id} closed")
+
+
+@app.command()
+def tui(
+    session_id: str = typer.Argument(None, help="Session to watch (default: most recent)"),
+) -> None:
+    """Open the terminal dashboard: live event stream, alerts, process tree, stats."""
+    import time
+
+    from handcuff.tui.app import run_tui
+
+    if should_show_banner():
+        # Hold the banner briefly before Textual clears the screen and
+        # takes over — otherwise it flashes by unseen, since Textual's
+        # alt-screen switch happens almost immediately on run().
+        time.sleep(0.6)
+
+    run_tui(session_id=session_id)
+
+
+@app.command()
+def replay(
+    session_id: str,
+    to_alert: int = typer.Option(
+        None, "--to-alert", help="Jump straight to the Nth alert (1-indexed) and print it"
+    ),
+) -> None:
+    """Scrub through a past session.
+
+    Interactive by default: n=next, p=previous, a=next alert,
+    A=previous alert, q=quit. Pass --to-alert N for a non-interactive
+    jump-and-print (useful for scripting/CI).
+    """
+    from handcuff.replay import ReplaySession
+
+    conn = connect(DEFAULT_DB_PATH)
+    rs = ReplaySession(conn, session_id)
+    if rs.total == 0:
+        typer.echo("session has no events")
+        raise typer.Exit()
+
+    def render(ev) -> str:
+        marker = f" [ALERT: {', '.join(ev.alert_rule_ids)}]" if ev.alert_rule_ids else ""
+        return f"[{rs.cursor + 1}/{rs.total}] seq={ev.seq} {ev.kind}{marker}  {ev.payload}"
+
+    if to_alert is not None:
+        rs.cursor = 0
+        event = None
+        for _ in range(to_alert):
+            event = rs.next_alert()
+            if event is None:
+                typer.echo(f"only {rs.alert_count()} alert(s) in this session")
+                raise typer.Exit(code=1)
+        typer.echo(render(event))
+        return
+
+    typer.echo(render(rs.current()))
+    typer.echo("commands: n=next p=prev a=next-alert A=prev-alert q=quit")
+    while True:
+        try:
+            cmd = input("> ").strip()
+        except EOFError:
+            break
+        if cmd == "q":
+            break
+        elif cmd == "n":
+            ev = rs.step_forward()
+        elif cmd == "p":
+            ev = rs.step_backward()
+        elif cmd == "a":
+            ev = rs.next_alert() or rs.current()
+        elif cmd == "A":
+            ev = rs.prev_alert() or rs.current()
+        else:
+            typer.echo("unknown command")
+            continue
+        typer.echo(render(ev))
+
+
+@app.command()
+def export(
+    session_id: str,
+    format: str = typer.Option("json", help="Export format: json, md, or html"),
+    output: str = typer.Option(None, help="Output file path (default: <session_id>.<format>)"),
+) -> None:
+    """Export a session report."""
+    from handcuff.export.html_export import export_session_html
+    from handcuff.export.md_export import export_session_md
+
+    exporters = {"json": export_session_json, "md": export_session_md, "html": export_session_html}
+    if format not in exporters:
+        typer.echo(f"unknown format {format!r}; choose from: {', '.join(exporters)}")
+        raise typer.Exit(code=2)
+    conn = connect(DEFAULT_DB_PATH)
+    out_path = Path(output) if output else Path(f"{session_id}.{format}")
+    exporters[format](conn, session_id, out_path)
+    typer.echo(f"exported to {out_path}")
+
+
+@app.command()
+def verify(
+    session_id: str = typer.Argument(None, help="Session id to verify from the live DB"),
+    file: str = typer.Option(None, "--file", help="Verify a JSON export file instead"),
+) -> None:
+    """Re-validate a session's hash chain and signature."""
+    from handcuff.verify import verify_export_file, verify_session_db
+
+    if file:
+        result = verify_export_file(Path(file))
+    elif session_id:
+        conn = connect(DEFAULT_DB_PATH)
+        result = verify_session_db(conn, session_id)
+    else:
+        typer.echo("provide a session_id or --file")
+        raise typer.Exit(code=2)
+
+    typer.echo(f"chain: {'OK' if result.chain.ok else 'FAILED'}")
+    if not result.chain.ok:
+        typer.echo(f"  failed at seq={result.chain.failed_seq} reason={result.chain.reason}")
+    if result.signature_ok is not None:
+        typer.echo(f"signature: {'OK' if result.signature_ok else 'FAILED'}")
+
+    if not result.chain.ok or result.signature_ok is False:
+        raise typer.Exit(code=1)
+
+
+rules_app = typer.Typer(help="Manage alert rules / trust list.")
+trust_app = typer.Typer(help="Manage the trust allowlist (domains/paths/cmds).")
+rules_app.add_typer(trust_app, name="trust")
+app.add_typer(rules_app, name="rules")
+
+
+@trust_app.command("add")
+def trust_add(
+    kind: str = typer.Argument(..., help="domain|path|cmd"),
+    value: str = typer.Argument(...),
+) -> None:
+    """Add an entry to the trust list."""
+    from handcuff.rules.trust import add_trust
+
+    conn = connect(DEFAULT_DB_PATH)
+    add_trust(conn, kind, value)
+    typer.echo(f"trusted {kind}: {value}")
+
+
+@trust_app.command("list")
+def trust_list(kind: str = typer.Option(None, help="Filter by kind (domain|path|cmd)")) -> None:
+    """List trust list entries."""
+    from handcuff.rules.trust import list_trust
+
+    conn = connect(DEFAULT_DB_PATH)
+    entries = list_trust(conn, kind=kind)
+    if not entries:
+        typer.echo("no trust entries")
+        return
+    for e in entries:
+        typer.echo(f"{e.kind:<8} {e.value}")
+
+
+@trust_app.command("rm")
+def trust_rm(
+    kind: str = typer.Argument(..., help="domain|path|cmd"),
+    value: str = typer.Argument(...),
+) -> None:
+    """Remove an entry from the trust list."""
+    from handcuff.rules.trust import remove_trust
+
+    conn = connect(DEFAULT_DB_PATH)
+    removed = remove_trust(conn, kind, value)
+    typer.echo(f"removed: {removed}")
+
+
+config_app = typer.Typer(help="Show/edit configuration (~/.config/handcuff/config.yaml).")
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("list")
+def config_list() -> None:
+    """Show all config values (defaults merged with the config file)."""
+    from handcuff.config import DEFAULT_CONFIG_PATH, load_config
+
+    typer.echo(f"config file: {DEFAULT_CONFIG_PATH} (exists={DEFAULT_CONFIG_PATH.exists()})")
+    typer.echo(f"db path: {DEFAULT_DB_PATH}")
+    for k, v in load_config().items():
+        typer.echo(f"{k} = {v}")
+
+
+@config_app.command("get")
+def config_get(key: str) -> None:
+    """Print one config value."""
+    from handcuff.config import load_config
+
+    cfg = load_config()
+    if key not in cfg:
+        typer.echo(f"unknown key {key!r}; known: {', '.join(cfg)}")
+        raise typer.Exit(code=2)
+    typer.echo(f"{cfg[key]}")
+
+
+@config_app.command("set")
+def config_set(key: str, value: str) -> None:
+    """Set a config value, e.g. `handcuff config set retention_days 14`."""
+    from handcuff.config import CONFIG_KEYS, set_config_value
+
+    try:
+        typed = set_config_value(key, value)
+    except KeyError:
+        typer.echo(f"unknown key {key!r}; known: {', '.join(CONFIG_KEYS)}")
+        raise typer.Exit(code=2) from None
+    except ValueError as exc:
+        typer.echo(f"invalid value: {exc}")
+        raise typer.Exit(code=2) from None
+    typer.echo(f"{key} = {typed}")
+
+
+@app.command()
+def doctor() -> None:
+    """Environment diagnostics: platform, capture capabilities, DB/key health."""
+    from handcuff.doctor import format_report, run_doctor
+
+    typer.echo(format_report(run_doctor()))
+
+
+if __name__ == "__main__":
+    app()

handcuff/config.py

@@ -0,0 +1,65 @@
+"""Default paths (TRD §10) + user config file.
+
+The config file is a small flat YAML at ~/.config/handcuff/config.yaml,
+read/written via `handcuff config get|set|list`. Only known keys are
+accepted so a typo'd `config set` fails loudly instead of silently doing
+nothing."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+CONFIG_DIR = Path.home() / ".config" / "handcuff"
+DATA_DIR = Path.home() / ".local" / "share" / "handcuff"
+DEFAULT_DB_PATH = DATA_DIR / "handcuff.db"
+DEFAULT_KEY_PATH = CONFIG_DIR / "ed25519.key"
+DEFAULT_CONFIG_PATH = CONFIG_DIR / "config.yaml"
+
+# key -> (default, parser). Parsers turn the CLI string into the typed value.
+def _parse_bool(s: str) -> bool:
+    if s.lower() in {"true", "1", "yes", "on"}:
+        return True
+    if s.lower() in {"false", "0", "no", "off"}:
+        return False
+    raise ValueError(f"not a boolean: {s!r}")
+
+
+CONFIG_KEYS: dict[str, tuple[Any, Any]] = {
+    "webhook_url": (None, str),
+    "retention_days": (30, int),
+    "redaction": (True, _parse_bool),
+    "hash_content": (False, _parse_bool),
+}
+
+
+def load_config(path: Path = DEFAULT_CONFIG_PATH) -> dict[str, Any]:
+    """Defaults merged with whatever the config file overrides."""
+    cfg = {k: default for k, (default, _) in CONFIG_KEYS.items()}
+    if path.exists():
+        data = YAML(typ="safe").load(path.read_text(encoding="utf-8")) or {}
+        for k, v in data.items():
+            if k in CONFIG_KEYS:
+                cfg[k] = v
+    return cfg
+
+
+def set_config_value(key: str, raw_value: str, path: Path = DEFAULT_CONFIG_PATH) -> Any:
+    """Parse and persist one key. Returns the typed value. Raises
+    KeyError/ValueError on unknown key or unparseable value."""
+    if key not in CONFIG_KEYS:
+        raise KeyError(key)
+    _, parser = CONFIG_KEYS[key]
+    value = parser(raw_value)
+    yaml = YAML(typ="safe")
+    yaml.default_flow_style = False
+    data: dict[str, Any] = {}
+    if path.exists():
+        data = yaml.load(path.read_text(encoding="utf-8")) or {}
+    data[key] = value
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        yaml.dump(data, f)
+    return value

handcuff/core/bus.py

@@ -0,0 +1,74 @@
+"""Async event bus + fan-out with backpressure (AL-020).
+
+A single bounded ingress queue (maxsize=10_000) fans out to N consumer
+queues (StorageWriter, RulesEngine, TUI, ...). On ingress overflow we drop
+the *oldest* queued item, increment a counter, and synthesize a `LOSS`
+event summarizing the drop — the capture pipeline must never block the
+observed agent (NFR-2).
+
+Each consumer gets its own unbounded-ish fan-out queue so a slow consumer
+(e.g. a laggy TUI) cannot block a fast one (e.g. the storage writer):
+consumer queues are themselves bounded and drop-oldest independently.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import AsyncIterator
+
+from handcuff.core.events import EventKind, RawEvent
+
+INGRESS_MAXSIZE = 10_000
+CONSUMER_MAXSIZE = 10_000
+
+
+class EventBus:
+    def __init__(self, maxsize: int = INGRESS_MAXSIZE) -> None:
+        self._maxsize = maxsize
+        self._consumers: dict[str, asyncio.Queue[RawEvent]] = {}
+        self.dropped_count = 0
+
+    def subscribe(self, name: str, maxsize: int = CONSUMER_MAXSIZE) -> asyncio.Queue[RawEvent]:
+        q: asyncio.Queue[RawEvent] = asyncio.Queue(maxsize=maxsize)
+        self._consumers[name] = q
+        return q
+
+    def unsubscribe(self, name: str) -> None:
+        self._consumers.pop(name, None)
+
+    async def publish(self, event: RawEvent) -> None:
+        """Fan out to every consumer. Each consumer queue drops its own
+        oldest items on overflow rather than blocking the publisher."""
+        for name, q in self._consumers.items():
+            overflowed = False
+            # Ensure room for both the LOSS marker and the real event
+            # (2 free slots), for queues with capacity to hold both;
+            # a maxsize==1 queue can only ever hold the latest event.
+            room_needed = 2 if q.maxsize > 1 else 1
+            while q.maxsize - q.qsize() < room_needed:
+                try:
+                    q.get_nowait()
+                except asyncio.QueueEmpty:
+                    break
+                self.dropped_count += 1
+                overflowed = True
+            if overflowed and room_needed == 2:
+                loss = RawEvent(
+                    kind=EventKind.LOSS,
+                    ts=int(time.time() * 1000),
+                    pid=None,
+                    ppid=None,
+                    payload={
+                        "reason": "buffer_overflow",
+                        "dropped_estimate": self.dropped_count,
+                        "consumer": name,
+                    },
+                )
+                q.put_nowait(loss)
+            q.put_nowait(event)
+
+    async def consume(self, name: str) -> AsyncIterator[RawEvent]:
+        q = self._consumers[name]
+        while True:
+            yield await q.get()

handcuff/core/events.py

@@ -0,0 +1,159 @@
+"""Event & session dataclasses (AL-010).
+
+`RawEvent` is what capture backends emit (pre-sequencing). `Event` is the
+persisted, chain-hashed form written by the storage layer. Payloads are
+kind-specific TypedDicts documented in TRD §3.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, TypedDict
+
+
+class EventKind(str, Enum):
+    PROCESS_SPAWN = "PROCESS_SPAWN"
+    PROCESS_EXIT = "PROCESS_EXIT"
+    FILE_READ = "FILE_READ"
+    FILE_WRITE = "FILE_WRITE"
+    FILE_DELETE = "FILE_DELETE"
+    FILE_RENAME = "FILE_RENAME"
+    NET_CONNECT = "NET_CONNECT"
+    LOSS = "LOSS"
+    ALERT = "ALERT"
+    MARK = "MARK"
+    GATEWAY_DENY = "GATEWAY_DENY"
+    INJECTION_DETECTED = "INJECTION_DETECTED"
+    AGENT_STEP = "AGENT_STEP"
+    TOOL_CALL = "TOOL_CALL"
+    TOOL_RESULT = "TOOL_RESULT"
+    RETRIEVAL = "RETRIEVAL"
+
+
+class ProcessSpawnPayload(TypedDict, total=False):
+    argv: list[str]
+    cwd: str
+    exe: str
+    user: str
+
+
+class ProcessExitPayload(TypedDict, total=False):
+    exit_code: int
+    duration_ms: int
+
+
+class FileReadPayload(TypedDict, total=False):
+    path: str
+    bytes: int
+
+
+class GatewayDenyPayload(TypedDict, total=False):
+    op: str
+    path: str
+    reason: str
+
+
+class FileWritePayload(TypedDict, total=False):
+    path: str
+    bytes_delta: int
+    op: str
+    content_hash: str
+
+
+class FileDeletePayload(TypedDict, total=False):
+    path: str
+
+
+class FileRenamePayload(TypedDict, total=False):
+    path: str
+    to: str
+
+
+class NetConnectPayload(TypedDict, total=False):
+    dst_ip: str
+    domain: str | None
+    port: int
+    proto: str
+    bytes: int
+
+
+class LossPayload(TypedDict, total=False):
+    expected_seq: int
+    reason: str
+    dropped_estimate: int
+
+
+class AlertPayload(TypedDict, total=False):
+    rule_id: str
+    severity: str
+    message: str
+
+
+class MarkPayload(TypedDict, total=False):
+    note: str
+
+
+class AgentStepPayload(TypedDict, total=False):
+    agent: str
+    run_id: str
+    parent_run_id: str | None
+    kind: str  # "chain_start" | "chain_end" | "agent_action" | "agent_finish"
+    name: str
+
+
+class ToolCallPayload(TypedDict, total=False):
+    agent: str
+    run_id: str
+    tool: str
+    input_excerpt: str
+
+
+class ToolResultPayload(TypedDict, total=False):
+    agent: str
+    run_id: str
+    tool: str
+    output_excerpt: str
+    error: bool
+    blocked: bool
+
+
+class RetrievalPayload(TypedDict, total=False):
+    agent: str
+    run_id: str
+    retriever: str
+    doc_count: int
+
+
+class InjectionDetectedPayload(TypedDict, total=False):
+    source: str  # path or URL the tainting content came from
+    signature: str  # which heuristic signature matched
+    reason: str
+    excerpt: str  # short, already-redacted-adjacent excerpt for audit
+    taint_expires_at: int  # epoch ms; sensitive ops before this are gated
+
+
+@dataclass(slots=True)
+class RawEvent:
+    """Emitted by a capture backend, before sequencing/hashing."""
+
+    kind: EventKind
+    ts: int  # epoch ms
+    pid: int | None
+    ppid: int | None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class Event:
+    """Persisted, hash-chained event row (mirrors the `events` table)."""
+
+    session_id: str
+    seq: int
+    ts: int
+    kind: EventKind
+    pid: int | None
+    ppid: int | None
+    payload: dict[str, Any]
+    prev_hash: str
+    hash: str