Skip to content

Releases

SurrogateShield v0.2.0 - Production Release

Choose a tag to compare

@sherwinvishesh sherwinvishesh released this 01 Jun 03:18

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_off parameter to detect but not replace specific PII types
  • Persistent AES-256-GCM shadow map for multi-process / web server deployments
  • scan() / pii_finder alias 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.py covers the full Attacker Experiment module with mocked API calls
  • test7.py covers 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_values prevents 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

Choose a tag to compare

@sherwinvishesh sherwinvishesh released this 28 May 20:58

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.