feat: add configurable request and response guardrails

[fernandoescolar]

Description

This change adds native content guardrails to Envoy AI Gateway through a new GuardrailPolicy resource and request/response enforcement in the external processor.

The design proposal is included at docs/proposals/013-guardrails/proposal.md. It compares the ext-proc architecture with the Built on Envoy Bedrock Guardrails and Azure Content Safety dynamic-module extensions and records the adopted decisions, current scope, follow-up work, and open questions.

The API is available in both v1alpha1 and v1beta1 and targets AIServiceBackend resources. Rules support request or response evaluation, deterministic multi-policy composition, configurable payload limits and timeouts, and explicit fail-open or fail-closed behavior. Actions can block, monitor, or mask matching content. CRD admission validates provider configuration, actions, endpoints, targets, and unique rule names.

The runtime supports:

• deterministic in-process regular expression rules;
• Presidio analyzer requests;
• AWS Bedrock ApplyGuardrail requests signed with SigV4; and
• Azure AI Content Safety text analysis.

Provider credentials are resolved from Kubernetes Secrets or, for Bedrock, from the standard AWS credential chain. Secret changes and policy deletion trigger reconciliation of affected routes. Missing or revoked provider configuration follows the rule's failure mode and does not leave stale gateway configuration active.

External providers receive schema-extracted text instead of serialized request envelopes. Mask actions write transformed text back to its original JSON field. Response guardrails keep streaming responses buffered until evaluation completes, preventing unsafe content from being partially delivered. Violations return HTTP 403 with the GuardrailViolation error type.

The implementation adds structured logs without payload content, an OpenTelemetry evaluation counter, and guardrail span events. It also includes example manifests and task-oriented documentation.

Validation includes unit tests, CRD admission tests, controller lifecycle and Secret rotation tests, HTTP-stub integration tests, Envoy dataplane tests for request and response blocking, and a Testcontainers test against the pinned official Presidio analyzer image. Live Azure AI Content Safety and AWS Bedrock Guardrails tests passed against real provider resources. Credential-gated live tests remain skipped by default.

GitHub Copilot was used to assist with implementation, tests, documentation, and review. The contributor has reviewed and takes responsibility for the resulting changes.

Related Issues/PRs (if applicable)

fixes: #1409 (Prompt guard moderation)
fixes: #1415 (pii detection)
fixes: #1919 (external security provider)
related: #2128 (content governance)

Special notes for reviewers (if applicable)

The main review areas are the dual-version CRD contract, Secret lifecycle behavior, backend scoping, fail-open/fail-closed semantics, response buffering, and external provider request formats.

Live provider validation requires local credentials and is intentionally not part of default CI. Presidio requires Docker but no credentials.

# Presidio
export TEST_PRESIDIO_ENDPOINT="https://..."
export TEST_PRESIDIO_API_KEY="..." # optional
export TEST_PRESIDIO_BLOCKED_TEXT="text that your policy blocks"

# Azure Content Safety
export TEST_AZURE_CONTENT_SAFETY_ENDPOINT="https://..."
export TEST_AZURE_CONTENT_SAFETY_API_KEY="..."
export TEST_AZURE_CONTENT_SAFETY_BLOCKED_TEXT="text that should be blocked"

# Bedrock Guardrails
export TEST_AWS_BEDROCK_GUARDRAIL_REGION="us-east-1"
export TEST_AWS_BEDROCK_GUARDRAIL_ID="..."
export TEST_AWS_BEDROCK_GUARDRAIL_VERSION="1"
export TEST_AWS_BEDROCK_GUARDRAIL_BLOCKED_TEXT="text that should be blocked"
# AWS credentials for Bedrock Guardrails
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."

[netlify]

✅ Deploy Preview for theagentrouter ready!

Name	Link
🔨 Latest commit	a533fcf
🔍 Latest deploy log	https://app.netlify.com/projects/theagentrouter/deploys/6ac50ab73dce2c0008354a35
😎 Deploy Preview	https://deploy-preview-2696--theagentrouter.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[missBerg]

I haven't checked, as there are many PRs open at the moment, but have you submitted a design doc PR for this? Would be helpful!
Also, have you checked these extensions:

https://builtonenvoy.io/extensions/bedrock-guardrails/
https://builtonenvoy.io/extensions/azure-content-safety/

[fernandoescolar]

I’ve added a proposal/technical design document (docs/proposals/013-guardrails/proposal.md) to help clarify the motivation, architecture, implementation details, and current scope of this PR.

I’m sorry I did not follow the project’s contribution and review protocol correctly from the beginning. I’ve reviewed the guidelines and updated the PR to align with them.

[jrderuiter]

Would love to see native guardrail support! Any thoughts on extensibility? E.g. if users want to add another (not yet supported) guardrail service with a HTTP interface, how could they do that?

(I see that you mention calling external executables as being out of scope, but also assume extensibility should have some role in this proprosal).

[fernandoescolar]

Yes, I think extensibility should definitely be part of the proposal.

One possible approach would be to define a small HTTP interface that custom guardrail services can implement, similar in spirit to Presidio’s API. For example, the runtime could send something like:

{
  "text": "some user input",
  "context": {
    "stage": "input"
  }
}

to a configured endpoint such as:

POST /analyze

and expect a normalized response:

{
  "action": "allow",
  "findings": [
    {
      "type": "PII",
      "start": 10,
      "end": 20,
      "score": 0.92
    }
  ]
}

action could be something like allow, block, or modify, with optional findings / replacement content depending on the guardrail.

Presidio is a useful precedent here because the analyzer is exposed behind a simple HTTP contract, while the implementation of the detection remains completely independent.

That would let us provide native integrations for common guardrail providers, while also having a generic HTTP guardrail adapter for services we don’t support yet. It also avoids the security / portability concerns of invoking arbitrary local executables.

[fernandoescolar]

Would love to see native guardrail support! Any thoughts on extensibility? E.g. if users want to add another (not yet supported) guardrail service with a HTTP interface, how could they do that?

(I see that you mention calling external executables as being out of scope, but also assume extensibility should have some role in this proprosal).

Hi! I have added a custom HTTP provider to the PR :)