secretgate 0.3.1

Lean security proxy for AI coding tools — scan and redact secrets before they reach LLM APIs

secretgate

AI coding agents are powerful — but they have shell access, and one wrong curl, git push, or API call can leak your secrets. You shouldn't have to choose between productivity and security.

secretgate makes AI-assisted development secure by default. One command wraps your coding tool in a security boundary that intercepts all outbound traffic and catches secrets before they leave your machine. No config changes to your tools, no workflow disruption — just secretgate wrap -- claude and code with confidence.

Our goal is to make secretgate the state-of-the-art, security-by-design standard for AI coding tools — so that every developer, team, and organization can adopt AI agents without compromising on security. We believe security should be invisible, automatic, and accessible to everyone.

Architecture

IDE / CLI / Agent (e.g. Claude Code)
       │
       │  https_proxy=http://localhost:8083
       ▼
┌──────────────────────────────────────┐
│            secretgate                │
│                                      │
│  :8083 Forward Proxy (all traffic)   │  ← default, intercepts everything
│  :8082 Reverse Proxy (LLM APIs)     │  ← optional, per-provider routing
│                                      │
│  ┌────────────────────────────────┐  │
│  │  Secret Scanner (~90 regexes) │  │
│  ├────────────────────────────────┤  │
│  │  Modes: redact / block / audit│  │
│  ├────────────────────────────────┤  │
│  │  Audit Logger                 │  │
│  └────────────────────────────────┘  │
│                                      │
│  TLS MITM: auto-generated CA +      │
│  per-domain certs, cached in memory  │
└───────────┬──────────────────────────┘
            │
            ▼
  github.com, api.anthropic.com,
  pypi.org, npmjs.com, ...

How it works

1. Set https_proxy to point all traffic through secretgate (or use secretgate wrap)
2. secretgate intercepts every outbound HTTPS request via TLS MITM and scans for secrets
3. Detected secrets are handled based on the mode:
   • redact: replace with REDACTED<aws-access-key:a1b2c3d4e5f6> placeholders before forwarding
   • block: reject the request entirely
   • audit: log and forward unchanged (good for testing)
4. Everything is logged for audit

Placeholders are deterministic and self-documenting — same secret always produces the same placeholder, and the type identifier tells the LLM what kind of secret was redacted without exposing the value.

Installation

Quick install (installs via pipx, or falls back to pip):

curl -fsSL https://raw.githubusercontent.com/secretgate/secretgate/main/install.sh | bash

Or install manually:

pipx install secretgate    # recommended
pip install secretgate     # if pipx is not available

With optional detect-secrets support:

pip install secretgate[detect-secrets]

Quickstart

One command — starts the proxy, sets env vars, runs your tool:

secretgate wrap -- claude

When Claude exits, secretgate stops automatically. All HTTPS traffic from that session flows through secretgate. Works on Linux, macOS, and Windows.

First-time setup (generate and trust the CA certificate):

./scripts/setup.sh

# Or manually:
secretgate ca init          # generate CA
secretgate ca trust         # print OS-specific trust instructions

Options:

secretgate wrap -- claude                    # default: redact mode
secretgate wrap --mode audit -- claude       # audit mode (log only)
secretgate wrap --mode block -- claude       # block mode (reject secrets)
secretgate wrap -f 9090 -- curl https://...  # custom proxy port

Always launch Claude through secretgate — add to .bashrc / .zshrc:

alias claude-safe='secretgate wrap -- claude'

Compatible tools

secretgate wrap works with any tool that respects the standard https_proxy env var. Just replace claude with your tool:

CLI tools:

secretgate wrap -- claude           # Claude Code
secretgate wrap -- aider            # Aider (Python)
secretgate wrap -- codex            # OpenAI Codex CLI (Node.js)
secretgate wrap -- open-interpreter # Open Interpreter (Python)

IDEs (wrap the launch command — env vars propagate to extensions):

secretgate wrap -- cursor           # Cursor
secretgate wrap -- code             # VS Code (with Copilot, Continue, etc.)
secretgate wrap -- windsurf         # Windsurf

Notes:

• Some Electron apps may have their own proxy settings that override env vars
• Tools that bundle their own certificate store might ignore NODE_EXTRA_CA_CERTS / SSL_CERT_FILE
• SSH-based operations ([e-mail]:...) bypass the HTTP proxy regardless

We've verified with Claude Code and curl so far. If you test with other tools, we'd love to hear about it — open an issue or PR at github.com/secretgate/secretgate. Testers and contributors are very welcome!

Manual setup (two terminals)

# Terminal 1: start with forward proxy enabled
secretgate serve --forward-proxy-port 8083

# Terminal 2: set env vars and run your tool
export https_proxy=http://localhost:8083
export http_proxy=http://localhost:8083
export SSL_CERT_FILE=$(secretgate ca path)
claude

What you'll see in the logs

[info     ] request                        messages=19 model=claude-opus-4-6
[warning  ] secret_detected                line=93 pattern='API Key' service=Anthropic
[warning  ] secret_detected                line=99 pattern='AWS Access Key' service=Amazon
[warning  ] secret_detected                line=100 pattern='high-entropy value (Key)' service=entropy
[warning  ] secrets_audit_only             secrets_found=3

Secrets in conversation history (from previous assistant responses) are caught on the next turn when they become part of the outbound request.

How the forward proxy works

The forward proxy performs TLS MITM (man-in-the-middle) to inspect HTTPS traffic:

• Generates a local CA certificate (stored in ~/.secretgate/certs/)
• Creates per-domain certificates on the fly, cached in memory
• Scans outbound request bodies for secrets (responses pass through unmodified)
• Uses regex-only scanning (entropy detection disabled to avoid false positives on code/JSON)
• Uses the same deterministic REDACTED<slug:hash12> placeholder format
• Handles chunked transfer encoding and streaming responses (SSE)

Tested with

• Claude Code — LLM API traffic intercepted and scanned, secrets in conversation messages detected (audit + redact modes verified)
• curl to httpbin.org — HTTPS POST bodies with AWS access keys and secret keys detected and redacted
• git, pip, npm — should work via standard https_proxy env var but not yet manually verified
• localhost traffic bypasses the proxy by default (standard HTTP proxy behavior); set no_proxy="" to override

Tested on

• Linux (Ubuntu/WSL2) and Windows — secretgate wrap and forward proxy verified on both platforms
• macOS — should work but not yet manually verified

CA Trust Instructions

# macOS
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain $(secretgate ca path)

# Ubuntu/Debian
sudo cp $(secretgate ca path) /usr/local/share/ca-certificates/secretgate.crt
sudo update-ca-certificates

# Python/httpx/requests
export SSL_CERT_FILE=$(secretgate ca path)

# Node.js
export NODE_EXTRA_CA_CERTS=$(secretgate ca path)

Passthrough Domains

Skip TLS MITM for specific domains (e.g., internal services):

# config.yaml
passthrough_domains:
  - internal.example.com
  - vpn.company.net

Limitations

• SSH git remotes ([e-mail]:...) bypass HTTP proxy — only HTTPS remotes are intercepted
• HTTP/2 not supported (HTTP/1.1 only — sufficient for git, curl, pip, npm)
• Node.js apps need NODE_EXTRA_CA_CERTS env var
• localhost bypasses proxy by default — set no_proxy="" if needed

Helper scripts (Linux/macOS only)

These require bash and are not available on Windows. Use secretgate wrap instead, which works on all platforms.

• scripts/setup.sh — one-time setup: install CA, print trust instructions, suggest shell config
• scripts/with-secretgate.sh — standalone wrapper (starts proxy, runs command, stops proxy)

./scripts/with-secretgate.sh claude
./scripts/with-secretgate.sh curl https://example.com

Reverse proxy mode (LLM APIs only)

If you only need to scan LLM API traffic (not all HTTPS), use the reverse proxy without the forward proxy. Configure your AI tool to use secretgate as its API base URL:

secretgate serve --port 8082 --mode redact

# OpenAI-compatible tools (Cursor, Continue, etc.)
export OPENAI_BASE_URL=http://localhost:8082/openai

# Anthropic-compatible tools
export ANTHROPIC_BASE_URL=http://localhost:8082/anthropic

# Ollama
export OLLAMA_HOST=http://localhost:8082/ollama

Note: this only catches traffic explicitly routed to the proxy. An AI agent with shell access can still leak secrets via git push, curl, etc. Use the forward proxy for a real security boundary.

Modes

Mode	Behavior	Use case
redact	Replace secrets with placeholders, restore on response	Production use
block	Reject requests containing secrets (HTTP 403)	Strict environments
audit	Log secrets but forward request unchanged	Testing, evaluation

Extra detection with detect-secrets

For broader coverage, enable Yelp's detect-secrets as a supplementary scanner (23 additional regex plugins, entropy detectors disabled to avoid false positives):

pip install secretgate[detect-secrets]
secretgate serve --detect-secrets

Or via environment variable:

export SECRETGATE_DETECT_SECRETS=true

Offline scanning

Scan files or stdin for secrets without running the proxy:

secretgate scan .env config.yaml          # scan specific files
cat .env | secretgate scan                # scan stdin
git diff --cached | secretgate scan       # scan staged changes
secretgate scan --no-entropy src/         # regex-only (fewer false positives)

Supported patterns

secretgate ships with ~90 regex patterns covering AWS (including STS/temporary credentials), GCP/Google (OAuth tokens, HMAC, Firebase), Azure (AD secrets, DevOps PATs, Cosmos DB, Service Bus, SAS tokens), Cloudflare, GitHub, GitLab, Slack, Discord, Telegram, OpenAI, Anthropic, Hugging Face, Stripe, Shopify, Twilio, SendGrid, Mailchimp, npm, PyPI, Vercel, Databricks, HashiCorp Vault/Terraform, Grafana, New Relic, Sentry, database connection strings, and more.

See the full list: docs/supported-patterns.md

Adding custom secret patterns

Drop patterns in ~/.secretgate/signatures.yaml or pass --signatures /path/to/file.yaml.

- MyCompany:
    - Internal API Key: "myco_[a-zA-Z0-9]{32}"
    - Database URL: "myco_db://.*@prod\\.mycompany\\.com"

Contributing

We welcome contributions! Here's how we work:

Branch strategy

• main is the production branch — always deployable, published to PyPI
• All changes go through feature branches and pull requests
• Branch naming: feat/..., fix/..., chore/...
• PRs require 1 approving review before merging
• Squash merge only — keeps main history clean (one commit per PR)
• Feature branches are auto-deleted after merge

Workflow

1. Create a feature branch from main
2. Make your changes, ensure tests pass (pytest tests/ -v) and lint is clean (ruff check src/ tests/)
3. Open a PR against main
4. Get a review, address feedback
5. Maintainer squash-merges once approved

Development setup

git clone https://github.com/secretgate/secretgate.git
cd secretgate
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

Pre-commit hooks

secretgate includes pre-commit hooks for development. After pip install -e ".[dev]":

pre-commit install

This enables ruff lint/format, trailing whitespace fixes, and secretgate's own secret scanner on staged files.

Releasing

Releases are published to PyPI automatically via GitHub Actions using trusted publishing (no API tokens needed).

1. Bump the version in pyproject.toml
2. Create a GitHub Release with tag vX.Y.Z
3. The publish.yml workflow builds and uploads to PyPI

License

Apache 2.0