Pastewatch

Pastewatch

[](https://github.com/ppiankov/pastewatch/releases) [](https://github.com/ppiankov/pastewatch/releases/tag/v0.28.0) [](LICENSE) [](https://github.com/ppiankov/pastewatch/actions/workflows/ci.yml) [](https://ancc.dev)

Detects and obfuscates sensitive data before it reaches AI systems — clipboard monitoring, CLI scanner, MCP server, API proxy, shell guard hooks, and VS Code extension.

It operates before paste, not after submission.

If sensitive data never enters the prompt, the incident does not exist.

---

Core Principle

Principiis obsta - resist the beginnings.

Pastewatch intervenes at the earliest irreversible boundary: the moment data leaves the user's control.

Once pasted into an AI system, data cannot be reliably recalled, audited, or constrained.

Pastewatch refuses that transition.

---

Why This Matters

Every AI agent sends your file contents, command outputs, and tool results to a cloud API. If those contain secrets, the secrets leave your machine — silently, irreversibly, and into infrastructure you don't control.

Pastewatch makes secret leakage structurally impossible without breaking any agent functionality:

  What the agent does                What actually happens
  ──────────────────                 ──────────────────────
  Read a file with secrets     →    MCP returns placeholders, secrets stay in RAM
  Run a bash command with DSN  →    Guard blocks before execution
  Send tool results to API     →    Proxy redacts secrets from the request body
  Write code with placeholders →    MCP resolves originals locally on write-back

The agent works normally. It reads files, runs commands, writes code. It just never sees the real values — and neither does the cloud.

No behavioral rules. No trust assumptions. No ML. The architecture prevents the leak.

Why Pastewatch

• Before-paste boundary — secrets never leave your machine. Nightfall, Prisma, Check Point all intercept downstream. Pastewatch prevents upstream
• MCP server for AI agents — no other tool provides redacted read/write at the tool level. The agent works with placeholders, your secrets stay local
• Bash guard with deep parsing — pipes, subshells, redirects, database CLIs, infra tools. Every shell command the agent runs is scanned before execution
• API proxy — catches everything, including subagents and tools that bypass hooks. Last line of defense before the network boundary
• Canary honeypots — "prove it works" not "trust it works." Plant format-valid fake secrets and verify they're caught
• Local-only, deterministic, no ML — no cloud dependency, no probabilistic scoring, no telemetry. Runs offline, gives the same answer every time
• One command — pastewatch-cli launch claude and every layer is active. No manual setup, no env vars, no second terminal

---

What Pastewatch Does

Pastewatch started as a clipboard monitor — scan before paste, replace secrets with placeholders. It evolved into a full secret protection stack for AI agent workflows:

| Layer | What it does | How it works | |-------|-------------|-------------| | Clipboard monitor | Scans before paste | macOS menubar app, replaces secrets in clipboard | | CLI scanner | Scans files, directories, git diffs | pastewatch-cli scan --dir . | | Startup sweep | Warns about pre-existing shell config credentials | pastewatch-cli launch scans common startup files once per changed finding summary | | MCP server | Redacted read/write for AI agents | Agent sees placeholders, originals stay in RAM | | Shell guard | Blocks secrets in commands and file access | Pre-execution hook for Claude Code, Cline, Cursor, Windsurf, Continue, Amazon Q | | API proxy | Redacts secrets from outbound API traffic | Sits between agent and cloud, scans every request | | VS Code extension | Real-time detection in the editor | Highlights secrets as you type |

All layers share the same detection engine — 30+ pattern types, deterministic regex, no ML. Every layer operates locally. Nothing phones home.

False negatives are preferred over false positives.

---

What Pastewatch is NOT

• Not a DLP system — no policies, no enforcement workflows, no admin console
• Not a compliance product — it does not certify, audit, or generate reports for regulators
• Not an AI classifier — deterministic pattern matching only, no probabilistic scoring
• Not a policy engine — it does not decide what you're allowed to do, it prevents structural leaks

Pastewatch does not:

• phone home or collect telemetry
• require cloud connectivity
• guess, infer, or act when uncertain
• store clipboard history or file contents
• make decisions — it presents evidence and lets you decide

---

How Pastewatch Works

Pastewatch scans text for sensitive patterns and replaces them with non-sensitive placeholders. The same engine powers all six layers:

1. Detection — regex-based pattern matching across 30+ secret types (API keys, DSNs, tokens, credentials, PII)
2. Obfuscation — matched values are replaced with typed placeholders (`, `)
3. Resolution — MCP server stores originals in local RAM, restores them on write-back. Secrets never leave the machine

The clipboard monitor scans before paste. The CLI scans files on demand. The MCP server scans on read and resolves on write. The guard scans commands before execution. The proxy scans API requests before they leave the network. Each layer catches what the others miss.

---

Quick Start

30 seconds from zero to protected AI agent session:

# 1. Install
brew install ppiankov/tap/pastewatch

# 2. Set up hooks and MCP server for your agent
pastewatch-cli setup claude-code

# 3. Run through the proxy — one command, fully protected
pastewatch-cli launch claude

The launch command starts the proxy, waits for it to be ready, sets ANTHROPIC_BASE_URL, and runs your agent. When the agent exits, the proxy stops. Every outbound API request is scanned and secrets are redacted before they leave your machine.

Important: The setup step injects credential handling rules into your agent's CLAUDE.md. Without these rules, agents may echo passwords in shell output or store plaintext credentials in memory files — formats that bypass regex detection. The rules ensure agents use detectable keywords (password=, secret=) and never store raw values. See [docs/CLAUDE-SNIPPET.md](docs/CLAUDE-SNIPPET.md) for the full snippet.

For persistent setup, add a shell alias:

# .zshrc / .bashrc
alias claude='pastewatch-cli launch claude'

---

Installation

From Release (Recommended)

1. Download the latest .dmg from Releases
2. Open the DMG and drag Pastewatch.app to Applications
3. Launch Pastewatch from Applications
4. Grant notification permissions when prompted

CLI via Homebrew

brew install ppiankov/tap/pastewatch
pastewatch-cli doctor    # verify installation

CLI Manual Install (No Homebrew)

For environments where Homebrew is not available (CI runners, restricted workstations):

# macOS (universal binary — Apple Silicon + Intel)
curl -L -o pastewatch-cli https://github.com/ppiankov/pastewatch/releases/latest/download/pastewatch-cli

# Linux x86_64
curl -L -o pastewatch-cli https://github.com/ppiankov/pastewatch/releases/latest/download/pastewatch-cli-linux-amd64

# Linux arm64
curl -L -o pastewatch-cli https://github.com/ppiankov/pastewatch/releases/latest/download/pastewatch-cli-linux-arm64

chmod +x pastewatch-cli
sudo mv pastewatch-cli /usr/local/bin/
pastewatch-cli doctor

Or build from source (requires Swift 5.9+):

git clone https://github.com/ppiankov/pastewatch.git
cd pastewatch
swift build -c release
sudo cp .build/release/PastewatchCLI /usr/local/bin/pastewatch-cli

From Source (GUI)

git clone https://github.com/ppiankov/pastewatch.git
cd pastewatch
swift build -c release
./.build/release/pastewatch

---

Detection Scope

Pastewatch detects only deterministic, high-confidence patterns:

| Type | Examples | |------|----------| | Email | user@company.com | | Phone | +60123456789, (555) 123-4567 | | IP Address | 192.168.1.100 | | AWS Keys | AKIAIOSFODNN7EXAMPLE | | API Keys | sk_test_..., ghp_... | | UUIDs | 550e8400-e29b-41d4-a716-446655440000 | | JWT Tokens | eyJhbGciOiJIUzI1NiIs... | | DB Connections | postgres://..., clickhouse://... | | SSH Keys | -----BEGIN RSA PRIVATE KEY----- | | Credit Cards | 4111111111111111 (Luhn validated) | | File Paths | /etc/nginx/nginx.conf, /home/deploy/.ssh/id_rsa | | Hostnames | db-primary.internal.corp.net | | Credentials | password=..., secret: ..., api_key=... | | Slack Webhooks | https://hooks.slack.com/services/... | | Discord Webhooks | https://discord.com/api/webhooks/... | | Azure Connections | DefaultEndpointsProtocol=https;AccountName=...;AccountKey=... | | GCP Service Accounts | {"type": "service_account", ...} | | OpenAI Keys | sk-proj-..., sk-svcacct-... | | Anthropic Keys | sk-ant-api03-..., sk-ant-admin01-... | | Hugging Face Tokens | hf_... | | Groq Keys | gsk_... | | npm Tokens | npm_... | | PyPI Tokens | pypi-... | | RubyGems Tokens | rubygems_... | | GitLab Tokens | glpat-... | | Telegram Bot Tokens | 123456789:AA... | | SendGrid Keys | SG.... | | Shopify Tokens | shpat_..., shpca_... | | DigitalOcean Tokens | dop_v1_..., doo_v1_... | | Perplexity Keys | pplx-... | | JDBC URLs | jdbc:oracle:thin:@..., jdbc:db2://..., jdbc:postgresql://... | | XML Credentials | `, , etc. in XML configs | | XML Usernames | , in XML configs | | XML Hostnames | , , ` in XML configs | | High Entropy Strings | Opt-in Shannon entropy detection (4.0 bits/char threshold) |

Each type has a severity level (critical, high, medium, low) used in SARIF, JSON, and markdown output.

No ML. No probabilistic scoring. No confidence levels.

If detection is ambiguous, Pastewatch does nothing.

---

Obfuscation Model

Detected values are replaced with typed, numbered placeholders:

john.doe@example.com  →  
AKIAIOSFODNN7EXAMPLE  →  
192.168.1.100         →  

How placeholders work depends on the layer:

| Layer | Placeholder lifetime | Recovery | |-------|---------------------|----------| | Clipboard | Discarded after paste | None — one-way | | CLI scan | Output only | None — report only | | MCP server | Stored in RAM for the session | Write-back resolves originals locally | | API proxy | Replaced in-flight | None — redacted before it leaves |

The MCP server is the only layer that maintains a mapping — it must, because the agent needs to write code with real values restored. The mapping lives in process memory and is lost when the session ends. No persistence, no disk, no cloud.

---

User Experience

• Clipboard/GUI — silent by default. When obfuscation occurs, a minimal macOS notification: Pastewatch: Obfuscated: Email (1), API Key (1)
• CLI — findings printed to stdout, exit code 6 if secrets found
• Startup sweep — one stderr warning per changed shell config finding summary during launch; disable with --no-startup-sweep ([details](docs/startup-sweep.md))
• MCP — transparent to the agent. It reads placeholders and writes them back. No user interaction needed
• Guard hook — blocks with a clear message: BLOCKED: file contains secrets. Use pastewatch_read_file instead
• Proxy — redacts silently. When secrets are caught, injects a [PASTEWATCH] alert into the agent's response so it can warn the user

No previews. No animations. No confirmations. Silence is success.

---

CLI Mode

Pastewatch includes a CLI tool for scanning text without the GUI:

# Scan from stdin
echo "password=hunter2" | pastewatch-cli scan

# Scan a file
pastewatch-cli scan --file config.yml

# Scan a directory recursively
pastewatch-cli scan --dir ./project --check

# SARIF output for GitHub code scanning
pastewatch-cli scan --dir . --format sarif > results.sarif

# Suppress known-safe values
pastewatch-cli scan --file app.yml --allowlist .pastewatch-allow

# Custom detection rules
pastewatch-cli scan --file data.txt --rules custom-rules.json

# Baseline: suppress known findings
pastewatch-cli baseline create --dir . --output .pastewatch-baseline.json
pastewatch-cli scan --dir . --baseline .pastewatch-baseline.json --check

# Check mode (exit code only, for CI)
git diff --cached | pastewatch-cli scan --check

# JSON output
pastewatch-cli scan --format json --check  **Single session.** The proxy handles one agent session at a time. Run a separate `pastewatch-cli proxy` instance (on a different port) for each concurrent session.

Your machine ┌──────────────────────────────────────┐ │ Agent (any process, any tool) │ │ │ │ │ ▼ │ │ pastewatch proxy (localhost:8443) │ │ scan request body → redact secrets │ │ │ │ │ ▼ │ │ corporate proxy (if present) │ │ │ │ └───────────┼──────────────────────────┘ │ ▼ Cloud API api.anthropic.com (secrets never arrive)

```bash
# One command — starts proxy, launches agent, cleans up on exit
pastewatch-cli launch claude

# With options
pastewatch-cli launch --audit-log /tmp/pw.log -- claude --model opus

# Any agent
pastewatch-cli launch -- codex --full-auto

Or start the proxy manually for more control:

# Start the proxy in one terminal
pastewatch-cli proxy

# Start your agent in another
ANTHROPIC_BASE_URL=http://127.0.0.1:8443 claude

Corporate proxy chaining. Many organizations require all outbound traffic to go through a corporate proxy. Pastewatch chains transparently — it scans and redacts first, then forwards through the corporate proxy:

# Corporate proxy at proxy.corp:8080
# Pastewatch scans → forwards to corporate proxy → corporate proxy forwards to API
pastewatch-cli launch --forward-proxy http://proxy.corp:8080 -- claude

  Agent (claude)
    │
    ▼
  pastewatch proxy (localhost:8443)     ← scans + redacts secrets
    │
    ▼
  corporate proxy (proxy.corp:8080)     ← existing network policy
    │
    ▼
  api.anthropic.com                     ← secrets never arrive

If the corporate proxy requires a specific port, match it:

# Corporate proxy expects traffic on :3456
pastewatch-cli launch --port 3456 --forward-proxy http://127.0.0.1:3457 -- claude

Custom gateway / private-CA endpoints. To front an LLM gateway or corporate API endpoint (any pass-through proxy) instead of api.anthropic.com, point --upstream at it. The upstream base path is preserved, and any custom auth headers the agent sends are forwarded through:

# Gateway with a pass-through base path (preserved when forwarding)
pastewatch-cli launch --upstream https://gateway.example.com/v1/passthrough -- claude

If the gateway's TLS certificate chains to a private/corporate CA, trust it with --ca-cert (added on top of the system trust store):

pastewatch-cli launch \
  --upstream https://gateway.example.com/v1/passthrough \
  --ca-cert /path/to/corp-ca.pem \
  -- claude

As a last-resort escape hatch, --insecure skips upstream TLS verification entirely (prints a warning; use only for trusted private gateways):

pastewatch-cli launch --upstream https://gateway.example.com -- claude --insecure

Both flags govern only the proxy-to-upstream connection; the agent-to-proxy hop stays plain HTTP on 127.0.0.1.

Gateway reachable only through a corporate proxy. If the upstream gateway is behind a corporate HTTP proxy (common in enterprise networks), route pastewatch's upstream connection throug

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ppiankov
• Source: ppiankov/pastewatch
• License: MIT

Install and usage instructions live in the source repository linked above.