diff --git a/app/_ai_gateway_entities/ai-mcp-server.md b/app/_ai_gateway_entities/ai-mcp-server.md index 136e2c571b2..3e107afd637 100644 --- a/app/_ai_gateway_entities/ai-mcp-server.md +++ b/app/_ai_gateway_entities/ai-mcp-server.md @@ -37,6 +37,8 @@ related_resources: url: /mcp/ - text: MCP version support url: /ai-gateway/mcp-version-support/ + - text: AI MCP Sanitizer Policy + url: /ai-gateway/policies/ai-mcp-sanitizer/ - text: Model Context Protocol specification url: https://modelcontextprotocol.io/ - text: Map a RESTful API to MCP tools @@ -201,6 +203,8 @@ rows: example: "Use [Rate Limiting](/ai-gateway/policies/rate-limiting/) or [Rate Limiting Advanced](/ai-gateway/policies/rate-limiting-advanced/) Policy to control MCP request volume per AI Consumer or AI Consumer Group." - use_case: "Track all MCP traffic and ACL decisions." example: "Enable request and response logging through [AI logging Policies](/ai-gateway/policies/?category=logging) and audit trails." + - use_case: "Protect sensitive data in tool calls" + example: "Use the [AI MCP Sanitizer](/ai-gateway/policies/ai-mcp-sanitizer/) Policy (tech preview) to redact PII in `tools/call` arguments and results. Targeting results [changes how some server types stream](/ai-gateway/policies/ai-mcp-sanitizer/#streaming-and-performance-trade-offs)." - use_case: "Traffic control" example: "Apply [Request Transformer](/ai-gateway/policies/request-transformer/) or [Response Transformer](/ai-gateway/policies/response-transformer/) Policy to modify MCP payloads, or use [ACLs](#acl-tool-control) for fine-grained tool access." {% endtable %} @@ -762,7 +766,7 @@ features: description: Handling WebSocket and gRPC upstreams supported: false - title: "AI Guardrails" - description: Applying guardrails to MCP AI requests and responses + description: Applying content safety guardrails to MCP AI requests and responses. For PII protection, see the [AI MCP Sanitize Policy](/ai-gateway/policies/ai-mcp-sanitizer/). supported: false {% endfeature_table %} diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md new file mode 100644 index 00000000000..f0c50add837 --- /dev/null +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -0,0 +1,257 @@ +--- +title: 'AI MCP Sanitizer' +name: 'AI MCP Sanitizer' +publisher: kong-inc +icon: ai-mcp-sanitizer.png +description: 'Detect and redact personally identifiable information (PII) in MCP tool call arguments and results.' +min_version: + ai-gateway: '2.3' +works_on: + - konnect +products: + - ai-gateway +content_type: plugin +tech_preview: true +categories: + - ai +tags: + - ai + - mcp + - dlp + - security +related_resources: + - text: AI PII Sanitizer Policy + url: /ai-gateway/policies/ai-sanitizer/ + - text: AI MCP Server + url: /ai-gateway/entities/ai-mcp-server/ + - text: AI Policy + url: /ai-gateway/entities/ai-policy/ + - text: MCP version support + url: /ai-gateway/mcp-version-support/ + - text: Model Context Protocol specification + url: https://modelcontextprotocol.io/ +--- + +The AI MCP Sanitizer Policy detects and redacts personally identifiable information (PII) in [Model Context Protocol (MCP)](/ai-gateway/mcp/) `tools/call` traffic on {{site.ai_gateway}}. +It can sanitize the arguments an agent sends to a tool, the result a tool returns, or both. + +MCP tools often front systems of record such as CRMs, ticketing tools, and medical or financial databases, where arguments and results routinely contain PII. +The [AI PII Sanitizer Policy](/ai-gateway/policies/ai-sanitizer/) processes only chat-completion bodies. MCP traffic uses JSON-RPC params and result structures, so the Policy can't protect it." +The AI MCP Sanitizer Policy adds PII sanitization to MCP traffic proxied by an [AI MCP Server](/ai-gateway/entities/ai-mcp-server/). + +The Policy uses the same [PII service](#ai-pii-anonymizer-service), PII categories, custom patterns, blocking, and recovery options as the AI PII Sanitizer Policy. +If you already use that Policy, the connection and detection settings work the same way. + +## Use cases + +Use the AI MCP Sanitizer Policy in the following situations: + +{% table %} +columns: + - title: Problem to solve + key: situation + - title: Typical scenario + key: example + - title: What to configure + key: config +rows: + - situation: Customer data goes into a third-party tool. + example: "An agent puts a customer's Social Security number into the arguments of a CRM or ticketing tool call." + config: "Target `tool_arguments` so the tool server receives redacted values." + - situation: A system of record returns sensitive records. + example: "A tool returns a medical or financial record, and you don't want that record in the LLM context." + config: "Target `tool_results` so the agent receives a sanitized result." + - situation: A call must not proceed if it contains PII. + example: "A tool must never receive or return PII, and a redacted call isn't acceptable." + config: "Set [`block_if_detected`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-block-if-detected) to `true` to [reject the call](#block-instead-of-redact) instead of redacting it." + - situation: Your data includes identifiers that the built-in categories don't cover. + example: "Your systems use employee IDs in the format `EMP-123456`." + config: "Add [`custom_patterns`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-custom-patterns) with a regular expression for the identifier, and include `custom` in [`anonymize`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-anonymize)." + - situation: A tool must work with placeholders, but the agent needs the real values back. + example: "The tool returns a placeholder it received in the arguments, and the agent needs the original value to continue." + config: "Set [`recover_redacted`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-recover-redacted) to `true` to [restore the original values](#recover-redacted-values) in the tool result." +{% endtable %} + +## What gets sanitized + +The Policy sanitizes the `tools/call` method only. +It doesn't sanitize other MCP methods, such as `resources/read` or `prompts/get`. + +You choose what to sanitize with [`sanitize_targets`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-sanitize-targets). +Each target names a location in the MCP protocol instead of an abstract direction: + +{% table %} +columns: + - title: Target + key: target + - title: Direction + key: direction +rows: + - target: "`tool_arguments`" + direction: "The `tools/call` request, from {{site.ai_gateway}} to the tool server" + - target: "`tool_results`" + direction: "The `tools/call` response, from the tool server through {{site.ai_gateway}} to the calling agent" +{% endtable %} + +You can enable either target, or both. +The default is `tool_arguments`. + +{{site.ai_gateway}} sanitizes only the fields that contain user data: + +* **Sanitized:** string values in the tool call arguments, `text` entries in `result.content[]`, and string values in `result.structuredContent`. +* **Not sanitized:** the tool name, JSON-RPC envelope fields such as `jsonrpc` and `id`, `result.isError`, `result._meta`, and `result.content[]` entries of type `image`, `audio`, or `resource`. + +Rewriting tool names and protocol fields would break tool dispatch, access control, and protocol negotiation. +Skipping binary content avoids sending large payloads to the PII service for no benefit. + +## Choose what to sanitize + +Choose targets based on which direction of the tool call includes PII and whether you need streaming: + +* **Sanitize only `tool_arguments`** if your agents send user data to a third-party tool and you need to keep streaming. + This target doesn't hold responses or change how [`conversion-listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type) servers run, so the [streaming and single-pass changes](#streaming-and-performance-trade-offs) don't apply. + Set `recover_redacted` to `false` as well, because enabling it also holds the result. +* **Sanitize only `tool_results`** if your tools return records from a system of record, such as a CRM or a medical database, and you want to keep that data out of the LLM context. + {{site.ai_gateway}} forwards the arguments to the tool server unchanged. + Set `recover_redacted` to `false`, because you can't use recovery when `tool_results` is a target. +* **Sanitize both** if user data goes to the tool and the tool returns PII too. + The streaming and single-pass changes apply because `tool_results` is targeted. + +## How it works + +The AI MCP Sanitizer Policy sanitizes a `tools/call` request and its result in the following order: + +1. A client sends a `tools/call` request to the AI MCP Server. +1. {{site.ai_gateway}} authorizes the request and applies rate limiting. + {{site.ai_gateway}} rejects a request that fails either check before it calls the PII service. +1. If `tool_arguments` is targeted, the Policy sends the argument text to the PII service and replaces each value with its sanitized version. +1. {{site.ai_gateway}} forwards the sanitized request to the tool server. +1. If `tool_results` is targeted, {{site.ai_gateway}} holds the complete result from the tool server. + The Policy sends the result text to the PII service. + {{site.ai_gateway}} then returns the sanitized result to the agent. + +{% mermaid %} +sequenceDiagram + autonumber + participant Agent as MCP client + participant Kong as AI MCP Server + participant PII as PII service + participant Tool as MCP tool server + + Agent->>Kong: tools/call request + Kong->>Kong: Authorize and rate limit + Kong->>PII: Send argument text (tool_arguments) + PII->>Kong: Return sanitized text + Kong->>Tool: Forward sanitized request + Tool->>Kong: Return result + Kong->>PII: Send result text (tool_results) + PII->>Kong: Return sanitized text + Kong->>Agent: Return sanitized result +{% endmermaid %} + +{:.info} +> {{site.ai_gateway}} never sanitizes the authentication tools that it handles itself, because their arguments are credentials and not user PII. + +### Supported server types + +The Policy works with the [`passthrough-listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type), [`listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type), and [`conversion-listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type) AI MCP Server types. +It handles both JSON and SSE-framed responses, and re-frames sanitized SSE responses automatically. + +## Streaming and performance trade-offs + +Sanitizing a tool result requires the complete result before {{site.ai_gateway}} sends any of it to the agent. +The PII service scores text as a whole, and a placeholder can't replace bytes that {{site.ai_gateway}} has already sent. +For that reason, targeting `tool_results` changes how some server types proxy traffic: + +{% table %} +columns: + - title: Server type + key: type + - title: What changes + key: change + - title: Effect + key: effect +rows: + - type: "[`passthrough-listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type)" + change: "{{site.ai_gateway}} buffers a streamed `tools/call` response and sends it as one body." + effect: "For an upstream that streams a response incrementally, time to first byte becomes time to last byte. An SSE response that contains one complete message isn't affected." + - type: "[`conversion-listener`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-type)" + change: "{{site.ai_gateway}} disables single-pass conversion for converter tools that the AI MCP Server owns, and sends the call to the upstream as a separate request." + effect: "Each call opens one additional outbound connection. That connection doesn't use the load balancer, retries, upstream TLS or mTLS settings, the keepalive pool, or the configured timeouts." +{% endtable %} + +Enabling `recover_redacted` also requires {{site.ai_gateway}} to hold the result, so the same changes apply. + +Removing `tool_results` from `sanitize_targets` and disabling `recover_redacted` restores the previous behavior. +A configuration that targets only `tool_arguments` without recovery doesn't change streaming or single-pass behavior. +{{site.ai_gateway}} never buffers long-lived streams, such as `subscriptions/listen` and GET-initiated SSE. + +{:.warning} +> Each sanitized call adds at least one round trip to the PII service. +> Load test the PII service with your largest and most deeply nested tool payloads before you enable the Policy in production. + +## Block instead of redact + +When `block_if_detected` is `true` and the PII service finds sensitive data, {{site.ai_gateway}} rejects the call instead of redacting it: + +* For `tool_arguments`, the agent receives a JSON-RPC error and {{site.ai_gateway}} doesn't send the request to the tool server. +* For `tool_results`, {{site.ai_gateway}} replaces the result with a JSON-RPC error. + +The error uses the format and HTTP status that match the client's [MCP protocol revision](/ai-gateway/mcp-version-support/). + +## Recover redacted values + +When [`recover_redacted`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-recover-redacted) is `true`, the tool server receives placeholders instead of the original values. +If the tool returns a placeholder in its result, {{site.ai_gateway}} restores the original value before it sends the result to the agent. +The `recover_redacted` setting is `true` by default. + +## Error handling + +The AI MCP Sanitizer Policy uses [`stop_on_error`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-stop-on-error) to decide what happens when the PII service is unreachable, returns a non-200 response, or returns a malformed response. +When `stop_on_error` is `true`, {{site.ai_gateway}} fails the call. When it's `false`, the call continues without sanitization. + +## Differences from the AI PII Sanitizer Policy + +The AI MCP Sanitizer Policy shares most settings with the AI PII Sanitizer Policy. +The following table lists the settings that differ: + +{% table %} +columns: + - title: Setting + key: setting + - title: AI PII Sanitizer + key: sanitizer + - title: AI MCP Sanitizer + key: mcp +rows: + - setting: Targeting + sanitizer: "`sanitization_mode`: `INPUT`, `OUTPUT`, or `BOTH`" + mcp: "[`sanitize_targets`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-sanitize-targets): `tool_arguments`, `tool_results`, or both" + - setting: "`allow_all_conversation_history`" + sanitizer: Supported + mcp: Not available. Conversation history is an LLM concept. +{% endtable %} + +{:.info} +> `INPUT`, `OUTPUT`, and `BOTH` are ambiguous on MCP traffic, because an AI MCP Server is both a server to the agent and a client of the tool server.`sanitize_targets` names the protocol location instead. + +## AI PII Anonymizer service + +{% include /md/ai-gateway/v2/policies/pii-service.md policy_name="AI MCP Sanitizer" %} + +## Logging and analytics + +The AI MCP Sanitizer Policy adds sanitization details to the MCP logs. + +{% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} + + +## Configuration notes + +* [`anonymize`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-anonymize) must contain at least one value. + The default is `all_and_credentials`. +* If `anonymize` includes `custom`, you must set [`custom_patterns`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-custom-patterns). + Each pattern needs a `name` and a `regex`. + The optional `score` is a number between 0 and 1 and defaults to 0.5. +* [`sanitize_targets`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-sanitize-targets) must contain at least one target. + The default is `tool_arguments`. diff --git a/app/_ai_gateway_policies/ai-sanitizer/index.md b/app/_ai_gateway_policies/ai-sanitizer/index.md index dea358a5a3e..2ea344e674a 100644 --- a/app/_ai_gateway_policies/ai-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-sanitizer/index.md @@ -77,139 +77,7 @@ sequenceDiagram ## AI PII Anonymizer service -Kong publishes the AI PII Anonymizer service as public Docker images. Each image includes a built-in NLP model and is tagged using the `version-lang_code` format. For example: - -* `ai-pii-service:v0.2.2-en`: English model, version 0.2.2 -* `ai-pii-service:v0.2.2-it`: Italian model, version 0.2.2 -* `ai-pii-service:v0.2.2-fr`: French model, version 0.2.2 - -{:.info} -> All models are bundled into a single image per version, tagged using the format `v`. For example: `v0.2.2` -> If you need to add or modify models, edit the configuration file at `ai_pii_service/nlp_engine_conf.yml`. - -### Sanitization endpoints - -* `POST /llm/v1/sanitize`: Sanitize specified types of PII information, including credentials, and custom patterns -* `POST /llm/v1/sanitize_credentials`: Only for sanitizing credentials - -See the [AI PII Sanitizer OpenAPI specification](/ai-gateway/policies/ai-sanitizer/api/) for complete details. - -### Available anonymization modes - -You can anonymize data in requests using the following redact modes: - -* `placeholder`: Replaces sensitive data with a fixed placeholder pattern, `PLACEHOLDER{i}`, where `i` is a sequence number. Identical original values receive the same placeholder. - - For example, the location `New York City` might be replaced with `LOCATION`. - -* `synthetic`: Redact the sensitive data with a word in the same type. - - For example, the name `John` might be replaced with `Amir`. - - * Custom patterns are replaced with `CUSTOM{i}`. - * Credentials are replaced with a string of `#` characters matching the original length. - -### Custom patterns - -You can define an array of custom patterns on a per-request basis. -Currently, only regex patterns are supported, and all fields are required: `name`, `regex`, and `score`. - -The `name` must be unique for each pattern. - -### Fields that can be anonymized - -You can use the following fields in the `anonymize` array: - -* `general`: Anonymizes general PII entities such as person names, locations, and organizations. -* `phone`: Anonymizes phone numbers (for example, `mobile`, `landline`). -* `email`: Anonymizes email addresses. -* `creditcard`: Anonymizes credit card numbers. -* `crypto`: Anonymizes cryptocurrency addresses. -* `date`: Anonymizes dates and timestamps. -* `ip`: Anonymizes IP addresses (both IPv4 and IPv6). -* `nrp`: Anonymizes a person’s nationality, religious, or political group. -* `ssn`: Anonymizes Social Security Numbers (SSN) and other related identifiers like ITIN, NIF, ABN, and more. -* `domain`: Anonymizes domain names. It was deprecated, use `url` instead. -* `url`: Anonymizes web URLs. -* `medical`: Anonymizes medical identifiers (for example, medical license numbers, NHS numbers, medicare numbers). -* `driverlicense`: Anonymizes driver's license numbers. -* `passport`: Anonymizes passport numbers. -* `bank`: Anonymizes bank account numbers and related banking identifiers (for example, VAT codes, IBAN). -* `nationalid`: Anonymizes various national identification numbers (for example, Aadhaar, PESEL, NRIC, social security, or voter IDs). -* `custom`: Anonymizes user-defined custom PII patterns using regular expressions only when custom patterns are provided. -* `credentials`: Anonymizes the credentials, similar to `/sanitize_credentials`. -* `all`: Includes all the fields above, including custom ones. - -### Access the Docker images - -Kong distributes these images publicly on Docker Hub, under the `kong/ai-pii-service` repository. No authentication is required to pull them. - -#### Pull the AI PII service image - -To pull an image: - -```bash -docker pull kong/ai-pii-service:TAG -``` - -Replace `TAG` with the appropriate version and language code, such as: - -```bash -docker pull kong/ai-pii-service:v0.2.2-en -``` - -#### Run the AI PII service as a standalone container - -To run the image directly, without a `Dockerfile`: - -```bash -docker run -d kong/ai-pii-service:v0.2.2-en -``` - -#### AI PII service Dockerfile usage - -Alternatively, to use an image in a `Dockerfile`, reference it as follows: - -```dockerfile -FROM kong/ai-pii-service:v0.2.2-en -``` - -### Available language tags - -The following language-specific images are currently available: - -* `-en` (English) -* `-es` (Spanish) -* `-fr` (French) -* `-de` (German) -* `-it` (Italian) -* `-ja` (Japanese) -* `-ko` (Korean) -* `-nl` (Dutch) -* `-pt` (Portuguese) -* `-th` (Thai) -* `-tr` (Turkish) - -{% include /md/ai-gateway/v2/policies/spacy-pii-note.md %} - -### Image configuration options - -This service takes the following optional environment variables at startup: -* `GUNICORN_WORKERS`: Specifies the number of Gunicorn processes to run -* `PII_SERVICE_ENGINE_CONF`: Specifies the natural language processing (NLP) engine configuration file -* `GUNICORN_LOG_LEVEL`: Specifies log level -* `GUNICORN_CERTFILE` and `GUNICORN_KEYFILE`: Specifies TLS certificates for HTTPS access. - -### Serve AI PII service securely - -To serve the AI PII service over https requires additional configuration: - -1. Ensure you have trusted TLS certificates for your environment. -2. Set the `GUNICORN_CERTFILE` and `GUNICORN_KEYFILE` environment variables when starting the AI PII service. The service will switch to serving HTTPS on port `8443`. -3. Set `scheme: https` and `port: 8443` when configuring the AI PII Sanitizer Policy. The policy will connect with HTTPS. - -{:.info} -> This policy does not verify SSL/TLS connections directly, it follows the global [`tls_certificate_verify`](/ai-gateway/configuration/#tls-certificate-verify) setting. Certificates can be managed with the [AI CA Certificates](/ai-gateway/entities/ai-ca-certificate/) and [AI Certificates](/ai-gateway/entities/ai-certificate/) entities. +{% include /md/ai-gateway/v2/policies/pii-service.md policy_name="AI PII Sanitizer" show_endpoints=true %} ## Forward proxy support diff --git a/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md b/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md new file mode 100644 index 00000000000..39d507ce4e7 --- /dev/null +++ b/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md @@ -0,0 +1,24 @@ +When you enable `log_statistics` in the AI MCP Server's [`config.logging`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-config-logging), each logged RPC that the Policy processed includes a `sanitizer` object in the [`ai.mcp` log entry](/ai-gateway/ai-audit-log-reference/#ai-mcp-logs). +{{site.ai_gateway}} adds the object to the same log entry as the rest of the request, so one request produces one entry. + +The `sanitizer` object has the following properties: + +{% table %} +columns: + - title: Property + key: property + - title: Description + key: description +rows: + - property: "`ai.mcp.rpc[].sanitizer.identified`" + description: The number of PII items the PII service identified. + - property: "`ai.mcp.rpc[].sanitizer.sanitized`" + description: The number of PII items the Policy sanitized. + - property: "`ai.mcp.rpc[].sanitizer.duration`" + description: The duration of sanitization. + - property: "`ai.mcp.rpc[].sanitizer.sanitized_items`" + description: A list of the sanitized PII items. Each item includes `original_text`, `redact_text`, `entity_type`, and `count`. +{% endtable %} + +The `sanitized_items` entries include the original text, so the log contains the sensitive data. +Set [`skip_logging_sanitized_items`](/ai-gateway/policies/ai-mcp-sanitizer/reference/#schema--config-skip-logging-sanitized-items) to `true` to omit `sanitized_items` and keep that data out of your logs. diff --git a/app/_includes/md/ai-gateway/v2/policies/pii-service.md b/app/_includes/md/ai-gateway/v2/policies/pii-service.md new file mode 100644 index 00000000000..6a962308b63 --- /dev/null +++ b/app/_includes/md/ai-gateway/v2/policies/pii-service.md @@ -0,0 +1,135 @@ +Kong publishes the AI PII Anonymizer service as public Docker images. Each image includes a built-in NLP model and is tagged using the `version-lang_code` format. For example: + +* `ai-pii-service:v0.2.2-en`: English model, version 0.2.2 +* `ai-pii-service:v0.2.2-it`: Italian model, version 0.2.2 +* `ai-pii-service:v0.2.2-fr`: French model, version 0.2.2 + +{:.info} +> All models are bundled into a single image per version, tagged using the format `v`. For example: `v0.2.2` +> If you need to add or modify models, edit the configuration file at `ai_pii_service/nlp_engine_conf.yml`. + +{% if include.show_endpoints %} +### Sanitization endpoints + +* `POST /llm/v1/sanitize`: Sanitize specified types of PII information, including credentials, and custom patterns +* `POST /llm/v1/sanitize_credentials`: Only for sanitizing credentials + +See the [AI PII Sanitizer OpenAPI specification](/ai-gateway/policies/ai-sanitizer/api/) for complete details. +{% endif %} + +### Available anonymization modes + +You can anonymize data in requests using the following redact modes: + +* `placeholder`: Replaces sensitive data with a fixed placeholder pattern, `PLACEHOLDER{i}`, where `i` is a sequence number. Identical original values receive the same placeholder. + + For example, the location `New York City` might be replaced with `LOCATION`. + +* `synthetic`: Redact the sensitive data with a word in the same type. + + For example, the name `John` might be replaced with `Amir`. + + * Custom patterns are replaced with `CUSTOM{i}`. + * Credentials are replaced with a string of `#` characters matching the original length. + +### Custom patterns + +You can define an array of custom patterns on a per-request basis. +Currently, only regex patterns are supported, and all fields are required: `name`, `regex`, and `score`. + +The `name` must be unique for each pattern. + +### Fields that can be anonymized + +You can use the following fields in the `anonymize` array: + +* `general`: Anonymizes general PII entities such as person names, locations, and organizations. +* `phone`: Anonymizes phone numbers (for example, `mobile`, `landline`). +* `email`: Anonymizes email addresses. +* `creditcard`: Anonymizes credit card numbers. +* `crypto`: Anonymizes cryptocurrency addresses. +* `date`: Anonymizes dates and timestamps. +* `ip`: Anonymizes IP addresses (both IPv4 and IPv6). +* `nrp`: Anonymizes a person’s nationality, religious, or political group. +* `ssn`: Anonymizes Social Security Numbers (SSN) and other related identifiers like ITIN, NIF, ABN, and more. +* `domain`: Anonymizes domain names. It was deprecated, use `url` instead. +* `url`: Anonymizes web URLs. +* `medical`: Anonymizes medical identifiers (for example, medical license numbers, NHS numbers, medicare numbers). +* `driverlicense`: Anonymizes driver's license numbers. +* `passport`: Anonymizes passport numbers. +* `bank`: Anonymizes bank account numbers and related banking identifiers (for example, VAT codes, IBAN). +* `nationalid`: Anonymizes various national identification numbers (for example, Aadhaar, PESEL, NRIC, social security, or voter IDs). +* `custom`: Anonymizes user-defined custom PII patterns using regular expressions only when custom patterns are provided. +* `credentials`: Anonymizes the credentials{% if include.show_endpoints %}, similar to `/sanitize_credentials`{% endif %}. +* `all`: Includes all the fields above, including custom ones. + +### Access the Docker images + +Kong distributes these images publicly on Docker Hub, under the `kong/ai-pii-service` repository. No authentication is required to pull them. + +#### Pull the AI PII service image + +To pull an image: + +```bash +docker pull kong/ai-pii-service:TAG +``` + +Replace `TAG` with the appropriate version and language code, such as: + +```bash +docker pull kong/ai-pii-service:v0.2.2-en +``` + +#### Run the AI PII service as a standalone container + +To run the image directly, without a `Dockerfile`: + +```bash +docker run -d kong/ai-pii-service:v0.2.2-en +``` + +#### AI PII service Dockerfile usage + +Alternatively, to use an image in a `Dockerfile`, reference it as follows: + +```dockerfile +FROM kong/ai-pii-service:v0.2.2-en +``` + +### Available language tags + +The following language-specific images are currently available: + +* `-en` (English) +* `-es` (Spanish) +* `-fr` (French) +* `-de` (German) +* `-it` (Italian) +* `-ja` (Japanese) +* `-ko` (Korean) +* `-nl` (Dutch) +* `-pt` (Portuguese) +* `-th` (Thai) +* `-tr` (Turkish) + +{% include /md/ai-gateway/v2/policies/spacy-pii-note.md %} + +### Image configuration options + +This service takes the following optional environment variables at startup: +* `GUNICORN_WORKERS`: Specifies the number of Gunicorn processes to run +* `PII_SERVICE_ENGINE_CONF`: Specifies the natural language processing (NLP) engine configuration file +* `GUNICORN_LOG_LEVEL`: Specifies log level +* `GUNICORN_CERTFILE` and `GUNICORN_KEYFILE`: Specifies TLS certificates for HTTPS access. + +### Serve AI PII service securely + +To serve the AI PII service over https requires additional configuration: + +1. Ensure you have trusted TLS certificates for your environment. +2. Set the `GUNICORN_CERTFILE` and `GUNICORN_KEYFILE` environment variables when starting the AI PII service. The service will switch to serving HTTPS on port `8443`. +3. Set `scheme: https` and `port: 8443` when configuring the {{include.policy_name}} Policy. The policy will connect with HTTPS. + +{:.info} +> This policy does not verify SSL/TLS connections directly, it follows the global [`tls_certificate_verify`](/ai-gateway/configuration/#tls-certificate-verify) setting. Certificates can be managed with the [AI CA Certificates](/ai-gateway/entities/ai-ca-certificate/) and [AI Certificates](/ai-gateway/entities/ai-certificate/) entities. diff --git a/app/_landing_pages/ai-gateway/ai-data-gov.yaml b/app/_landing_pages/ai-gateway/ai-data-gov.yaml index 7b36a8dfef5..9f28f2030e0 100644 --- a/app/_landing_pages/ai-gateway/ai-data-gov.yaml +++ b/app/_landing_pages/ai-gateway/ai-data-gov.yaml @@ -135,14 +135,18 @@ rows: type: h2 text: "Data loss prevention" description: "You can use {{site.ai_gateway}} features to protect personally identifiable information and prevent data loss." - column_count: 1 + column_count: 2 columns: - blocks: - type: aigw_policy config: slug: ai-sanitizer icon: ai-sanitizer.png - + - blocks: + - type: aigw_policy + config: + slug: ai-mcp-sanitizer + - header: type: h2 text: "RAG security" diff --git a/app/_landing_pages/ai-gateway/mcp.yaml b/app/_landing_pages/ai-gateway/mcp.yaml index 5748344aeb8..eadf7584d44 100644 --- a/app/_landing_pages/ai-gateway/mcp.yaml +++ b/app/_landing_pages/ai-gateway/mcp.yaml @@ -64,6 +64,7 @@ rows: - An [AI Auth Strategy](/ai-gateway/entities/ai-auth-strategy/) (`key-auth` or `openid-connect`) to authenticate AI Consumers, optionally paired with [protected resource metadata](/ai-gateway/entities/ai-mcp-server/#protected-resource-metadata) for MCP-spec OAuth2. - [AI metrics](/ai-gateway/monitor-ai-llm-metrics/#mcp-traffic-metrics) and [AI audit logs](/ai-gateway/ai-audit-log-reference/#ai-mcp-logs) to monitor MCP traffic. - ACLs to enforce access controls for MCP tool usage. + - The [AI MCP Sanitizer Policy](/ai-gateway/policies/ai-mcp-sanitizer/) (tech preview) to detect and redact PII in tool call arguments and results. - The [Rate Limiting policy](/ai-gateway/policies/rate-limiting/) and other traffic control policies to govern usage. - columns: @@ -89,7 +90,7 @@ rows: icon: /assets/icons/lock.svg title: Secure and govern your MCP traffic description: | - Apply security, governance, and observability to MCP servers with AI Policies. + Apply security, governance, and observability to MCP servers with AI Policies, including PII sanitization. ctas: - text: AI Auth Strategy entity url: /ai-gateway/entities/ai-auth-strategy/ @@ -97,6 +98,8 @@ rows: url: /ai-gateway/entities/ai-mcp-server/#protected-resource-metadata - text: Rate Limiting policy url: /ai-gateway/policies/rate-limiting/ + - text: AI MCP Sanitizer policy (tech preview) + url: /ai-gateway/policies/ai-mcp-sanitizer/ - header: type: h2 diff --git a/app/ai-gateway/ai-audit-log-reference.md b/app/ai-gateway/ai-audit-log-reference.md index 1446939ff75..1378f0fb6e7 100644 --- a/app/ai-gateway/ai-audit-log-reference.md +++ b/app/ai-gateway/ai-audit-log-reference.md @@ -686,6 +686,12 @@ rows: {% endtable %} +### AI MCP Sanitizer logs + +If you use the [AI MCP Sanitizer Policy](/ai-gateway/policies/ai-mcp-sanitizer/), {{site.ai_gateway}} logs include sanitization details under the `ai.mcp` object. + +{% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} + ### AI A2A Proxy logs If you create an [AI Agent](/ai-gateway/entities/ai-agent/), {{site.ai_gateway}} logs include additional fields under the `ai.a2a` object when `log_statistics` is enabled. These fields provide observability into Agent-to-Agent (A2A) protocol traffic, including operation names, task lifecycle state, latency, streaming metrics, and optional request/response payloads. diff --git a/app/assets/icons/plugins/ai-mcp-sanitizer.png b/app/assets/icons/plugins/ai-mcp-sanitizer.png new file mode 100644 index 00000000000..be69c832203 Binary files /dev/null and b/app/assets/icons/plugins/ai-mcp-sanitizer.png differ