Integrating Custom Security Services

Unduh

Mode fokus

Ukuran font

Terakhir diperbarui: 2026-10-15 10:15:13

Diterjemahkan oleh AI

Scenarios
Custom security services are used to integrate customer-owned or third-party security products (such as self-built content moderation platforms and third-party security products) into the AI Gateway. After configuration is complete, the gateway forwards the complete original request in full to the external security service for review before request forwarding and optionally after the model response is returned. It then performs allow, block, or content rewriting actions based on the verdict returned by the external service.
This feature applies to the following scenarios:
Enterprises that have built their own content security/risk control systems may want the AI Gateway to reuse existing security capabilities instead of switching to a different security product.
You need to use both the gateway's built-in security policies and third-party security products to apply layered protection to the same resource.
Content processing must be completed alongside security detection. For example, after PII is identified, masked text is returned to replace the original text before forwarding continues.
Prerequisites
An AI Gateway instance has been created and is in the Running state.
An available external security service detection interface is ready. It supports HTTP/HTTPS and can receive the original request/response bodies forwarded in full by the gateway, then parse the content to be inspected on its own.
The field path and value in the external service response used to determine "block/allow" have been identified, for example, result.blocked = true.
If the external service requires authentication, obtain the API Key, including the request header name and secret value.
If you plan to use the service long-term, configure it in Service Management in advance. For temporary verification only, you can manually enter the address on the configuration page.
Operation Steps
Step 1: Entering the Custom Security Service Page
1. Log in to the AI Gateway console and select the target gateway instance to go to its details page.
2. In the left sidebar, choose Security and Configuration > Security Protection to go to the Security Protection page.
3. Click the Custom Security Service Tab at the top of the page to go to the Custom Security Service page.
Note:
The review process is as follows: the caller request enters the AI Gateway → full forwarding (the gateway performs field mapping) → the external security service performs detection → verdict mapping resolution (the hit result is resolved based on the response verdict mapping) → after being allowed, the request is forwarded to the upstream model. When the detection direction is Input+Output, the forwarding and verdict steps are repeated after the model response is returned to perform a second review on the output content.
Step 2: Filling in Basic Information
In the custom security service policy module, click Create Policy and fill in the following parameters in the dialog box that appears:
Policy Name: The policy identifier must start with a letter and can contain letters, digits, -, and _ (required).
Description: A description of the policy's purpose (optional).
Step 3: Configuring Service Connections
1. In Service Address Method, select the address source (required):
Select Existing Service (default, recommended): In the Select Service dropdown list, select a service that has been registered in the Service Management module. The service list supports both HTTP and HTTPS protocols. In addition, a refresh button and a Create Service entry are provided on the right side of the dropdown list. Clicking Create Service takes you to the Create Service page in Service Management. After the service is created, return to this page and click the refresh button to select the newly created service.
Enter Address Manually: Enter the full address of the external security service's detection interface in the Service Address field (HTTP/HTTPS supported). The port and path are included in the address and cannot be configured separately.
2. In Authentication Method, select the authentication type (required):
None: The external service does not require authentication.
API Key (Header): Enter the Header Name (for example, X-API-Key) and the Secret Value.
3. Click Test Connection to verify the connectivity from the gateway to the external service. If the verdict mapping fields have been filled in, the test result will also display the parsed results of the verdict fields.
Note:
It is recommended to reuse backend services that have been registered in Service Management to maintain addresses centrally. Use the manual address entry only for temporary verification scenarios. Manually entered addresses are not saved as service records in Service Management. For production use, select an existing service instead.
Attention:
The Header Name and Secret Value are stored in encrypted form. The Secret Value cannot be viewed after it is saved, so keep a backup yourself.
If the external service uses Bearer Token authentication, set the Header Name to Authorization and the Secret Value to Bearer <token value>.
Step 4: Configuring Response Determination Mappings
Use the following three groups of settings to tell the gateway how to read verdict information from the response returned by the external service:
1. Verdict Mapping:
Verdict Field Path: The field path in the external service response used to determine whether the request is blocked, for example, result.blocked (required).
Verdict Value: The request is considered blocked when the field value equals this value, for example, true or BLOCK (required).
2. Interception Message: Select the message source (required).
Use Default Message: The input box is pre-filled with the default message "Your request contains prohibited content and has been blocked by the security policy. Modify your request and try again." You can directly edit it to use a custom fixed message.
Read from Response: Enter the field path in the external service response where the interception message is located. If the field is empty, the default message is used.
3. Content Rewriting (optional): After you enable this feature, enter the Rewritten Content Field Path (required, for example, result.sanitized_text), and the gateway rewrites the output. When the request is allowed, the gateway takes the complete value of this field and replaces the original detected text with it (for example, masked text). If this feature is disabled, the original text is passed through unchanged. Content rewriting takes effect only in the output direction (response review) and must be used together with the Input + Output detection direction. Content rewriting is not supported in the input direction. If the external service returns rewritten content during the input phase, or returns rewritten content when content rewriting is not enabled in the policy, the gateway ignores the replacement field and continues to determine the verdict based on the hit field.
Note:
The gateway supports only single-level or simply nested field path extraction. It does not support scripts or expressions for array traversal or multi-condition joint evaluation. If the external service response structure is complex, add an adapter API on the external service side to flatten the verdict result before integration.
Step 5: Configuring Detection Behavior Control
Detection Direction (required): Input only (default) or Input + Output.
Match Action (required): Observe or Block. When the match action is Block, the gateway blocks the request or rewrites the content based on the review verdict, and returns the interception message.
Total Detection Timeout (required): The maximum wait time for calling the external service. Valid values range from 50 to 5000 milliseconds (inclusive), with a default of 500 milliseconds.
Detection Failure Policy (required): Allow on exception / Block on exception.
Attention:
When Allow on exception is selected, requests are allowed if the review times out or the connection fails, which poses a security bypass risk. The total detection timeout adds to the overall request latency. When the detection direction is Input + Output, the total latency is the sum of the two external call durations.
Step 6: Binding the Effective Scope and Submitting
1. In Effective Scope, select the scope (required):
All: Applies to all resources under this instance, including Model APIs, MCP services (excluding SSE), and Agent APIs (A2A).
Partial: Applies only to selected resources. In the Select Resources area, switch resource types via the Model API, MCP Service, and Agent API tabs (each tab shows the selected quantity). Search by name and select resources in the corresponding list. The list displays the resource name, path, and protocol.
2. Click Submit to complete the creation. Click Close to discard this configuration.
Step 7: Viewing and Managing Policies
1. In the policy list, you can filter policies by name or description using the search box. Click a policy name to open the details panel on the right, where you can view the Basic Information, Effective Scope, and Response Verdict Mapping configurations. Click Back to Policy List to return to the list page.
2. In the Actions column on the right side of the policy list, you can perform the following operations: Edit, Disable (recoverable), and Delete (irrecoverable).
Disable: A dialog box prompts, "Are you sure you want to disable the policy 'Policy Name'? After disabling, the policy will stop taking effect immediately, and its bound resources will no longer be protected by this policy." The disabling takes effect after you click Confirm Disable. After disabling, you can re-enable the policy at any time from the list, and the policy configuration will be fully retained.
Delete: A dialog box prompts, "Are you sure you want to delete the policy 'Policy Name'? After deletion, the policy will take effect immediately and the operation cannot be undone." The deletion takes effect after you click Confirm Delete.
Step 8: Viewing Content Moderation Details
1. In the Content Review Details module below the Custom Security Service page, you can filter by Hit Action and Detection Direction to view the review hit records of all policies under this Tab.
2. Click Download Details to export the current filter results as a CSV file, with a limit of up to 1,000 records.
Submission Protocol Description (External Security Service Integration Specification)
This section specifies the review interface contract between the AI Gateway (hereinafter referred to as the "Gateway") and the external security service (hereinafter referred to as the "Review Service"), for use by developers integrating with the Review Service.
The gateway does not directly forward raw service packets. Instead, it first encapsulates the raw request/response into a unified review envelope (Schema Version 2.0) and then POSTs it to the review service. Regardless of whether the raw service uses the OpenAI-compatible protocol, Anthropic, Dify, A2A, or MCP, the gateway outputs the same envelope structure. The review service only needs to integrate with the contract once, without adapting parsers for each protocol.
Protocol Overview and Terminology
Interaction Roles
Role
Responsibilities
AI gateway (caller)
Encapsulate a unified review envelope, initiate review requests, parse review conclusions, and perform release / blocking / rewriting based on policies.
External security service (review service)
Receive review requests, complete content determination based on its own detection capabilities, and return review conclusions in JSON format.
Terminology
Term
Definition
Audit Request
A detection call initiated by the gateway to the audit service
Audit Unit
Detection object corresponding to an audit request, uniquely identified by audit_id. It can be a complete request/response Body, an SSE Event Batch, or the complete content of an oversized Body transferred in segments.
Decision
Decision returned by the audit service for an audit unit: allow, block, or replace
Inline Envelope
Audit request form in which the Body is directly embedded in content.body, as opposed to "segmented transfer"
Event Batch
An audit unit composed of one or more complete SSE Events in streaming response scenarios
Transfer
A complete transfer process consisting of the begin, chunk, and end phases in oversized Body scenarios
Normative Verb Conventions
This specification adopts the requirement levels defined in RFC 2119: MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY.
Protocol Design Principles
Semantic Preservation: The unified envelope does not alter the semantics of the original service protocol. It only declares the protocol type through the protocol field. Based on this, the review service can select a dedicated parser or directly perform generic detection on content.body.
Normalized Structure, Not Normalized Bytes: The JSON Body is parsed into a complete JSON value, preserving the semantics of objects, arrays, and scalars. However, byte-level formatting such as spaces, line breaks, and field order is not guaranteed to match the original packet. For oversized bodies, raw bytes are transmitted during the Chunk phase.
HTTP Conventions
Item
Convention
Request Method
POST
Request Content-Type
For inline envelope audit requests and the Begin and End phases of an oversized Body, the Content-Type is application/json; for the Chunk phase of an oversized Body, it is application/octet-stream.
Response Content-Type
The response of the audit service must be application/json.
Protocol version request header
X-CNGW-Audit-Schema-Version: 2.0, which the gateway carries in all audit requests.
Authentication
Both parties agree on a fixed Header. The Header name and value are configured on the gateway side, corresponding to API Key (Header) in the console.
Status code semantics
For normal audit conclusions (including block), HTTP 2xx must be returned. A non-2xx return indicates audit service call failure (rather than content violation), and the gateway handles it according to the configured detection failure policy.
Attention:
The review service MUST NOT express content violations by returning non-2xx status codes. Content violations MUST be expressed in the HTTP 2xx response body. In standard response mode, this is decision = "block". In custom field mapping mode, the hit verdict field takes the hit value.
Unified Submission Envelope
The following is an example of submitting an MCP Streamable HTTP request for review (inline envelope form):
{
  "schema_version": "2.0",
  "audit_id": "7c96777a-5f8f-4e58-9b16-2fdc0de3a7ba",
  "direction": "request",
  "protocol": {
    "category": "mcp",
    "name": "mcp-streamable-http",
    "version": "2025-03-26"
  },
  "http": {
    "method": "POST",
    "path": "/mcp",
    "headers": {
      "content-type": ["application/json"],
      "accept": ["application/json, text/event-stream"],
      "mcp-protocol-version": ["2025-03-26"]
    }
  },
  "streaming": {
    "mode": "possible",
    "format": "sse",
    "unit": "full_body"
  },
  "content": {
    "media_type": "application/json",
    "encoding": "json",
    "body": {
      "jsonrpc": "2.0",
      "id": 17,
      "method": "tools/call",
      "params": {
        "name": "knowledge_search",
        "arguments": { "query": "Please introduce this product" }
      }
    }
  },
  "gateway_context": {
    "request_id": "req-123",
    "gateway_id": "gateway-abc123",
    "route_id": "route-456",
    "service_id": "service-789"
  }
}
Top-Level Fields
Field
Type
Constraint
Description
schema_version
string
Required
Fixed to 2.0
audit_id
string
Required
Unique ID of the current audit unit. In standard response mode, it must be echoed back as is. In custom field mapping mode, echoing back is not required.
direction
string
Required
request (request for review) or response (response for review)
protocol
object
Required
Identification result of the original service protocol. For details, see the original service protocol identifier.
http
object
Required
Metadata of the original HTTP request or response
streaming
object
Required
Streaming intent in the request direction, or actual streaming review status in the response direction
content
object
Required
Original protocol Body (inline envelope) or transfer description (segmented transfer)
gateway_context
object
Optional
The gateway automatically supplements this field based on the current request context, and it is not filled in by the caller.
http Fields
Field
Type
Description
method
string
Original request method, carried only in request for review
path
string
Original request path, excluding Query String, carried only in request for review
status_code
int
Original response status code, carried only in response for review
headers
object
Header names are uniformly converted to lowercase, and values are uniformly string arrays.
query
string
Original Query String, not carried by default, appears only after the gateway explicitly enables Query passthrough
Field Rules:
Request review submissions carry method, path, and headers. Regular response review submissions carry status_code and headers.
By default, only content-type, accept, mcp-protocol-version, and a2a-version are passed through. Other headers are determined by the gateway allowlist configuration.
Credential and session headers such as authorization, cookie, x-api-key, and mcp-session-id are not sent with review requests.
Note:
Credential headers are not passed through by default, to prevent customer keys from leaking to third-party review services. If the review service's detection logic requires Query parameters, you must explicitly enable Query pass-through on the gateway.
content Encoding
The review service SHOULD parse content.body according to content.encoding and SHOULD NOT assume that the Body is always a JSON object.
Field
Type
Description
media_type
string
Original media type. For JSON, the type is the original Content-Type with parameters removed and converted to lowercase.
encoding
string
Body encoding method: json / text / base64
body
mixed
Content encoded by encoding; not present during segmented transfer (Begin phase)
transfer
object
Transfer description, only present in the Begin phase of segmented transfer for oversized Body
Original Body
encoding
body Value
JSON
json
A complete JSON value, which can be an object, array, or scalar
Text
text
Original string (original text/* type)
Binary
base64
Base64 string (media type remains unchanged)
Empty Body
base64
Empty string ""; SSE empty termination unit uses text encoding, see Stream End Semantics.
Note:
Requests without a Body do not generate request content for review. For example, GET /sse in MCP Legacy SSE is used only to establish the response stream. The request phase is skipped directly, and streaming response review can still proceed afterward.
gateway_context Field
This object is populated by the gateway based on the current request context and may contain the following fields:
Field
Type
Constraint
Description
request_id
string
Optional
Request ID, which may be inherited from the value passed in by the client.
trace_id
string
Optional
Trace ID, which may be inherited from the value passed in by the client.
gateway_id
string
Optional
Gateway instance ID
route_id
string
Optional
Matched route ID
service_id
string
Optional
Matched service ID
workspace_id
string
Optional
Workspace ID
consumer_id
string
Optional
Consumer ID, populated after successful authentication.
tenant_id
string
Optional
Reserved field, not output when no stable data source is available.
Attention:
All fields are optional. The review service SHOULD NOT treat the presence of any field as a prerequisite for protocol parsing.
gateway_id, route_id, service_id, workspace_id, and consumer_id obtained after successful authentication come from the gateway runtime context and can serve as stable governance dimensions.
request_id and trace_id may be inherited from client-provided values and can be used for log correlation. They SHOULD NOT be used alone as a basis for trusted identity.
streaming Field
This field is used to distinguish between the streaming intent in the request direction and the actual streaming review status in the response direction.
mode
Applicable Direction
Description
none
Request/Response
The original request does not express streaming return intent, or the response is non-streaming.
requested
Request
The original request explicitly requires streaming return.
possible
Request
The original protocol may return SSE, such as MCP Streamable HTTP.
active
Response time
Streaming response review is in progress and only occurs in Event Batch review.
Note:
During request review, when mode is requested or possible, the review unit is unit = "full_body". When mode = "none", format and unit may be omitted.
During response review, ordinary non-streaming responses typically carry only mode = "none". For field rules of streaming responses, see Streaming Response Review.
Original Business Protocol Identifier
The protocol field declares which service protocol semantics content.body should be parsed according to.
Field
Type
Constraint
Description
category
string
Required
Protocol category: llm / dify / a2a / mcp / agent
name
string
Required
Protocol name. See the table below.
version
string
Optional
Protocol version. See the notes below for its source.
operation
string
Optional
Operation identifier. Currently output only for LLM protocols.
Scenario
protocol.category
protocol.name
Identification Basis
OpenAI Chat Completions
llm
openai-chat-completions
Path /v1/chat/completions
OpenAI Responses
llm
openai-responses
Path /v1/responses
Anthropic Messages
llm
anthropic-messages
Path /v1/messages
A2A JSON-RPC
a2a
a2a-jsonrpc
JSON-RPC call method
A2A HTTP+JSON
a2a
a2a-http-json
application/a2a+json, :send, or :stream
MCP Streamable HTTP
mcp
mcp-streamable-http
MCP Streamable HTTP
Note:
The review service can select an internal parser based on protocol.name, or it can directly perform general detection on the complete content.body.
For OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, protocol.version is v1, and protocol.operation is chat.completions, responses, and messages, respectively.
The A2A protocol.version is taken from the A2A-Version Header in the request. If the request does not carry this Header, this field may be omitted.
The MCP protocol.version is taken from the MCP-Protocol-Version Header in the request. If the initialize request has not completed version negotiation, this field is omitted.
Submitting Common Requests and Responses for Review
Submitting Requests for Review
Envelope characteristics of request review:
direction = "request";
Carries http.method, http.path, and http.headers.
content.body represents the complete service protocol Body at the time of review execution according to content.encoding, including modifications made to the request body by higher-priority plugins. JSON is a complete JSON value, and byte-level format consistency is not guaranteed.
Submitting Common Responses for Review
Regular response review reuses the same envelope, with the only differences being direction = "response" and http carrying status_code. The following is an example of A2A JSON-RPC response review:
{
  "schema_version": "2.0",
  "audit_id": "b238ce7f-8616-4914-b21f-a65f144cf90f",
  "direction": "response",
  "protocol": {
    "category": "a2a",
    "name": "a2a-jsonrpc",
    "version": "1.0"
  },
  "http": {
    "status_code": 200,
    "headers": { "content-type": ["application/json"] }
  },
  "streaming": { "mode": "none" },
  "content": {
    "media_type": "application/json",
    "encoding": "json",
    "body": {
      "jsonrpc": "2.0",
      "id": "task-001",
      "result": {
        "id": "task-001",
        "status": { "state": "completed" },
        "artifacts": [
          { "parts": [ { "kind": "text", "text": "Content returned by the A2A Agent" } ] }
        ]
      }
    }
  },
  "gateway_context": { "request_id": "req-123" }
}
Submitting Streaming Responses for Review
After stream response review is enabled, the gateway does not wait for the entire SSE stream to end before submitting it for review. Instead, it processes the stream according to the following sequence:
1. The gateway assembles the received complete SSE Event into an Event Batch (review unit).
2. Call the review service synchronously in stream order to submit the current Batch for review.
3. Only after the gateway obtains the review conclusion and processes it according to the policy does it deliver the current Batch to the client.
Processing Rules:
The review service is not called for Batches that are not selected by filtering rules or sampling rules.
When the review service times out, encounters a network error, or returns a non-2xx status code, the gateway processes the request according to the policy-configured Fail-Open or Fail-Closed behavior.
Batch boundaries are dynamically generated by the gateway based on the number of Events, bytes, or wait time.
Event Batch Submission Format for Review
The following is an example of submitting an MCP Streamable HTTP SSE response for review:
{
  "schema_version": "2.0",
  "audit_id": "audit-stream-0003",
  "direction": "response",
  "protocol": { "category": "mcp", "name": "mcp-streamable-http", "version": "2025-03-26" },
  "http": {
    "status_code": 200,
    "headers": { "content-type": ["text/event-stream"] }
  },
  "streaming": {
    "mode": "active",
    "format": "sse",
    "unit": "event_batch",
    "stream_id": "req-123:response",
    "sequence": 3,
    "final": false,
    "context_before": {
      "media_type": "text/event-stream",
      "encoding": "text",
      "body": "...previous approved context tail..."
    }
  },
  "content": {
    "media_type": "text/event-stream",
    "encoding": "text",
    "body": "data: {\\"jsonrpc\\":\\"2.0\\",\\"id\\":17,\\"result\\":{\\"content\\":[{\\"type\\":\\"text\\",\\"text\\":\\"Content returned for the current batch\\"}]}}\\n\\n"
  },
  "gateway_context": {
    "request_id": "req-123",
    "gateway_id": "gateway-abc123",
    "route_id": "route-456",
    "service_id": "service-789"
  }
}
streaming Field (Streaming Response)
Field
Type
Description
mode
string
Fixed to active during streaming response review.
format
string
Currently fixed to sse.
unit
string
Fixed to event_batch, indicating that the current audit unit consists of one or more complete SSE Events.
stream_id
string
Remains unchanged within the same logical response stream for correlation and observation; global uniqueness is not guaranteed, and it must not be used as an isolation key for security identity or persistent state.
sequence
int
Sequence number of the actual review unit within the current logical response stream, strictly increasing from 1.
final
bool
Whether the current Batch is the last review unit of this logical response stream.
context_before
object
Optional released history tail, used only to identify cross-Batch risks and not part of the current rewritable content.
Attention:
A unique audit_id is generated for each Event Batch. In standard response mode, the audit_id of the current Batch must be returned. The audit_id is not used for cross-Batch correlation, and stream_id should be used instead.
The review service should complete the review based on the current content and context_before, and should not rely solely on stream_id to maintain cross-Batch state on the server side over the long term.
The review service should not assume that a single request produces only one Event, and should not rely on a fixed Batch size.
content and Context Rules
content.body is the complete raw text of the SSE Event currently pending review, and may contain one or more Events.
For a regular Batch, content.media_type is fixed to text/event-stream, and content.encoding is fixed to text.
context_before.body may only be the tail of the preceding text and is not guaranteed to form a complete SSE Event by itself. The review service can use it for auxiliary judgment, but must not incorporate it into the replacement result.
Content that has already appeared in context_before has been delivered to the client, and subsequent Batches must not modify or retract it.
Handling Review Results
For the response format of the review service, see Review Response. In standard response mode, the schema_version and audit_id of the current Batch must be returned. The handling behavior for each review conclusion is as follows:
Review Conclusion
Gateway Behavior
allow
Forward the current Batch to the client as is.
block
Terminate the response stream. Because the HTTP 200 response header is usually already sent in SSE scenarios, the client receives event: error instead of a new HTTP 403.
replace
Allowed to return only when stream response rewriting is enabled. content must be the complete replacement value for the current entire Event Batch (not a Patch) and consist of complete SSE Events. After replacement, continue processing subsequent Batches. If the replacement content contains a termination Event recognizable by the protocol, end the response stream.
Example of a streaming replace response:
{
  "schema_version": "2.0",
  "audit_id": "audit-stream-0003",
  "decision": "replace",
  "reason_code": "CONTENT_REDACTED",
  "content": {
    "media_type": "text/event-stream",
    "encoding": "text",
    "body": "data: {\\"jsonrpc\\":\\"2.0\\",\\"id\\":17,\\"result\\":{\\"content\\":[{\\"type\\":\\"text\\",\\"text\\":\\"Replaced safe content\\"}]}}\\n\\n"
  }
}
The table above describes the handling behavior when Match Action = Block. When the match action is Observe, the gateway only records the verdict and does not block or rewrite content. Detection exceptions are still handled according to the detection failure policy.
Stream End Semantics
OpenAI Chat Completions, OpenAI Responses, Anthropic, Dify, and A2A determine final = true based on their respective protocol termination Events.
MCP Streamable HTTP and custom SSE have no unified in-band termination marker. When the upstream connection reaches EOF: if there is still content pending review, the last non-empty Batch can directly carry final = true. If review units have been generated, final = true has not yet appeared, and review bypass has not been entered, an empty termination unit with final = true and content.body = "" is sent, whose encoding is text. In the event of an abnormal interruption, receipt of a termination unit is not guaranteed.
An empty termination unit is only allowed to return allow or block, and is not allowed to return replace.
Once a unit has final = true, no subsequent Event Batches are generated for the same stream_id.
Review Response
The response of the review service must be JSON. The mapping between review conclusions and console policy configurations is as follows:
Review Conclusion
Console Configuration Item
Final Gateway Behavior
allow
﻿
Pass through the current moderation unit as is.
block
Action taken = Block
Block the request or terminate the response stream, and return the interception message.
replace
Action taken = Block and Content rewriting enabled (output direction only; replacement is not performed when the action taken is Observe).
Replace the current audit unit entirely with the content returned by the audit service; replacement takes precedence over blocking.
The gateway supports a custom field mapping mode, which corresponds to the three configuration groups of Response Verdict Mapping in the console. It reads the verdict, prompt, and replacement fields according to the configured paths and does not require a fixed schema_version, audit_id, or decision to be returned.
Note:
When rewriting is enabled in the output direction and a replacement field exists, replacement takes precedence over hit blocking. The replacement content must still pass format and size validation.
When the match action is Observe, content blocking and replacement are not performed.
The Begin/Chunk confirmation responses and End associated fields for oversized Body segmentation must comply with the requirements of the oversized request Body segmentation protocol. Field mapping can be used for the review verdict in the End phase.
Allow
{
  "schema_version": "2.0",
  "audit_id": "7c96777a-5f8f-4e58-9b16-2fdc0de3a7ba",
  "decision": "allow"
}
Block
{
  "schema_version": "2.0",
  "audit_id": "7c96777a-5f8f-4e58-9b16-2fdc0de3a7ba",
  "decision": "block",
  "reason_code": "CONTENT_RISK",
  "message": "The content does not comply with the security policy."
}
reason_code and message are optional fields. Whether message is used as a client prompt is determined by the gateway policy. It takes effect when the Interception Prompt Message in the console is configured as "Read from Response", and falls back to the default message when the read result is empty.
Replace
The following is an example of performing a full Body replacement on a non-streaming response of MCP tools/call (direction = "response"):
{
  "schema_version": "2.0",
  "audit_id": "audit-response-001",
  "decision": "replace",
  "reason_code": "CONTENT_REDACTED",
  "content": {
    "media_type": "application/json",
    "encoding": "json",
    "body": {
      "jsonrpc": "2.0",
      "id": 17,
      "result": {
        "content": [ { "type": "text", "text": "Replaced safe content" } ],
        "isError": false
      }
    }
  }
}
When replace is returned, the following constraints must be met:
Carry the complete content object;
content.media_type and content.encoding must be exactly the same as those in the submitted request.
content.body represents the entire current review unit after replacement, and is a complete replacement value rather than a Patch.
Only the output direction is supported (response review), and Content Rewriting must be enabled in the console. Replacement is not supported for input direction review.
Attention:
In standard response mode, if replace is returned during the input phase or when content rewriting is not enabled, the gateway **converts it to block** and then processes it according to the observation/interception policy.
Oversized Request Body Segmentation Protocol
When the request Body does not fit into a single JSON envelope, the gateway still calls the same Endpoint and completes the review through three phases: begin → chunk → end.
General Rules:
Item
Convention
Trigger Condition
Determined by the gateway configuration. By default, segmentation is triggered when the size exceeds 1 MiB. The access party should not hardcode this threshold.
Storage Capacity
By default, a maximum of 32 MiB is received. Requests exceeding this limit do not enter the review process. The access party should not hardcode this threshold.
Chunk Size
Determined by the content.transfer.chunk_bytes declared in the Begin phase. The gateway dynamically adjusts it based on the Body size.
Timeout
begin, all chunks, and end share the same total transfer timeout, subject to the configuration actually delivered by the gateway. When a policy is created in the console, it corresponds to total detection timeout (default: 500 ms, range: 50 to 5000 ms).
Streaming Intent
The gateway does not fully parse the Body again before Begin. When the streaming intent cannot be clearly determined from the path or Header, streaming.mode is conservatively marked as possible, and this value does not indicate that the response is necessarily streaming.
Rewrite Capability
The current segmentation protocol does not support replace and only returns allow or block.
Begin
Request header:
Content-Type: application/json
X-CNGW-Audit-Schema-Version: 2.0
X-CNGW-Audit-Id: <audit_id>
X-CNGW-Audit-Transfer-Phase: begin
X-CNGW-Audit-Transfer-Id: <transfer_id>
The request body is a unified envelope. protocol, http, streaming, and gateway_context are the same as those in the inline envelope. content no longer contains body and instead carries a transfer description:
{
  "content": {
    "media_type": "application/json",
    "encoding": "json",
    "transfer": {
      "transfer_id": "transfer-123",
      "total_bytes": 5242880,
      "sha256": "<SHA-256 hexadecimal value of the complete original Body>",
      "chunk_bytes": 262144
    }
  }
}
The review service confirms receipt:
{
  "schema_version": "2.0",
  "audit_id": "<audit_id>",
  "transfer_id": "transfer-123",
  "status": "continue",
  "next_sequence": 1
}
Chunk
Request header:
Content-Type: application/octet-stream
X-CNGW-Audit-Schema-Version: 2.0
X-CNGW-Audit-Id: <audit_id>
X-CNGW-Audit-Transfer-Phase: chunk
X-CNGW-Audit-Transfer-Id: transfer-123
X-CNGW-Audit-Transfer-Sequence: 1
X-CNGW-Audit-Transfer-Offset: 0
The request body is raw bytes without JSON or Base64 wrapping. Each time sequence = N is received, the review service returns:
{
  "schema_version": "2.0",
  "audit_id": "<audit_id>",
  "transfer_id": "transfer-123",
  "status": "continue",
  "next_sequence": 2
}
End
Request header:
Content-Type: application/json
X-CNGW-Audit-Schema-Version: 2.0
X-CNGW-Audit-Id: <audit_id>
X-CNGW-Audit-Transfer-Phase: end
X-CNGW-Audit-Transfer-Id: transfer-123
Request body:
{
  "schema_version": "2.0",
  "audit_id": "<audit_id>",
  "transfer_id": "transfer-123",
  "phase": "end",
  "chunks": 20,
  "total_bytes": 5242880,
  "sha256": "<SHA-256 hexadecimal value of the complete original Body>"
}
The review service should validate sequence, offset, total_bytes, and sha256.
Attention:
All chunks are raw bytes. After reassembly, they should be interpreted according to media_type: JSON can be parsed as a JSON value, text is read using the corresponding character set, and binary remains raw bytes. The content.encoding in the Begin phase describes how the content is represented in the inline envelope and is not the transfer encoding of the chunks. Even if its value is base64, you must not perform Base64 decoding again on the reassembled chunks.
After validation and review are complete, the review service returns the final allow or block and must also echo back schema_version, audit_id, and transfer_id as-is:
{
  "schema_version": "2.0",
  "audit_id": "<audit_id>",
  "transfer_id": "transfer-123",
  "decision": "allow"
}

Bantuan dan Dukungan

Apakah halaman ini membantu?

Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.

masukan

Original Body	`encoding`	`body` Value
JSON	`json`	A complete JSON value, which can be an object, array, or scalar
Text	`text`	Original string (original `text/*` type)
Binary	`base64`	Base64 string (media type remains unchanged)
Empty Body	`base64`	Empty string `""`; SSE empty termination unit uses `text` encoding, see Stream End Semantics.

Scenario	`protocol.category`	`protocol.name`	Identification Basis
OpenAI Chat Completions	`llm`	`openai-chat-completions`	Path `/v1/chat/completions`
OpenAI Responses	`llm`	`openai-responses`	Path `/v1/responses`
Anthropic Messages	`llm`	`anthropic-messages`	Path `/v1/messages`
A2A JSON-RPC	`a2a`	`a2a-jsonrpc`	JSON-RPC call method
A2A HTTP+JSON	`a2a`	`a2a-http-json`	`application/a2a+json`, `:send`, or `:stream`
MCP Streamable HTTP	`mcp`	`mcp-streamable-http`	MCP Streamable HTTP

Review Conclusion	Gateway Behavior
`allow`	Forward the current Batch to the client as is.
`block`	Terminate the response stream. Because the HTTP 200 response header is usually already sent in SSE scenarios, the client receives `event: error` instead of a new HTTP 403.
`replace`	Allowed to return only when stream response rewriting is enabled. `content` must be the complete replacement value for the current entire Event Batch (not a Patch) and consist of complete SSE Events. After replacement, continue processing subsequent Batches. If the replacement content contains a termination Event recognizable by the protocol, end the response stream.

Role	Responsibilities
AI gateway (caller)	Encapsulate a unified review envelope, initiate review requests, parse review conclusions, and perform release / blocking / rewriting based on policies.
External security service (review service)	Receive review requests, complete content determination based on its own detection capabilities, and return review conclusions in JSON format.

Term	Definition
Audit Request	A detection call initiated by the gateway to the audit service
Audit Unit	Detection object corresponding to an audit request, uniquely identified by `audit_id`. It can be a complete request/response Body, an SSE Event Batch, or the complete content of an oversized Body transferred in segments.
Decision	Decision returned by the audit service for an audit unit: allow, block, or replace
Inline Envelope	Audit request form in which the Body is directly embedded in `content.body`, as opposed to "segmented transfer"
Event Batch	An audit unit composed of one or more complete SSE Events in streaming response scenarios
Transfer	A complete transfer process consisting of the begin, chunk, and end phases in oversized Body scenarios

Item	Convention
Request Method	POST
Request Content-Type	For inline envelope audit requests and the Begin and End phases of an oversized Body, the Content-Type is `application/json`; for the Chunk phase of an oversized Body, it is `application/octet-stream`.
Response Content-Type	The response of the audit service must be `application/json`.
Protocol version request header	`X-CNGW-Audit-Schema-Version: 2.0`, which the gateway carries in all audit requests.
Authentication	Both parties agree on a fixed Header. The Header name and value are configured on the gateway side, corresponding to API Key (Header) in the console.
Status code semantics	For normal audit conclusions (including block), HTTP 2xx must be returned. A non-2xx return indicates audit service call failure (rather than content violation), and the gateway handles it according to the configured detection failure policy.

Field	Type	Constraint	Description
`schema_version`	string	Required	Fixed to `2.0`
`audit_id`	string	Required	Unique ID of the current audit unit. In standard response mode, it must be echoed back as is. In custom field mapping mode, echoing back is not required.
`direction`	string	Required	`request` (request for review) or `response` (response for review)
`protocol`	object	Required	Identification result of the original service protocol. For details, see the original service protocol identifier.
`http`	object	Required	Metadata of the original HTTP request or response
`streaming`	object	Required	Streaming intent in the request direction, or actual streaming review status in the response direction
`content`	object	Required	Original protocol Body (inline envelope) or transfer description (segmented transfer)
`gateway_context`	object	Optional	The gateway automatically supplements this field based on the current request context, and it is not filled in by the caller.

`mode`	Applicable Direction	Description
`none`	Request/Response	The original request does not express streaming return intent, or the response is non-streaming.
`requested`	Request	The original request explicitly requires streaming return.
`possible`	Request	The original protocol may return SSE, such as MCP Streamable HTTP.
`active`	Response time	Streaming response review is in progress and only occurs in Event Batch review.

Review Conclusion	Console Configuration Item	Final Gateway Behavior
`allow`		Pass through the current moderation unit as is.
`block`	Action taken = Block	Block the request or terminate the response stream, and return the interception message.
`replace`	Action taken = Block and Content rewriting enabled (output direction only; replacement is not performed when the action taken is Observe).	Replace the current audit unit entirely with the content returned by the audit service; replacement takes precedence over blocking.

Item	Convention
Trigger Condition	Determined by the gateway configuration. By default, segmentation is triggered when the size exceeds 1 MiB. The access party should not hardcode this threshold.
Storage Capacity	By default, a maximum of 32 MiB is received. Requests exceeding this limit do not enter the review process. The access party should not hardcode this threshold.
Chunk Size	Determined by the `content.transfer.chunk_bytes` declared in the Begin phase. The gateway dynamically adjusts it based on the Body size.
Timeout	begin, all chunks, and end share the same total transfer timeout, subject to the configuration actually delivered by the gateway. When a policy is created in the console, it corresponds to total detection timeout (default: 500 ms, range: 50 to 5000 ms).
Streaming Intent	The gateway does not fully parse the Body again before Begin. When the streaming intent cannot be clearly determined from the path or Header, `streaming.mode` is conservatively marked as `possible`, and this value does not indicate that the response is necessarily streaming.
Rewrite Capability	The current segmentation protocol does not support `replace` and only returns `allow` or `block`.

tencent cloud

Cloud Native Intelligent Gateway

Integrating Custom Security Services

Scenarios

Prerequisites

Operation Steps

Step 1: Entering the Custom Security Service Page

Step 2: Filling in Basic Information

Step 3: Configuring Service Connections

Step 4: Configuring Response Determination Mappings

Step 5: Configuring Detection Behavior Control

Step 6: Binding the Effective Scope and Submitting

Step 7: Viewing and Managing Policies

Step 8: Viewing Content Moderation Details

Submission Protocol Description (External Security Service Integration Specification)

Protocol Overview and Terminology

HTTP Conventions

Unified Submission Envelope

Top-Level Fields

http Fields

content Encoding

gateway_context Field

streaming Field

Original Business Protocol Identifier

Submitting Common Requests and Responses for Review

Submitting Requests for Review

Submitting Common Responses for Review

Submitting Streaming Responses for Review

Event Batch Submission Format for Review

streaming Field (Streaming Response)

content and Context Rules

Handling Review Results

Stream End Semantics

Review Response

Allow

Block

Replace

Oversized Request Body Segmentation Protocol

Begin

Chunk

End

Bantuan dan Dukungan