quash-api 0.1.0__py3-none-any.whl

api_test_agent/__init__.py

@@ -0,0 +1 @@
+"""API testing agent — LangGraph agent + tools over the pure api_test_engine."""

api_test_agent/_arg_masking.py

@@ -0,0 +1,76 @@
+"""Redact secret-carrying tool-call ARGUMENTS before they hit the event wire /
+UI (review finding C2).
+
+The parallel tool node streams each tool call's args to stdout/UI *before* the
+tool runs. The LLM's own literal args — a ``set_variable(secret=True,
+value=<literal>)`` or an ``http_request`` ``Authorization`` header — would
+otherwise egress verbatim into LLM context, session history, and the terminal.
+Value-based masking can't help: the literal is usually a BRAND-NEW secret being
+registered, so it isn't in the known-secret list yet. So we redact by ARGUMENT
+SHAPE at the emit boundary. This affects only the EMITTED copy; the tool still
+receives the real args.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_MASK = "****"
+
+# A dict key (a body field, a query param, a nested field) whose NAME marks its
+# value as a credential — masked at ANY depth. Broad on purpose: over-redacting
+# the emitted event costs a little observability; under-redacting leaks a secret.
+_SECRET_KEY_RE = re.compile(
+    r"(secret|password|passwd|api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token"
+    r"|bearer|credential|cred|private[_-]?key|client[_-]?secret|session[_-]?(id|token)|passphrase|otp|pin)",
+    re.I,
+)
+# A HEADER name whose value is a credential (broader than the key regex — an
+# ``X-Whatever-Auth`` header is a token; ``Accept``/``Content-Type`` are not).
+_SECRET_HEADER_RE = re.compile(r"(authoriz|cookie|token|api[_-]?key|secret|credential|cred|session|auth|bearer|x-.*-key)", re.I)
+
+
+def _scrub(obj: Any, *, in_headers: bool = False) -> Any:
+    """Recursively redact credential-shaped values in a copy of *obj*."""
+    if isinstance(obj, dict):
+        out: dict[Any, Any] = {}
+        for k, v in obj.items():
+            child_headers = bool(isinstance(k, str) and k.lower() == "headers")
+            hdr_name = isinstance(k, str) and _SECRET_HEADER_RE.search(k)
+            key_secret = isinstance(k, str) and _SECRET_KEY_RE.search(k)
+            if (in_headers and hdr_name) or key_secret:
+                # Mask a credential STRING; recurse a container; but leave a
+                # bool/number/None (a `secret: true` flag, an id) alone — a flag
+                # is not a credential, and masking it would corrupt tool logic.
+                if isinstance(v, str):
+                    out[k] = _MASK
+                elif isinstance(v, (dict, list)):
+                    out[k] = _scrub(v, in_headers=child_headers)
+                else:
+                    out[k] = v
+            else:
+                out[k] = _scrub(v, in_headers=child_headers)
+        return out
+    if isinstance(obj, list):
+        return [_scrub(v, in_headers=in_headers) for v in obj]
+    return obj
+
+
+def scrub_tool_call_args(name: str, args: Any) -> Any:
+    """Return a COPY of *args* with credential-shaped values redacted at any
+    depth (headers by name, secret-named body/query fields, and the documented
+    ``set_variable`` secret value). Never mutates the input — the tool must still
+    receive the real args."""
+    if not isinstance(args, dict):
+        return args
+    out = _scrub(args)
+    # set_variable(secret=True, value=...) — the `value` key isn't credential-
+    # named, so mask it explicitly. Read the ORIGINAL flag (the scrubbed copy's
+    # `secret` is untouched now, but the original is the source of truth).
+    if name == "set_variable" and args.get("secret") and "value" in out:
+        out["value"] = _MASK
+    return out
+
+
+__all__ = ["scrub_tool_call_args"]

api_test_agent/_log_redaction.py

@@ -0,0 +1,161 @@
+"""The agent's log lines never carry a request URL's secrets (live smoke B1).
+
+httpx logs every request at INFO (``HTTP Request: GET <url> "HTTP/1.1 200"``),
+and the agent's stderr is relayed into the worker's log. :class:`RedactUrls`
+rewrites every record — its message AND its exception traceback — and
+:func:`install` also covers an UNCAUGHT exception (``sys.excepthook``). A URL
+keeps its scheme, host and path and its query keys; a query VALUE stays only
+when it is harmless: a credential-NAMED parameter (the engine's shared
+``credential_names`` rule — the cloud masks results with the same rule) or a
+token-SHAPED value under any name (a captured token in ``?cursor=``) becomes
+``…``; userinfo and fragment are dropped; the run's loaded secret values
+(:func:`set_secret_values`) are masked anywhere."""
+
+from __future__ import annotations
+
+import logging
+import re
+import sys
+import traceback
+from collections.abc import Callable, Iterable
+from typing import Final
+from urllib.parse import urlsplit
+
+from api_test_engine.credential_names import credential_query_name, token_shaped
+
+
+class _LinearPattern:
+    r"""``re.compile(pattern).sub(repl, text)``, exactly, in linear time — for a
+    pattern whose every attempt first reads a RUN (here: a URL scheme) to its
+    end, and can fail only after it.
+
+    ``re`` tries such a pattern at every start inside a run, and each attempt
+    reads the same run to the same end and fails there the same way, so a run
+    of starts is quadratic: ``a.a.a…`` (a scheme at every letter, no ``://``
+    ever found) costs one scan per start. This attempts the SAME pattern
+    (``match``ed in place, so the leading ``\b`` still reads the text before
+    it) where the first group of *seek*'s next match begins, and when an
+    attempt fails it seeks on from where *run*, read from that start, ends:
+    every start in between reads that run to that end and fails there too.
+    From wherever the scan resumes (the text's start, a match's end, a run's
+    end), *seek* finds the first start the pattern matches from, or an
+    earlier one where its first step holds (so a failed attempt is always a
+    run that failed at its end). The same matches, in the same order, through
+    the same *repl*: the same text, and no bound on any length.
+
+    Ported from ``quash_cloud.apitest.result_masking._LinearPattern`` (same
+    class, same fix for the same regex shape) rather than imported: this
+    package must never import ``quash_cloud`` (the import-linter "engine is
+    pure"-style layering this repo also applies to the agent; see
+    ``api_test_agent/cloud_rpc.py``'s own note on the reverse direction)."""
+
+    def __init__(self, pattern: str, *, seek: str, run: str) -> None:
+        self.pattern = re.compile(pattern)
+        #: Group 1 marks a start (a group keeps ``re``'s fast literal scan).
+        self._seek = re.compile(seek)
+        #: ``*``-repeated, so it always matches.
+        self._run = re.compile(run)
+
+    def sub(self, repl: Callable[[re.Match[str]], str], text: str) -> str:
+        out: list[str] = []
+        kept = pos = 0
+        while (seek := self._seek.search(text, pos)) is not None:
+            at = seek.start(1)
+            match = self.pattern.match(text, at)
+            if match is None:
+                run = self._run.match(text, at)
+                assert run is not None  # a ``*``-repeated run always matches
+                pos = max(run.end(), at + 1)
+                continue
+            out += (text[kept:at], repl(match))
+            kept = match.end()
+            pos = max(kept, at + 1)
+        out.append(text[kept:])
+        return "".join(out)
+
+
+#: Its run is the scheme. It seeks, inside ``re``, the FIRST start of each
+#: scheme run (a letter at a word boundary; the atomic group never retries a
+#: later one) that ``://`` follows: a later start of the same run ends at the
+#: same ``://``, so plain text costs no attempt at all.
+_URL: Final[_LinearPattern] = _LinearPattern(
+    r"\b[A-Za-z][A-Za-z0-9+.-]*://[^\s'\"<>]+",
+    seek=r"(?<![A-Za-z0-9+.-])(?>[A-Za-z0-9+.-]*?(\b[A-Za-z]))(?=[A-Za-z0-9+.-]*+://)",
+    run=r"[A-Za-z0-9+.-]*")
+_HIDDEN = "…"
+_MASK = "****"
+_SECRETS: list[str] = []
+
+
+def set_secret_values(values: Iterable[str]) -> None:
+    """The run's loaded secret values (masking input only, never logged)."""
+    _SECRETS[:] = sorted({str(v) for v in values if v and len(str(v)) >= 4}, key=len,
+                         reverse=True)
+
+
+def _redact(url: str) -> str:
+    try:
+        parts = urlsplit(url)
+        host = parts.hostname or ""
+        port = f":{parts.port}" if parts.port else ""
+    except ValueError:
+        return _HIDDEN
+    if ":" in host:  # an IPv6 literal
+        host = f"[{host}]"
+    out = f"{parts.scheme}://{host}{port}{parts.path}"
+    if parts.query:
+        pairs = []
+        for pair in parts.query.split("&"):
+            key, eq, value = pair.partition("=")
+            hide = eq and value and (credential_query_name(key) or token_shaped(value))
+            pairs.append(f"{key}={_HIDDEN}" if hide else pair)
+        out += "?" + "&".join(pairs)
+    return out
+
+
+def redact_urls(text: str) -> str:
+    """*text* with every URL redacted (see the module docstring) and every
+    loaded secret value masked."""
+    text = _URL.sub(lambda m: _redact(m.group(0)), text)
+    for secret in _SECRETS:
+        text = text.replace(secret, _MASK)
+    return text
+
+
+class RedactUrls(logging.Filter):
+    """Rewrites a record's message with :func:`redact_urls` (its args folded
+    in first) and its traceback / stack text too."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            message = record.getMessage()
+        except Exception:  # noqa: BLE001 — a malformed record is dropped, never raised
+            return False
+        record.msg = redact_urls(message)
+        record.args = ()
+        if record.exc_info and not record.exc_text:
+            record.exc_text = "".join(traceback.format_exception(*record.exc_info)).rstrip()
+        if record.exc_text:
+            record.exc_text = redact_urls(record.exc_text)
+        if record.stack_info:
+            record.stack_info = redact_urls(record.stack_info)
+        return True
+
+
+def _excepthook(kind, value, tb) -> None:  # noqa: ANN001 — sys.excepthook's signature
+    sys.stderr.write(redact_urls("".join(traceback.format_exception(kind, value, tb))))
+
+
+def install() -> None:
+    """Put :class:`RedactUrls` on every root handler and on the HTTP client
+    loggers themselves, and redact an uncaught exception's traceback.
+    Idempotent."""
+    targets: list[logging.Filterer] = [*logging.getLogger().handlers]
+    targets += [logging.getLogger(name) for name in ("httpx", "httpcore")]
+    for target in targets:
+        if not any(isinstance(f, RedactUrls) for f in target.filters):
+            target.addFilter(RedactUrls())
+    sys.excepthook = _excepthook
+
+
+__all__ = ["RedactUrls", "install", "redact_urls", "set_secret_values"]

api_test_agent/_ssrf.py

@@ -0,0 +1,122 @@
+"""SSRF guard for agent-driven URL fetches (review finding C3).
+
+Every place the agent — or an imported spec/doc it was steered by (a prompt-
+injection surface) — can make us fetch an arbitrary URL (``fetch_url``,
+``import_openapi`` by URL, the OpenAPI source loader, and the ``manage`` import
+path) must refuse INTERNAL targets. Without this, an LLM-controlled URL reaches
+``169.254.169.254`` (cloud metadata), ``localhost``, or an RFC1918 host — with
+the raw body returned into LLM context.
+
+Guard: resolve the host and reject if ANY resolved address is loopback /
+link-local (includes the metadata range) / private / reserved / multicast /
+unspecified; validate the initial URL AND every redirect hop (redirects are
+followed MANUALLY so a public URL cannot 3xx into an internal one). ``http_request``
+keeps its own explicit host-allowlist rail; this guard covers the ingest/doc
+fetchers that had none.
+
+Residual (documented, out of scope this pass): DNS rebinding between our
+resolution and httpx's own connect is not closed here — a fully robust version
+pins the resolved IP and connects to it with the original Host header.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import socket
+from typing import Any
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+
+class SsrfError(Exception):
+    """A URL was refused because it targets a non-public / internal address."""
+
+
+# Ranges the category flags below can miss depending on the Python point-release
+# (RFC 6598 CGNAT hosts Alibaba Cloud metadata 100.100.100.200 and is common for
+# k8s / internal load-balancers). Blocked explicitly so the guard is version-proof.
+_EXTRA_BLOCKED = [
+    ipaddress.ip_network("100.64.0.0/10"),    # RFC 6598 carrier-grade NAT
+    ipaddress.ip_network("192.0.0.0/24"),     # IETF protocol assignments
+    ipaddress.ip_network("192.88.99.0/24"),   # 6to4 relay anycast
+    ipaddress.ip_network("::ffff:0:0/96"),    # IPv4-mapped IPv6 (defense in depth)
+]
+
+
+def _addr_blocked(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    # Allow ONLY globally-routable public addresses. `not is_global` is the
+    # allowlist-style backstop that catches anything the explicit category flags
+    # miss (CGNAT, benchmarking, future special-use); the flags + explicit nets
+    # are belt-and-braces so a Python release that mis-classifies a range can't
+    # open a hole.
+    if (
+        not ip.is_global or ip.is_loopback or ip.is_link_local or ip.is_private
+        or ip.is_reserved or ip.is_multicast or ip.is_unspecified
+    ):
+        return True
+    return any(ip.version == net.version and ip in net for net in _EXTRA_BLOCKED)
+
+
+def assert_public_url(url: str) -> None:
+    """Raise :class:`SsrfError` unless *url* is http(s) with a host that resolves
+    ENTIRELY to public addresses."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise SsrfError(f"refusing non-http(s) URL scheme '{parsed.scheme or '?'}'")
+    host = parsed.hostname
+    if not host:
+        raise SsrfError("refusing URL with no host")
+    try:
+        infos = socket.getaddrinfo(
+            host, parsed.port or (443 if parsed.scheme == "https" else 80),
+            proto=socket.IPPROTO_TCP,
+        )
+    except socket.gaierror as exc:
+        raise SsrfError(f"refusing '{host}': DNS resolution failed ({exc})") from exc
+    for info in infos:
+        raw = info[4][0].split("%")[0]  # strip any IPv6 scope id
+        try:
+            ip = ipaddress.ip_address(raw)
+        except ValueError as exc:
+            raise SsrfError(f"refusing '{host}': unparseable address {raw!r}") from exc
+        if _addr_blocked(ip):
+            raise SsrfError(f"refusing '{host}': resolves to non-public address {ip}")
+
+
+def _next_redirect(resp: httpx.Response) -> str | None:
+    loc = resp.headers.get("location")
+    return urljoin(str(resp.url), loc) if resp.is_redirect and loc else None
+
+
+async def safe_get(client: httpx.AsyncClient, url: str, *, max_redirects: int = 5, **kwargs: Any) -> httpx.Response:
+    """``client.get`` that validates the URL AND every redirect hop against
+    :func:`assert_public_url`. Redirects are followed manually (never httpx auto)
+    so a public URL cannot 3xx into an internal target."""
+    kwargs.pop("follow_redirects", None)
+    current = url
+    for _ in range(max_redirects + 1):
+        assert_public_url(current)
+        resp = await client.get(current, follow_redirects=False, **kwargs)
+        nxt = _next_redirect(resp)
+        if nxt is None:
+            return resp
+        current = nxt
+    raise SsrfError(f"too many redirects (> {max_redirects}) starting at {url}")
+
+
+def safe_get_sync(url: str, *, max_redirects: int = 5, **kwargs: Any) -> httpx.Response:
+    """Synchronous counterpart of :func:`safe_get` for the sync ``manage`` path."""
+    kwargs.pop("follow_redirects", None)
+    current = url
+    for _ in range(max_redirects + 1):
+        assert_public_url(current)
+        resp = httpx.get(current, follow_redirects=False, **kwargs)
+        nxt = _next_redirect(resp)
+        if nxt is None:
+            return resp
+        current = nxt
+    raise SsrfError(f"too many redirects (> {max_redirects}) starting at {url}")
+
+
+__all__ = ["SsrfError", "assert_public_url", "safe_get", "safe_get_sync"]