Skip to content

PII

Detects personally identifiable information (PII) in text using a local NLP engine. Supports automatic masking (replace PII with placeholders) or blocking, across 40+ entity types spanning 10+ countries.

Engine: Local — no external API call, no tokens consumed.

Advanced security features:

  • Unicode normalization: Prevents bypasses using fullwidth characters (e.g. @ → @) or zero-width spaces
  • Encoded PII detection: Optionally detects PII hidden in Base64, URL-encoded, or hex strings
  • URL context awareness: Detects emails in query parameters (e.g. GET /api?user=john@example.com)
  • Extended entity support: CVV, BIC_SWIFT, and more beyond standard entity types

Policy configuration

Field Type Default Description
name string — Must be "PII" (registry name).
suppress_enforcement bool true If true, a detection does not raise GuardrailEnforcementTriggered; if false, blocking behaviour can stop the pipeline when block is true.
config.entities list[str] all entity types Presidio entity identifiers to scan (e.g. US_SSN, EMAIL_ADDRESS). An empty list disables checks in the SDK.
config.block bool false true: signal enforcement when PII is found. false: mask only (pre-flight / input masking path).
config.detect_encoded_pii bool false Also scan Base64-, URL-, and hex-encoded segments.
config.allow_list list[str] [] Extra spans (exact match) allowed in addition to built-in defaults.
{
  "version": 1,
  "pre_flight": {
    "version": 1,
    "guardrails": [
      {
        "name": "PII",
        "suppress_enforcement": true,
        "config": {
          "entities": ["US_SSN", "EMAIL_ADDRESS", "PHONE_NUMBER"],
          "block": false,
          "detect_encoded_pii": true,
          "allow_list": []
        }
      }
    ]
  }
}

Supported stages

Stage block=false (masking) block=true (blocking) Notes
input ✅ ✅ Masking must use this stage. The masked text is forwarded to the LLM instead of the original
output — ✅ Block LLM responses that contain PII before they reach the user

Stage usage

Stage block Behaviour
input false (default) Masks PII — replaces with <ENTITY_TYPE> before sending to LLM
input true Blocks the request entirely when PII is found
output true Blocks LLM response when it contains PII
output false Not supported — masking on output does not work as expected

Supported entities

Global

Entity Description
CREDIT_CARD Credit card numbers
CRYPTO Cryptocurrency wallet addresses
DATE_TIME Date and time expressions
EMAIL_ADDRESS Email addresses
IBAN_CODE International Bank Account Numbers
IP_ADDRESS IPv4 and IPv6 addresses
NRP Nationalities, religious and political groups
LOCATION Location names
PERSON Person names
PHONE_NUMBER Phone numbers in various formats
MEDICAL_LICENSE Medical license numbers
URL URLs

Custom (built-in extensions)

Entity Description
CVV Credit card CVV/CVC security codes
BIC_SWIFT Bank BIC/SWIFT codes

United States

Entity Description
US_BANK_NUMBER US bank account numbers
US_DRIVER_LICENSE US driver's license numbers
US_ITIN Individual Taxpayer Identification Numbers
US_PASSPORT US passport numbers
US_SSN Social Security Numbers

United Kingdom

Entity Description
UK_NHS UK National Health Service numbers
UK_NINO UK National Insurance numbers

Spain

Entity Description
ES_NIF Spanish tax identification numbers
ES_NIE Spanish foreign identity numbers

Italy

Entity Description
IT_FISCAL_CODE Italian fiscal codes
IT_DRIVER_LICENSE Italian driver's license numbers
IT_VAT_CODE Italian VAT codes
IT_PASSPORT Italian passport numbers
IT_IDENTITY_CARD Italian identity card numbers

Poland

Entity Description
PL_PESEL Polish national identification numbers

Singapore

Entity Description
SG_NRIC_FIN Singapore NRIC/FIN numbers
SG_UEN Singapore Unique Entity Numbers

Australia

Entity Description
AU_ABN Australian Business Numbers
AU_ACN Australian Company Numbers
AU_TFN Australian Tax File Numbers
AU_MEDICARE Australian Medicare card numbers

India

Entity Description
IN_PAN Indian Permanent Account Numbers
IN_AADHAAR Indian Aadhaar numbers
IN_VEHICLE_REGISTRATION Indian vehicle registration numbers
IN_VOTER Indian voter ID numbers
IN_PASSPORT Indian passport numbers

Finland

Entity Description
FI_PERSONAL_IDENTITY_CODE Finnish personal identity codes

South Korea

Entity Description
KR_RRN Korean Resident Registration Numbers

China (mainland)

Entity Description
CN_RESIDENT_ID 18-digit resident identity card (居民身份证), regex + checksum
CN_USCC Unified Social Credit Code (统一社会信用代码), GB 32100-2015
CN_MOBILE Mainland mobile numbers (1[3-9]#########, optional +86)

Taiwan

Entity Description
TW_NATIONAL_ID Taiwan national ID (1 letter + 9 digits), regex + checksum

Hong Kong

Entity Description
HK_ID Hong Kong identity card (1–2 letters + 6 digits + check digit)

What it returns

{
    "guardrail_name": "PII",
    "detected_entities": {
        "EMAIL_ADDRESS": ["user@example.com"],
        "US_SSN": ["457-55-5462"]
    },
    "entity_types_checked": ["EMAIL_ADDRESS", "US_SSN", "CREDIT_CARD"],
    "checked_text": "Contact me at <EMAIL_ADDRESS>, SSN: <US_SSN>",
    "block_mode": false,
    "pii_detected": true,
    "detect_encoded_pii": false
}
Field Description
detected_entities Map of entity type → list of matched values
entity_types_checked Entity types configured for this run
checked_text Input text with PII replaced by <ENTITY_TYPE> placeholders
block_mode Whether blocking mode was active
pii_detected true if any PII was found
detect_encoded_pii Whether encoded PII scanning was enabled

With encoded PII detection enabled

When detect_encoded_pii: true, encoded PII is masked with <ENTITY_TYPE_ENCODED>:

{
    "detected_entities": {
        "EMAIL_ADDRESS": [
            "user@example.com",
            "am9obkBleGFtcGxlLmNvbQ==",
            "%6a%6f%65%40domain.com"
        ]
    },
    "checked_text": "Contact <EMAIL_ADDRESS> or <EMAIL_ADDRESS_ENCODED> or <EMAIL_ADDRESS_ENCODED>"
}