handcuff 0.2.0__py3-none-any.whl

handcuff/alerts/webhooks.py

@@ -0,0 +1,56 @@
+"""Webhook alerts (AL-042).
+
+Posts a minimal JSON payload to a configured URL when a `critical`
+severity alert fires. Deliberately content-light: only rule_id,
+severity, message, and timestamp — never argv, file paths, domains, or
+any other captured content (NFR-1: nothing leaves the machine except to
+a user-configured webhook, and even then, as little as possible).
+
+HTTPS is required for remote hosts; plain HTTP is only allowed to
+localhost (useful for local test receivers / local automation), so a
+misconfigured webhook URL can't silently leak alert text in the clear
+over the network.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+import httpx
+
+from handcuff.rules.engine import Alert
+
+_LOCALHOST_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def is_allowed_url(url: str) -> bool:
+    parsed = urlparse(url)
+    if parsed.scheme == "https":
+        return True
+    if parsed.scheme == "http" and parsed.hostname in _LOCALHOST_HOSTS:
+        return True
+    return False
+
+
+def alert_payload(alert: Alert) -> dict:
+    """Content-light payload: no argv/path/domain/file content, ever."""
+    return {
+        "rule_id": alert.rule_id,
+        "severity": alert.severity,
+        "message": alert.message,
+        "ts": alert.ts,
+    }
+
+
+async def post_alert(url: str, alert: Alert, timeout: float = 5.0) -> bool:
+    """Post a critical alert to the configured webhook. Returns False
+    (never raises) on any failure — a broken webhook must not crash or
+    stall the recording session."""
+    if not is_allowed_url(url):
+        return False
+    try:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(url, json=alert_payload(alert))
+            return resp.status_code < 400
+    except httpx.HTTPError:
+        return False

handcuff/banner.py

@@ -0,0 +1,128 @@
+"""Startup banner (Handcuff's "logo"), printed like Claude Code/Gemini
+CLI show a welcome screen on launch.
+
+Two-column layout matching Claude Code's actual screen: a bordered
+panel (icon + welcome + identity) on the left, "Quick start"/"What's
+new" on the right — not a single lonely box in empty space.
+
+Uses Rich's own box-drawing (rounded corners, the magnifying-glass
+icon) which Rich encodes correctly for the detected terminal — verified
+directly against Windows Terminal. Only hand-typed *content* avoids
+non-ASCII (verified while building this that this environment's
+console can mangle hand-typed non-ASCII depending on code page); Rich's
+box-drawing glyphs are a separate, correctly-handled concern.
+"""
+
+from __future__ import annotations
+
+import getpass
+import os
+import platform
+import sys
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from rich import box
+from rich.align import Align
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich_pixels import Pixels
+
+from handcuff.tui.widgets.hero import render_hero_pixels
+
+# Explicit hex, not a named Rich color ("bright_cyan" etc.): verified
+# directly from a user screenshot that named ANSI colors get remapped
+# by the terminal's own color theme (rendered as purple instead of
+# cyan there), while hex triggers Rich's 24-bit true-color escape codes
+# and bypasses that remapping — same reason the Hero widget's lens ring
+# (already hex-based) rendered correctly cyan in that same screenshot.
+ACCENT = "#00D9FF"  # matches the TUI theme's primary color
+
+
+def _version() -> str:
+    try:
+        return version("handcuff")
+    except PackageNotFoundError:
+        return "0.1.0"
+
+
+def _short_cwd(max_len: int = 42) -> str:
+    cwd = str(Path.cwd())
+    home = str(Path.home())
+    if cwd.startswith(home):
+        cwd = "~" + cwd[len(home) :]
+    if len(cwd) <= max_len:
+        return cwd
+    head, tail = cwd[: max_len // 2 - 2], cwd[-(max_len // 2 - 1) :]
+    return f"{head}...{tail}"
+
+
+def _icon() -> Pixels:
+    """Reuses the exact same robot-inside-a-lens image the TUI's Hero
+    widget draws (frozen, non-animated) — the startup banner and the
+    live dashboard used to show two unrelated icons; this keeps the
+    mascot consistent everywhere Handcuff shows its face."""
+    return render_hero_pixels(lens_color=ACCENT)
+
+
+def _left_panel() -> Panel:
+    welcome = Text(f"Welcome back, {getpass.getuser()}!", style="bold white", justify="center")
+    info = Text(
+        f"v{_version()}  -  {getpass.getuser()}  -  {platform.system()} {platform.release()}",
+        style="dim",
+        justify="center",
+    )
+    cwd = Text(_short_cwd(), style="dim", justify="center")
+
+    body = Group(
+        Text(""),
+        Align.center(_icon()),
+        Text(""),
+        Align.center(welcome),
+        Align.center(info),
+        Align.center(cwd),
+        Text(""),
+    )
+    return Panel(body, box=box.ROUNDED, border_style=ACCENT, width=50)
+
+
+def _right_column() -> Text:
+    right = Text()
+    right.append("Quick start\n\n", style=f"bold {ACCENT}")
+    right.append("handcuff watch -- <cmd>\n", style="bold white")
+    right.append("  record a process as it runs\n\n", style="dim")
+    right.append("handcuff tui\n", style="bold white")
+    right.append("  open this live dashboard\n\n", style="dim")
+    right.append("handcuff doctor\n", style="bold white")
+    right.append("  check capture capabilities\n\n", style="dim")
+    right.append("What's new\n", style=f"bold {ACCENT}")
+    right.append("Real OS-level file & network blocking (--enforce)\n", style="dim")
+    right.append("Session replay, export, and trust lists\n", style="dim")
+    return right
+
+
+def banner_grid() -> Table:
+    grid = Table.grid(expand=False, padding=(0, 3))
+    grid.add_column()
+    grid.add_column()
+    grid.add_row(_left_panel(), _right_column())
+    return grid
+
+
+def should_show_banner() -> bool:
+    """Skip the banner when output isn't an interactive terminal (piped/
+    redirected output, CI logs) or when explicitly suppressed — mirrors
+    how `--quiet` already suppresses noise elsewhere in this CLI."""
+    if os.environ.get("HANDCUFF_NO_BANNER"):
+        return False
+    return sys.stdout.isatty()
+
+
+def print_banner(console: Console | None = None, force: bool = False) -> None:
+    if not force and not should_show_banner():
+        return
+    console = console or Console()
+    console.print(banner_grid())
+    console.print()

handcuff/capture/base.py

@@ -0,0 +1,28 @@
+"""CaptureBackend protocol (TRD §4).
+
+All platform-specific capture implementations conform to this Protocol
+so the rest of the system (bus, writer, `doctor`) is backend-agnostic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+from handcuff.core.events import RawEvent
+
+
+@runtime_checkable
+class CaptureBackend(Protocol):
+    name: str
+    capabilities: set[str]  # subset of {"process", "file", "network", "argv", "content"}
+
+    async def start(self, root_pid: int, watch_paths: list[Path]) -> None: ...
+
+    def events(self) -> AsyncIterator[RawEvent]: ...
+
+    async def stop(self) -> None: ...
+
+    @staticmethod
+    def available() -> bool: ...

handcuff/capture/file_watch.py

@@ -0,0 +1,143 @@
+"""File event capture (AL-030) via watchdog.
+
+Emits FILE_WRITE / FILE_DELETE / FILE_RENAME RawEvents for changes under
+`watch_paths`. watchdog delivers callbacks on its own observer threads, so
+we hand events across to the asyncio side through a thread-safe queue that
+`events()` drains on the event loop.
+
+Windows fidelity caveat (documented honestly): watchdog's Windows backend
+(ReadDirectoryChangesW) reports *what* changed but not *which PID* caused
+it. So file events here are attributed to the session, not to a specific
+process in the tree. True per-PID file attribution on Windows needs a
+kernel minifilter driver, which is out of scope for the no-privilege
+default backend.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import os
+import queue
+import time
+from pathlib import Path
+from typing import Any
+
+from watchdog.events import (
+    DirDeletedEvent,
+    FileCreatedEvent,
+    FileDeletedEvent,
+    FileModifiedEvent,
+    FileMovedEvent,
+    FileSystemEvent,
+    FileSystemEventHandler,
+)
+from watchdog.observers import Observer
+
+from handcuff.core.events import EventKind, RawEvent
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _size(path: str) -> int:
+    try:
+        return Path(path).stat().st_size
+    except OSError:
+        return 0
+
+
+# Content hashing is opt-in (AL-033) and size-capped: hashing huge files on
+# every modify callback would stall the observer thread and thrash disk.
+CONTENT_HASH_MAX_BYTES = 1 * 1024 * 1024
+
+
+def _content_sha256(path: str, max_bytes: int = CONTENT_HASH_MAX_BYTES) -> str | None:
+    """SHA-256 of the file's bytes, or None if unreadable or over the cap.
+    Only the hash is recorded — never the content itself."""
+    try:
+        p = Path(path)
+        if p.stat().st_size > max_bytes:
+            return None
+        return hashlib.sha256(p.read_bytes()).hexdigest()
+    except OSError:
+        return None
+
+
+class _Handler(FileSystemEventHandler):
+    def __init__(self, sink: queue.Queue[RawEvent], hash_content: bool = False) -> None:
+        self._sink = sink
+        self._hash_content = hash_content
+
+    def _write_payload(self, path: str, op: str) -> dict:
+        payload = {"path": path, "bytes_delta": _size(path), "op": op}
+        if self._hash_content:
+            digest = _content_sha256(path)
+            if digest is not None:
+                payload["content_sha256"] = digest
+        return payload
+
+    def on_created(self, event: FileSystemEvent) -> None:
+        if isinstance(event, FileCreatedEvent):
+            path = os.fsdecode(event.src_path)
+            self._emit(EventKind.FILE_WRITE, self._write_payload(path, "create"))
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        if isinstance(event, FileModifiedEvent):
+            path = os.fsdecode(event.src_path)
+            self._emit(EventKind.FILE_WRITE, self._write_payload(path, "modify"))
+
+    def on_deleted(self, event: FileSystemEvent) -> None:
+        if isinstance(event, (FileDeletedEvent, DirDeletedEvent)):
+            self._emit(EventKind.FILE_DELETE, {"path": os.fsdecode(event.src_path)})
+
+    def on_moved(self, event: FileSystemEvent) -> None:
+        if isinstance(event, FileMovedEvent):
+            self._emit(
+                EventKind.FILE_RENAME,
+                {"path": os.fsdecode(event.src_path), "to": os.fsdecode(event.dest_path)},
+            )
+
+    def _emit(self, kind: EventKind, payload: dict) -> None:
+        self._sink.put(
+            RawEvent(kind=kind, ts=_now_ms(), pid=None, ppid=None, payload=payload)
+        )
+
+
+class FileCaptureBackend:
+    name = "watchdog"
+    capabilities = {"file"}
+
+    def __init__(self, hash_content: bool = False) -> None:
+        self._observer: Any | None = None
+        self._sink: queue.Queue[RawEvent] = queue.Queue()
+        self._stopped = False
+        self._hash_content = hash_content
+
+    @staticmethod
+    def available() -> bool:
+        return True
+
+    async def start(self, root_pid: int, watch_paths: list[Path]) -> None:
+        self._stopped = False
+        self._observer = Observer()
+        handler = _Handler(self._sink, hash_content=self._hash_content)
+        for p in watch_paths:
+            path = p.expanduser().resolve()
+            if path.exists() and path.is_dir():
+                self._observer.schedule(handler, str(path), recursive=True)
+        self._observer.start()
+
+    async def events(self):
+        while not self._stopped or not self._sink.empty():
+            try:
+                yield self._sink.get_nowait()
+            except queue.Empty:
+                await asyncio.sleep(0.05)
+
+    async def stop(self) -> None:
+        self._stopped = True
+        if self._observer is not None:
+            self._observer.stop()
+            self._observer.join(timeout=3)

handcuff/capture/net_watch.py

@@ -0,0 +1,139 @@
+"""Network event capture (AL-031) via psutil polling.
+
+Polls `psutil.net_connections` and emits a NET_CONNECT RawEvent the first
+time a given (pid, remote_ip, remote_port) tuple is seen for a PID in the
+observed process tree. Reverse-DNS is attempted (best-effort, cached) to
+attach a domain.
+
+Windows fidelity caveats (documented honestly):
+  * Enumerating connections for other processes' PIDs can require admin on
+    some Windows configs; when access is denied we simply see fewer
+    connections rather than crashing.
+  * Polling means very short-lived connections between polls can be missed
+    (same tradeoff as procfs process capture).
+  * Byte counts are not available from net_connections, so `bytes` is 0.
+  * Loopback (127.0.0.1/::1) connections are unreliable to attribute on
+    Windows specifically: verified while building this that the PID for
+    the client side of a loopback TCP connection is frequently reported
+    as 0 by the time our poll observes it (Windows appears to zero the
+    owning-PID field once the socket leaves ESTABLISHED, which for fast
+    loopback round-trips can happen within a few ms) — distinct from the
+    general short-connection-miss tradeoff above, this affects loopback
+    specifically even when the connection lives longer than a poll
+    interval. Non-loopback (real network) connections were verified to
+    attribute PIDs correctly and reliably. Practical effect: don't rely
+    on this capture path to see an agent's own calls to a service on
+    localhost; it's built for outbound calls to real hosts/domains.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+import time
+from collections.abc import Callable
+
+import psutil
+
+from handcuff.core.events import EventKind, RawEvent
+
+DEFAULT_POLL_INTERVAL_MS = 200
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+class NetworkCaptureBackend:
+    name = "psutil-net"
+    capabilities = {"network"}
+
+    def __init__(
+        self,
+        pid_filter: Callable[[int], bool] | None = None,
+        poll_interval_ms: int = DEFAULT_POLL_INTERVAL_MS,
+        resolve_dns: bool = True,
+    ) -> None:
+        self._pid_filter = pid_filter or (lambda _pid: True)
+        self._poll_interval_s = poll_interval_ms / 1000
+        self._resolve_dns = resolve_dns
+        self._seen: set[tuple[int | None, str, int]] = set()
+        self._dns_cache: dict[str, str | None] = {}
+        self._queue: asyncio.Queue[RawEvent] = asyncio.Queue()
+        self._stopped = False
+        self._task: asyncio.Task | None = None
+
+    @staticmethod
+    def available() -> bool:
+        return True
+
+    async def start(self, root_pid: int, watch_paths) -> None:
+        self._stopped = False
+        self._task = asyncio.ensure_future(self._poll_loop())
+
+    def _resolve(self, ip: str) -> str | None:
+        if not self._resolve_dns:
+            return None
+        if ip in self._dns_cache:
+            return self._dns_cache[ip]
+        try:
+            name = socket.gethostbyaddr(ip)[0]
+        except (OSError, socket.herror):
+            name = None
+        self._dns_cache[ip] = name
+        return name
+
+    async def _poll_loop(self) -> None:
+        while not self._stopped:
+            try:
+                conns = psutil.net_connections(kind="inet")
+            except (psutil.AccessDenied, PermissionError):
+                conns = []
+
+            for c in conns:
+                if not c.raddr:
+                    continue
+                if c.pid is not None and not self._pid_filter(c.pid):
+                    continue
+                remote_ip = c.raddr.ip
+                remote_port = c.raddr.port
+                key = (c.pid, remote_ip, remote_port)
+                if key in self._seen:
+                    continue
+                self._seen.add(key)
+                proto = "tcp" if c.type == socket.SOCK_STREAM else "udp"
+                domain = await asyncio.get_event_loop().run_in_executor(
+                    None, self._resolve, remote_ip
+                )
+                await self._queue.put(
+                    RawEvent(
+                        kind=EventKind.NET_CONNECT,
+                        ts=_now_ms(),
+                        pid=c.pid,
+                        ppid=None,
+                        payload={
+                            "dst_ip": remote_ip,
+                            "domain": domain,
+                            "port": remote_port,
+                            "proto": proto,
+                            "bytes": 0,
+                        },
+                    )
+                )
+            await asyncio.sleep(self._poll_interval_s)
+
+    async def events(self):
+        while not self._stopped or not self._queue.empty():
+            try:
+                yield await asyncio.wait_for(self._queue.get(), timeout=0.5)
+            except TimeoutError:
+                if self._stopped:
+                    break
+
+    async def stop(self) -> None:
+        self._stopped = True
+        if self._task is not None:
+            try:
+                await asyncio.wait_for(self._task, timeout=2)
+            except (TimeoutError, asyncio.CancelledError):
+                self._task.cancel()

handcuff/capture/psutil_backend.py

@@ -0,0 +1,117 @@
+"""Cross-platform process capture backend (AL-023).
+
+Implements `CaptureBackend` using `psutil` polling of the process tree.
+On Linux, `psutil` reads `/proc` under the hood, so this *is* the
+procfs-based default path described in TRD §2/§4. On macOS and Windows
+it uses the platform's native process APIs via the same `psutil` calls
+— reduced fidelity is possible on those platforms (short-lived
+processes between polls can be missed) and is reported honestly via
+`capabilities` / `doctor`, never silently upgraded.
+
+This backend requires no elevated privileges.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import getpass
+import time
+from collections.abc import AsyncIterator
+from pathlib import Path
+
+import psutil
+
+from handcuff.capture.tree import ProcessTreeTracker
+from handcuff.core.events import EventKind, RawEvent
+
+DEFAULT_POLL_INTERVAL_MS = 50
+
+
+class PsutilCaptureBackend:
+    name = "psutil"
+    capabilities = {"process", "argv"}
+
+    def __init__(self, poll_interval_ms: int = DEFAULT_POLL_INTERVAL_MS) -> None:
+        self._poll_interval_s = poll_interval_ms / 1000
+        self._tracker: ProcessTreeTracker | None = None
+        self._queue: asyncio.Queue[RawEvent] = asyncio.Queue()
+        self._stopped = False
+        self._task: asyncio.Task | None = None
+        self._start_times: dict[int, float] = {}
+
+    @staticmethod
+    def available() -> bool:
+        return True  # psutil works everywhere we support
+
+    async def start(self, root_pid: int, watch_paths: list[Path]) -> None:
+        self._tracker = ProcessTreeTracker(root_pid)
+        self._stopped = False
+        self._task = asyncio.ensure_future(self._poll_loop())
+
+    async def _poll_loop(self) -> None:
+        assert self._tracker is not None
+        while not self._stopped:
+            added, removed = self._tracker.refresh()
+            now = time.time()
+            now_ms = int(now * 1000)
+
+            for pid in added:
+                self._start_times[pid] = now
+                payload: dict = {}
+                try:
+                    proc = psutil.Process(pid)
+                    payload = {
+                        "argv": proc.cmdline(),
+                        "cwd": _safe(proc.cwd),
+                        "exe": _safe(proc.exe),
+                        "user": _safe(proc.username, default=getpass.getuser()),
+                    }
+                except (psutil.NoSuchProcess, psutil.AccessDenied):
+                    pass
+                await self._queue.put(
+                    RawEvent(
+                        kind=EventKind.PROCESS_SPAWN,
+                        ts=now_ms,
+                        pid=pid,
+                        ppid=self._tracker.root_pid,
+                        payload=payload,
+                    )
+                )
+
+            for pid in removed:
+                started = self._start_times.pop(pid, now)
+                duration_ms = int((now - started) * 1000)
+                await self._queue.put(
+                    RawEvent(
+                        kind=EventKind.PROCESS_EXIT,
+                        ts=now_ms,
+                        pid=pid,
+                        ppid=self._tracker.root_pid,
+                        payload={"exit_code": None, "duration_ms": duration_ms},
+                    )
+                )
+
+            await asyncio.sleep(self._poll_interval_s)
+
+    async def events(self) -> AsyncIterator[RawEvent]:
+        while not self._stopped or not self._queue.empty():
+            try:
+                yield await asyncio.wait_for(self._queue.get(), timeout=0.5)
+            except TimeoutError:
+                if self._stopped:
+                    break
+
+    async def stop(self) -> None:
+        self._stopped = True
+        if self._task is not None:
+            try:
+                await asyncio.wait_for(self._task, timeout=2)
+            except (TimeoutError, asyncio.CancelledError):
+                self._task.cancel()
+
+
+def _safe(fn, default: str | None = None):
+    try:
+        return fn()
+    except (psutil.NoSuchProcess, psutil.AccessDenied, Exception):
+        return default

handcuff/capture/redact.py

@@ -0,0 +1,67 @@
+"""Redaction engine (AL-032), on by default.
+
+Scrubs secret-looking substrings from argv and file paths *before* they
+are persisted. The redaction map is never stored — once redacted, the
+original secret is gone from Handcuff's records.
+
+Patterns: OpenAI-style `sk-...` keys, AWS access key ids, JWTs, GitHub
+tokens, and generic high-entropy 32+ char tokens. Benign strings are
+left untouched.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+
+from handcuff.core.events import EventKind, RawEvent
+
+# High-confidence, specific patterns first.
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    ("openai", re.compile(r"sk-[A-Za-z0-9_\-]{20,}")),
+    ("aws_akid", re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b")),
+    ("github", re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b")),
+    ("jwt", re.compile(r"\beyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+")),
+    ("slack", re.compile(r"\bxox[baprs]-[A-Za-z0-9\-]{10,}\b")),
+]
+
+# Generic high-entropy token: long alnum run that "looks random".
+_TOKEN_RE = re.compile(r"\b[A-Za-z0-9+/_\-]{32,}\b")
+_ENTROPY_THRESHOLD = 3.5  # bits/char; random base64 ~5-6, english words ~2-3
+
+
+def _shannon_entropy(s: str) -> float:
+    if not s:
+        return 0.0
+    counts = Counter(s)
+    n = len(s)
+    return -sum((c / n) * math.log2(c / n) for c in counts.values())
+
+
+def redact_string(value: str) -> str:
+    redacted = value
+    for label, pat in _PATTERNS:
+        redacted = pat.sub(f"‹redacted:{label}›", redacted)
+
+    def _maybe_token(m: re.Match[str]) -> str:
+        tok = m.group(0)
+        if tok.startswith("‹redacted:"):
+            return tok
+        if _shannon_entropy(tok) >= _ENTROPY_THRESHOLD:
+            return "‹redacted:token›"
+        return tok
+
+    redacted = _TOKEN_RE.sub(_maybe_token, redacted)
+    return redacted
+
+
+def redact_event(event: RawEvent) -> RawEvent:
+    """Mutate `event.payload` in place, redacting argv and path-like fields."""
+    payload = event.payload
+    if event.kind == EventKind.PROCESS_SPAWN and isinstance(payload.get("argv"), list):
+        payload["argv"] = [redact_string(str(a)) for a in payload["argv"]]
+    for key in ("path", "to", "cwd", "exe"):
+        if isinstance(payload.get(key), str):
+            payload[key] = redact_string(payload[key])
+    return event