---

Tanuki sits between your local Claude Code agent and the Anthropic API, rewriting every target-identifying string in real time. Your tools hit the real target; the model only ever sees a fictional localhost project.

Table of Contents

• Overview
• How it works
• Example
• Quick start
• Configuration
• CLI reference
• What gets rewritten
• Environment variables
• Architecture
• Verifying an engagement
• Known limitations
• Fail-closed behaviour
• Disclaimer
• License

Overview

Tanuki is an anonymization proxy built for AI-assisted security testing and bug bounty hunting. When you drive an agent like Claude Code through a pentest, every real domain, IP, and payload in your prompts leaves your machine. That's an OpSec risk, and it can also breach bug bounty program rules or an NDA.

Tanuki runs as a Docker container and transparently intercepts that API traffic. Before a prompt leaves your machine, it swaps real target data (domains, subdomains, IPs, emails, paths, cloud identifiers, and aggressive security terminology) for harmless fictional development equivalents. When the model responds, the fiction is mapped back to reality so your local tools execute against the real targets. The model believes it is helping you debug a local dev application, and the upstream provider is blind to your actual engagement.

How it works

flowchart TD
    classDef default fill:#050505,stroke:#8b0000,stroke-width:1px,color:#ff3333,font-family:Courier
    classDef proxy fill:#110000,stroke:#ff0000,stroke-width:2px,color:#ffffff,font-family:Courier
    classDef hooks fill:#000000,stroke:#550000,stroke-width:1px,stroke-dasharray:4 4,color:#cc0000,font-family:Courier
    classDef upstream fill:#0a0a0a,stroke:#333333,stroke-width:1px,color:#666666,font-family:Courier
    classDef data fill:#1a0505,stroke:#aa0000,stroke-width:1px,color:#ff6666,font-family:Courier

    subgraph Host["LOCAL MACHINE"]
        C["Claude Code"]
        H[/"Tanuki Hooks<br/>(docker exec)"/]
        C -. "Tool execution" .-> H
    end

    subgraph Container["DOCKER CONTAINER"]
        P{"Tanuki Proxy<br/>[scratch ~10MB]"}:::proxy
        D[("( mappings volume )")]:::data
    end

    A((("Anthropic API"))):::upstream

    C == "Real prompt data" ==> P
    P -. "Loads config" .-> D
    P -- "Rewrites to Fiction" --> A
    A -- "Responds in Fiction" --> P
    P == "Rewrites to Real" ==> C

    class C default
    class H hooks

    style Host fill:transparent,stroke:#8b0000,stroke-width:1px,color:#8b0000,font-family:Courier
    style Container fill:#020000,stroke:#4a0000,stroke-width:1px,stroke-dasharray:3 3,color:#8b0000,font-family:Courier

Example

You're testing bounty.amazon.com. Here's what Tanuki does:

Each target domain gets three mappings: the base domain, a wildcard for subdomains that have not been seen yet, and a dedicated mapping per subdomain as it is detected. The wildcard is what stops an unmapped host like internal-admin.amazon.com from leaking its label upstream.

Quick start

git clone https://github.com/Pigyon/tanuki.git
cd tanuki
docker compose up -d
claude

That pulls the latest published image from GitHub Container Registry, so no Go toolchain and no build are needed.

To build from source instead of pulling:

docker compose -f compose.yaml -f compose.dev.yaml up -d --build

On startup the proxy auto-configures the Claude Code hook and proxy env in .claude/settings.json, and writes the cover-story .claude/CLAUDE.md. Domains, emails, and IPs are auto-detected from your conversation, so no manual target configuration is needed.

When you type "check bounty.amazon.com for SQL injection", the proxy:

1. Detects amazon.com and bounty.amazon.com as new domains
2. Creates all derivative mappings (org, email, path, cloud)
3. Rewrites the request before it reaches the API

Wrapper script

A ./tanuki wrapper is included so you don't have to type docker compose exec tanuki /tanuki <command>:

./tanuki add example.com
./tanuki map
./tanuki status

Verify rewriting

Test the rewriting engine without hitting the API:

./tanuki test "scan bounty.amazon.com for SQL injection and contact [email protected]"

Configuration

Everything is optional; without it, targets are auto-detected from your conversation. To pre-configure an engagement, edit compose.yaml:

environment:
  # Custom fiction org name (default: DEVTARGET)
  - TANUKI_FICTION_ORG=ACMECORP
  # Pre-seed target domains (comma-separated)
  - TANUKI_DOMAINS=example.com,api.example.com
  # Pre-seed target IPs (comma-separated)
  - TANUKI_IPS=93.184.216.34
  # Custom rewrite rules (semicolon-separated, pipe-delimited real|fiction)
  - TANUKI_RULES=John Smith|Jane Developer;Project Phoenix|Test Alpha

Custom rewrite rules

For strings that aren't domains or IPs (people, project names, internal jargon), add custom rules via compose.yaml (applied on every container start) or at runtime:

./tanuki add-rule "John Smith" "Jane Developer"
./tanuki add-rule "Project Phoenix" "Test Alpha"

Named engagements

For separate projects or custom fiction org names:

./tanuki init bugbounty --fiction-org ACMECORP
./tanuki add bounty.amazon.com

CLI reference

All commands run via ./tanuki <command> (or docker compose exec tanuki /tanuki <command>):

What gets rewritten

Mapping-based (per engagement, all auto-detected)

Terminology (built-in, applied to all engagements)

Compound pentest-specific terms are replaced with neutral dev equivalents. Only unambiguous multi-word terms are replaced. Single words like target, payload, or exploit are left alone so legitimate code discussions don't break.

Run ./tanuki terms to see the full dictionary. The list lives in internal/tanuki/terminology.json and is embedded at build time; to customize it, edit the file and rebuild.

Environment variables

Set in compose.yaml:

Architecture

Container: scratch-based image with a single static Go binary plus CA certs. No OS, no shell, no runtime, ~10MB total. All capabilities dropped, read-only filesystem, no privilege escalation.

Everything runs in Docker. The proxy, hooks, and CLI all execute inside the container; hooks are invoked by Claude Code via docker exec, so no host-side binary is needed.

Matching: an Aho-Corasick automaton does longest-first replacement in a single pass over the stream.

JSON-aware: request and response bodies are rewritten string by string, never as raw text. Protocol fields (model, role, type, ids, tool names) are left alone, base64 data is neither rewritten nor scanned, and thinking blocks go back to the API exactly as the model wrote them, since they are signed.

Known limitations

• No HTTPS on the proxy. The proxy listens on plain HTTP. That's acceptable because it only accepts connections from localhost (Claude Code on the same machine); the upstream connection to the Anthropic API uses HTTPS.
• Literal string matching only. Encoded forms (URL-encoded, base64, and similar) won't be caught by the Aho-Corasick automaton.
• Terminology is one-directional. Pentest terms are rewritten real→fiction only. The model's responses use fiction terms, which pass through as-is.
• Wildcard subdomains are not reversible. Every subdomain without its own mapping collapses onto a single wildcard value, so it cannot be mapped back. Auto-detection creates dedicated mappings for subdomains it sees, and those round-trip normally; the wildcard is the safety net for anything that slips past detection, and it favours hiding the hostname over keeping it usable.
• Detection is the weak link, not the rewrite. Every outbound body is re-scanned after rewriting and refused if a real value survives, so a rewriter bug cannot leak. Nothing protects against a value the detector never recognised in the first place — the two limitations below are therefore the ones that matter.
• Curated TLD list for auto-detection. Auto-detection uses a curated list of ~70 common TLDs to avoid false positives from code patterns like readme.md, foo.bar, or user.id. TLDs that collide with everyday code (.info, .name, .app, .store, .top, .site, as in logger.info or user.name) are left out. Domains on those or other unusual TLDs (.pizza, .click, .it, .id) can be added manually with ./tanuki add.
• Ignored domains need an explicit add to become targets. github.com, google.com, and your own email domain are skipped by auto-detection so Claude Code's own git remotes, connectors, and account context don't pollute the table. The trade-off is that auto-detection alone will not map one of these, so on the rare engagement that targets GitHub or Google you must ./tanuki add github.com first; the residual check also skips ignored domains, so it will not catch the omission for you.
• Thinking stays in fiction. Thinking blocks are signed by the API, so they are passed through unchanged in both directions. Thinking shown in Claude Code reads in fiction terms.
• Streamed text is held back briefly. A fiction value can be streamed a few characters per event, so the proxy holds back the end of a text or tool-input block while it could still be the start of one, and sends it once the next event settles it. Display can lag by a few characters; the full value always arrives reversed.

Verifying an engagement

tanuki verify answers two questions without sending anything anywhere.

Do my mappings actually hold? With no arguments it takes every real value in the table and puts it through the shapes a target takes in practice — bare, in a URL, inside backticks, as a markdown link, in a JSON field, in an HTTP header, upper-cased, at the end of a sentence — then checks the value is gone from each. A mapping that covers the bare string can still fail inside one of these, so it is worth running before an engagement starts rather than during it.

$ ./tanuki verify
Verifying 8 mappings against 12 shapes

96 checks, 0 leaks
Every mapped value was rewritten in every shape.

Is this document safe to send? Given files, -, or a < file redirect, it rewrites the text and reports the real-looking values that no mapping covers. This is the check to run over a draft report before it is submitted.

$ ./tanuki verify report.md
  LEAK  report.md
        partner-portal.acme-supplier.io
        93.184.216.34

2 value(s) have no mapping and would be sent as-is.
Add them with: tanuki add <domain> / tanuki add-ip <ip>

It exits non-zero when it finds something, so it drops into a pre-submission hook or CI as-is.

Fail-closed behaviour

The proxy will not forward a prompt it cannot anonymize.

Every body is checked after it is rewritten. The last thing that happens before a /v1/messages request leaves is a re-scan for anything that still looks like a real target. If one survived, the request is refused with 400 and the value is written to the tanuki log — never into the HTTP response, which the client may fold into its next prompt. In a working pipeline this never fires; when it does, it means the rewriter missed something and the body must not go upstream.

Targets are mapped wherever they first appear. The proxy runs detection over every outbound body, so a target in the prompt you type, in tool output, in an @-mentioned file, a paste, CLAUDE.md, a session resumed elsewhere, or from any client that is not Claude Code gets a fiction before the rewrite rather than travelling upstream in the clear.

A request is also refused when there is no active engagement, or the mapping table is unreadable, or the table is empty and the body holds nothing recognisable. A brand-new engagement no longer blocks: the first request naming a target maps it and forwards the anonymized body.

Set TANUKI_ON_LEAK=warn to log a surviving value and forward anyway. That trades the guarantee for uptime, and is meant for diagnosing a false positive, not for normal use.

The check inherits detection's blind spots: it recognises the same curated TLD list and the same literal forms, so a target on an unusual TLD or in an encoded form is invisible to both. It catches rewriter failures, not detector failures.

Disclaimer

Tanuki is intended for authorized security testing only: engagements you have written permission to perform, such as an in-scope bug bounty program or a contracted pentest. It reduces the exposure of target data to third-party model providers; it is not a guarantee of anonymity and does not exempt you from any program rules, NDA, or law. You are responsible for how you use it.

License

Apache 2.0