sproxy 0.1.0__py3-none-any.whl

sproxy/scanner.py

@@ -0,0 +1,109 @@
+"""Outbound leak detection.
+
+Two independent detectors:
+
+* **Known values** - exact substring match against resolved secret values (and
+  any extra ``watch_values``). Zero false positives; this is the core guard.
+* **Patterns** - regexes for well-known credential shapes (provider API keys,
+  cloud keys, tokens, JWTs, private keys). Higher recall, used to catch secrets
+  sproxy was never told about.
+
+The scanner deliberately reports only *which rule* matched, never the matched
+text, so findings are safe to write to the audit log.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# Cap how much of a body we scan so a huge upload can't stall the proxy.
+MAX_SCAN_BYTES = 2 * 1024 * 1024
+
+# (name, regex). Patterns are chosen for high signal / low false-positive rate.
+_PATTERN_SPECS: list[tuple[str, str]] = [
+    ("anthropic_api_key", r"sk-ant-[A-Za-z0-9_-]{20,}"),
+    ("openai_api_key", r"sk-(?:proj-)?[A-Za-z0-9_-]{20,}"),
+    ("github_token", r"gh[pousr]_[A-Za-z0-9]{36,}"),
+    ("github_fine_grained_pat", r"github_pat_[A-Za-z0-9_]{22,}"),
+    ("aws_access_key_id", r"(?:AKIA|ASIA)[0-9A-Z]{16}"),
+    ("google_api_key", r"AIza[0-9A-Za-z_-]{35}"),
+    ("slack_token", r"xox[baprs]-[A-Za-z0-9-]{10,}"),
+    ("stripe_secret_key", r"(?:sk|rk)_live_[0-9a-zA-Z]{24,}"),
+    ("gitlab_pat", r"glpat-[A-Za-z0-9_-]{20,}"),
+    ("jwt", r"eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"),
+    ("private_key", r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----"),
+]
+
+PATTERNS: list[tuple[str, re.Pattern]] = [
+    (name, re.compile(rx)) for name, rx in _PATTERN_SPECS
+]
+
+
+@dataclass(frozen=True)
+class Finding:
+    kind: str  # "secret" or "pattern"
+    name: str  # secret name, or pattern name
+
+    def __str__(self) -> str:  # pragma: no cover - display only
+        return f"{self.kind}:{self.name}"
+
+
+class Scanner:
+    def __init__(
+        self,
+        secret_values: dict[str, str] | None = None,
+        watch_values: list[str] | None = None,
+        detect_patterns: bool = True,
+    ):
+        # name -> value, and value -> name for reverse lookup during redaction.
+        self.secret_values = dict(secret_values or {})
+        for i, v in enumerate(watch_values or []):
+            if v:
+                self.secret_values.setdefault(f"watch_{i}", v)
+        self._value_to_name = {v: n for n, v in self.secret_values.items() if v}
+        self.detect_patterns = detect_patterns
+
+    def scan(self, text: str) -> list[Finding]:
+        """Return findings for a piece of outbound text (URL, header, body)."""
+        if not text:
+            return []
+        if len(text) > MAX_SCAN_BYTES:
+            text = text[:MAX_SCAN_BYTES]
+        findings: list[Finding] = []
+        seen: set[tuple[str, str]] = set()
+
+        for value, name in self._value_to_name.items():
+            if value in text and ("secret", name) not in seen:
+                findings.append(Finding("secret", name))
+                seen.add(("secret", name))
+
+        if self.detect_patterns:
+            for name, rx in PATTERNS:
+                if rx.search(text) and ("pattern", name) not in seen:
+                    findings.append(Finding("pattern", name))
+                    seen.add(("pattern", name))
+
+        return findings
+
+    def secret_names(self, findings: list[Finding]) -> set[str]:
+        return {f.name for f in findings if f.kind == "secret"}
+
+    def redact(self, text: str) -> tuple[str, list[Finding]]:
+        """Replace any known secret values and pattern matches in ``text`` with a
+        marker. Returns the redacted text and the findings that were redacted."""
+        if not text:
+            return text, []
+        findings: list[Finding] = []
+        out = text
+        for value, name in self._value_to_name.items():
+            if value and value in out:
+                out = out.replace(value, f"[sproxy:redacted:{name}]")
+                findings.append(Finding("secret", name))
+        if self.detect_patterns:
+            for name, rx in PATTERNS:
+                new, n = rx.subn(f"[sproxy:redacted:{name}]", out)
+                if n:
+                    out = new
+                    findings.append(Finding("pattern", name))
+        return out, findings

sproxy/secrets_resolver.py

@@ -0,0 +1,104 @@
+"""Resolve secret source specs to their real values.
+
+Sources are resolved once, up front, by the trusted CLI process - never by the
+agent and never by the addon. Supported backends:
+
+    gopass:PATH        `gopass show -o PATH`
+    pass:PATH          `pass show PATH` (first line)
+    vault:PATH#FIELD   `vault kv get -field=FIELD PATH` (FIELD defaults to "value")
+    env:VAR            environment variable VAR
+    file:PATH          contents of a file (stripped)
+    literal:VALUE      the value itself (handy for tests/demos)
+
+A resolver is a callable ``(path: str) -> str``; the defaults shell out, but
+tests inject fakes.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Callable
+
+
+class SecretResolutionError(RuntimeError):
+    pass
+
+
+def _run(cmd: list[str]) -> str:
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    except FileNotFoundError as exc:
+        raise SecretResolutionError(f"{cmd[0]} not found on PATH") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        raise SecretResolutionError(
+            f"{' '.join(cmd)} failed ({exc.returncode}): {stderr}"
+        ) from exc
+    return result.stdout
+
+
+def _gopass(path: str) -> str:
+    return _run(["gopass", "show", "-o", path]).strip()
+
+
+def _pass(path: str) -> str:
+    # `pass` prints the whole entry; the secret is conventionally the first line.
+    return _run(["pass", "show", path]).splitlines()[0] if path else ""
+
+
+def _vault(spec: str) -> str:
+    # spec is "PATH#FIELD"; FIELD defaults to "value". The KV v2 CLI resolves
+    # the /data/ segment itself, so pass the logical path (e.g. secret/app).
+    # Auth is whatever the `vault` CLI already uses (VAULT_ADDR/VAULT_TOKEN/
+    # ~/.vault-token) - sproxy never handles Vault credentials itself.
+    path, _, field = spec.partition("#")
+    field = field or "value"
+    if not path:
+        raise SecretResolutionError("vault source needs a path, e.g. vault:secret/app#api_key")
+    return _run(["vault", "kv", "get", f"-field={field}", path]).strip()
+
+
+def _env(var: str) -> str:
+    if var not in os.environ:
+        raise SecretResolutionError(f"environment variable {var} is not set")
+    return os.environ[var]
+
+
+def _file(path: str) -> str:
+    try:
+        with open(os.path.expanduser(path), encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError as exc:
+        raise SecretResolutionError(f"cannot read {path}: {exc}") from exc
+
+
+DEFAULT_BACKENDS: dict[str, Callable[[str], str]] = {
+    "gopass": _gopass,
+    "pass": _pass,
+    "vault": _vault,
+    "env": _env,
+    "file": _file,
+    "literal": lambda v: v,
+}
+
+
+def resolve(source: str, backends: dict[str, Callable[[str], str]] | None = None) -> str:
+    """Resolve a ``backend:path`` spec to its value."""
+    backends = backends or DEFAULT_BACKENDS
+    if ":" not in source:
+        raise SecretResolutionError(
+            f"secret source {source!r} must look like 'backend:path' "
+            f"(one of: {', '.join(sorted(backends))})"
+        )
+    backend, _, path = source.partition(":")
+    fn = backends.get(backend)
+    if fn is None:
+        raise SecretResolutionError(
+            f"unknown secret backend {backend!r} in {source!r}; "
+            f"known backends: {', '.join(sorted(backends))}"
+        )
+    value = fn(path)
+    if value == "":
+        raise SecretResolutionError(f"secret source {source!r} resolved to an empty value")
+    return value

sproxy-0.1.0.dist-info/METADATA

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: sproxy
+Version: 0.1.0
+Summary: Local egress guard for coding agents: inject secrets, block secret leaks to hosts they may not reach, and keep a tamper-evident audit log.
+Author-email: Igor Pejic <hi@igorpejic.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/igorpejic/sproxy
+Project-URL: Issues, https://github.com/igorpejic/sproxy/issues
+Keywords: mitmproxy,proxy,secrets,dlp,egress,ai-agents,claude-code,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mitmproxy>=11
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# sproxy (secure proxy)
+
+## Motivation
+Do not send the secrets (API tokens, passwords) to LLM providers.
+If the secrets are in the conversation context, you can consider them compromised.
+So, don't let them ever enter the context.
+sproxy helps with this.
+
+## How it works?
+
+At request time, sproxy detects the secrets placeholders and injects the real
+secrets to the outbound requests.
+The LLMs only see the placeholder values at all times.
+
+```
+             placeholder {{GITHUB_TOKEN}}                 real secret
+   ┌────────┐  ───────────────────────►  ┌────────┐  ───────────────►   ┌──────────┐
+   │  LLM   │                            │ sproxy │   leak scan +       │ approved │
+   │ agent  │  ◄───────────────────────  │        │   audit             │  host    │
+   └────────┘        response            └────────┘                     └──────────┘
+                                              │
+                                              ├─►  ✗ block leak to attacker domain
+                                              └─►  🧾 .sproxy/audit.jsonl
+```
+
+## Features
+
+- provides a list of placeholder env values to be used by the LLM
+- configure specific domains to which the secret should be ingested
+- monitor and audit all traffic originating from LLM
+- works with authorization Headers, Parameters and Postgres protocol
+- local-first and fully open-source
+- works with Codex, Claude Code and other harnesses
+
+
+## Prerequisites
+
+sproxy uses [mitmdump](https://docs.mitmproxy.org/stable/overview/installation/) and will
+be pulled automatically by `pip install`:
+
+```bash
+pip install sproxy
+```
+
+If you prefer to install mitmproxy separately, use `pip install --no-deps sproxy`
+and make sure `mitmdump` is available on your `PATH` (or pass `--mitmdump` to
+`sproxy run`).
+
+
+## Quickstart
+
+```bash
+# 1. Write a starter policy and edit it.
+sproxy init                        # creates ./sproxy.toml
+
+# 2. Run your agent behind the guard.
+
+# Start sproxy
+sproxy run
+# And load the placeholder Env variables
+eval $(sproxy env) && codex
+
+# Or run the process together with sproxy
+sproxy run -- codex
+
+# 3. After a session, check the audit log wasn't touched.
+sproxy audit verify .sproxy/audit.jsonl
+```
+
+On first run, mitmproxy generates its CA at `~/.mitmproxy/mitmproxy-ca-cert.pem`.
+sproxy points the agent's TLS trust env vars (`NODE_EXTRA_CA_CERTS`,
+`REQUESTS_CA_BUNDLE`, `SSL_CERT_FILE`, …) at that file automatically.
+Run `sproxy ca` to print the path.
+
+
+To observe secret injection on your local machine, follow [QUICKSTART.md](./QUICKSTART.md).
+
+
+### Placeholder environment variables
+
+When a secret name is a valid environment-variable name, sproxy also exports
+that name to the guarded process as an per-session secret placedholer
+starting with `sproxy`.
+For example, with a `GITHUB_API_KEY` secret, an SDK sees:
+
+```text
+GITHUB_API_KEY=sproxy_v1_<random-session-handle>
+```
+
+sproxy replaces that handle with the real key only for the secret's allowed
+hosts. The handle is different for every `sproxy run` session and stops working
+when that session ends.
+
+Secret backends supported:
+
+- `gopass:PATH`,
+- `pass:PATH`,
+- `vault:PATH#FIELD` (HashiCorp Vault, via the `vault` CLI's existing auth)
+- `env:VAR`
+- `file:PATH`
+- `literal:VALUE`
+
+
+### Config file
+
+The policy is loaded from `-c PATH` config file if given, else `./sproxy.toml`, else the
+user-level `~/.config/sproxy/sproxy.toml`.
+Relative paths inside a policy (`audit_log`, `sslrootcert`, `confdir`) resolve
+against the config file's own directory.
+
+Editing the policy while `sproxy run` hot-reloads sproxy.
+(Note that you might have to re-authorize loading the secrets).
+
+
+## PostgreSQL
+
+The usual placeholder injection does not work for PostgreSQL like it does for http.
+SCRAM authentication proves knowledge of the password inside the client,
+so there is no request in flight to rewrite.
+Instead, each `[postgres.NAME]` profile becomes a local endpoint that
+terminates the wire protocol: the agent's client
+authenticates to sproxy with a per-session token.
+Sproxy opens the real connection to the host pinned in
+policy. The real password never enters the agent's environment,
+but it sees a fake placeholder which sproxy uses.
+
+```toml
+[postgres.develop]
+host = "db.example.com"          # the real server
+port = 5432
+listen = 6432                    # local endpoint port; omit for auto-assigned
+password_source = "gopass:work/postgres/develop/password"
+user = "app_readonly"            # optional: default role
+database = "appdb"               # optional: default database
+sslmode = "verify-full"          # upstream TLS (default); "disable" only for local dev servers
+sslrootcert = ""                 # CA bundle (e.g. the AWS RDS bundle); "" = system trust store
+```
+
+Each endpoint is advertised to the session through an environment variable
+named after the profile which will render after `sproxy run` or `sproxy env`.
+
+## The audit log
+
+Stores one line per request captured.
+Example:
+
+```json
+{"seq":1,"ts":"...","host":"attacker.com","method":"POST","decision":"blocked","rules":["secret:GITHUB_TOKEN"], ...}
+```
+
+## TLS interception & certificate pinning
+
+sproxy reads HTTPS by acting as a MITM with a trusted local CA. Clients that
+pin certificates (require a specific cert, not merely a valid one) will
+reject that CA and fail the handshake, and won't have their secrets replaced.
+Use `passthrough_hosts` to whitelist such hosts:
+```toml
+passthrough_hosts = ["api.vendor.com"]     # tunneled without interception
+```
+
+## Commands
+
+| Command                                                                      | What it does                                     |
+| ---------------------------------------------------------------------------- | ------------------------------------------------ |
+| `sproxy run [-c policy] [--port N] [--insecure] [--log-file path] [--no-reload] [-- <cmd…>]` | Run a command behind the guard; no command holds a session open. Policy edits apply live unless `--no-reload` |
+| `sproxy init [-c path] [--force]`                                            | Write a starter policy                           |
+| `sproxy env`                                                                 | Print exports that join this shell to the live session |
+| `sproxy ca [-c policy]`                                                      | Print the mitmproxy CA cert path                 |
+| `sproxy audit verify <log>`                                                  | Check the audit chain is intact                  |
+| `sproxy version`                                                             | Print version                                    |
+
+
+
+## License
+MIT

sproxy-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+sproxy/__init__.py,sha256=v5xSxVM3ALaddKBUapCk3jH2nbLNrTlLxPHtFirgcdA,283
+sproxy/__main__.py,sha256=-qiWeoH9e6HFOq4x5ywHq5EWFMj6e6PaX4lXF0z0oWE,85
+sproxy/addon.py,sha256=qAj1aOswGpmyfKzmv28Ekvxt_tpPpRq-nZ9r7zYGjbE,18686
+sproxy/audit.py,sha256=hkrnpxBUM0yErv-dEZ4C_9wDW2uC7JlwDiK5YtVVsrw,3234
+sproxy/auth.py,sha256=h2cZPYzNs35U8bNwsmexAprmmU4o-sJLSDuUxMtFO34,1234
+sproxy/ca.py,sha256=EHtvWmjTqezQJYjPU2c4IyzD1nM1luFEDowLAA1sC54,2393
+sproxy/cli.py,sha256=j41uRMgtv-_6GtUaoED-ll-HJi1S-YseJQJUC2AS7Vs,11178
+sproxy/pg.py,sha256=LfTlVbQUiJVyFgTDpyvS0YaGyvwtpXonUm88Dui_uCU,25403
+sproxy/policy.py,sha256=7q5rEnYAYqWE7Aopog9vK1-rXogkzxXeqKoqI5YZakw,10534
+sproxy/replacements.py,sha256=SKA5Y0slNdVXu9Yhi8nJ_Havnk3l3EeMUrUWqbpEy14,1055
+sproxy/runner.py,sha256=O2t0ofHvoomT3H8E0Iztlf6aikl1CWzwFjdqoMafknQ,33023
+sproxy/scanner.py,sha256=n6x6G5T5GnjnwbtTsJtukDskMLT9wbFcqBuaYMGMd5c,4249
+sproxy/secrets_resolver.py,sha256=0aYjC4dMqeOBVSONoQalkdvfRfPw57axdUQU9Lxt43A,3540
+sproxy-0.1.0.dist-info/licenses/LICENSE,sha256=JoZ5Fxk5z-cnfUHtuYmWdF8nrZRaXneJQu6WBm8ycQY,1067
+sproxy-0.1.0.dist-info/METADATA,sha256=WkFSuh_MwOvjOoX9gkv8VAGDFyms590YvBlI3eAKtpw,7844
+sproxy-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+sproxy-0.1.0.dist-info/entry_points.txt,sha256=AV_wKPkzkSin3W5AAF-6LBfIIT6WhQBpFfu6LmRBDxw,43
+sproxy-0.1.0.dist-info/top_level.txt,sha256=KOGn-X9-FP91vvInt0Y2s3IFIKarKtTpRAJuwoDRkbU,7
+sproxy-0.1.0.dist-info/RECORD,,

sproxy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sproxy-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sproxy = sproxy.cli:main

sproxy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Pejic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sproxy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sproxy