Skip to main content

PII Detector

The pii-detector policy is the gateway's shared PII redaction control. It evaluates request content before the upstream call and also powers buffered response redaction when the policy is present in the chain. The policy supports base PII matching, optional healthcare-mode HIPAA-style heuristics, optional PCI detection, custom regex patterns, and configurable redaction markers.

Configuration​

pack:
  name: pii-protection
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector

policy:
  pii-detector:
    action: redact
    healthcare_mode: false
    pci_mode: true
    detect_patterns: []
    redaction:
      marker_format: label
      include_metadata: true
      preserve_length: false
      custom_markers: {}

Fields​

FieldTypeDescriptionDefault
action"redact" | "block"Controls the request-phase verdict. redact returns a redaction verdict on input. block rejects the request on input. Response handling still uses the shared output redaction pipeline when the policy is enabled."redact"
healthcare_modebooleanAdds HIPAA-like text heuristics, including names, addresses, city mentions, fax numbers, MRNs, health-plan identifiers, license numbers, device identifiers, and text mentions of biometric or photo identifiers.false
pci_modebooleanEnables PCI detection for PAN/card numbers, CVV/CVC values, and expiration dates. Today it does not detect cardholder names.true
detect_patternsstring[]Additional regexes evaluated against request and response text. Matches from these regexes are recorded as the generic generic_id kind. Named capture groups do not create custom labels.[]
redaction.marker_format"label" | "asterisk" | "partial"label uses built-in markers like [REDACTED:SSN]. asterisk uses *** or length-preserving asterisks. partial currently has custom masking only for SSNs, PANs, and email addresses; other kinds fall back to label markers."label"
redaction.include_metadatabooleanEmits detailed redaction metadata, including replacement spans and span hashes.true
redaction.preserve_lengthbooleanPreserves original character length for asterisk replacements.false
redaction.custom_markersobjectOverrides replacements by marker key. Use lowercase keys such as ssn, email, mrn, or generic_id. Custom regex matches use generic_id.{}

What the detector actually matches​

Base detector​

Always-active matching includes:

  • email addresses
  • SSNs
  • phone numbers
  • public IPv4 and IPv6 addresses
  • URLs with identifying paths or queries
  • MAC addresses, IMEIs, and VINs
  • ZIP codes and dates
  • account numbers and routing-like identifiers
  • license plates

Healthcare mode additions​

When healthcare_mode: true, the shared redaction pipeline also runs HIPAA-style heuristics for:

  • names
  • addresses and city mentions
  • fax numbers
  • MRNs
  • health-plan or policy identifiers
  • certificate and driver's license numbers
  • device IDs
  • biometric mentions
  • photo or facial-image mentions

PCI mode additions​

When pci_mode: true, the policy adds:

  • payment card numbers (PAN)
  • CVV/CVC values
  • expiration dates

How it works​

  1. Request phase: the gateway scans the joined request messages.
  2. Detection: the gateway runs the base detector, optionally adds HIPAA-style detections, optionally adds PCI detections, then applies custom regex matches as generic_id.
  3. Input verdict: on the first detection, the policy returns a redact or block verdict depending on action.
  4. Response phase: when the policy is present in the chain, the gateway can also redact buffered output text.
  5. Audit details: when include_metadata is true, redaction metadata includes redaction kind, replacement text, span offsets, and a SHA-256 hash of the original span.

Valid examples​

Default request redaction and output redaction​

pack:
  name: pii-defaults
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector

policy:
  pii-detector:
    action: redact
    redaction:
      marker_format: label
      include_metadata: true

Healthcare mode with custom MRN marker​

pack:
  name: healthcare-redaction
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector

policy:
  pii-detector:
    action: redact
    healthcare_mode: true
    redaction:
      marker_format: label
      custom_markers:
        mrn: "[MEDICAL-RECORD-REDACTED]"

PCI-sensitive request blocking​

pack:
  name: pci-request-block
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector

policy:
  pii-detector:
    action: block
    pci_mode: true

Custom regexes with generic marker override​

pack:
  name: custom-identifiers
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - pii-detector

policy:
  pii-detector:
    action: redact
    detect_patterns:
      - 'EMP-\d{6}'
      - 'ACCT-\d{8,12}'
    redaction:
      marker_format: label
      custom_markers:
        generic_id: "[REDACTED-ID]"

Combine with HIPAA heuristics​

pack:
  name: healthcare-stack
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - prompt-injection
    - pii-detector
    - hipaa-phi-detector

policy:
  pii-detector:
    action: redact
    healthcare_mode: true
    pci_mode: false
    redaction:
      marker_format: label
      include_metadata: true

  hipaa-phi-detector:
    action: redact
    mode: hipaa_18
    safe_harbor_method: true

Combining with other policies​

Recommended combinations that map to current policy kinds:

CombinationPurpose
prompt-injection → pii-detectorBlock adversarial requests before redacting PII
pii-detector → dlp-filterRedact structured identifiers first, then apply broader pattern controls
pii-detector → data-routing-policySanitize sensitive content before provider eligibility rules are enforced

Best practices​

  • Use action: redact unless you specifically need request-phase hard blocks.
  • Keep include_metadata: true if you need audit evidence for what was changed.
  • Use lowercase marker keys in custom_markers.
  • Remember that custom regexes produce generic_id detections rather than custom labels.
  • Enable healthcare_mode only where HIPAA-like heuristics are actually required.

Next steps​