Repository navigation
Releases
SurrogateShield v0.2.0 - Production Release
What's New in v0.2.0
This release marks SurrogateShield's transition to Production/Stable status,
with expanded PII detection coverage, a new adversarial evaluation suite,
and the standalone pip-installable Python library.
New Features
- Attacker Experiment — Simulates an informed adversary intercepting
sanitized API traffic and attempting to recover original PII from both
SurrogateShield and Presidio output. Proves surrogate-based anonymization
achieves equivalent inference resistance to placeholder redaction. - Ablation Study (Table 4) — Per-stage F1 contribution analysis across
four pipeline configurations (PatternScan only → full cascade), computed
post-hoc from existing answers files. - Presidio Side-by-Side Comparison (Table 1) — Per-entity-type
precision/recall/F1 for SurrogateShield vs Microsoft Presidio, including
SS-only types Presidio cannot detect. - BERTScore Utility Preservation (Table 2) — Semantic similarity scoring
(roberta-large) comparing original vs SurrogateShield-sanitized vs
Presidio-redacted text, with paired t-test significance testing. - API Transparency Panel — Shows exactly what was sent to the LLM,
what raw response came back, and the final restored output.
Python Library (pip install surrogateshield)
The full detection and masking pipeline is now available as a self-contained
pip package with no dashboard dependency. Five-function public API:
config, scan, mask, unmask, flush. Supports Anthropic, OpenAI,
Gemini, and any local model.
import surrogateshield as shield
shield.config(detailed_view=False)
sanitized = shield.mask(user_text)
response = llm.chat(sanitized)
restored = shield.unmask(response)
shield.flush()Detection Improvements
pii_offparameter to detect but not replace specific PII types- Persistent AES-256-GCM shadow map for multi-process / web server deployments
scan()/pii_finderalias for read-only PII inspection- Service-query detection now supports the full extended street suffix list
Test Coverage
- 134 checks across 7 test files — no API key required
test6.pycovers the full Attacker Experiment module with mocked API callstest7.pycovers the standalone pip library end-to-end
Bug Fixes
- HKDF key derivation corrected (device secret as IKM, conversation ID as salt)
- ResolvePass Pass 2 scoped to unresolved surrogates only — prevents silent
corruption of unrelated words containing surrogate components - PatternScan
skip_valuesprevents re-detection of surrogates quoted back
by the user in multi-turn conversations
Full documentation: https://sherwinvishesh.github.io/SurrogateShield/docs.html
PyPI: https://pypi.org/project/surrogateshield/
Paper: under review
SurrogateShield – Journal Submission Version
Journal Submission Release
This release contains the exact source code used for the experiments,
evaluation, and results reported in the journal submission of
"SurrogateShield".
Reproducibility
This release is frozen to ensure reproducibility of the published results.
Citation
If you use this code, please cite the corresponding publication.
Notes
This release corresponds to the version submitted for peer review and may differ from future development versions.