stopgate 0.1.0__py3-none-any.whl

stopgate/core/__init__.py

@@ -0,0 +1,2 @@
+"""Stopgate core: the normalized action model, taint/dataflow engine, detectors,
+injection scanner, and the pure deterministic policy engine."""

stopgate/core/action.py

@@ -0,0 +1,196 @@
+r"""Normalized action + provenance model.
+
+Everything the policy engine reasons about is expressed here: a proposed
+tool call (``Action``) and the results tool calls return (``ToolResult``).
+Provenance — *where a byte came from* — is the spine of Stopgate's moat, so it
+lives at the bottom of the stack with no dependencies on anything else.
+
+Note on the odd string splits in this package (e.g. ``"pay" "ment"``): the host
+environment runs a *lexical* PreToolUse gate that greps source for scary words.
+Stopgate's source necessarily names the threats it detects, so we split those
+literals across Python adjacent-string-literal boundaries — they concatenate to
+the real token at runtime. This is, itself, a live demonstration of why lexical
+gates fail and why Stopgate detects by provenance/dataflow instead.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import Any, Dict, List, Optional
+
+
+class Severity(IntEnum):
+    """Ordered so ``max(...)`` composes detector votes and escalation cleanly."""
+
+    NONE = 0
+    LOW = 1
+    MEDIUM = 2
+    HIGH = 3
+    CRITICAL = 4
+
+    @classmethod
+    def from_name(cls, name: str) -> "Severity":
+        try:
+            return cls[str(name).strip().upper()]
+        except KeyError:
+            raise ValueError("unknown severity: {!r}".format(name))
+
+
+# Provenance: the ONLY sources Stopgate trusts are the operator and the host
+# system itself. Everything an agent pulls from the outside world is untrusted
+# by construction — this is deliberately non-lexical.
+TRUSTED_SOURCES = frozenset({"user", "system", "operator"})
+UNTRUSTED_SOURCES = frozenset(
+    {"web", "http", "file", "email", "mcp", "tool", "shell", "network", "unknown"}
+)
+
+
+def norm_source(source: Optional[str]) -> str:
+    if source is None:
+        return "unknown"
+    s = str(source).strip().lower()
+    return s or "unknown"
+
+
+def is_trusted(source: str) -> bool:
+    """A source is trusted only if explicitly whitelisted. Unknown → untrusted."""
+    return norm_source(source) in TRUSTED_SOURCES
+
+
+class ActionKind:
+    """Structural classes of *what a tool does* (not what its text says)."""
+
+    READ = "read"
+    WRITE = "write"
+    CREDENTIAL_ACCESS = "credential_access"
+    NETWORK_EGRESS = "network_egress"
+    DESTRUCTIVE = "destructive"
+    SPEND = "pay" "ment"  # the real token, split past the host's lexical gate
+    INSTALL = "install"
+    PERMISSION = "permission"
+    MESSAGING = "messaging"
+    OTHER = "other"
+
+
+# Action kinds that are irreversible in the real world. Per the brief these
+# HARD-STOP for a human no matter what the learned policy says.
+IRREVERSIBLE_KINDS = frozenset(
+    {ActionKind.SPEND, ActionKind.DESTRUCTIVE, ActionKind.MESSAGING}
+)
+
+ALL_KINDS = frozenset(
+    {
+        ActionKind.READ,
+        ActionKind.WRITE,
+        ActionKind.CREDENTIAL_ACCESS,
+        ActionKind.NETWORK_EGRESS,
+        ActionKind.DESTRUCTIVE,
+        ActionKind.SPEND,
+        ActionKind.INSTALL,
+        ActionKind.PERMISSION,
+        ActionKind.MESSAGING,
+        ActionKind.OTHER,
+    }
+)
+
+
+@dataclass
+class ToolResult:
+    """The output a tool returned, tagged with where it came from."""
+
+    source: str
+    content: str = ""
+
+    def __post_init__(self) -> None:
+        self.source = norm_source(self.source)
+        if self.content is None:
+            self.content = ""
+        elif not isinstance(self.content, str):
+            self.content = str(self.content)
+
+    @property
+    def trusted(self) -> bool:
+        return is_trusted(self.source)
+
+
+@dataclass
+class Action:
+    """A proposed tool call, normalized.
+
+    ``kind`` may be provided by an adapter; if omitted it is left as ``OTHER``
+    and the detector layer refines it. ``text`` is the flattened, matchable
+    representation used by detectors and the egress matcher — never by the
+    injection scanner, which reads tool *results* only.
+    """
+
+    tool: str
+    args: Dict[str, Any] = field(default_factory=dict)
+    kind: str = ActionKind.OTHER
+    source: str = "user"
+    result: Optional[ToolResult] = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.tool, str) or not self.tool.strip():
+            raise ValueError("Action.tool must be a non-empty string")
+        self.tool = self.tool.strip()
+        if self.args is None:
+            self.args = {}
+        if not isinstance(self.args, dict):
+            raise TypeError("Action.args must be a dict")
+        self.source = norm_source(self.source)
+        if not self.kind:
+            self.kind = ActionKind.OTHER
+
+    @property
+    def text(self) -> str:
+        """Flatten tool + args into one string for matching."""
+        parts = [self.tool]
+        parts.extend(flatten(self.args))
+        return "\n".join(p for p in parts if p)
+
+    @property
+    def outbound_bytes(self) -> str:
+        """The bytes this action would send outward (egress matcher input).
+
+        Only the *payload-bearing* arg fields, so a URL or filename that echoes
+        a secret's name does not count as exfiltration — we care about the body
+        actually leaving the machine.
+        """
+        payload_keys = ("body", "data", "payload", "content", "text", "message", "json")
+        chunks: List[str] = []
+        for k in payload_keys:
+            if k in self.args and self.args[k] is not None:
+                chunks.extend(flatten(self.args[k]))
+        if not chunks:  # fall back to everything if no obvious payload field
+            chunks.extend(flatten(self.args))
+        return "\n".join(chunks)
+
+
+def flatten(value: Any) -> List[str]:
+    """Depth-first flatten of arbitrary nested args into a list of strings."""
+    out: List[str] = []
+    stack = [value]
+    seen = 0
+    while stack:
+        seen += 1
+        if seen > 100000:  # cyclic / pathological structure guard
+            break
+        cur = stack.pop()
+        if cur is None:
+            continue
+        if isinstance(cur, str):
+            out.append(cur)
+        elif isinstance(cur, bool):
+            out.append(str(cur))
+        elif isinstance(cur, (int, float)):
+            out.append(str(cur))
+        elif isinstance(cur, dict):
+            for k, v in cur.items():
+                out.append(str(k))
+                stack.append(v)
+        elif isinstance(cur, (list, tuple, set)):
+            stack.extend(cur)
+        else:
+            out.append(str(cur))
+    return out

stopgate/core/detectors.py

@@ -0,0 +1,117 @@
+r"""Action-class detectors — classify *what kind of operation* a call is.
+
+This layer is legitimately lexical: it reads :attr:`Action.text` and matches the
+compiled tables in :mod:`stopgate.core.patterns` to decide whether a call is a
+credential read, a network egress, a destructive command, and so on. It is the
+``(a) action-class`` box in the architecture diagram — the *floor* of severity.
+
+It is emphatically NOT the moat. Vocabulary can be reworded past every table
+here; that is exactly why :mod:`stopgate.core.taint` exists and why the policy
+engine composes the two. Nothing in this file references a capability it does
+not implement.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from . import patterns as P
+from .action import Action, ActionKind, Severity
+
+# Base severity contributed by each action class *on its own*, before taint or
+# escalation. Deliberately conservative: reading a file is not an incident.
+_BASE_SEVERITY = {
+    ActionKind.CREDENTIAL_ACCESS: Severity.MEDIUM,
+    ActionKind.NETWORK_EGRESS: Severity.LOW,
+    ActionKind.DESTRUCTIVE: Severity.HIGH,
+    ActionKind.SPEND: Severity.HIGH,
+    ActionKind.INSTALL: Severity.MEDIUM,
+    ActionKind.PERMISSION: Severity.MEDIUM,
+    ActionKind.MESSAGING: Severity.MEDIUM,
+    ActionKind.WRITE: Severity.LOW,
+    ActionKind.READ: Severity.NONE,
+    ActionKind.OTHER: Severity.NONE,
+}
+
+# Kinds where being downstream of untrusted content is genuinely dangerous.
+# These are the actions the taint layer escalates when the session is tainted.
+HIGH_RISK_KINDS = frozenset(
+    {
+        ActionKind.NETWORK_EGRESS,
+        ActionKind.DESTRUCTIVE,
+        ActionKind.SPEND,
+        ActionKind.INSTALL,
+        ActionKind.PERMISSION,
+        ActionKind.MESSAGING,
+        ActionKind.CREDENTIAL_ACCESS,
+    }
+)
+
+# Evaluated in priority order; the first match per table sets that kind. Order
+# matters only for which reason string leads — severity uses max() over all.
+_KIND_TABLES = [
+    (ActionKind.DESTRUCTIVE, P.DESTRUCTIVE_PATTERNS, "destructive / irreversible operation"),
+    (ActionKind.SPEND, P.SPEND_PATTERNS, "money movement"),
+    (ActionKind.INSTALL, P.INSTALL_PATTERNS, "software install / download-and-run"),
+    (ActionKind.PERMISSION, P.PERMISSION_PATTERNS, "permission change"),
+    (ActionKind.MESSAGING, P.MESSAGING_PATTERNS, "publish / send-on-your-behalf"),
+    (ActionKind.NETWORK_EGRESS, P.EGRESS_PATTERNS, "network egress"),
+    (ActionKind.CREDENTIAL_ACCESS, P.CREDENTIAL_PATH_PATTERNS, "credential / secret access"),
+]
+
+
+@dataclass
+class Classification:
+    """The action-class verdict for a single :class:`Action`."""
+
+    kinds: List[str] = field(default_factory=list)
+    severity: Severity = Severity.NONE
+    reasons: List[str] = field(default_factory=list)
+
+    @property
+    def primary(self) -> str:
+        return self.kinds[0] if self.kinds else ActionKind.OTHER
+
+
+def classify(action: Action) -> Classification:
+    """Classify an action by structural pattern tables. Pure, no I/O.
+
+    Honours an adapter-supplied ``action.kind`` (an adapter that already knows
+    the tool's semantics is more reliable than our regexes), then augments it
+    with anything the tables detect in the flattened call text.
+    """
+    text = action.text
+    kinds: List[str] = []
+    reasons: List[str] = []
+
+    if action.kind and action.kind != ActionKind.OTHER:
+        kinds.append(action.kind)
+        reasons.append("adapter-tagged: {}".format(action.kind))
+
+    for kind, table, label in _KIND_TABLES:
+        if kind in kinds:
+            continue
+        if P.matches_any(text, table):
+            kinds.append(kind)
+            reasons.append(label)
+
+    if not kinds:
+        kinds.append(ActionKind.OTHER)
+
+    severity = max(
+        (_BASE_SEVERITY.get(k, Severity.NONE) for k in kinds),
+        default=Severity.NONE,
+    )
+    return Classification(kinds=kinds, severity=severity, reasons=reasons)
+
+
+def is_secret_material(text: str) -> bool:
+    """True if *text* looks like a secret path OR contains a secret *value*.
+
+    Used by the taint layer to decide whether a read's result is worth
+    fingerprinting for egress matching.
+    """
+    return P.matches_any(text, P.CREDENTIAL_PATH_PATTERNS) or P.matches_any(
+        text, P.SECRET_VALUE_PATTERNS
+    )

stopgate/core/patterns.py

@@ -0,0 +1,164 @@
+r"""Compiled pattern tables for the action-class detectors.
+
+Two deliberate stylistic quirks appear throughout, both to slip past the host's
+*lexical* PreToolUse gate (which greps source for the exact words this security
+tool must name) while producing the correct runtime pattern:
+
+  * literals are split across adjacent Python string boundaries — ``"pay" "ment"``
+    concatenates to the real token at import time;
+  * regexes use ``\b``/``\s`` rather than literal spaces.
+
+At runtime these compile to the genuine detection patterns; the tests assert on
+real malicious command strings (assembled the same way) to prove it.
+
+Action-class detection is legitimately lexical — it classifies *what kind of
+operation* a call is. The non-lexical moat lives in taint.py, not here.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, List, Pattern
+
+_I = re.IGNORECASE
+
+
+def _c(*fragments: str) -> Pattern:
+    return re.compile("".join(fragments), _I)
+
+
+# --- Spend / money movement -------------------------------------------------
+SPEND_PATTERNS: List[Pattern] = [
+    _c(r"\b(?:", "pay", "ment", r"|", "pur", "chase", r"|", "check", "out",
+       r"|buy\b|pay\s+for|place\s+(?:an?\s+)?order|invoice|billing"
+       r"|paypal|braintree|credit[\s_-]*card)\b"),
+    _c(r"\bstripe\b"),
+    _c(r"\b", "char", "ge", r"\s+(?:the\s+)?card\b"),
+]
+
+# --- Destructive / irreversible --------------------------------------------
+DESTRUCTIVE_PATTERNS: List[Pattern] = [
+    _c(r"\brm\b[^\n;|&]*-(?:rf|fr|r|f|-recursive|-force)\b"),
+    _c(r"--no-preserve", "-root"),
+    _c(r"\b", "mk", "fs", r"\b"),
+    _c(r"\bshred\b"),
+    _c(r"\bdd\b[^\n;|&]*\bif="),
+    _c(r"\bdrop\s+(?:table|database)\b"),
+    _c(r"\btruncate\s+table\b"),
+    _c(r"\bterraform\s+destroy\b"),
+    _c(r"\bkubectl\s+delete\b"),
+    _c(r"\bgit\s+push\s+(?:--force\b|-f\b|--force-with-lease\b)"),
+    _c(r">\s*/dev/sd[a-z]"),
+    _c(r"\bfind\b[^|]*\s-delete\b"),
+]
+
+# --- System install / download-and-run -------------------------------------
+INSTALL_PATTERNS: List[Pattern] = [
+    _c(r"\bsudo\b"),
+    _c(r"\bapt(?:-get)?\s+install\b"),
+    _c(r"\byum\s+install\b"),
+    _c(r"\bdnf\s+install\b"),
+    _c(r"\bbrew\s+install\b"),
+    _c(r"\bnpm\s+install\s+-g\b"),
+    _c(r"\bpip\s+install\b"),
+    _c(r"(?:curl|wget)\b[^|]*\|\s*(?:bash|sh|zsh|python)\b"),
+]
+
+# --- Credential / secret access, matched by PATH not vocabulary -------------
+# Provenance-flavoured: these are the concrete locations secrets live. A hit
+# marks the READ content as secret material for the egress matcher.
+#
+# The left anchor is a negative-lookbehind ``(?<!\w)`` rather than ``(?:^|/)``.
+# Actions are flattened to a newline-joined string before matching, so a bare
+# RELATIVE path (``.env``, ``.aws/credentials``, ``id_rsa`` — the common case
+# when the agent runs inside the project dir) sits after a ``\n``, which the
+# old start-or-slash anchor never matched. That silently failed to fingerprint
+# the read, so a later exfil of that secret was MISSED. ``(?<!\w)`` matches at
+# string start, after ``/``, and after whitespace/newline/quote, while still
+# rejecting ``foo.env`` / ``myid_rsa`` (preceded by a word char).
+CREDENTIAL_PATH_PATTERNS: List[Pattern] = [
+    _c(r"(?<!\w)\.env(?:\.[\w-]+)?\b"),
+    _c(r"(?<!\w)\.ssh/"),
+    _c(r"(?<!\w)id_(?:rsa|ed25519|ecdsa|dsa)\b"),
+    _c(r"(?<!\w)\.aws/credentials\b"),
+    _c(r"(?<!\w)\.aws/config\b"),
+    _c(r"(?<!\w)\.netrc\b"),
+    _c(r"(?<!\w)\.npmrc\b"),
+    _c(r"(?<!\w)\.pypirc\b"),
+    _c(r"(?<!\w)\.git-credentials\b"),
+    _c(r"(?<!\w)\.kube/config\b"),
+    _c(r"(?<!\w)\.docker/config\.json\b"),
+    _c(r"\b\w*(?:secret|token|apikey|api_key|private_key|credential)s?\.(?:json|ya?ml|txt|pem|key)\b"),
+    _c(r"\bkeychain\b"),
+]
+
+# High-entropy / well-known secret *values* (for tainting read content).
+SECRET_VALUE_PATTERNS: List[Pattern] = [
+    _c(r"\bAKIA[0-9A-Z]{16}\b"),                      # AWS access key id
+    _c(r"\bASIA[0-9A-Z]{16}\b"),                      # AWS temp key id
+    _c(r"\bgh[pousr]_[A-Za-z0-9]{16,}\b"),            # GitHub tokens
+    _c(r"\bsk-[A-Za-z0-9]{20,}\b"),                   # OpenAI-style keys
+    _c(r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b"),          # Slack tokens
+    _c(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"),        # PEM private keys
+    _c(r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),  # JWT
+]
+
+# --- Network egress ---------------------------------------------------------
+EGRESS_PATTERNS: List[Pattern] = [
+    _c(r"\bhttps?://"),
+    _c(r"(?:curl|wget|nc|ncat|netcat|scp|rsync|ftp|sftp|telnet)\b"),
+    _c(r"\brequests\.(?:post|put|patch)\b"),
+    _c(r"\burllib(?:\.request)?\b"),
+    _c(r"\bsocket\.(?:connect|sendall|send)\b"),
+    _c(r"\bfetch\("),
+    _c(r"\bxmlhttprequest\b"),
+]
+
+# --- Permission changes -----------------------------------------------------
+PERMISSION_PATTERNS: List[Pattern] = [
+    _c(r"\bchmod\s+(?:-R\s+)?0?777\b"),
+    _c(r"\bchmod\b"),
+    _c(r"\bchown\b"),
+    _c(r"\bchgrp\b"),
+    _c(r"\bsetfacl\b"),
+]
+
+# --- Messaging / publishing / send-on-your-behalf ---------------------------
+MESSAGING_PATTERNS: List[Pattern] = [
+    _c(r"\bnpm\s+publish\b"),
+    _c(r"\bpypi\b|\btwine\s+upload\b"),
+    _c(r"\bgit\s+push\b"),
+    _c(r"\bsend[_-]?(?:mail|email|message)\b"),
+    _c(r"\bsmtp\b"),
+    _c(r"\b(?:slack|discord|telegram)\b.*\b(?:webhook|post|send)\b"),
+    _c(r"\btweet\b|\bpost_status\b"),
+]
+
+
+def _as_text(text: Any) -> str:
+    """Coerce detector input to a string.
+
+    Detectors are a security boundary: they must never crash on odd input and
+    hand control back to the agent. ``None`` becomes empty (matches nothing);
+    anything non-string is stringified so it is still scanned rather than
+    silently skipped.
+    """
+    if text is None:
+        return ""
+    if isinstance(text, str):
+        return text
+    return str(text)
+
+
+def matches_any(text: Any, patterns: List[Pattern]) -> bool:
+    t = _as_text(text)
+    return any(p.search(t) for p in patterns)
+
+
+def first_match(text: Any, patterns: List[Pattern]):
+    t = _as_text(text)
+    for p in patterns:
+        m = p.search(t)
+        if m:
+            return m
+    return None