PII Detection and Redaction

The PII guardrail detects sensitive data in request and response text. It can mask each match with a redaction token and let traffic continue, or block the request or response.

PII detection runs inside the gateway, so no external moderation service is called. Matched values are not written to gateway logs, usage records, or error responses.

In this guide, you will create a PII guardrail that masks built-in detector matches, add a custom pattern, and verify both masking and blocking behavior.

Prerequisites

Before starting, prepare the following:

• Review Guardrail Behavior for hook points and enforcement modes.
• A self-hosted AISIX gateway with the admin and proxy listeners available.
• The admin key from the gateway config.yaml.
• A working model alias and caller API key that can send chat-completions requests.

Built-in Detectors

Enable any of the built-in detectors by listing its type under detectors. Two detectors validate a checksum before matching so that a random digit run is not masked.

type	Matches
email	Email addresses
china_mobile	Mainland China mobile numbers
china_id_card	Mainland China resident ID numbers (ISO 7064 checksum)
bank_card	Bank card numbers (Luhn checksum)
us_ssn	US Social Security Numbers
ip_address	IPv4 / IPv6 addresses
api_key	API keys and tokens (OpenAI, AWS, GitHub, Slack, Google signatures)
jwt	JSON Web Tokens
private_key	PEM private key blocks

Match Actions

Each match resolves to one of two actions:

• mask: replace the matched span with a token such as [EMAIL_REDACTED] and continue to the upstream model.
• block: reject the request or response with 422 Unprocessable Entity.

default_action sets the action for every detector and custom pattern. Set action on an individual detector or custom pattern to override it.

Create a PII Guardrail

The example below masks email addresses and API keys in caller requests before AISIX sends them to the upstream provider.

Set the values used by the example requests:

export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

Create an input guardrail that masks the email and api_key detectors:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-redaction-policy",
    "enabled": true,
    "hook_point": "input",
    "kind": "pii",
    "default_action": "mask",
    "detectors": [
      { "type": "email" },
      { "type": "api_key" }
    ]
  }'

❶ input masks the caller request before AISIX sends it upstream. Use output to redact provider responses, or both to cover both sides. See Guardrail Hook Point.

❷ default_action sets the action for listed detectors. mask replaces each match with a redaction token. Set a detector-level action only when one detector needs to behave differently.

Save the returned id if you want to inspect, update, or delete the guardrail later.

Verify Masking

Send a request whose prompt contains an email address:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "email me at alice@example.com about the order"
      }
    ]
  }'

The request succeeds with HTTP/1.1 200 OK. AISIX rewrites the prompt before calling the upstream model, so the provider receives the masked prompt:

email me at [EMAIL_REDACTED] about the order

The original value does not reach the upstream provider, the gateway log, or the usage record. Usage records carry per-detector match counts, including detector names but not matched text.

Block Sensitive Data

Use block when a detector should reject traffic instead of masking it. The example below blocks requests that contain a mainland China resident ID:

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "block-id-card",
    "enabled": true,
    "hook_point": "input",
    "kind": "pii",
    "default_action": "block",
    "detectors": [
      { "type": "china_id_card" }
    ]
  }'

A request whose content includes a valid ID number is rejected:

curl -sSi -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${AISIX_MODEL}"'",
    "messages": [
      {
        "role": "user",
        "content": "my id is 11010519491231002X"
      }
    ]
  }'

A blocked response starts with HTTP/1.1 422 Unprocessable Entity and includes this body:

{
  "error": {
    "message": "request blocked by content policy (guardrail 'block-id-card')",
    "type": "content_filter"
  }
}

The message is deliberately generic and does not echo the matched value.

Add a Custom Pattern

Add custom_patterns to detect data specific to your organization. Each pattern needs a name and a regex. AISIX uses the name in the redaction token and match counts, and rejects an invalid regex before applying the rule.

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/guardrails" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-custom",
    "enabled": true,
    "hook_point": "both",
    "kind": "pii",
    "default_action": "mask",
    "detectors": [
      { "type": "email" }
    ],
    "custom_patterns": [
      {
        "name": "employee_id",
        "regex": "EMP-[0-9]{6}"
      }
    ]
  }'

A match on this pattern is masked as [EMPLOYEE_ID_REDACTED].

Streaming Responses

For output checks on streamed responses, AISIX buffers the response, applies redaction when the response is complete, and then emits the masked result. Buffering is required because a matched span can cross stream chunks.

If a streamed response exceeds the scan buffer, on_buffer_exceeded controls whether AISIX releases or drops the response. The default max_buffer_bytes is 262144.

• fail_closed (default): drop the response rather than release unmasked content.
• fail_open: release the unscanned content.

{
  "kind": "pii",
  "hook_point": "output",
  "default_action": "mask",
  "detectors": [
    { "type": "email" }
  ],
  "max_buffer_bytes": 262144,
  "on_buffer_exceeded": "fail_closed"
}

Next Steps

You have configured the built-in PII guardrail and verified mask and block behavior. Review Guardrail Behavior when you need to adjust hook points or enforcement modes. To combine local PII detection with an external guardrail service, add AWS Bedrock Guardrails, Azure AI Content Safety Guardrails, or Alibaba Cloud AI Guardrails.