nullwire-mcp

🧠 Why NullWire exists

Your AI assistant is great at debugging an API call, until the request it needs to read carries an Authorization header, a session cookie, a database URL or a customer's email. Pasting raw traffic into a chat means pasting your secrets with it.

NullWire sits between your app and the network. It records what passes through, scrubs every secret out of the recorded copy, and hands that clean copy to your assistant through the Model Context Protocol. Your app keeps working exactly as before, because the live traffic is never touched.

  your app ──► NullWire (127.0.0.1) ──► the real server
                    │
                    ├─ forwards your traffic as-is (bodies untouched)
                    └─ keeps a scrubbed copy in RAM ──► your AI assistant (MCP)

✨ At a glance

⚖️ How it compares

NullWire is deliberately narrow: it lets an AI assistant look at your network traffic while the secrets in it are replaced before the model sees them. Other tools do other jobs, and some of them do those jobs better. Here is the honest picture.

NullWire does not replace mitmproxy for full HTTPS interception, Langfuse for production tracing, or Presidio for PII pipelines. If one of those fits your job, use it. If you want your assistant to see traffic and never the secrets in it, that is what NullWire is for.

These comparisons come from each project's own documentation. If something is out of date, please open an issue.

🚀 Quick start

1. Install it

Pick whichever fits your machine. Every method checks the download against the release's SHA256SUMS.txt and installs nothing if it doesn't match. Release binaries also carry signed GitHub build provenance and keyless cosign signatures (*.sigstore.json), and each release includes a CycloneDX SBOM (nullwire-sbom.cdx.json).

npx -y nullwire-mcp install --client all

curl -fsSL https://raw.githubusercontent.com/VoxNode-ux/nullwire-mcp/main/scripts/install.sh | sh -s -- --setup

irm https://raw.githubusercontent.com/VoxNode-ux/nullwire-mcp/main/scripts/install.ps1 | iex
nullwire-mcp install --client all

curl -fsSL https://voxnode-ux.github.io/nullwire-mcp/install.sh | sh -s -- --setup

irm https://voxnode-ux.github.io/nullwire-mcp/install.ps1 | iex

# Debian, Ubuntu: download the .deb from the release page, then
sudo apt install ./nullwire-mcp_1.2.0_amd64.deb
# Fedora, RHEL
sudo dnf install ./nullwire-mcp-1.2.0-1.x86_64.rpm
# Alpine (packages are not signed with an Alpine key)
sudo apk add --allow-untrusted ./nullwire-mcp_1.2.0_x86_64.apk
# Arch Linux (AUR)
yay -S nullwire-mcp-bin
# Nix
nix run github:VoxNode-ux/nullwire-mcp

winget install VoxNode.NullWire
choco install nullwire-mcp

pipx run nullwire-mcp install --client all        # or: pip install nullwire-mcp
gh extension install VoxNode-ux/gh-nullwire && gh nullwire scan --discover
mise use -g github:VoxNode-ux/nullwire-mcp        # mise, no plugin needed
mise plugin install nullwire-mcp https://github.com/VoxNode-ux/asdf-nullwire-mcp   # or the asdf plugin

brew install VoxNode-ux/nullwire/nullwire-mcp                                   # macOS, Linux
scoop bucket add nullwire https://github.com/VoxNode-ux/scoop-nullwire           # Windows
scoop install nullwire-mcp

chmod +x nullwire-linux-amd64
sha256sum -c SHA256SUMS.txt --ignore-missing   # verify the download (macOS: shasum -a 256 -c)
gh attestation verify nullwire-linux-amd64 --repo VoxNode-ux/nullwire-mcp   # optional: verify signed build provenance

go install github.com/VoxNode-ux/nullwire-mcp@latest
# or
git clone https://github.com/VoxNode-ux/nullwire-mcp && cd nullwire-mcp
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o nullwire-mcp .

docker run -i --rm ghcr.io/voxnode-ux/nullwire-mcp

2. Add it to your MCP clients

One command registers NullWire with every supported client it finds on your machine:

nullwire-mcp install --client all --dry-run   # look first: nothing is written
nullwire-mcp install --client all             # then do it, and restart the client

It covers Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Cline, Roo Code, Gemini CLI and Codex CLI. See Connect your MCP clients for details, or add it by hand:

# Claude Code
claude mcp add nullwire -- /path/to/nullwire-mcp

// Claude Desktop, Cursor, Windsurf, Cline and other JSON-configured clients
{
  "mcpServers": {
    "nullwire": {
      "command": "/path/to/nullwire-mcp",
      "args": ["-port", "8080"]
    }
  }
}

The client starts NullWire, and NullWire starts the proxy in the same process. A live status bar on stderr shows what is happening:

⚡ [NullWire-MCP] Proxy 127.0.0.1:8080 | RAM Ring: 3/50 | Scrubbed: 7 Tokens, 2 Cookies, 1 IPs | Disk: 0B

3. Send some traffic through it

# Plain HTTP through the proxy
curl -x http://127.0.0.1:8080 http://httpbin.org/headers

# HTTPS through the proxy (a blind tunnel, see "How it works")
curl -x http://127.0.0.1:8080 https://example.com

# HTTPS with full request visibility: the reverse gateway
nullwire-mcp -target https://api.example.com
curl http://127.0.0.1:8080/v1/things -H "Authorization: Bearer sk-live-..."

4. Ask your assistant

"Use inspect_traffic to show my last 5 requests and tell me why the third one returned 401."

🔭 How it works

flowchart LR
    A[Your app or curl] -->|HTTP_PROXY / base URL| P[NullWire proxy<br/>127.0.0.1:8080]
    P -->|bodies untouched| S[(Real server)]
    S -->|bodies untouched| P
    P --> C[Capture copy]
    C --> R[Redaction layers]
    R --> B[(RAM ring<br/>50 flows)]
    B -->|MCP over stdio| M[AI assistant]

The key idea: the model reads a scrubbed copy, your app talks to the real server. Request and response bodies are never rewritten. Only a few negotiation headers are adjusted (see Safety shields), so debugging barely changes the behaviour you are debugging.

Four ways to capture traffic

Why no HTTPS interception? Reading HTTPS from a forward proxy would require a custom root certificate installed on your machine. That is key material and a trust-store change, the opposite of a zero-footprint tool. The reverse gateway gets you the same visibility with no certificate games.

Several APIs at once

Give each upstream a name. The first path segment picks the upstream and is removed before forwarding:

nullwire-mcp -target openai=https://api.openai.com,anthropic=https://api.anthropic.com

export OPENAI_BASE_URL=http://127.0.0.1:8080/openai/v1       # → https://api.openai.com/v1
export ANTHROPIC_BASE_URL=http://127.0.0.1:8080/anthropic    # → https://api.anthropic.com

Names are letters, digits, ., _ and - (up to 32 characters, case-insensitive). One unnamed URL may be added as the default for paths that match no name. An X-Target-URL header overrides everything for a single request.

🧰 MCP tools

NullWire exposes three tools over stdio. It speaks MCP protocol versions 2026-07-28, 2025-11-25 and 2024-11-05, and accepts JSON-RPC batches.

A flow looks like this (illustrative):

{
  "id": 7,
  "timestamp": "2026-10-31T09:14:02Z",
  "method": "POST",
  "url": "https://api.example.com/v1/charge",
  "request_headers": { "Authorization": "[REDACTED_TOKEN#a1b2c3]", "Content-Type": "application/json" },
  "request_body": "{\"card_token\":\"[REDACTED_TOKEN#9f3e21]\",\"amount\":4200}",
  "status_code": 401,
  "response_body": "{\"error\":\"invalid_api_key\"}",
  "latency_ms": 143,
  "redaction_count": 2
}

Tags are stable and correlatable. [REDACTED_TOKEN#a1b2c3] is a short salted hash, so the same secret gets the same tag everywhere in one run. Your assistant can see that two requests used the same token without learning it. The salt is random per run, so tags can't be compared across restarts or reversed.

Tag kinds: TOKEN, COOKIE, IP and KEY (private keys).

export_sanitized_curl produces something like:

# Replay of flow 7
# Set environment variables first:
# export NULLWIRE_AUTH_TOKEN=...   # was [REDACTED_TOKEN#a1b2c3]
curl -X POST 'https://api.example.com/v1/charge' \
  -H "Authorization: $NULLWIRE_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '…'

Placeholders are NULLWIRE_AUTH_TOKEN, NULLWIRE_COOKIE, NULLWIRE_IP and NULLWIRE_PRIVATE_KEY. CONNECT tunnels have no replayable request, and NullWire says so.

🧽 What gets redacted

Every URL, header, request body and response body passes through these layers, in this order:

Headers. Authorization, Cookie, Set-Cookie, X-Api-Key, Api-Key, X-Auth-Token and Proxy-Authorization are always redacted, plus common cloud and developer-tool headers (X-Auth-Key, Ocp-Apim-Subscription-Key, X-Amz-Security-Token, X-Goog-Api-Key, Private-Token, X-Vault-Token, Apikey, and others), plus any you add. Use ignore_headers to opt a header out.

Cloud credentials without a prefix. AWS secret access keys, Azure storage and Service Bus keys, Azure AD client secrets (…8Q~…) and SQL connection-string passwords have no vendor prefix. They are caught by the name they are stored under (SecretAccessKey, AccountKey, SharedAccessKey, client_secret, Password= in a connection string), by their shape (a standalone 40-character random base64 string, an Azure AD secret), or by the header they travel in. Cloudflare API tokens are caught by Authorization: Bearer, X-Auth-Key, the new cfut_/cfat_ prefixes, or the randomness detector.

Vendor tiers. Matching all prefixes the same way would redact ordinary words, so they are tiered:

Prefixes are matched case-sensitively, so asiapacific_region is left alone.

Bodies are decoded before scrubbing. gzip and deflate (up to 1 MiB expanded, a decompression-bomb guard). multipart/form-data forms are split into fields; file parts keep only the field name, file name and size.

🛡️ Safety shields

Limits

⚙️ Configuration

Pass -secrets-config path/to/file.json to tune redaction without recompiling. Every field is optional.

{
  "sensitive_headers":     ["X-Company-Auth", "X-Api-Signature"],
  "ignore_url_substrings": ["/healthz", "/metrics"],
  "ignore_headers":        ["User-Agent"],
  "custom_vendors": [
    { "name": "Internal DB", "prefix": "db_prod_", "pattern": "" },
    { "name": "Acme Auth",   "prefix": "acme_",    "pattern": "acme_[a-zA-Z0-9]{32}" }
  ],
  "extra_regex_patterns": [
    { "name": "app_key", "pattern": "app_k_[a-zA-Z0-9]{24}" }
  ]
}

Patterns use Go's RE2 syntax, which runs in linear time, so a bad pattern cannot freeze the proxy.

🔌 Connect your MCP clients: install

install writes NullWire into your MCP clients' config files, and removes it again, so you never have to hunt for the right file or JSON key.

nullwire-mcp install --list                          # supported clients and whether they are here
nullwire-mcp install --client all --dry-run          # preview every change
nullwire-mcp install --client cursor,vscode          # just these two
nullwire-mcp install --client cursor -- -port 8081   # save server flags with the entry (after --)
nullwire-mcp install --uninstall --client all        # take it back out
nullwire-mcp install --print                         # a snippet to paste into clients that aren't supported

Other clients (Zed, Continue, JetBrains and more) are not edited. Use --print and paste the snippet where that client keeps its MCP servers.

How it stays safe

• With --client all it only touches clients it finds on your machine. Name a client explicitly to create its config.
• The first time it changes a file it keeps a copy next to it as <file>.nullwire-bak. That copy is never overwritten, so it always holds the original.
• Files are written through a temporary file and renamed, and symlinked dotfiles stay symlinks.
• Your other servers, settings, numbers and extra fields on the NullWire entry (such as env) are kept. JSON keys may be re-ordered.
• A config it can't parse as plain JSON (for example one with comments) is left alone, with a clear message.
• Running it twice changes nothing the second time.

🔎 Scan your machine: scan and protect

Secrets leak long before traffic does: a token in an MCP config, a password in .env. NullWire can find them. Scanning never writes to disk and never prints a secret: findings are shown already scrubbed, and shell history text is never shown at all.

nullwire-mcp scan --discover                 # known MCP client configs, ~/.env, ~/.codex/config.toml, …
nullwire-mcp scan .mcp.json .env             # specific files
nullwire-mcp scan --deep ./my-project --toml --yaml --zip
nullwire-mcp scan --history                  # opt-in: count secrets in shell history

File types are recognised by name, so nullwire-mcp scan some.env config.toml settings.yaml bundle.zip routes each to the right scanner. Files over 4 MiB are skipped. ZIP archives are read in memory under a zip-bomb shield: entries over 1 MiB, archives over 20 MiB of content or 1000 entries are skipped and reported.

Git hook. Block commits that contain secrets with pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/VoxNode-ux/nullwire-mcp
    rev: v1.2.0
    hooks:
      - id: nullwire-scan            # builds nullwire-mcp from source (needs Go)
      # - id: nullwire-scan-system   # or use the nullwire-mcp already on your PATH

The hook runs nullwire-mcp scan --fail --yaml on staged .env, MCP config, TOML and YAML files. The report shows scrubbed values only.

Shortcut. Add alias nw="nullwire-mcp" to your ~/.bashrc or ~/.zshrc (PowerShell: Set-Alias nw nullwire-mcp), then nw scan --discover.

protect runs a quick scan of the usual places, then starts the normal server:

nullwire-mcp protect --target https://api.example.com --deep .

It accepts the server options (--port, --target, --cacert, --dns, --secrets-config, --scrub-headers, --allow-uninspectable) plus --deep DIR, --history and --no-scan. The scan report goes to stderr, so the MCP channel on stdout stays clean, and stop signals are passed on to the server.

📟 CLI reference

nullwire-mcp [flags]                 run the MCP server and the proxy
nullwire-mcp scan [options] [PATH…]  look for secrets in files
nullwire-mcp protect [options]       scan, then run the server
nullwire-mcp install [options]       register NullWire with your MCP clients

📱 Platform notes

Termux and Android. Static Go binaries have no system DNS settings or CA certificates on Android. NullWire detects Termux and uses 1.1.1.1 and 9.9.9.9 for lookups, printing a notice (those resolvers will see the hostnames you contact). Choose your own with -dns <resolver>, or -dns system to turn this off. Upstream HTTPS uses the CA certificates found in Termux's standard locations; add more with -cacert.

chmod +x nullwire-linux-arm64
sleep infinity | ./nullwire-linux-arm64   # keep stdin open; use a second session for curl

Corporate networks. If your company re-signs HTTPS traffic, add its root with -cacert /path/to/company-root.pem.

Windows. Use the .exe and the same flags. scan --history also checks PowerShell's PSReadLine history.

🔐 Security model and honest limits

NullWire is a diagnostic tool. Be clear-eyed about what it does and does not promise.

What it guarantees

• Nothing is written to disk by the server, and a stop signal clears the buffer (references are dropped; memory is not zeroed). The install command edits MCP client configs only when you run it, and backs each file up first.
• The proxy is reachable only from your own machine.
• The model never sees the live traffic, only the scrubbed copy.
• Request and response bodies are never rewritten. Headers are adjusted only where inspection needs it: Accept-Encoding is reduced to gzip/deflate, and the WebSocket permessage-deflate offer is dropped.

What it does not do

• Release binaries carry signed build provenance, not OS-vendor code-signing certificates. Verify authenticity with SHA256SUMS.txt and gh attestation verify. Because they are not signed with an Apple Developer ID or Microsoft Authenticode certificate, on macOS you may need xattr -d com.apple.quarantine ./nullwire-darwin-arm64.
• It is not a TLS interceptor. CONNECT tunnels show only the destination and byte counts. Use the reverse gateway when you need HTTPS content.
• Redaction is pattern and heuristic based. A secret in a shape nobody anticipated, and low in randomness, can slip through. The randomness detector can also redact a harmless long identifier. Add your own patterns in the config for secrets you know about.
• Brotli and Zstd bodies are never decoded (the standard library can't, and pulling in a package would break the zero-dependency rule). They are refused (requests) or flagged (responses).
• WebSocket flows appear when the connection closes. Messages compressed with permessage-deflate can't be read, so NullWire drops the client's extension offer to keep frames readable.
• An XML secret element that contains nested markup is not covered by the XML layer.
• Upstream connections use HTTP/1.1. HTTP/2 and gRPC bodies are not captured.

If you find a secret NullWire missed, please open an issue with a fake sample that has the same shape. Never post a real one.

✅ Tested on

🟡 emulated means run under QEMU, not on real hardware. Details are in docs/test-results.md.

🧪 Development

go vet ./...
go test -race ./...

• Zero dependencies: go.mod has no require lines, and CI keeps it that way.
• Release transparency: every release is built with Go 1.26 and includes SHA256SUMS.txt, a CycloneDX SBOM (nullwire-sbom.cdx.json) and a signed build provenance attestation, which you can verify with gh attestation verify. The same proof is attached to each release as nullwire-provenance.intoto.jsonl. The go vet and go test -race logs of every CI run are saved as a test-logs artifact for 30 days. Pushes to main update a rolling latest pre-release; numbered tags produce stable releases. Pull requests never publish anything.
• Quality checks: quality.yml runs golangci-lint (errcheck, staticcheck, revive, ineffassign), reports test coverage (Codecov) and compares benchmarks against the base branch with benchstat. Run the benchmarks yourself with go test -run='^$' -bench=. -benchmem ./.... chaos_test.go injects network faults (slowloris, dropped connections, malformed and truncated streams) and checks that nothing crashes or leaks.
• Supply chain: releases are signed with keyless cosign, the Docker image is signed and scanned with Trivy every week, reproducible.yml rebuilds the binaries on four different runners and requires identical checksums, and security.yml (weekly) runs govulncheck, gosec and the fuzz targets. Verify a download with cosign verify-blob --bundle nullwire-linux-amd64.sigstore.json --certificate-identity-regexp 'https://github.com/VoxNode-ux/nullwire-mcp/\.github/workflows/release\.yml@.*' --certificate-oidc-issuer https://token.actions.githubusercontent.com nullwire-linux-amd64.
• Releases: a stable tag publishes the release, the .deb/.rpm/.apk packages, the npm package (with provenance), the Homebrew and Scoop taps, the AUR, winget, Chocolatey, PyPI and the official MCP Registry. Release notes are grouped by pull request label (.github/release.yml).
• Fuzzing: the scrubber, the IPv6 and vendor-key matchers and the WebSocket frame reader have fuzz targets. They check that no secret survives scrubbing, that results don't depend on how input is chunked, and that nothing panics.
• CI: checks the shell and Node installers for syntax errors, runs go vet and the race detector, cross-compiles static binaries for all 9 platforms (Linux x86-64, ARM64, ARMv7 and RISC-V 64; macOS Intel and Apple Silicon; Windows x86-64 and ARM64; FreeBSD x86-64), and publishes a multi-arch Docker image (amd64 and arm64). smoke.yml and smoke-extra.yml run on demand (Actions → Run workflow): end-to-end redaction tests on Ubuntu, macOS (Apple Silicon and Intel), Windows (x86-64 and ARM64), a FreeBSD VM, and QEMU-emulated Linux ARMv7 and RISC-V 64. Security checks run govulncheck and the fuzz targets. GitHub Actions are pinned to full commit hashes.

❓ Troubleshooting