Skip to main content

HIPAA PHI Detector

The hipaa-phi-detector policy is a text-focused PHI safeguard for the Keeptrusts gateway. It evaluates request messages before the upstream call and, when the policy is present in the chain, also enables buffered response redaction for matching output text. The detector uses the base PII engine plus HIPAA-oriented heuristics such as names, addresses, fax numbers, medical record numbers, health-plan identifiers, license or certificate numbers, device identifiers, and text mentions of biometric or photo identifiers.

Configuration​

pack:
  name: hipaa-phi-detector
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - hipaa-phi-detector

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

Fields​

FieldTypeDescriptionDefault
action"redact" | "block"Request-phase behavior when the detector finds PHI-like content. redact returns a redaction verdict and enables response redaction in the shared output pipeline. block blocks the request on input, but output handling still uses buffered redaction rather than a hard output block."redact"
modestringAccepted compatibility field. The gateway currently only recognizes hipaa_18, and the value does not change detection behavior today."hipaa_18"
safe_harbor_methodbooleanAccepted compatibility field. The current detector reads the flag but does not change matching logic based on it.true

What the detector actually covers​

The detector is heuristic and text-only. It combines the base PII detector with HIPAA-oriented matching rules.

Base PII engine​

The shared detector contributes matches for items such as:

  • email addresses
  • Social Security numbers
  • phone numbers
  • public IP addresses
  • URLs with specific paths or query strings
  • dates
  • account numbers
  • ZIP codes
  • license plates

HIPAA-oriented extensions​

When the HIPAA detector is active, the gateway also looks for:

  • person names
  • street addresses and city mentions
  • fax numbers
  • medical record numbers
  • health-plan or policy identifiers
  • certificate and driver's license numbers
  • device identifiers and serial numbers
  • text mentions of biometric identifiers
  • text mentions of photos or facial images

How it works​

  1. Request evaluation: the gateway joins request messages and evaluates hipaa-phi-detector during the input phase.
  2. Detection: the gateway combines the general PII detector with HIPAA-specific heuristics.
  3. Input verdict: if a match is found, action: redact produces a redaction verdict and action: block produces a block verdict.
  4. Response redaction: when the policy is in the chain, the gateway also enables buffered output redaction for matching response text. That output path uses the shared redaction pipeline.
  5. Audit details: the decision event records the first matched kind, reason code, confidence counts, and the redaction targets.

Important limitations​

  • This policy is not a formal HIPAA Safe Harbor certification engine.
  • mode and safe_harbor_method are accepted for forward compatibility, but they do not change matching behavior today.
  • Detection is text-focused. Image files, voice samples, and non-text artifacts are not inspected by this policy.

Valid examples​

Redact matching PHI-like content​

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

policies:
  chain:
    - hipaa-phi-detector

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

Block PHI-like input before it reaches the model​

pack:
  name: hipaa-block
  version: "1.0.0"
  enabled: true

policies:
  chain:
    - hipaa-phi-detector

policy:
  hipaa-phi-detector:
    action: block
    mode: hipaa_18
    safe_harbor_method: true

Best practices​

  • Use action: redact when you want the gateway to sanitize content instead of rejecting the turn.
  • Pair hipaa-phi-detector with healthcare-compliance when you need both PHI protection and medical-content controls.
  • Use rbac for minimum-necessary access rules; the HIPAA detector only finds PHI-like text, it does not authorize access.
  • Validate with representative PHI test strings and inspect emitted events before rollout.

Next steps​