sproxy 0.1.0__py3-none-any.whl

sproxy/cli.py

@@ -0,0 +1,293 @@
+"""sproxy command-line interface.
+
+    sproxy run [-c policy.toml] [--port N] [--insecure] [--log-file path]
+               [--no-reload] [-- <command...>]
+                                     (no command: hold the session open for `sproxy env`)
+                                     (edits to the policy file apply live)
+    sproxy init [-c path]            write a starter policy
+    sproxy env                       print exports that join the live session
+    sproxy ca   [-c policy.toml]     print the CA cert path + trust hints
+    sproxy audit verify <log>        check the audit chain is intact
+    sproxy version
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from sproxy import __version__, audit, ca
+from sproxy.policy import PolicyError, default_policy, load
+from sproxy.runner import RunnerError, _port_open, run, session_env_path
+
+DEFAULT_POLICY_FILE = "sproxy.toml"
+
+STARTER_POLICY = """\
+# sproxy policy - local egress guard for coding agents.
+# Run:  sproxy run -- claude
+#
+# Saving this file applies it to a running session (`kill -HUP` forces it).
+# Secret handles, database endpoints and the postgres token stay valid; only
+# `port` and `confdir` need a restart.
+
+# "enforce" blocks/redacts per the rules below. "monitor" only audits.
+mode = "enforce"
+
+# Proxy listen port on 127.0.0.1.
+port = 8080
+
+# What to do when a managed secret heads to a host it is not allowed to reach:
+# "block", "redact", or "warn".
+on_leak = "block"
+
+# Detect credential-shaped strings (API keys, tokens, JWTs, private keys) that
+# sproxy was never told about, and surface them in the audit log.
+detect_patterns = true
+
+# Tamper-evident JSONL audit log. "" disables it. Verify with `sproxy audit verify`.
+audit_log = ".sproxy/audit.jsonl"
+
+# Extra literal values to treat as secrets and block from leaving anywhere.
+watch_values = []
+
+# Hosts to tunnel WITHOUT TLS interception - use for clients that pin
+# certificates (a TLS handshake error against a host usually means it pins).
+# Their contents cannot be inspected, so they are recorded in the audit log as
+# "passthrough / uninspected".
+passthrough_hosts = []
+
+# Secrets to inject and guard.
+#   name = "backend:path"                     -> no host restriction
+#   name = { source = "...", allow_hosts=[] } -> restricted to specific hosts
+# Globs are supported ("*.github.com" does NOT match the bare "github.com", list the apex too).
+# Backends: gopass:, pass:, vault: (vault:secret/app#field), env:, file:, literal:
+# A valid environment-variable name (e.g. GITHUB_TOKEN) is also exported to the
+# guarded process as an opaque, per-session handle. sproxy replaces that handle
+# with the real value only for the secret's allowed hosts.
+# In requests, write the placeholder {{NAME}} where the secret should go, e.g.
+#   Authorization: Bearer {{GITHUB_TOKEN}}
+[secrets]
+# GITHUB_TOKEN = { source = "gopass:personal/github/token", allow_hosts = ["github.com", "api.github.com"] }
+# ANTHROPIC_API_KEY = { source = "env:ANTHROPIC_API_KEY", allow_hosts = ["api.anthropic.com"] }
+
+# PostgreSQL access. sproxy terminates the wire protocol on a local endpoint:
+# the client authenticates with a per-session token, and sproxy alone performs
+# TLS + SCRAM against the real server - the password never enters the agent's
+# environment. Inside the session:
+#   psql "$SPROXY_POSTGRES_DEVELOP"                # endpoint + token + defaults, ready to use
+#   psql "$SPROXY_POSTGRES_DEVELOP dbname=other"   # append params to override
+# [postgres.develop]
+# host = "db.example.com"          # the real server; policy is the only place it's set
+# port = 5432
+# listen = 6432                    # local endpoint port; omit for auto-assigned
+# password_source = "gopass:work/postgres/develop/password"
+# user = "app_readonly"            # optional: default role (client's choice wins)
+# database = "appdb"               # optional: default database
+# sslmode = "verify-full"          # upstream TLS (default); "disable" only for local dev servers
+# sslrootcert = ""                 # CA bundle (e.g. AWS RDS); "" = system trust store
+"""
+
+
+def _split_command(argv: list[str]) -> tuple[list[str], list[str]]:
+    """Split ``argv`` at the first ``--`` into (options, command)."""
+    if "--" in argv:
+        i = argv.index("--")
+        return argv[:i], argv[i + 1 :]
+    return argv, []
+
+
+def _user_policy_file() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
+    return Path(base) / "sproxy" / DEFAULT_POLICY_FILE
+
+
+def _find_policy_file() -> Path | None:
+    """First existing policy: ./sproxy.toml, then the user-level config."""
+    for candidate in (Path(DEFAULT_POLICY_FILE), _user_policy_file()):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _load_policy(path: str | None) -> tuple["object", Path | None]:
+    """The policy plus the file it came from (None when there was no file)."""
+    if path:
+        return load(path), Path(path)
+    found = _find_policy_file()
+    if found is not None:
+        print(f"sproxy: using policy {found.resolve()}", file=sys.stderr)
+        if found == Path(DEFAULT_POLICY_FILE) and _user_policy_file().exists():
+            # Easy to be caught out by: editing the user-level config has no
+            # effect on a session started in a directory that has its own.
+            print(
+                f"sproxy: note: {_user_policy_file()} is ignored while this "
+                f"directory has its own {DEFAULT_POLICY_FILE}",
+                file=sys.stderr,
+            )
+        return load(found), found
+    print(
+        f"sproxy: no {DEFAULT_POLICY_FILE} found here or at {_user_policy_file()} - "
+        f"running in monitor mode (audit only, no blocking). "
+        f"Run `sproxy init` to configure enforcement.",
+        file=sys.stderr,
+    )
+    return default_policy(), None
+
+
+def cmd_run(opts: argparse.Namespace, command: list[str]) -> int:
+    try:
+        policy, config_path = _load_policy(opts.config)
+    except FileNotFoundError:
+        print(f"error: policy file not found: {opts.config}", file=sys.stderr)
+        return 2
+    except PolicyError as exc:
+        print(f"error: invalid policy: {exc}", file=sys.stderr)
+        return 2
+    try:
+        return run(
+            policy,
+            command,
+            insecure=opts.insecure,
+            mitmdump=opts.mitmdump,
+            log_file=opts.log_file,
+            config_path=config_path,
+            port=opts.port,
+            watch_config=not opts.no_reload,
+        )
+    except RunnerError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def cmd_init(opts: argparse.Namespace) -> int:
+    target = Path(opts.config or DEFAULT_POLICY_FILE)
+    if target.exists() and not opts.force:
+        print(f"error: {target} already exists (use --force to overwrite)", file=sys.stderr)
+        return 1
+    target.write_text(STARTER_POLICY, encoding="utf-8")
+    print(f"wrote {target}. Edit it, then: sproxy run -- claude")
+    return 0
+
+
+def cmd_env(opts: argparse.Namespace) -> int:
+    """Print export lines that join this shell to the live sproxy session."""
+    path = session_env_path()
+    try:
+        content = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        print("sproxy: no live session (start one with `sproxy run`)", file=sys.stderr)
+        return 1
+    port = None
+    for line in content.splitlines():
+        if line.startswith("# sproxy-port:"):
+            try:
+                port = int(line.split(":", 1)[1])
+            except ValueError:
+                pass
+    if port is not None and not _port_open(port):
+        print(
+            f"sproxy: found {path} but nothing is listening on port {port} - "
+            "the session is gone (stale file)",
+            file=sys.stderr,
+        )
+        return 1
+    print(content, end="")
+    return 0
+
+
+def cmd_ca(opts: argparse.Namespace) -> int:
+    confdir = None
+    if opts.config:
+        try:
+            confdir = load(opts.config).confdir or None
+        except (FileNotFoundError, PolicyError):
+            confdir = None
+    cert = ca.cert_path(confdir)
+    print(cert)
+    if not cert.exists():
+        print(
+            "note: cert not generated yet - it appears after mitmdump runs once "
+            "(e.g. via `sproxy run`).",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def cmd_audit(opts: argparse.Namespace) -> int:
+    ok, count, message = audit.verify(opts.log)
+    print(message)
+    return 0 if ok else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="sproxy", description="Local egress guard for coding agents.")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser(
+        "run",
+        help="run a command behind the guard; with no command, hold a session "
+        'open for other shells to join via eval "$(sproxy env)"',
+    )
+    r.add_argument("-c", "--config", help=f"policy file (default: ./{DEFAULT_POLICY_FILE})")
+    r.add_argument("--port", type=int, help="override the listen port")
+    r.add_argument("--insecure", action="store_true", help="disable upstream TLS verification")
+    r.add_argument("--mitmdump", help="path to the mitmdump binary")
+    r.add_argument(
+        "--log-file",
+        help="write sproxy/mitmproxy output here, leaving the command's terminal untouched",
+    )
+    r.add_argument(
+        "--no-reload",
+        action="store_true",
+        help="pin the policy for the whole session instead of applying edits to "
+        "the file as they are saved (SIGHUP also stops reloading)",
+    )
+
+    i = sub.add_parser("init", help="write a starter policy file")
+    i.add_argument("-c", "--config", help=f"output path (default: ./{DEFAULT_POLICY_FILE})")
+    i.add_argument("--force", action="store_true", help="overwrite an existing file")
+
+    sub.add_parser(
+        "env",
+        help='print export lines joining this shell to the live session: eval "$(sproxy env)"',
+    )
+
+    c = sub.add_parser("ca", help="print the mitmproxy CA cert path")
+    c.add_argument("-c", "--config", help="policy file (to read confdir)")
+
+    a = sub.add_parser("audit", help="audit-log tools")
+    asub = a.add_subparsers(dest="audit_cmd", required=True)
+    av = asub.add_parser("verify", help="verify the audit chain is intact")
+    av.add_argument("log", help="path to the audit .jsonl file")
+
+    sub.add_parser("version", help="print version")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    before, command = _split_command(raw)
+    parser = build_parser()
+    opts = parser.parse_args(before)
+
+    if opts.cmd == "run":
+        return cmd_run(opts, command)
+    if opts.cmd == "init":
+        return cmd_init(opts)
+    if opts.cmd == "env":
+        return cmd_env(opts)
+    if opts.cmd == "ca":
+        return cmd_ca(opts)
+    if opts.cmd == "audit":
+        return cmd_audit(opts)
+    if opts.cmd == "version":
+        print(f"sproxy {__version__}")
+        return 0
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())