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.
One of these configuration paths:
- AISIX Cloud with an environment, an attached gateway, and a write-scoped admin token. For On-Premises, follow the AISIX Cloud Quickstart. To request Hybrid Cloud access, contact API7.
- An open-source AISIX gateway that loads a declarative resources.yaml file.
A working model alias and caller API key that can send Chat Completions requests.
curl. The AISIX Cloud path also uses jq.

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 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]. Input masking continues to the upstream model; output masking continues to the caller.
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. Choose one configuration path, then use the shared verification procedure.

Export the gateway values used by both paths:

# AISIX_PROXY has no trailing slash or endpoint path.
# The local quickstarts use http://127.0.0.1:3000.
export AISIX_PROXY="YOUR_AISIX_GATEWAY_URL"
export AISIX_API_KEY="YOUR_CALLER_API_KEY"
export AISIX_MODEL="gpt-4o-mini"

AISIX Cloud

Export the control-plane connection details:

# AISIX_CP includes /api and has no trailing slash.
# The local On-Premises quickstart uses http://localhost:8080/api.
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_BASE_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Create an input guardrail that masks the email and api_key detectors, and capture its ID:

GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pii-redaction-policy",
    "enabled": false,
    "hook_point": "input",
    "kind": "pii",
    "config": {
      "default_action": "mask",
      "detectors": [
        { "type": "email" },
        { "type": "api_key" }
      ]
    }
  }' | jq -r '.guardrail.id')

❶ Creating the guardrail disabled prevents it from applying globally before its attachment exists. Enable it after attaching it below.

❷ 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.

Attach the guardrail to the whole environment (scope_type: "env" binds every request in the environment and omits scope_id; use model, api_key, or team with a scope_id to narrow it):

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scope_type": "env" }'

Enable the guardrail after its attachment exists:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

The enabled configuration projects to attached gateways automatically.

Open-Source AISIX Gateway

Add the guardrail to the resources file that already defines the example model and caller API key:

resources.yaml
guardrails:
  - name: pii-redaction-policy
    enabled: true
    hook_point: input
    kind: pii
    default_action: mask
    detectors:
      - type: email
      - type: api_key

❶ mask replaces every detected span with a redaction token and lets the request continue.

❷ Each detector runs inside the gateway. An individual detector can set action: block when it should override the default.

Every enabled guardrail in resources.yaml applies to every request handled by that gateway. Validate the complete file, then reload the gateway. See Reload a Resources File for the runnable Docker workflow.

For response-side PII redaction on streamed traffic, AISIX holds response content until it can apply the guardrail. See Streaming Output for buffer defaults and overflow behavior.

Verify Masking

Send a request whose prompt contains an email address. AISIX Cloud projection is asynchronous; if the first request does not reflect the new rule, wait for the gateway to apply the latest revision and retry. See Resource Projection for convergence checks.

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

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 following examples add a second guardrail that blocks requests containing a valid mainland China resident ID.

AISIX Cloud

Create the blocking guardrail and attach it to the environment:

BLOCK_GUARDRAIL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "block-id-card",
    "enabled": false,
    "hook_point": "input",
    "kind": "pii",
    "config": {
      "default_action": "block",
      "detectors": [
        { "type": "china_id_card" }
      ]
    }
  }' | jq -r '.guardrail.id')

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/guardrails/$BLOCK_GUARDRAIL_ID/attachments" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scope_type": "env" }'

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$BLOCK_GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Open-Source AISIX Gateway

Add the blocking guardrail alongside the masking guardrail in resources.yaml:

resources.yaml
guardrails:
  - name: pii-redaction-policy
    enabled: true
    hook_point: input
    kind: pii
    default_action: mask
    detectors:
      - type: email
      - type: api_key

  - name: block-id-card
    enabled: true
    hook_point: input
    kind: pii
    default_action: block
    detectors:
      - type: china_id_card

Validate the complete file and reload the gateway.

Verify Blocking

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

curl -sSi -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "model": "${AISIX_MODEL}",
    "messages": [
      {
        "role": "user",
        "content": "my id is 11010519491231002X"
      }
    ]
  }
EOF

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 Rust-compatible regex. AISIX uses the name in the redaction token and match counts. An invalid expression prevents the guardrail from entering the active chain.

The following examples add an employee ID pattern to pii-redaction-policy while preserving its existing email and API-key detectors.

AISIX Cloud

Replace the existing guardrail's configuration with the expanded detector set:

curl -sS -X PATCH "$AISIX_CP/environments/$ENV_ID/guardrails/$GUARDRAIL_ID" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "default_action": "mask",
      "detectors": [
        { "type": "email" },
        { "type": "api_key" }
      ],
      "custom_patterns": [
        {
          "name": "employee_id",
          "regex": "EMP-[0-9]{6}"
        }
      ]
    }
  }'

The existing attachment remains in place when the guardrail configuration changes.

Open-Source AISIX Gateway

Add the same pattern to the existing guardrail entry:

resources.yaml
guardrails:
  - name: pii-redaction-policy
    enabled: true
    hook_point: input
    kind: pii
    default_action: mask
    detectors:
      - type: email
      - type: api_key
    custom_patterns:
      - name: employee_id
        regex: 'EMP-[0-9]{6}'

Validate the complete file and reload the gateway. A match on this pattern is masked as [EMPLOYEE_ID_REDACTED] through either configuration path.

Next Steps

You have configured the built-in PII guardrail and verified mask and block behavior. Use these guides to refine or expand the policy:

Guardrail Behavior: adjust hook points, enforcement mode, or streaming output.
Microsoft Presidio Guardrails: use self-hosted NER entities and anonymization operators.
Choosing a Guardrail Provider: compare built-in PII detection with remote guardrail services.

Prerequisites​

Built-in Detectors​

Match Actions​

Create a PII Guardrail​

AISIX Cloud​

Open-Source AISIX Gateway​

Verify Masking​

Block Sensitive Data​

AISIX Cloud​

Open-Source AISIX Gateway​

Verify Blocking​

Add a Custom Pattern​

AISIX Cloud​

Open-Source AISIX Gateway​

Next Steps​

Prerequisites

Built-in Detectors

Match Actions

Create a PII Guardrail

AISIX Cloud

Open-Source AISIX Gateway

Verify Masking

Block Sensitive Data

AISIX Cloud

Open-Source AISIX Gateway

Verify Blocking

Add a Custom Pattern

AISIX Cloud

Open-Source AISIX Gateway

Next Steps