Summary

The data-mask plugin masks or redacts sensitive fields in HTTP request data — query parameters, headers, and body — before they appear in access logs or logger plugin outputs (e.g. file-logger, http-logger, kafka-logger).

Problem

API gateways sit in front of every service and naturally observe all request data, including credentials, tokens, PII, and payment card numbers. When access logging is enabled, this sensitive data is routinely written to log files or shipped to log aggregation systems, creating compliance risk under GDPR, PCI-DSS, HIPAA, and similar regulations.

Currently, APISIX has no built-in mechanism to sanitize sensitive fields before logging. Operators must either:

• Disable logging of request data entirely, losing visibility
• Post-process logs after the fact, which is operationally complex and leaves a window of exposure
• Implement masking in each upstream service, which is inconsistent

Scenarios

Scenario 1 — Credential sanitization in query parameters

A legacy API accepts credentials as query parameters (e.g. /api?password=secret&token=abc). With access logging enabled, these values appear in the request URI logged by every logger plugin. data-mask can remove the password field and replace the token with ***** before any logger sees the request.

Scenario 2 — Authorization header redaction

A service passes Authorization: Bearer <token> on every request. Log pipelines shipped to third-party SIEM systems must not contain bearer tokens. data-mask removes or redacts the header in the log phase; upstream communication is unaffected.

Scenario 3 — Partial masking of payment card numbers

An e-commerce API receives card numbers in JSON bodies or query strings. PCI-DSS requires only the first 6 and last 4 digits to be visible. data-mask's regex action can transform 1234-5678-9012-3456 → 1234-****-****-3456 using a single rule.

Scenario 4 — Nested JSON body field masking via JSONPath

A batch API receives a JSON body with user records, each containing a token and nested credit.card. JSONPath expressions ($.users[*].token, $.users[*].credit.card) let a single rule mask all matching nested fields without enumerating each one.

Design

The plugin runs in the log phase and modifies the request context (ctx.var) used by logger plugins. Upstream communication is unaffected — the plugin never alters the actual request sent to the upstream.

Three masking actions are supported:

• remove — deletes the field entirely from the logged data
• replace — substitutes the field value with a fixed string
• regex — applies an ngx.re.sub regex substitution; capture groups are available as $1, $2, etc.

Three field types are supported:

• query — URL query parameters
• header — HTTP request headers
• body — request body (json format supports JSONPath; urlencoded for form data)

Example

Mask sensitive query parameters and log with file-logger:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
  "uri": "/anything",
  "plugins": {
    "data-mask": {
      "request": [
        { "type": "query", "name": "password", "action": "remove" },
        { "type": "query", "name": "token",    "action": "replace", "value": "*****" },
        { "type": "query", "name": "card",     "action": "regex",
          "regex": "(\\d+)\\-\\d+\\-\\d+\\-(\\d+)", "value": "$1-****-****-$2" }
      ]
    },
    "file-logger": { "path": "logs/access.log" }
  },
  "upstream": { "type": "roundrobin", "nodes": { "httpbin.org:80": 1 } }
}'

Send a request:

curl "http://127.0.0.1:9080/anything?password=secret&token=abc123&card=1234-5678-9012-3456"

The logged URI in logs/access.log will be:

/anything?token=*****&card=1234-****-****-3456

The password field is absent; token is replaced; card digits are partially masked.

Changes

• apisix/plugins/data-mask.lua: Plugin implementation
• conf/config.yaml.example: Register plugin at priority 1500
• apisix/cli/config.lua: Add to default plugin list
• docs/en/latest/plugins/data-mask.md: English documentation with full examples
• docs/zh/latest/plugins/data-mask.md: Chinese documentation

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible