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 canceled.

Name	Link
🔨 Latest commit	5d28c3f
🔍 Latest deploy log	https://app.netlify.com/projects/theagentrouter/deploys/6aacdfd5feedd300083b09ae

[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.