stacktrace-cli 0.5.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,10 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.5.0"
+import logging as _logging
+
+__version__ = "0.5.2"
+
+# Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
+# logged in any other process would reach Python's last-resort handler and
+# print onto the user's terminal.
+_logging.getLogger(__name__).addHandler(_logging.NullHandler())

stacktrace_cli/cli.py

@@ -40,6 +40,7 @@ from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
 from .telemetry import emit_error
 from .telemetry.cli import telemetry as telemetry_cmd
+from .webhook.cli import webhook as webhook_cmd
 
 PASSTHROUGH: Final = ("scan", "bom", "policy")
 
@@ -586,3 +587,4 @@ main.add_command(monitor)
 main.add_command(daemon_cmd, "daemon")
 main.add_command(findings)
 main.add_command(telemetry_cmd, "telemetry")
+main.add_command(webhook_cmd, "webhook")

stacktrace_cli/cloud/__init__.py

@@ -0,0 +1,39 @@
+"""One entry point for a Claude Code cloud environment's setup script.
+
+A cloud environment's setup script runs once, as root, before the filesystem is
+snapshotted and reused by every later session. What a session needs that is not
+the CLI itself — the per-session boot hook and the asset identity — has to be
+laid down there so it lands inside the snapshot.
+
+Rather than paste that into the setup-script box, a setup script installs the
+CLI and runs this:
+
+    UV_TOOL_DIR=/usr/local/share/uv-tools UV_TOOL_BIN_DIR=/usr/local/bin \
+      uv tool install stacktrace-cli
+    stacktrace-cloud-setup
+
+Both variables matter: setup runs as root, and `uv tool install`'s root
+defaults put the tool's environment under `/root/.local/share/uv/tools` and the
+linked executable under `/root/.local/bin` — both inside `/root`, which a later
+non-root session user cannot traverse. `UV_TOOL_BIN_DIR` alone moves the
+symlink but not the environment it points into, so `command -v stacktrace` would
+find the binary while running it still fails; both must move.
+
+The work itself is `setup.sh`, shipped beside this module so it travels in the
+wheel. This shim only locates it and hands off, so the logic stays one auditable
+bash file rather than being reimplemented in Python.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    script = Path(__file__).with_name("setup.sh")
+    # execvp so the process *becomes* bash: its exit status is the setup
+    # script's, which is what the environment reads to decide the session may
+    # start, and there is no Python frame left to swallow a signal.
+    os.execvp("bash", ["bash", str(script), *sys.argv[1:]])

stacktrace_cli/cloud/setup.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# Lay down everything a Claude Code cloud session needs, at environment setup.
+#
+# Run once by the environment's setup script, as root, before the filesystem is
+# snapshotted. Two things, both of which must be inside that snapshot because
+# the setup script does not run again for later sessions:
+#
+#   1. /usr/local/bin/stacktrace-boot.sh — the per-session hook that configures
+#      the remote and starts the daemon. Registered as a SessionStart hook in
+#      every home so it fires whichever user the session runs as.
+#   2. The asset identity, in every home's ~/.config/stacktrace/asset-id, so
+#      `stacktrace remote sync` resolves it at the persisted rung (ADR-0065)
+#      instead of minting a fresh asset per session.
+#
+# The telemetry install id is deliberately NOT seeded here. Seeding it would
+# make `read_install_id()` non-None before any event runs, so the one-time
+# `installed` event (which `emit()` synthesizes only when the id is absent)
+# would never fire. Left unseeded, the daemon's first in-session event mints the
+# id and fires `installed` once per VM, correctly attributed `remote=true`
+# because it runs inside the session. Counting one install per VM rather than
+# per environment is ADR-0043's documented cloud tradeoff; per-environment is
+# not cleanly achievable for an ephemeral VM (a setup-time emit would carry the
+# wrong `remote` value and could not flush from a one-shot process).
+#
+# Every home rather than $HOME: setup runs as root and the user a session runs
+# as is not documented, so writing all of them removes the guess. The asset id
+# is unconditional — each environment instance gets its own, and a leftover from
+# a previous snapshot must not win.
+#
+# Scope (ADR-0070): this seeds the snapshot and starts the daemon per session.
+# It does not own daemon lifetime across a supervisor — that is ADR-0066, and a
+# cloud VM is one session per VM, so the daemon dying with the VM is correct.
+# The environment this targets is a fresh, single-tenant snapshot: it does not
+# defend against adversarial or pre-existing symlinks and special files in a
+# home, because that home does not exist until this run creates it.
+#
+# Options (all optional):
+#   --asset-id VALUE   use this asset id instead of minting one; also taken
+#                      from STACKTRACE_ASSET_EXTERNAL_ID in the environment
+#   --root DIR         treat DIR as / (for testing)
+#
+# The remote token and API URL are read by the boot hook at session time from
+# STACKTRACE_REMOTE_TOKEN and STACKTRACE_REMOTE_API_URL, not here: they belong
+# to the environment's variables, not to the snapshot this seeds.
+set -uo pipefail
+
+ASSET_ID="${STACKTRACE_ASSET_EXTERNAL_ID:-}"
+ROOT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    # `$# -ge 2` before the shift: without it, `--root` with no operand leaves
+    # the positional parameters unchanged under `set -u` with no `set -e`, and
+    # the loop spins forever — a malformed invocation would hang setup.
+    --asset-id) [ $# -ge 2 ] || { echo "✗ --asset-id needs a value" >&2; exit 2; }; ASSET_ID="$2"; shift 2 ;;
+    --root) [ $# -ge 2 ] || { echo "✗ --root needs a value" >&2; exit 2; }; ROOT="$2"; shift 2 ;;
+    -h|--help) sed -n '2,44p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "✗ unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+LOG="${ROOT}/var/log/stacktrace-cloud-setup.log"
+mkdir -p "$(dirname "$LOG")" 2>/dev/null || true
+exec > >(tee -a "$LOG") 2>&1
+echo "=== stacktrace cloud setup $(date -u +%FT%TZ) ==="
+
+# ---- identities ----------------------------------------------------------
+_uuid() {
+  if [ -r /proc/sys/kernel/random/uuid ]; then
+    cat /proc/sys/kernel/random/uuid
+  else
+    python3 -c 'import uuid; print(uuid.uuid4())'
+  fi
+}
+
+[ -n "$ASSET_ID" ] || ASSET_ID="cloud-$(_uuid)"
+# remote/identity.py:_is_identifier rejects whitespace, non-printable
+# characters, and anything over 255 characters. A value this accepts but the
+# runtime rejects is worse than no file: every session reads it, rejects it,
+# and mints a fresh asset — the per-session proliferation this exists to stop.
+case "$ASSET_ID" in
+  *[[:space:]]*|"") echo "✗ asset id must be non-empty with no whitespace" >&2; exit 2 ;;
+esac
+if [ "${#ASSET_ID}" -gt 255 ]; then
+  echo "✗ asset id must be 255 characters or fewer" >&2
+  exit 2
+fi
+if ! python3 -c 'import sys; sys.exit(0 if sys.argv[1].isprintable() else 1)' "$ASSET_ID"; then
+  echo "✗ asset id must contain no non-printable characters" >&2
+  exit 2
+fi
+# ---- the per-session boot hook -------------------------------------------
+# Failing hard here: if the hook cannot be written, every session's SessionStart
+# command points at a file that does not exist and the daemon never starts —
+# a silent total failure worse than a setup that stops and says so.
+BOOT="${ROOT}/usr/local/bin/stacktrace-boot.sh"
+mkdir -p "$(dirname "$BOOT")" || { echo "✗ cannot create $(dirname "$BOOT")" >&2; exit 1; }
+cat > "$BOOT" <<'BOOTSCRIPT' || { echo "✗ cannot write $BOOT" >&2; exit 1; }
+#!/usr/bin/env bash
+# Configure the remote and start the daemon for this cloud session. No-op
+# anywhere else. The asset id is already on disk from setup, so this does not
+# touch it: it only configures the token and starts the daemon, which resolves
+# the persisted asset id and mints the telemetry id on its first event.
+#
+# `daemon run` is started detached, not through a supervisor: a cloud VM runs
+# one session, so the daemon's lifetime is the VM's (ADR-0070). Where a host
+# runs several sessions, ADR-0066's `daemon start` replaces this one line.
+set -u
+[ "${CLAUDE_CODE_REMOTE:-}" = "true" ] || exit 0
+command -v stacktrace >/dev/null 2>&1 || exit 0
+[ -n "${STACKTRACE_REMOTE_TOKEN:-}" ] || exit 0
+
+STATE="$HOME/.local/state/stacktrace"
+mkdir -p "$STATE" && chmod 700 "$STATE"
+
+stacktrace remote configure \
+  --token "$STACKTRACE_REMOTE_TOKEN" \
+  --api-url "${STACKTRACE_REMOTE_API_URL:-https://api.stacktrace.ai}" >/dev/null 2>&1 || true
+
+# Streams redirected because own_std_streams only re-points fd 1/2 on log
+# rollover; without this the daemon inherits the hook's pipe to Claude Code.
+if ! stacktrace daemon status 2>/dev/null | grep -q '^running: yes'; then
+  setsid nohup stacktrace daemon run </dev/null >>"$STATE/daemon.log" 2>&1 &
+fi
+exit 0
+BOOTSCRIPT
+chmod 755 "$BOOT" || { echo "✗ cannot chmod $BOOT" >&2; exit 1; }
+echo "✓ $BOOT"
+
+# ---- seed every home -----------------------------------------------------
+# Every existing home is seeded because the future session user is unknown, so a
+# home that exists but cannot be seeded is a failure, not a skip: the session
+# might run as exactly that user and find no daemon. `failed` records any such
+# home and fails the whole run at the end, covering the mixed-success case where
+# one home seeds and another does not. A candidate that is not a directory (the
+# `/home/*` glob with no match, a stray file) is a genuine skip, not a home.
+seeded=0
+failed=0
+for home in "${ROOT}"/root "${ROOT}"/home/*; do
+  [ -d "$home" ] || continue
+
+  cfg="$home/.config/stacktrace"
+  if ! install -d -m 700 "$cfg" 2>/dev/null; then
+    echo "✗ cannot create $cfg — not seeding $home" >&2; failed=1; continue
+  fi
+
+  if ! printf '%s\n' "$ASSET_ID" > "$cfg/asset-id" 2>/dev/null; then
+    echo "✗ cannot write $cfg/asset-id — not seeding $home" >&2; failed=1; continue
+  fi
+  chmod 600 "$cfg/asset-id" 2>/dev/null || true
+
+  # Register the SessionStart hook, merging so any existing settings survive.
+  # The hook is the point of seeding a home — a home whose registration fails
+  # (an unwritable path, or a settings.json that is valid JSON of an unexpected
+  # shape) is a failure, not a skip, or setup would exit 0 having left that
+  # session with no daemon.
+  if ! python3 - "$home" <<'PY'
+import json, pathlib, sys
+home = pathlib.Path(sys.argv[1])
+p = home / ".claude" / "settings.json"
+command = "/usr/local/bin/stacktrace-boot.sh"
+try:
+    p.parent.mkdir(parents=True, exist_ok=True)
+    if p.exists():
+        # Present but unreadable or not valid JSON: do not clobber a real file.
+        s = json.loads(p.read_text())
+    else:
+        s = {}
+except Exception:
+    sys.exit(1)
+# A settings.json Claude Code accepts is a JSON object with object-shaped
+# `hooks` and a list-shaped `SessionStart`; anything else is a shape this must
+# not silently rewrite, so it fails the home rather than guessing.
+if not isinstance(s, dict):
+    sys.exit(1)
+hooks = s.setdefault("hooks", {})
+if not isinstance(hooks, dict):
+    sys.exit(1)
+starts = hooks.setdefault("SessionStart", [])
+if not isinstance(starts, list):
+    sys.exit(1)
+# Dedup only against an entry that actually fires on the events we need. An
+# existing entry carrying this command under a narrower matcher (say `compact`)
+# does not start the daemon at session start, so it must not suppress the
+# `startup|resume` registration. A matcher covers us when it names both events,
+# or when it is absent/empty — Claude Code treats that as matching every event.
+required = {"startup", "resume"}
+
+
+def covers(entry):
+    matcher = entry.get("matcher")
+    if matcher is None or matcher == "":
+        return True
+    return required.issubset({t.strip() for t in str(matcher).split("|")})
+
+
+already = any(
+    isinstance(e, dict)
+    and covers(e)
+    and any(isinstance(h, dict) and h.get("command") == command for h in e.get("hooks", []))
+    for e in starts
+)
+if not already:
+    starts.append({"matcher": "startup|resume",
+                   "hooks": [{"type": "command", "command": command}]})
+try:
+    p.write_text(json.dumps(s, indent=2) + "\n")
+except Exception:
+    sys.exit(1)
+PY
+  then
+    echo "✗ could not register the hook in $home — not seeding it" >&2
+    failed=1
+    continue
+  fi
+
+  # Root created these directories, so they are root-owned; give them to the
+  # home's owner or the session user cannot write its own config. The parent
+  # `.config` that `install -d` created is chowned as well as the leaf, since a
+  # root-owned .config blocks the user from creating any other config beneath it.
+  for d in "$home/.config" "$cfg" "$home/.claude"; do
+    [ -e "$d" ] && chown --reference="$home" "$d" 2>/dev/null || true
+  done
+  chown --reference="$home" "$cfg/asset-id" \
+    "$home/.claude/settings.json" 2>/dev/null || true
+
+  echo "✓ seeded $home"
+  seeded=$((seeded + 1))
+done
+
+if [ "$seeded" -eq 0 ]; then
+  echo "✗ no home directory was writable — every session will mint its own identity" >&2
+  exit 1
+fi
+
+if [ "$failed" -ne 0 ]; then
+  echo "✗ one or more home directories could not be seeded — a session running as" \
+       "that user would have no daemon, so failing the whole setup rather than" \
+       "accepting a snapshot that works for some users and not others" >&2
+  exit 1
+fi
+
+command -v stacktrace >/dev/null 2>&1 || echo "! stacktrace is not on PATH yet; the boot hook waits for it" >&2
+
+echo "✓ asset id:     $ASSET_ID"
+echo "✓ homes seeded: $seeded"
+exit 0

stacktrace_cli/daemon/activity_log.py

@@ -0,0 +1,94 @@
+"""The daemon's activity log: leveled, private and capped (ADR-0048).
+
+Every module logs to its own `logging.getLogger(__name__)`. Only the daemon
+attaches a file handler, to the `stacktrace_cli` package logger; everywhere
+else the package's `NullHandler` keeps those lines off the terminal.
+
+A line names kinds, counts, class names and event ids. It never carries a
+finding's title or body, an exception message, or anything from a transcript,
+and a peer-supplied session id is written with `%r`.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+from collections.abc import Mapping
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from stacktrace_cli.private_state import ensure_private_directory
+
+LEVEL_VARIABLE = "STACKTRACE_DAEMON_LOG_LEVEL"
+MAX_BYTES = 5 * 1024 * 1024
+BACKUP_COUNT = 1
+PACKAGE = "stacktrace_cli"
+
+
+def private_opener(path: str, flags: int) -> int:
+    return os.open(path, flags, 0o600)
+
+
+class _PrivateRotatingFileHandler(RotatingFileHandler):
+    def __init__(self, path: Path, *, max_bytes: int, own_std_streams: bool) -> None:
+        self._own_std_streams = own_std_streams
+        super().__init__(path, maxBytes=max_bytes, backupCount=BACKUP_COUNT, encoding="utf-8")
+
+    def _open(self):  # type: ignore[override]
+        stream = open(  # noqa: SIM115 - the handler owns and closes it
+            self.baseFilename,
+            self.mode,
+            encoding=self.encoding,
+            errors=self.errors,
+            opener=private_opener,
+        )
+        # The opener's mode applies only to a file it creates.
+        os.chmod(self.baseFilename, 0o600)
+        return stream
+
+    def doRollover(self) -> None:
+        super().doRollover()
+        # The detached launcher points this process's stdout and stderr at
+        # the file just renamed away. Follow it, or a crash traceback lands in
+        # the backup and is deleted with it at the next rollover.
+        if self._own_std_streams and self.stream is not None:
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os.dup2(self.stream.fileno(), 1)
+            os.dup2(self.stream.fileno(), 2)
+
+
+def level_from(environment: Mapping[str, str]) -> int:
+    name = environment.get(LEVEL_VARIABLE, "").strip().upper()
+    return logging.getLevelNamesMapping().get(name, logging.DEBUG)
+
+
+def configure(
+    path: Path,
+    *,
+    environ: Mapping[str, str] | None = None,
+    own_std_streams: bool = False,
+    max_bytes: int = MAX_BYTES,
+) -> logging.Handler:
+    ensure_private_directory(path.parent)
+    handler = _PrivateRotatingFileHandler(
+        path, max_bytes=max_bytes, own_std_streams=own_std_streams
+    )
+    formatter = logging.Formatter(
+        "%(asctime)s %(levelname)s %(name)s: %(message)s", datefmt="%Y-%m-%dT%H:%M:%SZ"
+    )
+    formatter.converter = time.gmtime
+    handler.setFormatter(formatter)
+    logger = logging.getLogger(PACKAGE)
+    logger.setLevel(level_from(os.environ if environ is None else environ))
+    logger.addHandler(handler)
+    return handler
+
+
+def release(handler: logging.Handler) -> None:
+    logger = logging.getLogger(PACKAGE)
+    logger.removeHandler(handler)
+    logger.setLevel(logging.NOTSET)
+    handler.close()

stacktrace_cli/daemon/bom.py

@@ -0,0 +1,56 @@
+"""The BOM job: `sync_endpoint()` on a timer.
+
+A full snapshot of what is installed, not an append stream — so there is nothing
+to cursor, and the spool already handles offline retry. It reads no part of the
+finding queue, and it must upload on a machine with a broken detector, an empty
+database, or no session ever scanned.
+
+**It re-collects rather than uploading the daemon's warm `CompositionSnapshots`.**
+`docs/specs/remote-sync.md`'s bar requires the payload be byte-identical to
+OpenACA's for the same endpoint state, and the snapshot is built for a different
+scope — `("claude-code", None)`, user scope with no project layering — by a
+different path than `_collect()`. Reusing it would be a payload change wearing
+the costume of a performance win.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from stacktrace_cli.remote.sync import SyncError, sync_endpoint
+
+
+@dataclass(frozen=True)
+class BomJobReport:
+    """What one run did, for a caller that has to tell the two zeros apart.
+
+    A machine with nothing installed and a machine that could not reach the
+    Cloud both upload nothing. The scheduled job does not care — it is due
+    again either way — but `stacktrace daemon sync-bom` is asked by a person,
+    and answering "0" to both is answering neither.
+    """
+
+    uploaded: int
+    failure: str | None = None
+
+
+def run_bom_job(*, report: Callable[[str], None]) -> BomJobReport:
+    """One `sync endpoint`, with its progress sent somewhere a daemon can write.
+
+    `drain_the_spool` and `allow_offline_cache` semantics are exactly as the CLI
+    has them: a machine that is offline caches its collection and the next run
+    replays it. `SyncError` is an outcome here rather than an exit code — there
+    is no process to exit — so it is reported and the job is simply due again.
+    """
+    try:
+        results = sync_endpoint(
+            project=None,
+            quiet=True,
+            allow_offline_cache=True,
+            reporter=report,
+        )
+    except SyncError as error:
+        report(f"bom sync: {error}")
+        return BomJobReport(uploaded=0, failure=str(error))
+    return BomJobReport(uploaded=len(results))