Skip to main content

PII Detector

The pii-detector policy is the shared PII redaction control. It checks request content before the upstream call. It also redacts supported buffered responses. For SSE traffic, the gateway buffers the assistant text before it emits the redacted stream.

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 marks input for redaction. block rejects input. Output continues to use shared redaction."redact"
healthcare_modebooleanAdds HIPAA text checks for names, addresses, fax numbers, MRNs, health-plan IDs, license numbers, device IDs, and biometric terms.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[]More regexes evaluated against request and response text. Matches from these regexes are recorded as the generic generic_id type. Named capture groups do not create custom labels.[]
redaction.marker_format"label" | "asterisk" | "partial"label uses markers such as [REDACTED:SSN]. asterisk uses asterisks. partial has special masks only for SSNs, PANs, and email."label"
redaction.include_metadatabooleanEmits detailed redaction metadata, including replacement spans and span hashes.true
redaction.preserve_lengthbooleanKeeps the input 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 rules​

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

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

PCI mode rules​

When pci_mode: true, the policy adds:

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

How it works​

  1. Request phase: The gateway checks one string made from the request messages.
  2. Detection: It runs the base detector and optional HIPAA and PCI checks.
  3. It applies custom regex matches as generic_id.
  4. Input verdict: The first match returns the configured redact or block verdict.
  5. Response phase: The chain entry also enables supported output redaction.
  6. Audit details: With include_metadata, metadata includes match type, replacement text, offsets, and the source span SHA-256 hash.

For stream: true, redaction prevents token-by-token pass-through. The gateway holds the assistant text until the stream is complete.

Correct 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]"

Use 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

Use with other policies​

Recommended groups that map to active policy types:

CombinationPurpose
prompt-injection → pii-detectorBlock adversarial requests before redacting PII
pii-detector → dlp-filterRedact structured identifiers first, then apply broader pattern controls
pii-detector with data-routing-policyRedact identifiers and independently restrict targets by their declared data metadata

Best practices​

  • Use action: redact unless request-phase hard blocks are necessary.
  • Keep include_metadata: true if audit evidence for changed content is necessary.
  • Use lowercase marker keys in custom_markers.
  • Custom regexes make generic_id detections. They do not make custom labels.
  • Enable healthcare_mode only where HIPAA-like heuristics are necessary.
  • Test buffered and streaming response paths. Streaming redaction changes delivery latency.

Next steps​