Skip to main content

HIPAA PHI Detector

The hipaa-phi-detector policy is a text control for PHI. It checks request messages before the upstream call. It also enables buffered response redaction when the chain contains this policy. The detector uses the base PII engine and HIPAA heuristics. These heuristics include names, addresses, fax numbers, medical record numbers, and health-plan IDs. They also include license numbers, device IDs, and biometric or photo terms.

Configuration​

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

policies:
  chain:
    - hipaa-phi-detector

policy:
  hipaa-phi-detector:
    action: redact

Fields​

FieldTypeDescriptionDefault
action"redact" | "block"Selects request behavior for PHI content. redact enables shared response redaction. block stops input, but output continues to use buffered redaction."redact"

What the detector finds​

The detector is heuristic and text-only. It uses 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 specified 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 address and city terms
  • fax numbers
  • medical record numbers
  • health-plan or policy identifiers
  • certificate and driver's license numbers
  • device identifiers and serial numbers
  • biometric-identifier terms in text
  • photo or facial-image terms in text

How it works​

  1. Request check: The gateway makes one string from request messages and runs hipaa-phi-detector during the input phase.
  2. Detection: The gateway uses the general PII detector with HIPAA heuristics.
  3. Input verdict: A match returns the redact or block action.
  4. Response redaction: The chain entry also enables buffered output redaction for matching response text.
  5. The output path uses the shared redaction pipeline.
  6. Audit details: The event records the first match type, cause code, confidence counts, and redaction targets.

Important limitations​

  • This policy is not a formal HIPAA Safe Harbor certification engine.
  • The policy configuration accepts only action.
  • The policy checks text only. It does not check images, voice samples, or other non-text data.
  • Use stream: false when HIPAA-specific response heuristics are necessary. The SSE redaction buffer does not prove that each HIPAA-specific match was changed.

Correct 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

Block PHI-like input before the model receives it​

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

policies:
  chain:
    - hipaa-phi-detector

policy:
  hipaa-phi-detector:
    action: block

Best practices​

  • Use action: redact when the gateway must remove content and not reject the turn.
  • Pair hipaa-phi-detector with healthcare-compliance when PHI protection and medical-content controls are necessary.
  • Use rbac for minimum-necessary access rules. The HIPAA detector finds PHI-like text, but it does not authorize access.
  • Test typical PHI strings and examine emitted events before rollout.

Next steps​