Security vendor integration guide

A security vendor can connect its detection into the gateway on two paths. Both are already implemented in the product; no custom development is required:

1. How to choose

• Detection depends on model inference or a vendor cloud service, and a single call takes tens of milliseconds or more: choose the HTTP API. The platform calls a fixed contract. Results enter the unified content-detection, trial-judge, and audit path. Thresholds and failure policy are configured by the administrator in a traffic rule.
• Rule-like, locally computable judgments (headers, identity, keywords, format checks, rewrite/redaction, streaming-output truncation), or when it must apply to MCP, API services, or external agents: choose a WASM gateway extension.
• Both can be used together: the extension does lightweight front checks and rewrites; the HTTP API does semantic risk scoring.

2. Path 1: content-safety detector HTTP API

Contract

Full fields are in Custom content-safety detector API. The points:

• POST {base_url}/v1/content-safety, Authorization: Bearer <API-key>, JSON request and response.
• The request contains direction (input / output) and userText. The output direction carries responseText. Multi-turn detection on carries history.
• The response must give scores for the 6 fixed categories and jailbreak, all 0–1. Optional labels are for audit only. A missing key, unknown key, or out-of-range score is an invalid response.
• Timeout 8 seconds. Timeout, connection failure, or an invalid response is handled by the rule's On detection failure action; it is not silently allowed.

Go-live steps

1. The vendor deploys the detector and confirms the gateway can reach its Base URL (an intranet address must be allowed through platform outbound protection).
2. An administrator adds a provider under Model Providers, chooses the preset Custom content-safety detector, and fills in Base URL and API key.
3. On the Content safety row under Global settings › Default models, select that service, set Model type to Custom content-safety detector, and save. On save the platform actually calls with one violating sample and one safe sample. A failed check does not save and gives a reason.
4. Use the Content detection action in a traffic rule. Choose risk categories, thresholds, and the On detection failure handling.
5. Use Try a sentence and Validate rule to send a safe sample and a real business-risk sample separately. Confirm hits match expectations, then enable it for a pilot caller.

3. Path 2: WASM gateway extension

Contract

Full development, build, validate, and publish notes are in Gateway extension development. The points:

• Package contract zenova.gateway-plugin/v4. The manifest declares supportedServiceKinds (model, mcp, http_proxy, a2a).
• Three interfaces: request-gate (allow or reject), request-transform (rewrite the request), gateway-response-transform (inspect a streaming response).
• Each execution: 2,000,000 instruction budget, 20 ms, 4 MiB memory. External services may be reached only through http_request; destinations must be declared in the manifest and authorized by the install-time key binding.
• On upload the platform compiles with the production host and runs one synthetic request. Failure is refused.

Go-live steps

1. The vendor generates a template with Gateway extensions › Download SDK or zr-plugin init, writes logic, then zr-plugin build and zr-plugin validate.
2. An administrator uploads the extension package under Gateway extensions (or the vendor publishes with zr-plugin publish using a user token that has gateway-extension management permission).
3. On the extension detail Permissions tab, check network targets, keys, and security and PII requirements. When the vendor cloud must be reached, configure key bindings and allowed destinations under Bindings.
4. Fill in configuration and install (installed as disabled). After status is In effect, enable it. Under Bindings, choose service type and service scope. Configure a security-critical extension's failure policy as fail_closed.
5. Verify with hitting and non-hitting requests separately. Check intercepts, failures, and p95 duration under Execution stats. When duration approaches 20 ms, move heavy computation onto the HTTP-API side.

4. Acceptance checklist

• Safe samples are allowed; risk samples are blocked or rewritten as expected.
• When the detector is down or the extension errors, the request is handled by the configured failure policy, not allowed.
• Observability and audit can see each detection's result and reason.