sproxy 0.1.0__py3-none-any.whl

sproxy/policy.py

@@ -0,0 +1,274 @@
+"""Policy schema, loading, and host matching.
+
+A policy describes what a proxied agent session is allowed to do:
+
+* which secrets to inject and where they may travel (``[secrets]``),
+* what to do when a credential is detected leaving to a host it is not
+  allowed to reach (``on_leak``),
+* whether to run built-in credential pattern detection,
+* where to write the audit log.
+
+Only the standard library is used here so the module can be imported inside
+mitmdump's bundled interpreter as well as under pytest.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# Enforcement mode for the whole session.
+MODE_ENFORCE = "enforce"  # block/redact per policy
+MODE_MONITOR = "monitor"  # never modify traffic, only audit
+MODES = (MODE_ENFORCE, MODE_MONITOR)
+
+# Action taken when a secret/credential is found heading to a host it is not
+# allowed to reach.
+ON_LEAK_BLOCK = "block"
+ON_LEAK_REDACT = "redact"
+ON_LEAK_WARN = "warn"
+ON_LEAK_ACTIONS = (ON_LEAK_BLOCK, ON_LEAK_REDACT, ON_LEAK_WARN)
+
+
+class PolicyError(ValueError):
+    """Raised when a policy file is malformed."""
+
+
+@dataclass
+class SecretSpec:
+    """A single secret to inject and guard.
+
+    ``source`` is a backend spec such as ``gopass:personal/github/token``,
+    ``env:GITHUB_TOKEN``, ``pass:work/api``, ``file:/path`` or ``literal:...``.
+
+    ``allow_hosts`` are the only hosts this secret's value may be sent to. It is
+    injected only for requests to these hosts, and its appearance in a request
+    to any other host is treated as a leak. An empty list means the secret is
+    unrestricted: injected for every host and never treated as a leak.
+    """
+
+    name: str
+    source: str
+    allow_hosts: list[str] = field(default_factory=list)
+
+
+PG_SSLMODES = ("verify-full", "disable")
+
+
+@dataclass
+class PostgresProfile:
+    """One ``[postgres.NAME]`` table: a database the session may reach.
+
+    The profile pins the *destination* and holds the password source; the
+    connecting client still chooses everything else. Optional ``user`` and
+    ``database`` are defaults advertised with the endpoint, not restrictions -
+    what a role may do is enforced by the database itself, which only accepts
+    this profile's credential for its own role. ``listen`` is the local
+    gateway port - 0 means
+    pick a free one, which is fine because the endpoint is advertised to the
+    session through an environment variable, not hardcoded anywhere.
+    """
+
+    name: str
+    host: str
+    password_source: str
+    port: int = 5432
+    listen: int = 0
+    user: str = ""
+    database: str = ""
+    # Upstream TLS. "verify-full" encrypts and verifies the server identity;
+    # "disable" is for local development servers only.
+    sslmode: str = "verify-full"
+    sslrootcert: str = ""  # CA bundle for upstream verification; "" = system store
+
+    @property
+    def env_var(self) -> str:
+        """Name of the variable that advertises this endpoint to the session."""
+        return "SPROXY_POSTGRES_" + re.sub(r"[^A-Za-z0-9]+", "_", self.name).upper()
+
+
+@dataclass
+class Policy:
+    mode: str = MODE_MONITOR
+    port: int = 8080
+    on_leak: str = ON_LEAK_BLOCK
+    detect_patterns: bool = True
+    audit_log: str = ".sproxy/audit.jsonl"
+    watch_values: list[str] = field(default_factory=list)
+    # Hosts tunneled without TLS interception (certificate pinning). Their
+    # contents are not inspected.
+    passthrough_hosts: list[str] = field(default_factory=list)
+    secrets: list[SecretSpec] = field(default_factory=list)
+    postgres: list[PostgresProfile] = field(default_factory=list)
+    # confdir for the mitmproxy CA; empty means the mitmproxy default (~/.mitmproxy)
+    confdir: str = ""
+
+    def validate(self) -> None:
+        if self.mode not in MODES:
+            raise PolicyError(f"mode must be one of {MODES}, got {self.mode!r}")
+        if self.on_leak not in ON_LEAK_ACTIONS:
+            raise PolicyError(
+                f"on_leak must be one of {ON_LEAK_ACTIONS}, got {self.on_leak!r}"
+            )
+        if not (1 <= self.port <= 65535):
+            raise PolicyError(f"port out of range: {self.port}")
+        names = [s.name for s in self.secrets]
+        dupes = {n for n in names if names.count(n) > 1}
+        if dupes:
+            raise PolicyError(f"duplicate secret names: {sorted(dupes)}")
+        listens = [p.listen for p in self.postgres if p.listen] + [self.port]
+        dupe_ports = {p for p in listens if listens.count(p) > 1}
+        if dupe_ports:
+            raise PolicyError(f"postgres listen ports collide: {sorted(dupe_ports)}")
+        env_vars = [p.env_var for p in self.postgres]
+        dupe_vars = {v for v in env_vars if env_vars.count(v) > 1}
+        if dupe_vars:
+            raise PolicyError(
+                f"postgres profile names collide after env-var mangling: {sorted(dupe_vars)}"
+            )
+
+
+def host_matches(host: str, patterns: list[str]) -> bool:
+    """True if ``host`` matches any glob pattern in ``patterns``.
+
+    ``*.github.com`` matches ``api.github.com`` but not the bare ``github.com``;
+    add ``github.com`` explicitly (or use ``*github.com``) to cover the apex.
+    Matching is case-insensitive and ignores any trailing dot.
+    """
+    if not host:
+        return False
+    h = host.lower().rstrip(".")
+    for pat in patterns:
+        p = pat.lower().rstrip(".")
+        if fnmatch.fnmatch(h, p):
+            return True
+    return False
+
+
+def _as_str_list(value: object, ctx: str) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise PolicyError(f"{ctx} must be a list of strings")
+    return list(value)
+
+
+def _parse_secret(name: str, raw: object) -> SecretSpec:
+    """A secret entry is either a bare source string or a table with ``source``
+    and optional ``allow_hosts``. No ``allow_hosts`` means no host restriction."""
+    if isinstance(raw, str):
+        return SecretSpec(name=name, source=raw)
+    if isinstance(raw, dict):
+        source = raw.get("source")
+        if not isinstance(source, str) or not source:
+            raise PolicyError(f"secret {name!r} needs a non-empty 'source'")
+        allow = _as_str_list(raw.get("allow_hosts"), f"secret {name!r} allow_hosts")
+        return SecretSpec(name=name, source=source, allow_hosts=allow)
+    raise PolicyError(f"secret {name!r} must be a string or a table")
+
+
+def _parse_postgres(name: str, raw: object) -> PostgresProfile:
+    if not isinstance(raw, dict):
+        raise PolicyError(f"[postgres.{name}] must be a table")
+    ctx = f"postgres profile {name!r}"
+
+    def _str(key: str, default: str = "") -> str:
+        value = raw.get(key, default)
+        if not isinstance(value, str):
+            raise PolicyError(f"{ctx}: {key} must be a string")
+        return value
+
+    def _port(key: str, default: int, minimum: int) -> int:
+        value = raw.get(key, default)
+        if not isinstance(value, int) or isinstance(value, bool) or not minimum <= value <= 65535:
+            raise PolicyError(f"{ctx}: {key} must be a port number")
+        return value
+
+    host = _str("host")
+    if not host:
+        raise PolicyError(f"{ctx} needs a non-empty 'host'")
+    password_source = _str("password_source")
+    if not password_source:
+        raise PolicyError(f"{ctx} needs a non-empty 'password_source'")
+    sslmode = _str("sslmode", "verify-full")
+    if sslmode not in PG_SSLMODES:
+        raise PolicyError(f"{ctx}: sslmode must be one of {PG_SSLMODES}, got {sslmode!r}")
+    known = {"host", "port", "listen", "password_source", "user", "database", "sslmode", "sslrootcert"}
+    unknown = set(raw) - known
+    if unknown:
+        raise PolicyError(f"{ctx}: unknown keys {sorted(unknown)}")
+    return PostgresProfile(
+        name=name,
+        host=host,
+        password_source=password_source,
+        port=_port("port", 5432, minimum=1),
+        listen=_port("listen", 0, minimum=0),
+        user=_str("user"),
+        database=_str("database"),
+        sslmode=sslmode,
+        sslrootcert=_str("sslrootcert"),
+    )
+
+
+def from_dict(data: dict) -> Policy:
+    secrets_raw = data.get("secrets") or {}
+    if not isinstance(secrets_raw, dict):
+        raise PolicyError("[secrets] must be a table")
+    secrets = [_parse_secret(name, raw) for name, raw in secrets_raw.items()]
+    postgres_raw = data.get("postgres") or {}
+    if not isinstance(postgres_raw, dict):
+        raise PolicyError("[postgres] must be a table of profiles")
+    postgres = [_parse_postgres(name, raw) for name, raw in postgres_raw.items()]
+    policy = Policy(
+        mode=str(data.get("mode", MODE_MONITOR)),
+        port=int(data.get("port", 8080)),
+        on_leak=str(data.get("on_leak", ON_LEAK_BLOCK)),
+        detect_patterns=bool(data.get("detect_patterns", True)),
+        audit_log=str(data.get("audit_log", ".sproxy/audit.jsonl")),
+        watch_values=_as_str_list(data.get("watch_values"), "watch_values"),
+        passthrough_hosts=_as_str_list(data.get("passthrough_hosts"), "passthrough_hosts"),
+        secrets=secrets,
+        postgres=postgres,
+        confdir=str(data.get("confdir", "")),
+    )
+    policy.validate()
+    return policy
+
+
+def load(path: str | Path) -> Policy:
+    p = Path(path)
+    try:
+        data = tomllib.loads(p.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        raise PolicyError(f"could not read policy {p}: {exc}") from exc
+    policy = from_dict(data)
+    _anchor_paths(policy, p.resolve().parent)
+    return policy
+
+
+def _anchor_paths(policy: Policy, base: Path) -> None:
+    """Resolve config-relative paths against the policy file's directory, so a
+    policy behaves the same no matter where sproxy is launched from."""
+
+    def anchor(value: str) -> str:
+        expanded = Path(value).expanduser()
+        return str(expanded if expanded.is_absolute() else base / expanded)
+
+    if policy.audit_log:
+        policy.audit_log = anchor(policy.audit_log)
+    if policy.confdir:
+        policy.confdir = anchor(policy.confdir)
+    for profile in policy.postgres:
+        if profile.sslrootcert:
+            profile.sslrootcert = anchor(profile.sslrootcert)
+
+
+def default_policy() -> Policy:
+    """Safe fallback when no policy file is present: audit everything, block
+    nothing, run pattern detection so the user still sees leaks."""
+    return Policy(mode=MODE_MONITOR, detect_patterns=True)

sproxy/replacements.py

@@ -0,0 +1,28 @@
+"""Public request placeholders and private per-session replacement handles."""
+
+from __future__ import annotations
+
+
+def replacement_tokens(name: str, session_token: str = "") -> tuple[str, ...]:
+    """Tokens sproxy may replace with a configured secret's real value.
+
+    The ``{{NAME}}`` form is stable for hand-crafted requests. A non-empty
+    session token is an opaque, per-run value supplied to conventional SDKs
+    through their environment variable.
+    """
+    static = f"{{{{{name}}}}}"
+    return (static, session_token) if session_token else (static,)
+
+
+def replace_request_tokens(
+    text: str, name: str, value: str, session_token: str = ""
+) -> str:
+    """Replace every supported request token in ``text`` with ``value``."""
+    for token in replacement_tokens(name, session_token):
+        text = text.replace(token, value)
+    return text
+
+
+def has_session_token(text: str, session_token: str) -> bool:
+    """True when a private per-session handle appears in request text."""
+    return bool(session_token) and session_token in text