From 0f686dad526d312d06b16211afed327c0befda24 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 19 Oct 2026 18:24:45 +0200 Subject: [PATCH 01/11] Add WIP docs --- app/_ai_gateway_entities/ai-mcp-server.md | 2 + .../ai-mcp-sanitizer/index.md | 222 ++++++++++++++++++ 2 files changed, 224 insertions(+) create mode 100644 app/_ai_gateway_policies/ai-mcp-sanitizer/index.md diff --git a/app/_ai_gateway_entities/ai-mcp-server.md b/app/_ai_gateway_entities/ai-mcp-server.md index 136e2c571b2..b764fa89053 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 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..f79ac3f174f --- /dev/null +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -0,0 +1,222 @@ +--- +min_version: + ai-gateway: '2.0' # TODO: confirm. Aha AI-46 targets the 2.3 GA release (2026-10-29) as Tech Preview. +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/ +published: false +--- + + + +The AI MCP Sanitizer Policy detects and redacts personally identifiable information (PII) in [Model Context Protocol (MCP)](/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 carry PII. +The [AI PII Sanitizer Policy](/ai-gateway/policies/ai-sanitizer/) can't protect this traffic, because it expects chat-completion bodies and not MCP's JSON-RPC `params` and `result` structures. +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, 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. + +## 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`. +Each target names a location in the MCP protocol instead of an abstract direction: + +{% table %} +columns: + - title: Target + key: target + - title: Direction + key: direction + - title: Use it to + key: use +rows: + - target: "`tool_arguments`" + direction: "The `tools/call` request, from {{site.ai_gateway}} to the tool server" + use: Prevent a third-party tool from receiving user data. + - target: "`tool_results`" + direction: "The `tools/call` response, from the tool server through {{site.ai_gateway}} to the calling agent" + use: Prevent data from a system of record from appearing in the LLM context. +{% endtable %} + +You can enable either target, or both. +The default is `tool_arguments`. + +{{site.ai_gateway}} sanitizes only the fields that carry 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. + + + +## 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 its text to the PII service, and {{site.ai_gateway}} 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`, `listener`, and `conversion-listener` 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`" + change: "{{site.ai_gateway}} holds a streamed `tools/call` response and releases 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`" + 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 and doesn't use the load balancer, retries, upstream TLS or mTLS settings, the keepalive pool, or the configured timeouts." +{% endtable %} + +Enabling `recover_redacted` has the same effect, because {{site.ai_gateway}} must hold the result to restore placeholders in it. + +These changes reverse when you remove `tool_results` from `sanitize_targets` and disable `recover_redacted`. +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 the request doesn't reach 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` 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. + + + +## Error handling + +The AI MCP Sanitizer Policy uses `stop_on_error` to decide what happens when the PII service is unreachable, returns a non-200 response, or returns a malformed response. + +When the service returns fewer entries than {{site.ai_gateway}} sent, the behavior is still being decided. + + +## 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`: `tool_arguments`, `tool_results`, or both" + - setting: "`allow_all_conversation_history`" + sanitizer: Supported + mcp: Not available. Conversation history is an LLM concept. + - setting: "`continue_on_detection`, `rejection_mode`" + sanitizer: Supported + mcp: Not available in the first release. +{% endtable %} + +`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. + +## PII service + +The AI MCP Sanitizer Policy uses the same external PII service as the AI PII Sanitizer Policy. +For the Docker images, the `anonymize` categories, redact modes, custom patterns, and HTTPS setup, see [AI PII Anonymizer service](/ai-gateway/policies/ai-sanitizer/#ai-pii-anonymizer-service). +You run the PII service in your own environment. + +## Logging and analytics + + + +## Configuration notes + +* `anonymize` must contain at least one value. The default is `all_and_credentials`. +* If `anonymize` includes `custom`, you must set `custom_patterns`. Each pattern needs a `name`, a `regex`, and a `score` between 0 and 1. +* `sanitize_targets` must contain at least one target. + + From d007c8a10b0ebc787080a651c452e8299094dd65 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 19 Oct 2026 18:35:15 +0200 Subject: [PATCH 02/11] fix --- app/_ai_gateway_policies/ai-mcp-sanitizer/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index f79ac3f174f..3eeaf91f854 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -1,4 +1,5 @@ --- +description: 'Detect and redact personally identifiable information (PII) in MCP tool call arguments and results.' min_version: ai-gateway: '2.0' # TODO: confirm. Aha AI-46 targets the 2.3 GA release (2026-10-29) as Tech Preview. works_on: From 4918e37a60acb04269a91405211ac34e3f52ba39 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Mon, 19 Oct 2026 18:47:57 +0200 Subject: [PATCH 03/11] fix build --- app/_ai_gateway_policies/ai-mcp-sanitizer/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index 3eeaf91f854..fb3ee7d778b 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -1,7 +1,10 @@ --- +title: 'AI MCP Sanitizer' +name: 'AI MCP Sanitizer' +publisher: kong-inc description: 'Detect and redact personally identifiable information (PII) in MCP tool call arguments and results.' min_version: - ai-gateway: '2.0' # TODO: confirm. Aha AI-46 targets the 2.3 GA release (2026-10-29) as Tech Preview. + ai-gateway: '2.0' works_on: - konnect products: @@ -26,7 +29,6 @@ related_resources: url: /ai-gateway/mcp-version-support/ - text: Model Context Protocol specification url: https://modelcontextprotocol.io/ -published: false --- From 011b81b55e1e1a13be87781c3691caee912ee4d7 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Tue, 20 Oct 2026 09:18:14 +0200 Subject: [PATCH 04/11] add missing references --- app/_ai_gateway_entities/ai-mcp-server.md | 4 +++- .../ai-mcp-sanitizer/index.md | 22 +++++++++++++++---- .../ai-gateway/ai-data-gov.yaml | 8 +++++-- app/_landing_pages/ai-gateway/mcp.yaml | 5 ++++- tmp/vite-ruby-development.json | 1 + 5 files changed, 32 insertions(+), 8 deletions(-) create mode 100644 tmp/vite-ruby-development.json diff --git a/app/_ai_gateway_entities/ai-mcp-server.md b/app/_ai_gateway_entities/ai-mcp-server.md index b764fa89053..9e6cdd16a78 100644 --- a/app/_ai_gateway_entities/ai-mcp-server.md +++ b/app/_ai_gateway_entities/ai-mcp-server.md @@ -203,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 %} @@ -764,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, see the [AI MCP Sanitizer](/ai-gateway/policies/ai-mcp-sanitizer/) Policy. 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 index fb3ee7d778b..904ddb11586 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -33,7 +33,7 @@ related_resources: -The AI MCP Sanitizer Policy detects and redacts personally identifiable information (PII) in [Model Context Protocol (MCP)](/mcp/) `tools/call` traffic on {{site.ai_gateway}}. +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 carry PII. @@ -81,6 +81,17 @@ Skipping binary content avoids sending large payloads to the PII service for no +## 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` servers run, so the [streaming and single-pass changes](#streaming-and-performance-trade-offs) don't apply. +* **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. +* **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: @@ -151,7 +162,8 @@ A configuration that targets only `tool_arguments` without recovery doesn't chan {{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. +> 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 @@ -218,8 +230,10 @@ You run the PII service in your own environment. ## Configuration notes -* `anonymize` must contain at least one value. The default is `all_and_credentials`. -* If `anonymize` includes `custom`, you must set `custom_patterns`. Each pattern needs a `name`, a `regex`, and a `score` between 0 and 1. +* `anonymize` must contain at least one value. + The default is `all_and_credentials`. +* If `anonymize` includes `custom`, you must set `custom_patterns`. + Each pattern needs a `name`, a `regex`, and a `score` between 0 and 1. * `sanitize_targets` must contain at least one target. 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..775f6cf94ed 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/tmp/vite-ruby-development.json b/tmp/vite-ruby-development.json new file mode 100644 index 00000000000..db78f25f2ca --- /dev/null +++ b/tmp/vite-ruby-development.json @@ -0,0 +1 @@ +{"url":"http://localhost:3036","host":"localhost","port":3036,"https":false,"pid":61714} \ No newline at end of file From f69b0dead7d76a20338dffdf17f29167bd0e050e Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Tue, 20 Oct 2026 09:31:31 +0200 Subject: [PATCH 05/11] remove stray vite file Co-Authored-By: Claude Sonnet 5.5 --- tmp/vite-ruby-development.json | 1 - 1 file changed, 1 deletion(-) delete mode 100644 tmp/vite-ruby-development.json diff --git a/tmp/vite-ruby-development.json b/tmp/vite-ruby-development.json deleted file mode 100644 index db78f25f2ca..00000000000 --- a/tmp/vite-ruby-development.json +++ /dev/null @@ -1 +0,0 @@ -{"url":"http://localhost:3036","host":"localhost","port":3036,"https":false,"pid":61714} \ No newline at end of file From 7049eca6c1ecc0bdfa6975831f09897b731a3cb5 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 07:11:44 +0200 Subject: [PATCH 06/11] Add logging section --- .../ai-mcp-sanitizer/index.md | 99 ++++++++++++------- .../md/ai-gateway/v2/mcp-sanitizer-logs.md | 16 +++ app/ai-gateway/ai-audit-log-reference.md | 8 ++ 3 files changed, 88 insertions(+), 35 deletions(-) create mode 100644 app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index 904ddb11586..8e8a4a451bb 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -31,24 +31,52 @@ related_resources: 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 carry PII. -The [AI PII Sanitizer Policy](/ai-gateway/policies/ai-sanitizer/) can't protect this traffic, because it expects chat-completion bodies and not MCP's JSON-RPC `params` and `result` structures. +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/) can't protect this traffic, because it only processes chat-completion bodies and not MCP's JSON-RPC `params` and `result` structures. 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, 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." + 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`. +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 %} @@ -71,7 +99,7 @@ rows: You can enable either target, or both. The default is `tool_arguments`. -{{site.ai_gateway}} sanitizes only the fields that carry user data: +{{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`. @@ -79,14 +107,12 @@ The default is `tool_arguments`. 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` servers run, so the [streaming and single-pass changes](#streaming-and-performance-trade-offs) don't apply. + 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. * **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. * **Sanitize both** if user data goes to the tool and the tool returns PII too. @@ -101,7 +127,9 @@ The AI MCP Sanitizer Policy sanitizes a `tools/call` request and its result in t {{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 its text to the PII service, and {{site.ai_gateway}} returns the sanitized result to the agent. +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 @@ -124,13 +152,11 @@ sequenceDiagram {:.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`, `listener`, and `conversion-listener` AI MCP 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 @@ -147,10 +173,10 @@ columns: - title: Effect key: effect rows: - - type: "`passthrough-listener`" - change: "{{site.ai_gateway}} holds a streamed `tools/call` response and releases it as one body." + - 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`" + - 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 and doesn't use the load balancer, retries, upstream TLS or mTLS settings, the keepalive pool, or the configured timeouts." {% endtable %} @@ -164,31 +190,27 @@ A configuration that targets only `tool_arguments` without recovery doesn't chan {:.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 the request doesn't reach the tool server. +* 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` is `true`, the tool server receives placeholders instead of the original 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` to decide what happens when the PII service is unreachable, returns a non-200 response, or returns a malformed response. - +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. +The `stop_on_error` setting is `true` by default. When the service returns fewer entries than {{site.ai_gateway}} sent, the behavior is still being decided. - ## Differences from the AI PII Sanitizer Policy @@ -206,13 +228,10 @@ columns: rows: - setting: Targeting sanitizer: "`sanitization_mode`: `INPUT`, `OUTPUT`, or `BOTH`" - mcp: "`sanitize_targets`: `tool_arguments`, `tool_results`, 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. - - setting: "`continue_on_detection`, `rejection_mode`" - sanitizer: Supported - mcp: Not available in the first release. {% endtable %} `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. @@ -226,14 +245,24 @@ You run the PII service in your own environment. ## Logging and analytics - +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: + +{% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} + +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. + ## Configuration notes -* `anonymize` must contain at least one value. +* [`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`. - Each pattern needs a `name`, a `regex`, and a `score` between 0 and 1. -* `sanitize_targets` must contain at least one target. +* 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/_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..7d4ebb24653 --- /dev/null +++ b/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md @@ -0,0 +1,16 @@ +{% 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 %} diff --git a/app/ai-gateway/ai-audit-log-reference.md b/app/ai-gateway/ai-audit-log-reference.md index 1446939ff75..971f2bc883d 100644 --- a/app/ai-gateway/ai-audit-log-reference.md +++ b/app/ai-gateway/ai-audit-log-reference.md @@ -686,6 +686,14 @@ 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 a `sanitizer` object on each logged RPC in the `ai.mcp` object. The object tracks the number of PII items identified and sanitized, the time taken to sanitize, and metadata about each sanitized item. {{site.ai_gateway}} writes these fields when `log_statistics` is enabled in the AI MCP Server's [`config.logging`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-config-logging). + +{% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} + +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`. + ### 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. From c307f111d7f865875f8311d37b56cf2afb1d9193 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 07:48:29 +0200 Subject: [PATCH 07/11] updates --- .../ai-mcp-sanitizer/index.md | 19 +++++++------------ app/ai-gateway/ai-audit-log-reference.md | 2 +- 2 files changed, 8 insertions(+), 13 deletions(-) diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index 8e8a4a451bb..2db76a27997 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -4,7 +4,7 @@ name: 'AI MCP Sanitizer' publisher: kong-inc description: 'Detect and redact personally identifiable information (PII) in MCP tool call arguments and results.' min_version: - ai-gateway: '2.0' + ai-gateway: '2.3' works_on: - konnect products: @@ -85,15 +85,11 @@ columns: key: target - title: Direction key: direction - - title: Use it to - key: use rows: - target: "`tool_arguments`" direction: "The `tools/call` request, from {{site.ai_gateway}} to the tool server" - use: Prevent a third-party tool from receiving user data. - target: "`tool_results`" direction: "The `tools/call` response, from the tool server through {{site.ai_gateway}} to the calling agent" - use: Prevent data from a system of record from appearing in the LLM context. {% endtable %} You can enable either target, or both. @@ -181,7 +177,7 @@ rows: effect: "Each call opens one additional outbound connection and doesn't use the load balancer, retries, upstream TLS or mTLS settings, the keepalive pool, or the configured timeouts." {% endtable %} -Enabling `recover_redacted` has the same effect, because {{site.ai_gateway}} must hold the result to restore placeholders in it. +Enabling `recover_redacted` also requires {{site.ai_gateway}} to hold the result, so the same changes apply. These changes reverse when you remove `tool_results` from `sanitize_targets` and disable `recover_redacted`. A configuration that targets only `tool_arguments` without recovery doesn't change streaming or single-pass behavior. @@ -210,7 +206,6 @@ The `recover_redacted` setting is `true` by default. 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. The `stop_on_error` setting is `true` by default. -When the service returns fewer entries than {{site.ai_gateway}} sent, the behavior is still being decided. ## Differences from the AI PII Sanitizer Policy @@ -234,13 +229,14 @@ rows: mcp: Not available. Conversation history is an LLM concept. {% endtable %} -`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. +{:.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. ## PII service -The AI MCP Sanitizer Policy uses the same external PII service as the AI PII Sanitizer Policy. -For the Docker images, the `anonymize` categories, redact modes, custom patterns, and HTTPS setup, see [AI PII Anonymizer service](/ai-gateway/policies/ai-sanitizer/#ai-pii-anonymizer-service). +For the PII service Docker images, the `anonymize` categories, redact modes, custom patterns, and HTTPS setup, see [AI PII Anonymizer service](/ai-gateway/policies/ai-sanitizer/#ai-pii-anonymizer-service). You run the PII service in your own environment. ## Logging and analytics @@ -265,4 +261,3 @@ Set [`skip_logging_sanitized_items`](/ai-gateway/policies/ai-mcp-sanitizer/refer 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/ai-audit-log-reference.md b/app/ai-gateway/ai-audit-log-reference.md index 971f2bc883d..5fe0aac70a4 100644 --- a/app/ai-gateway/ai-audit-log-reference.md +++ b/app/ai-gateway/ai-audit-log-reference.md @@ -688,7 +688,7 @@ rows: ### AI MCP Sanitizer logs -If you use the [AI MCP Sanitizer Policy](/ai-gateway/policies/ai-mcp-sanitizer/), {{site.ai_gateway}} logs include a `sanitizer` object on each logged RPC in the `ai.mcp` object. The object tracks the number of PII items identified and sanitized, the time taken to sanitize, and metadata about each sanitized item. {{site.ai_gateway}} writes these fields when `log_statistics` is enabled in the AI MCP Server's [`config.logging`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-config-logging). +If you use the [AI MCP Sanitizer Policy](/ai-gateway/policies/ai-mcp-sanitizer/), {{site.ai_gateway}} logs include a `sanitizer` object on each logged RPC in the `ai.mcp` object. The object tracks the number of PII items identified and sanitized, the duration of sanitization, and metadata about each sanitized item. {{site.ai_gateway}} writes these fields when `log_statistics` is enabled in the AI MCP Server's [`config.logging`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-config-logging). {% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} From 2c356a8e67baac9dea13edeec9eca03192bba442 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 13:13:30 +0200 Subject: [PATCH 08/11] Add shared include for the pii service --- .../ai-mcp-sanitizer/index.md | 18 +-- .../ai-sanitizer/index.md | 134 +---------------- .../md/ai-gateway/v2/mcp-sanitizer-logs.md | 8 ++ .../md/ai-gateway/v2/policies/pii-service.md | 135 ++++++++++++++++++ app/ai-gateway/ai-audit-log-reference.md | 4 +- 5 files changed, 152 insertions(+), 147 deletions(-) create mode 100644 app/_includes/md/ai-gateway/v2/policies/pii-service.md diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index 2db76a27997..0ecfbc48730 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -38,7 +38,7 @@ MCP tools often front systems of record such as CRMs, ticketing tools, and medic The [AI PII Sanitizer Policy](/ai-gateway/policies/ai-sanitizer/) can't protect this traffic, because it only processes chat-completion bodies and not MCP's JSON-RPC `params` and `result` structures. 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, PII categories, custom patterns, blocking, and recovery options as the AI PII Sanitizer Policy. +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 @@ -109,10 +109,13 @@ Choose targets based on which direction of the tool call includes PII and whethe * **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. + Set `recover_redacted` to `false`, because you can't use recovery when `tool_results` is a target. ## How it works @@ -234,22 +237,15 @@ rows: > > `sanitize_targets` names the protocol location instead. -## PII service +## AI PII Anonymizer service -For the PII service Docker images, the `anonymize` categories, redact modes, custom patterns, and HTTPS setup, see [AI PII Anonymizer service](/ai-gateway/policies/ai-sanitizer/#ai-pii-anonymizer-service). -You run the PII service in your own environment. +{% include /md/ai-gateway/v2/policies/pii-service.md policy_name="AI MCP Sanitizer" %} ## Logging and analytics -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: +The AI MCP Sanitizer Policy adds sanitization details to the MCP logs. {% include md/ai-gateway/v2/mcp-sanitizer-logs.md %} - -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. ## Configuration notes 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 index 7d4ebb24653..39d507ce4e7 100644 --- a/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md +++ b/app/_includes/md/ai-gateway/v2/mcp-sanitizer-logs.md @@ -1,3 +1,8 @@ +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 @@ -14,3 +19,6 @@ rows: - 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/ai-gateway/ai-audit-log-reference.md b/app/ai-gateway/ai-audit-log-reference.md index 5fe0aac70a4..1378f0fb6e7 100644 --- a/app/ai-gateway/ai-audit-log-reference.md +++ b/app/ai-gateway/ai-audit-log-reference.md @@ -688,12 +688,10 @@ rows: ### AI MCP Sanitizer logs -If you use the [AI MCP Sanitizer Policy](/ai-gateway/policies/ai-mcp-sanitizer/), {{site.ai_gateway}} logs include a `sanitizer` object on each logged RPC in the `ai.mcp` object. The object tracks the number of PII items identified and sanitized, the duration of sanitization, and metadata about each sanitized item. {{site.ai_gateway}} writes these fields when `log_statistics` is enabled in the AI MCP Server's [`config.logging`](/ai-gateway/entities/ai-mcp-server/#schema-aigateway-mcpserver-config-logging). +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 %} -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`. - ### 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. From ab8efd42518ea989138078c77a003cf6f5acb206 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 17:23:07 +0200 Subject: [PATCH 09/11] add missing icon --- .../ai-mcp-sanitizer/index.md | 1 + app/assets/icons/plugins/ai-mcp-sanitizer.png | Bin 0 -> 4310 bytes 2 files changed, 1 insertion(+) create mode 100644 app/assets/icons/plugins/ai-mcp-sanitizer.png diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index 0ecfbc48730..d969fb2052c 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -2,6 +2,7 @@ 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' 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 0000000000000000000000000000000000000000..be69c832203df23fb0e62d6201c283f818b55ea0 GIT binary patch literal 4310 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 literal 0 HcmV?d00001 From e181e9f337fe25bab9bc34253212863ccbeeb4f2 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 21:43:26 -0700 Subject: [PATCH 10/11] Apply batched suggestions from code review Co-authored-by: Angel --- app/_ai_gateway_entities/ai-mcp-server.md | 2 +- app/_ai_gateway_policies/ai-mcp-sanitizer/index.md | 13 +++++-------- app/_landing_pages/ai-gateway/mcp.yaml | 2 +- 3 files changed, 7 insertions(+), 10 deletions(-) diff --git a/app/_ai_gateway_entities/ai-mcp-server.md b/app/_ai_gateway_entities/ai-mcp-server.md index 9e6cdd16a78..3e107afd637 100644 --- a/app/_ai_gateway_entities/ai-mcp-server.md +++ b/app/_ai_gateway_entities/ai-mcp-server.md @@ -766,7 +766,7 @@ features: description: Handling WebSocket and gRPC upstreams supported: false - title: "AI Guardrails" - description: Applying content safety guardrails to MCP AI requests and responses. For PII, see the [AI MCP Sanitizer](/ai-gateway/policies/ai-mcp-sanitizer/) Policy. + 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 index d969fb2052c..e814e0ea62f 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -36,7 +36,7 @@ The AI MCP Sanitizer Policy detects and redacts personally identifiable informat 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/) can't protect this traffic, because it only processes chat-completion bodies and not MCP's JSON-RPC `params` and `result` structures. +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. @@ -68,7 +68,7 @@ rows: 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." + 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 %} @@ -116,7 +116,6 @@ Choose targets based on which direction of the tool call includes PII and whethe 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. - Set `recover_redacted` to `false`, because you can't use recovery when `tool_results` is a target. ## How it works @@ -178,12 +177,12 @@ rows: 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 and doesn't use the load balancer, retries, upstream TLS or mTLS settings, the keepalive pool, or the configured timeouts." + 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. -These changes reverse when you remove `tool_results` from `sanitize_targets` and disable `recover_redacted`. +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. @@ -234,9 +233,7 @@ rows: {% 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. +> `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 diff --git a/app/_landing_pages/ai-gateway/mcp.yaml b/app/_landing_pages/ai-gateway/mcp.yaml index 775f6cf94ed..eadf7584d44 100644 --- a/app/_landing_pages/ai-gateway/mcp.yaml +++ b/app/_landing_pages/ai-gateway/mcp.yaml @@ -64,7 +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 [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: From da3cd76b72dab6469bd53fb7bbb6793569c28597 Mon Sep 17 00:00:00 2001 From: tomek-labuk Date: Wed, 21 Oct 2026 21:50:45 -0700 Subject: [PATCH 11/11] Update app/_ai_gateway_policies/ai-mcp-sanitizer/index.md Co-authored-by: Angel --- app/_ai_gateway_policies/ai-mcp-sanitizer/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md index e814e0ea62f..f0c50add837 100644 --- a/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md +++ b/app/_ai_gateway_policies/ai-mcp-sanitizer/index.md @@ -208,7 +208,7 @@ 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. -The `stop_on_error` setting is `true` by default. +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