PasteGuard

PasteGuard is a privacy layer designed to mask PII (Personally Identifiable Information) and secrets before they are sent to AI model providers (like ChatGPT, Claude, or Gemini). It allows users to provide real context to AI while ensuring providers only see non-sensitive placeholders.

It is designed for three primary use cases:

1. Browser Chat: Protecting web-based interfaces like ChatGPT, Claude, and Gemini via an experimental browser extension.
2. Apps & APIs: Integrating with existing applications, SDKs, and internal AI products via API/SDK integration.
3. Coding Agents: Protecting data sent to coding tools such as Codex, Claude Code, Cursor, and Windsurf.

This is particularly useful for regulated teams (finance, legal, healthcare, etc.) who need the performance of cloud-based LLMs but cannot send raw client, customer, or production data to external providers.

The score_threshold (0.0-1.0) specifically adjusts the confidence floor for the semantic labels PERSON and LOCATION.

• Higher threshold (e.g., 0.9): More conservative; reduces false positives but may miss some PII.
• Lower threshold (e.g., 0.5): More aggressive; catches more PII but increases false positives.

Note: Checksum-validated identifiers (like IBAN or Credit Cards) always score 1.0 and are never dropped by this threshold.

pii_detection:
  score_threshold: 0.7  # Default, good balance
  # score_threshold: 0.5  # More aggressive
  # score_threshold: 0.9  # More conservative (PERSON/LOCATION)

PasteGuard offers two primary privacy strategies depending on your sensitivity requirements:

Mask Mode

Replaces sensitive data with placeholders. The masked request is sent to a cloud AI provider, and the response is restored locally. Use this when you want the intelligence of cloud models but need to protect PII.

Route Mode

A stricter mode where requests containing sensitive data are intercepted and routed to a local model instead of being sent to a cloud provider at all. Use this when your policy prohibits sending even masked sensitive requests to cloud-based models.

The mode setting in config.yaml determines how Personally Identifiable Information (PII) is handled during requests. You can choose between mask and route modes:

• mask: Replaces PII with placeholders before sending the request to an upstream AI service, then restores the original PII in the response.
• route: Keeps PII requests local to your own LLM (e.g., Ollama, vLLM, llama.cpp) while routing non-PII requests to a configured cloud provider.

mode: mask

PasteGuard acts as a protected proxy for Codex CLI traffic. It distinguishes between inspected traffic and direct pass-through traffic:

• Inspected Traffic: POST /codex/responses is inspected for PII and secrets and logged in the dashboard. If these requests contain sensitive data configured with route_local, they are blocked because PasteGuard does not convert Codex Responses traffic to a local provider format.
• Pass-through Traffic: Other endpoints (e.g., /codex/models) are proxied directly to the upstream provider without inspection.

Upstream Mapping: By default, PasteGuard forwards requests to https://chatgpt.com/backend-api/codex.

Mask mode protects privacy by replacing Personally Identifiable Information (PII) with placeholders (e.g., [[PERSON_1]]) before the request is sent to an upstream AI provider. When the provider responds, PasteGuard automatically unmasks the placeholders so your application receives the original, human-readable text.

Workflow Lifecycle:

1. Request arrives: Your app sends a prompt containing PII.
2. PII detected: PasteGuard identifies sensitive entities (e.g., PERSON, EMAIL_ADDRESS).
3. Masked request sent: The upstream provider receives the prompt with placeholders instead of real data.
4. Response masked: The provider's response contains the placeholders.
5. Response unmasked: PasteGuard restores the original PII and returns the complete text to your app.

PasteGuard offers two privacy modes depending on your infrastructure and security requirements:

Mask Mode

• Best for: Teams using cloud LLMs (e.g., OpenAI, Anthropic).
• How it works: Replaces PII and secrets with placeholders before sending the request to the cloud provider. PasteGuard then restores the supported placeholders in the response received from the provider.
• Setup: Works out of the box with any provider.

Route Mode

• Best for: Teams with a local LLM infrastructure.
• How it works: Requests containing sensitive data are routed to a local LLM, while non-sensitive requests are sent to a cloud provider.
• Setup: Requires a local LLM provider to be configured in config.yaml.

Route mode provides a privacy-preserving way to handle LLM requests by inspecting them for Personally Identifiable Information (PII).

• Requests containing PII: These are automatically routed to a Local LLM (such as Ollama, vLLM, or llama.cpp) to ensure sensitive data stays within your network.
• Requests without PII: These are routed to high-performance cloud providers like OpenAI or Anthropic.

This mode is ideal when you have local GPU resources and must prevent PII from leaving your controlled environment while still utilizing cloud models for non-sensitive tasks.

By default, PasteGuard scans the following roles in Anthropic requests:

• User messages (String content or text blocks)
• Tool results (Text content in tool responses)

Assistant messages and system prompts are skipped by default. To include them in the protection scan, you must add them to the pii_detection.scan_roles or secrets_detection.scan_roles configuration settings.