PII Detection

Overview#

Guard's PII detector is built specifically for GCC government deployments. It identifies personally identifiable information using pattern matching tuned for regional document formats, phone number schemes, and national ID structures. Beyond standard regex patterns, it performs Arabic context-aware extraction that associates nearby number sequences with Arabic keywords like "رقم الهوية" (ID number) or "جواز السفر" (passport).

Supported PII Types#

National IDs#

Guard detects national identification numbers for GCC countries:

curl -X POST http://localhost:8002/api/v1/pii/detect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Emirates ID: 784-1985-1234567-1"}'

{
  "entities": [
    {"type": "NATIONAL_ID", "value": "784-1985-1234567-1", "start": 12, "end": 30}
  ],
  "has_pii": true
}

Phone Numbers#

GCC phone numbers are detected with country code prefixes. Supported country codes:

The detector handles various formatting including spaces, dots, and dashes between digit groups, as well as 00 prefix notation (e.g., 00971501234567).

Financial Data#

Credit Cards are detected using format matching plus Luhn algorithm validation. This prevents false positives from random digit sequences that happen to be 13-19 digits long. Only sequences that pass the Luhn checksum are flagged.

IBAN Numbers follow the international format: two-letter country code, two check digits, and up to 30 alphanumeric characters. Guard detects IBANs for all countries, with GCC IBANs being the most common in government deployments.

Email Addresses#

Standard email detection with full domain matching. Covers government domains (.gov.ae, .gov.sa) as well as general email patterns.

Other PII Types#

Arabic Context-Aware Detection#

Beyond fixed-pattern matching, Guard performs contextual PII extraction for Arabic text. When Arabic keywords associated with a PII type appear in the text, Guard searches within a 50-character window for nearby number sequences or patterns.

For example, text containing "رقم الهوية" (identity number) followed by a digit sequence will tag that sequence as a NATIONAL_ID, even if the number format does not match any fixed national ID pattern.

Supported Context Keywords#

Arabic normalization is applied to both keywords and text before matching, so diacritical variations, taa marbuta vs haa, and alef variants are all handled transparently.

Detecting PII#

curl -X POST http://localhost:8002/api/v1/pii/detect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Contact ahmed@gov.ae or call +971501234567. IBAN: AE070331234567890123456"}'

{
  "entities": [
    {"type": "EMAIL", "value": "ahmed@gov.ae", "start": 8, "end": 20},
    {"type": "PHONE", "value": "+971501234567", "start": 29, "end": 42},
    {"type": "IBAN", "value": "AE070331234567890123456", "start": 50, "end": 73}
  ],
  "has_pii": true
}

Each entity includes character-level start and end offsets for precise location tracking.

Redacting PII#

The redaction endpoint replaces each detected PII entity with a typed placeholder like [REDACTED_EMAIL] or [REDACTED_NATIONAL_ID].

curl -X POST http://localhost:8002/api/v1/pii/redact \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "My Emirates ID is 784-1985-1234567-1 and email is fatima@gov.ae"}'

{
  "original": "My Emirates ID is 784-1985-1234567-1 and email is fatima@gov.ae",
  "redacted": "My Emirates ID is [REDACTED_NATIONAL_ID] and email is [REDACTED_EMAIL]",
  "entities_redacted": 2
}

Integration with Evaluation#

PII detection runs automatically as part of the /governance/evaluate endpoint. When PII is found, the evaluation response includes the detected entities and a redacted version of the content. This means you do not need to call the PII endpoints separately if you are already using the evaluation pipeline.

{
  "allowed": true,
  "action": "warn",
  "violations": [],
  "pii_detected": [
    {"type": "PHONE", "value": "+971501234567", "start": 12, "end": 25}
  ],
  "content_score": 0.0,
  "redacted_content": "Contact me [REDACTED_PHONE] for details"
}

Integration with the Guarded Proxy#

When using the proxy endpoint (/proxy/chat/completions), PII detection runs on the user message before forwarding to the AI model. The count of detected PII entities is included in the response safety metadata:

{
  "safety": {
    "input_safe": true,
    "output_safe": true,
    "pii_detected": 2,
    "blocked": false
  }
}