stacktrace-cli 0.14.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

stacktrace/__init__.py

@@ -2,7 +2,7 @@
 
 import logging as _logging
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 # 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

stacktrace/daemon/config.py

@@ -32,6 +32,10 @@ SETTINGS: tuple[tuple[str, str, str], ...] = (
     # already inherits TYPESAFE_API_KEY -- by setting the environment
     # variable before forking, not by re-typing the flag.
     ("reasoning", "STACKTRACE_REASONING", "false"),
+    # ADR-0151: off unless a gateway on this host asks the daemon. Set only
+    # through the environment; `daemon run` gains no flag for it.
+    ("gateway_listen", "STACKTRACE_GATEWAY_LISTEN", "off"),
+    ("gateway_mode", "STACKTRACE_GATEWAY_MODE", "enforce"),
 )
 
 _UNITS: dict[str, int] = {"s": 1, "m": 60, "h": 3600, "d": 86400}
@@ -131,6 +135,22 @@ def parse_reasoning(value: str) -> bool:
     return normalized == "true"
 
 
+def parse_listen(value: str) -> tuple[str, int] | None:
+    """`off`, or `host:port` for the gateway listener (ADR-0151)."""
+    if value == "off":
+        return None
+    host, _, port = value.rpartition(":")
+    if not host or not port.isdigit() or not 0 <= int(port) <= 65535:
+        raise ValueError(f"gateway listen address must be 'off' or host:port, not {value!r}")
+    return host, int(port)
+
+
+def parse_gateway_mode(value: str) -> str:
+    if value not in ("enforce", "observe"):
+        raise ValueError(f"gateway mode must be 'enforce' or 'observe', not {value!r}")
+    return value
+
+
 @dataclass(frozen=True)
 class Setting:
     """One resolved value, the text it was resolved from, and where that came from."""
@@ -150,6 +170,8 @@ class DaemonConfig:
     webhook_interval: Setting
     bom_interval: Setting
     reasoning: Setting
+    gateway_listen: Setting
+    gateway_mode: Setting
 
     @property
     def scan_interval_seconds(self) -> float:
@@ -249,6 +271,8 @@ class DaemonConfig:
             "webhook_interval": webhook_interval,
             "bom_interval": bom_interval,
             "reasoning": None if reasoning is None else ("true" if reasoning else "false"),
+            "gateway_listen": None,
+            "gateway_mode": None,
         }
         resolved: dict[str, Setting] = {}
         for name, variable, default in SETTINGS:
@@ -274,6 +298,8 @@ class DaemonConfig:
             config.webhook_interval_seconds,
             config.bom_interval_seconds,
             config.reasoning_enabled,
+            parse_listen(config.gateway_listen.value),
+            parse_gateway_mode(config.gateway_mode.value),
         )
         if not config.kinds:
             raise ValueError("--agent-kind must name at least one agent kind")

stacktrace/daemon/fleet.py

@@ -407,7 +407,10 @@ class FleetSubscriber:
             self._run_names[run_id] = self.store.run_names(agent_kind, run_id)
         names = self._run_names[run_id]
         if names is None:
-            return None, None, None, None
+            # A gateway run has no usage row; its finding names the account
+            # the gateway verified, whose card the store keeps (ADR-0153).
+            account = session.get("account") if isinstance(session, dict) else None
+            return None, None, account if isinstance(account, str) and account else None, None
         signed = self._signed_in
         same = signed is not None and names.account is not None and names.account == signed[0]
         person = signed[1] if same and signed is not None else None

stacktrace/daemon/gateway.py

@@ -0,0 +1,153 @@
+"""The daemon's gateway listener: ADR-0119's contract, answered by the daemon (ADR-0151).
+
+A gateway on this host (the LiteLLM guardrail, the Envoy Lua filter) asks the
+same `/v1/evaluate` and `/v1/observe` it asks `stacktrace guard serve`. The
+rules, the fail-open behaviour and the reply are the guard's own. What changes
+is where a finding goes: into the daemon's `FindingStore`, so the Fleet drain
+uploads it and the notification sinks hear of it, as for a transcript finding.
+
+Off unless `STACKTRACE_GATEWAY_LISTEN` names an address. The private Unix
+socket and its `authorize` message are untouched: a gateway turn is far larger
+than that socket's frame and carries the arguments its contract excludes.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from datetime import UTC, datetime
+from http.server import ThreadingHTTPServer
+
+from stacktrace.cost.usage import AccountCard
+from stacktrace.detector.finding import Detection
+from stacktrace.detector.render import detection_json
+from stacktrace.gateway.analyzer import PolicyCheck
+from stacktrace.gateway.principal import Principal, session_key_id
+from stacktrace.gateway.service import Guard, loopback, make_server, serve_in_thread
+from stacktrace.gateway.sink import Recorder, Stamp
+
+from .accounts import email_digest
+from .config import DaemonConfig, parse_listen
+from .store import FindingStore, Notification, SessionKey
+from .usage import person_name
+
+__all__ = ["parse_listen", "start_gateway"]
+
+logger = logging.getLogger(__name__)
+
+
+class _LogSink:
+    """Verdict, fallback and call records go to the daemon's log; they are content-free."""
+
+    def write(self, record: dict[str, object]) -> None:
+        logger.info("gateway %s", json.dumps(record))
+
+
+def _qualify_spans(payload: dict[str, object], agent_kind: str, bare: str, keyed: str) -> str:
+    """Rename the client's bare session to `agent_kind:keyed` everywhere the finding names it.
+
+    Fleet refuses a finding whose evidence span, or whose target's session or
+    span, addresses another session than its own, so renaming only
+    `session.session_id` costs every gateway finding a 422.
+    """
+    qualified = f"{agent_kind}:{keyed}"
+
+    def span(value: object) -> object:
+        if isinstance(value, str) and value.rsplit(":", 2)[0] == bare:
+            return qualified + value[len(bare) :]
+        return value
+
+    for key in ("evidence", "finding_targets"):
+        rows = payload.get(key)
+        for row in rows if isinstance(rows, list) else ():
+            if not isinstance(row, dict):
+                continue
+            if "span" in row:
+                row["span"] = span(row["span"])
+            if row.get("session_id") == bare:
+                row["session_id"] = qualified
+    return qualified
+
+
+def _card(principal: Principal) -> AccountCard:
+    """The card a gateway principal travels with (ADR-0153). An email keeps
+    ADR-0112's digest and name, so its person key is a laptop run's; any
+    other id has no address, so no key and no name."""
+    email = principal.email()
+    name = person_name(None, email)
+    return AccountCard(
+        account=principal.account_id(),
+        email_digest=email_digest(email),
+        display_name=name,
+        plan=None,
+        seen_at=datetime.now(UTC).isoformat(),
+        name_from="email" if name else None,
+    )
+
+
+def _store_finding(
+    store: FindingStore,
+    publish: Callable[[Notification], None],
+    on_commit: Callable[[], None],
+) -> Callable[[Detection, Stamp], None]:
+    def write(detection: Detection, stamp: Stamp) -> None:
+        kind = detection.session.agent_kind
+        # Keyed by agent kind, session id and principal (ADR-0151), so two
+        # people's sessions never merge in the store or in Fleet.
+        session = SessionKey(kind, session_key_id(detection.session.session_id, stamp.principal))
+        payload = detection_json(detection)
+        # The store names a session by the qualified id a transcript's
+        # findings carry; a gateway session's id is the client's bare one.
+        document = payload["session"]
+        assert isinstance(document, dict)
+        document["session_id"] = _qualify_spans(
+            payload, kind, detection.session.session_id, session.session_id
+        )
+        payload["actor"] = stamp.actor
+        payload["action"] = stamp.action
+        payload["decided_by"] = stamp.decided_by
+        if stamp.principal is not None:
+            # The run's account and its card, as a laptop run's sign-in has
+            # them, so Fleet names the person with no new field (ADR-0153).
+            document["account"] = stamp.principal.account_id()
+            store.put_account_card(kind, _card(stamp.principal))
+        notifications = store.record(session, (payload,), underbuilt=None)
+        # As a scan commit does, so the finding leaves before the next drain interval.
+        on_commit()
+        for notification in notifications:
+            publish(notification)
+
+    return write
+
+
+def start_gateway(
+    config: DaemonConfig,
+    store: FindingStore,
+    publish: Callable[[Notification], None],
+    *,
+    token: str | None = None,
+    on_commit: Callable[[], None] = lambda: None,
+    policy: PolicyCheck | None = None,
+) -> ThreadingHTTPServer | None:
+    """Serve the guard contract on the configured address, or nothing when it is off."""
+    address = parse_listen(config.gateway_listen.value)
+    if address is None:
+        return None
+    if token is None and not loopback(address[0]):
+        logger.error("gateway listener not started: %s needs STACKTRACE_GUARD_TOKEN", address[0])
+        return None
+    mode = "observe" if config.gateway_mode.value == "observe" else "enforce"
+    recorder = Recorder(
+        [_LogSink()], on_finding=_store_finding(store, publish, on_commit), verdicts=True
+    )
+    try:
+        server = make_server(Guard(recorder=recorder, mode=mode, policy=policy), *address, token)
+    except OSError as error:
+        # The gateway fails open without us; scans and hooks must not stop too.
+        logger.error("gateway listener not started on %s:%s: %s", *address, error)
+        return None
+    serve_in_thread(server)
+    host, port = server.server_address[:2]
+    logger.info("gateway listener: %s on %s:%s", mode, host, port)
+    return server

stacktrace/daemon/gateway_policy.py

@@ -0,0 +1,161 @@
+"""Fleet policy at the gateway: the calls in a model response, judged by name (ADR-0151).
+
+The hook path resolves a component from local evidence. A gateway sees only the
+names the model sees, so this maps each pending call to a policy subject by
+name, through each agent kind's own naming map, and asks the same `decide`
+the hook path asks for a subject it could not resolve.
+
+- A plugin the policy names by `plugin@marketplace` matches its name alone:
+  the gateway sees no marketplace. A name both allowed and blocked is
+  ambiguous and is not blocked (ADR-0135 decision 4).
+- An MCP server rule names a command or a URL, never a name, so no MCP server
+  rule matches at the gateway. Only its category default can.
+- A subject the policy does not name passes, unless the organization turned
+  category defaults on for gateways.
+- No policy, or one older than its time to live, passes and is a fallback.
+
+Matching by name lets a server renamed in the user's own configuration pass.
+The hooks stay the authority for components; this is the backstop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from stacktrace.gateway.analyzer import PolicyVerdict
+from stacktrace.hooks.claude import policy_message
+from stacktrace.policy_display import policy_rows
+from stacktrace.sessions.access import GatewayToolCall
+
+# `Policy` through the runtime, which is this package's one OpenACA policy importer.
+from .policy_runtime import REFRESH_INTERVAL, Policy, PolicyRuntime, Result, Subject, decide
+
+#: How old a fetched policy may be before the gateway stops enforcing it. The
+#: daemon polls Fleet at most every 60 s; an hour is the hook path's evidence
+#: refresh interval, so both paths stop trusting what they hold together.
+POLICY_TTL_S = REFRESH_INTERVAL
+
+#: The gateway cannot see which of user, project or local configured a server.
+#: All three are standalone servers under `admission.mcps`, so this one selects
+#: the same category default as the others.
+_STANDALONE = "user"
+
+
+@dataclass(frozen=True)
+class Inputs:
+    """The policy as the daemon holds it now."""
+
+    policy: Policy | None
+    revision: int | None
+    #: Seconds since the last successful Fleet fetch; None before one.
+    age_s: float | None
+
+
+def claude_code_subject(call: GatewayToolCall) -> Subject | None:
+    """Claude Code's naming map. Built-in tools are not policy subjects."""
+    server = call.mcp_server
+    if server is not None:
+        # `mcp__plugin_<plugin>_<server>__<tool>` and `mcp__claude_ai_<name>__<tool>`
+        # (code.claude.com/docs/en/mcp, /permissions).
+        if server.startswith("plugin_"):
+            return Subject("mcp_tool", server.removeprefix("plugin_"), "plugin")
+        if server.startswith("claude_ai_"):
+            return Subject("mcp_tool", server, "claudeai")
+        return Subject("mcp_tool", server, _STANDALONE)
+    if call.tool_name == "Skill":
+        skill = call.arguments.get("skill")
+        return Subject("skill", skill, "") if isinstance(skill, str) and skill else None
+    if call.tool_name in ("Task", "Agent"):
+        agent = call.arguments.get("subagent_type")
+        if isinstance(agent, str) and ":" in agent:
+            return Subject("plugin_agent", agent, "")
+    return None
+
+
+#: Each agent kind names its tools its own way. Claude Code ships first.
+SUBJECTS: dict[str, Callable[[GatewayToolCall], Subject | None]] = {
+    "claude-code": claude_code_subject,
+}
+
+
+def _sanitized(plugin: str) -> str:
+    """A plugin name as Claude Code spells it inside an MCP tool name."""
+    return "".join(c if c.isalnum() or c in "_-" else "_" for c in plugin)
+
+
+def _owned_by(subject: Subject, plugin: str) -> bool:
+    if subject.kind == "mcp_tool":
+        return subject.source == "plugin" and subject.name.startswith(_sanitized(plugin) + "_")
+    return ":" in subject.name and subject.name.partition(":")[0] == plugin
+
+
+def _by_name(subject: Subject, policy: Policy, revision: int | None) -> Result | None:
+    """The plugin rule that names this subject's plugin, or None when none does, or two disagree."""
+    matches: dict[str, str] = {}
+    for state, targets in (
+        ("allowed", policy.plugins.allowed),
+        ("blocked", policy.plugins.blocked),
+    ):
+        for index, target in enumerate(targets):
+            plugin = getattr(target, "plugin", None)
+            if plugin is not None and _owned_by(subject, plugin.rpartition("@")[0]):
+                matches.setdefault(state, f"admission.plugins.{state}[{index}]")
+    if len(matches) != 1:
+        return None
+    ((state, rule),) = matches.items()
+    if state == "allowed":
+        return Result("allow", "policy_allowed", revision, rule)
+    return Result("deny", "policy_blocked", revision, rule, dict(policy_rows(policy))[rule])
+
+
+class GatewayPolicy:
+    """The `PolicyCheck` the daemon's listener runs on each turn's pending calls."""
+
+    def __init__(
+        self,
+        read: Callable[[], Inputs],
+        *,
+        category_defaults: bool = False,
+        ttl_s: float = POLICY_TTL_S,
+    ) -> None:
+        self._read = read
+        #: The organization's opt-in to category defaults at gateways. Fleet
+        #: has no such setting yet, so the daemon passes False.
+        self.category_defaults = category_defaults
+        self._ttl_s = ttl_s
+
+    def __call__(self, calls: tuple[GatewayToolCall, ...], agent_kind: str | None) -> PolicyVerdict:
+        naming = SUBJECTS.get(agent_kind or "")
+        subjects = [s for s in map(naming, calls) if s is not None] if naming else []
+        if not subjects:
+            return PolicyVerdict()
+        inputs = self._read()
+        if inputs.policy is None:
+            return PolicyVerdict(revision=inputs.revision, fallback="policy_unavailable")
+        if inputs.age_s is None or inputs.age_s > self._ttl_s:
+            return PolicyVerdict(revision=inputs.revision, fallback="policy_stale")
+        for subject in subjects:
+            result = _by_name(subject, inputs.policy, inputs.revision)
+            if result is None and self.category_defaults:
+                result = decide(subject, inputs.policy, inputs.revision)
+            if result is not None and result.outcome == "deny":
+                return PolicyVerdict(
+                    deny=True,
+                    message=policy_message(result.rule, result.detail),
+                    revision=inputs.revision,
+                    rule=result.rule,
+                )
+        return PolicyVerdict(revision=inputs.revision)
+
+
+def runtime_inputs(runtime: PolicyRuntime) -> Callable[[], Inputs]:
+    """Read the policy the daemon's runtime holds, as the gateway needs it."""
+
+    def read() -> Inputs:
+        with runtime.cache.guard:
+            policy, revision = runtime.cache.policy, runtime.cache.state.desired_revision
+        refreshed = runtime.refreshed_at
+        return Inputs(policy, revision, None if refreshed is None else runtime.clock() - refreshed)
+
+    return read

stacktrace/daemon/policy_runtime.py

@@ -238,30 +238,51 @@ class DecisionCache:
         """Use defaults from the same policy as the active decision table."""
         if policy is None:
             return Result("defer", reason, revision)
-        if kind == "mcp_tool" and source in {"user", "project", "local", "codex"}:
-            default = policy.mcps.default
-            category = "mcps"
-        elif (
-            (kind == "mcp_tool" and source == "plugin")
-            or kind == "plugin_agent"
-            or (kind in {"skill", "command"} and ":" in name)
-        ):
-            default = policy.plugins.default
-            category = "plugins"
-        elif kind in {"skill", "command"}:
-            default = policy.skills_default
-            category = "skills"
-        else:
-            return Result("defer", reason, revision)
-        return Result(
-            "deny" if default == "blocked" else "allow",
-            "policy_default",
-            revision,
-            f"admission.{category}.default",
-            default_description(category, default),
+        return decide(Subject(kind, name, source), policy, revision) or Result(
+            "defer", reason, revision
         )
 
 
+@dataclass(frozen=True)
+class Subject:
+    """What a hook or a gateway asks about: an action kind, a name and its source."""
+
+    kind: str
+    name: str
+    source: str
+
+
+def decide(subject: Subject, policy: Policy, revision: int | None = None) -> Result | None:
+    """The category default `policy` sets for `subject`; None when no category covers it.
+
+    The one decision function ADR-0151 shares between the hook path, for a
+    subject no evidence resolved, and the gateway, which sees names only.
+    """
+    kind, name, source = subject.kind, subject.name, subject.source
+    if kind == "mcp_tool" and source in {"user", "project", "local", "codex"}:
+        default = policy.mcps.default
+        category = "mcps"
+    elif (
+        (kind == "mcp_tool" and source == "plugin")
+        or kind == "plugin_agent"
+        or (kind in {"skill", "command"} and ":" in name)
+    ):
+        default = policy.plugins.default
+        category = "plugins"
+    elif kind in {"skill", "command"}:
+        default = policy.skills_default
+        category = "skills"
+    else:
+        return None
+    return Result(
+        "deny" if default == "blocked" else "allow",
+        "policy_default",
+        revision,
+        f"admission.{category}.default",
+        default_description(category, default),
+    )
+
+
 def configuration_digest(scope: Scope, watch_paths: tuple[str, ...]) -> str:
     """Stat bounded named paths on the worker; never discover paths on a hook."""
     root, project = Path(scope.config_root), Path(scope.project_root)
@@ -319,8 +340,26 @@ class PolicyRuntime:
         self._paths: dict[Scope, tuple[str, ...]] = {}
         self._error: str | None = None
         self._last_call: float | None = None
+        #: When a Fleet fetch last succeeded, and for which enrollment. The
+        #: gateway treats a policy older than its time to live as no policy
+        #: (ADR-0151), and a fetch certifies only its own binding's policy.
+        self._refreshed: tuple[Binding, float] | None = None
         self.worker = JobThread(Job("policy", 30, self.reconcile, wakeable=True))
 
+    @property
+    def refreshed_at(self) -> float | None:
+        """When the policy the cache holds now was last fetched, or None.
+
+        None once the enrollment changes: the cache then holds another
+        binding's policy, which this fetch never certified.
+        """
+        refreshed = self._refreshed
+        with self.cache.guard:
+            binding = self.cache.binding
+        if refreshed is None or refreshed[0] != binding:
+            return None
+        return refreshed[1]
+
     def start(self) -> None:
         self.worker.start()
         self.worker.wake()
@@ -354,6 +393,7 @@ class PolicyRuntime:
                 self._fetch_at = self.clock()
                 try:
                     self.fetcher.refresh()
+                    self._refreshed = (Binding.from_config(config), self.clock())
                     self._error = None
                 except PolicyInputError:
                     self._error = "policy_refresh_failed"

stacktrace/daemon/runtime.py

@@ -43,6 +43,8 @@ from .composition import (
 from .config import DaemonConfig
 from .costs import Baseline, CostPass, NearMissLog, OrgBaselines
 from .fleet import DrainReport, FleetSubscriber
+from .gateway import start_gateway
+from .gateway_policy import GatewayPolicy, runtime_inputs
 from .jobs import Backoff, Job, JobThread, Scheduler
 from .lifecycle import StartOutcome, report_start
 from .observer import SessionObserver, analyse_batch
@@ -617,6 +619,15 @@ def run_daemon(
             fleet_thread.start()
             usage_thread.start()
             policy.start()
+            # Read from the environment only, as `guard serve` reads it.
+            gateway = start_gateway(
+                settings,
+                store,
+                server.publish,
+                token=os.environ.get("STACKTRACE_GUARD_TOKEN") or None,
+                on_commit=wake_delivery_jobs,
+                policy=GatewayPolicy(runtime_inputs(policy)),
+            )
             try:
 
                 def ready() -> None:
@@ -625,6 +636,9 @@ def run_daemon(
 
                 service.run(on_ready=ready)
             finally:
+                if gateway is not None:
+                    gateway.shutdown()
+                    gateway.server_close()
                 policy.close()
                 fleet_thread.close()
                 usage_thread.close()