PII never leaves
your device. Surrogates do.

A single round-trip through the proxy, end to end.

Every message travels through detection, surrogate generation, encrypted mapping, the LLM call, and reconstruction. PII never crosses the API boundary in plaintext.

Three detectors. Each masks what it claims.

Stages run sequentially. Spans claimed by an earlier stage are not re-processed downstream, so structured PII is masked before any NER model can hallucinate around it.

Post-processing passes detection/logic.py

Quasi-identifier scorer per Sweeney (2000) k-anonymity

Surfaces combinations of non-PII attributes that statistically re-identify an individual. Warnings fire before the message is sent.

Structured, named, and inferred — across twenty-plus categories.

Pattern order matters. Patterns claim character spans; crypto and us_bank_number run before zip_us so 9-digit routing numbers and long hex strings are claimed before the ZIP pattern can fragment them.

Realistic surrogates, not [PLACEHOLDER] tokens.

Every surrogate is type-consistent and unique within a session. Fake names look like names. Fake SSNs pass format checks. Fake Bitcoin addresses are valid Base58. The LLM sees a coherent message — and produces a coherent response.

ShadowMap — encrypted surrogate ↔ original

Persisted to conversations/<conv_id>.shadowmap as nonce (12 bytes) ‖ AES-GCM ciphertext. Unreadable without the device key.

Per-type surrogate templates

Why realistic surrogates beat [ENTITY_TYPE] redaction.

Microsoft Presidio replaces PII with placeholder tokens. SurrogateShield replaces with type-consistent fakes. Per Table 7 (simulated attacker, per-value recovery): SurrogateShield 0.00% recovery on 196 targeted values, Presidio 1.53% on 196 — and BERTScore utility is ~95% vs ~84%.

Comparable types · both systems detect

SS-only types · Presidio does not detect

Precision, recall, F1 — and an ablation study.

Pair a question file with a ground-truth answer key. The evaluator scores detection quality, per-type breakdown, ResolvePass leak rate, BERTScore utility preservation, and a per-stage contribution ablation.

BERTScore — utility preservation

Measured with roberta-large. Higher F1 means anonymisation preserved more of the original message's semantic meaning — i.e. the LLM still has the structure it needs to produce a useful response.

Ablation — per-stage F1 contribution

Four pipeline configurations are simulated post-hoc from the existing answers file. Each entity's source field tells us which stage detected it.

An informed adversary recovers nothing.

attacker.py simulates an adversary who intercepts the sanitised API payload and is given an adversarial prompt disclosing every PII type that was replaced. They are instructed to use linguistic analysis, demographic inference, cross-field correlation, and format patterns to recover the originals. Both anonymisation systems are attacked.

Table 7 — Simulated attacker per-value recovery rates

Per-value rate: fraction of individual PII values recovered across all targeted values. Nᵥ = values targeted.

Per-attempt analysis

Local-only key material. AES-256-GCM on every write.

The device secret never leaves the machine. Each conversation derives an independent key. ShadowMap files are unreadable without the device key and degrade gracefully on corruption.

Documents are anonymised at index time.

Local RAG via ChromaDB + sentence-transformers (all-MiniLM-L6-v2). No server. Real PII never enters the vector store.

document.txt
    │
    ▼
SentinelLayer  ▸ detect PII
    │
    ▼
MimicGen      ▸ generate surrogates
    │
    ▼
rag_global ShadowMap
   { surrogate → original } persisted
    │
    ▼
Anonymised document
    │
    ▼
chunk @ RAG_CHUNK_SIZE = 512
    │
    ▼
sentence-transformers
   all-MiniLM-L6-v2
    │
    ▼
ChromaDB  ▸ ./chroma_db (persistent)

user query
    │
    ▼
SentinelLayer  ▸ anonymise query
    │
    ▼
embed ▸ ChromaDB ▸ retrieve top-3
    │
    ▼
Prepend anonymised context
    │
    ▼
LLM API  ← surrogates everywhere
    │
    ▼
ResolvePass
   restores user PII + indexed-doc PII
   via rag_global ShadowMap
    │
    ▼
Display to user

Single source of truth in config.py. Everything else is a module.

All thresholds, model identifiers, and toggles live in one file. Detection, generation, storage, reconstruction, and chat are independent modules with narrow interfaces.

SurrogateShield/
├── main.py                  # CLI entry + interactive dashboard
├── pipeline.py              # End-to-end message pipeline orchestration
├── config.py                # Single source of truth — thresholds & flags
├── util.py                  # DetectedEntity, Conversation, logging
├── settings_manager.py      # ~/.surrogateshield/settings.json
├── evaluator.py             # P/R/F1 + Presidio + BERTScore + ablation
├── json_tester.py           # Batch JSON question processing
├── attacker.py              # Adversarial PII recovery experiment
├── run.sh                   # venv activation + .env loading
│
├── detection/               # SentinelLayer — three-stage cascade
│   ├── logic.py             # Cascade + post-processing passes A–D
│   ├── pattern_scan.py      # PatternScan — regex + validators
│   ├── entity_trace.py      # EntityTrace — spaCy en_core_web_lg
│   ├── context_guard.py     # ContextGuard — distilbert-NER
│   ├── service_query.py     # Address fuzzing for location queries
│   ├── quasi_identifier.py  # Sweeney k-anonymity risk scorer
│   └── geo_data.py          # Pass-through whitelist (US states, countries)
│
├── generation/logic.py      # MimicGen — Faker, no collisions
├── storage/logic.py         # ShadowMap — AES-256-GCM
├── reconstruction/logic.py  # ResolvePass — exact · component · fuzzy
│
├── presidio/                # Comparison feature (optional)
│   ├── engine.py            # Lazy singleton AnalyzerEngine
│   ├── detect.py            # detect(text) → list[PresidioEntity]
│   └── redact.py            # redact(text, entities) → [TYPE] string
│
├── chatbot/
│   ├── chat.py              # Claude / Gemini / OpenAI / Ollama
│   └── rag.py               # RAGStore — Chroma + sentence-transformers
│
├── experiment/              # Batch test files
├── tests/                   # test1–test7 — no API key needed
│
├── python-library/          # Standalone pip package — surrogateshield
│   ├── pyproject.toml       # Package metadata + dependencies
│   ├── README.md            # Full library API reference
│   └── surrogateshield/     # Self-contained — zero imports from main app
│       ├── __init__.py      # Public API: config · scan · mask · unmask · flush
│       ├── _response_parser.py # Anthropic / OpenAI / Gemini / plain string
│       └── core/            # detection · generation · storage · reconstruction
│
└── conversations/           # Runtime — .json (surrogate text) + .shadowmap

Up and running in under a minute.

You must activate a virtual environment before installing. Installing into the system or base conda Python is the most common cause of "package not found" errors at runtime.

# Clone
$ git clone https://github.com/sherwinvishesh/SurrogateShield.git
$ cd SurrogateShield

# Create and activate a virtual environment  ← required
$ python -m venv .venv
$ source .venv/bin/activate           # Windows: .venv\Scripts\activate

# Install dependencies
$ pip install -r requirements.txt

# Download the spaCy model (required by EntityTrace)
$ python -m spacy download en_core_web_lg

# ContextGuard's distilbert-NER (~250 MB) is downloaded
# automatically from HuggingFace on first use.

# Set your API key
$ echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

# Launch
$ ./run.sh

Supported providers

Press a key. Do a thing.

# Interactive dashboard (recommended)
$ python main.py
$ ./run.sh

# Start a new conversation directly
$ python main.py chat
$ python main.py chat --load <conversation-id>
$ python main.py chat --rag

# PII detection sandbox — no API calls, no credits
$ python main.py pii-finder

# Index a document into the RAG store
$ python main.py add-doc path/to/document.txt

Dashboard shortcuts

The whole pipeline, in pip install surrogateshield.

No dashboard, no CLI — just the core detection and masking pipeline as a clean Python API. The package is self-contained: it imports nothing from the main application and carries its own copies of every detection, generation, storage, and reconstruction module. The public surface is five functions and a single import line.

# Core package — spaCy model installs automatically
$ pip install surrogateshield

# Optional: Rich colour tables for detected PII / surrogates
$ pip install "surrogateshield[display]"

Public API — five functions

Quick start — a full round-trip

import anthropic
import surrogateshield as shield

client = anthropic.Anthropic()
shield.config(detailed_view=False)   # silent in production

text = (
    "Hi, I'm Sarah Mitchell. My email is sarah.mitchell@gmail.com, "
    "my SSN is 123-45-6789, and I was born on 04/12/1990."
)

# Detect every PII field, swap in realistic fakes, store the mapping
sanitized = shield.mask(text)
# → "Hi, I'm Rachel Torres. My email is torresrachel@yahoo.com,
#    my SSN is 876-32-1045, and I was born on 09/27/1983."

response = client.messages.create(
    model="claude-sonnet-4-6", max_tokens=1024,
    messages=[{"role": "user", "content": sanitized}],
)

# unmask() takes the native SDK object directly — restores real values
print(shield.unmask(response))   # contains "Sarah Mitchell", real SSN, …
shield.flush()                      # end the session

The model never processes a single real value — yet the answer your users see contains their own data. Same flow works with OpenAI, Gemini, and local / Ollama models; unmask() auto-detects the response format.

Multi-turn conversations

Keep two histories: one in surrogates for the API, one with real values for display. The session shadow map stays alive across turns, so a surrogate minted in turn 1 still resolves in turn 5 — the model never sees a real value in any turn.

from openai import OpenAI
import surrogateshield as shield

client = OpenAI()
api_history, display_history = [], []   # surrogates vs real values

def chat(user_input):
    sanitized = shield.mask(user_input)
    api_history.append({"role": "user", "content": sanitized})
    display_history.append({"role": "user", "content": user_input})

    response = client.chat.completions.create(
        model="gpt-4o-mini", messages=api_history,
    )
    raw = response.choices[0].message.content   # surrogate text
    restored = shield.unmask(response)            # real values

    api_history.append({"role": "assistant", "content": raw})
    display_history.append({"role": "assistant", "content": restored})
    return restored

chat("My name is John Doe and I live at 42 Baker Street, London.")
print(chat("What was the address I mentioned earlier?"))
# → "42 Baker Street, London" restored from turn 1's shadow map
shield.flush()

One pattern, every provider

# Google Gemini — unmask() reads response.text automatically
model = genai.GenerativeModel("gemini-1.5-flash")
sanitized = shield.mask("My card is 4532015112830366, IP 192.168.1.100.")
print(shield.unmask(model.generate_content(sanitized)))
shield.flush()

# Local / Ollama — unmask() also accepts a plain string
sanitized = shield.mask("My phone is +44 7911 123456, postcode SW1A 1AA.")
raw_reply = ask_ollama(sanitized)              # your own HTTP call
print(shield.unmask(raw_reply))
shield.flush()

unmask() — three reconstruction passes

Each pass only runs on surrogates the previous one did not resolve, so partial matches never corrupt unrelated text.

config() — full parameter reference

Quasi-identifier combination scoring Sweeney k-anonymity

When a combination is detected, all constituent fields are added to the replace set — not just the obviously-sensitive ones.

Cite this work.

SurrogateShield is described in our paper on arXiv. Pick a format and copy — BibTeX is the default.