PII Detection and Redaction

The PII guardrail detects sensitive data in request and response text and either masks it (replaces each match with a [<DETECTOR>_REDACTED] token and continues) or blocks the request or response. It runs entirely inside the gateway — no external service is called — and the matched values never appear in 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 mask and block 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

Actions

Each match resolves to one of two actions:

• mask — replace the matched span with [<DETECTOR>_REDACTED] (for example [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 applies to every listed detector unless a detector sets its own action.

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:

email me at [EMAIL_REDACTED] about the order

The redacted value never reaches the upstream provider, the gateway log, or the usage record. Usage records carry only per-detector match counts (detector names, never the matched text).

Block Sensitive Data

Use block when a detector should reject traffic instead of masking it. The example below blocks any request that carries 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 — it never echoes the matched value.

Add a Custom Pattern

Add custom_patterns to detect data specific to your organization. Each pattern needs a name (used in the mask token and match counts) and a regex. AISIX 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

On the output hook, AISIX buffers a streamed response, applies redaction once it is complete, and then emits the masked result. Buffering is required because a masked span can straddle two stream chunks. If a streamed response exceeds the scan buffer (max_buffer_bytes, default 262144), on_buffer_exceeded decides what happens:

• 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 for hook points and enforcement modes. You can also combine PII redaction with an external guardrail service, such as AWS Bedrock Guardrails, Azure AI Content Safety Guardrails, or Alibaba Cloud AI Guardrails.