External Moderation

The external-moderation policy sends content to a third-party moderation provider. It blocks content that the provider flags. It also blocks when the provider cannot return a correct decision. The gateway supports eight providers:

• openai-moderation
• azure-content-safety
• bedrock-apply-guardrail
• embedding-endpoint
• presidio
• guardrails-ai
• dynamo-ai
• lakera

The policy runs in the input phase by default. Attach it to a response stage with conditional chain metadata when necessary.

Configuration

pack:
  name: external-moderation-example
  version: 1.0.0
  enabled: true

policies:
  chain:
    - external-moderation

policy:
  external-moderation:
    provider: openai-moderation
    secret_key_ref:
      env: VERDICTAN_OPENAI_API_KEY
    categories:
      - violence
      - self-harm
    threshold: 0.5
    timeout_ms: 3000
    fail_closed: true

Fields

Property	Type	Default	Description
provider	enum	runtime fallback: openai-moderation	Set one of the eight provider values explicitly. The active lint schema has a different default.
secret_key_ref	object	—	Secret reference in object form, typically secret_key_ref.env.
endpoint	string	—	Provider endpoint URL when the provider uses one.
categories	string[]	[]	Optional provider-specific category filters.
threshold	number	0.5	Score threshold used by the provider adapter.
timeout_ms	integer	3000	Provider timeout in milliseconds.
fail_closed	boolean	runtime behavior: true	Set true explicitly. Provider and configuration failures block even when this legacy field is false.
aws_region	string	—	Bedrock region.
aws_access_key_env	string	—	Optional Bedrock access-key env var name.
aws_secret_key_env	string	—	Optional Bedrock secret-key env var name.
aws_session_token_env	string	—	Optional Bedrock session-token env var name.
guardrail_id	string	—	Bedrock guardrail identifier.
guardrail_version	string	—	Bedrock guardrail version.
embedding_model	string	—	Model name for provider: embedding-endpoint.
reference_texts	string[]	[]	Reference texts for provider: embedding-endpoint.
presidio_language	string	en at runtime when not specified	Optional language hint for provider: presidio.
presidio_entities	string[]	[]	Optional Presidio entity filter list.
guard_name	string	—	Name for provider: guardrails-ai.
policy_id	string	—	Policy identifier for provider: dynamo-ai.
lakera_categories	string[]	[]	Optional Lakera category filters.

Provider notes

Provider	What you must supply
openai-moderation	Supply secret_key_ref.env. endpoint is optional.
azure-content-safety	secret_key_ref.env and endpoint
bedrock-apply-guardrail	aws_region, guardrail_id, guardrail_version, and credentials if your runtime does not have them
embedding-endpoint	Supply endpoint and reference_texts. You can also supply embedding_model and secret_key_ref.
presidio	Supply endpoint. presidio_language is optional because the adapter uses en by default.
guardrails-ai	endpoint and guard_name
dynamo-ai	endpoint and policy_id
lakera	Supply secret_key_ref.env. endpoint is optional.

How it works

1. The gateway makes one string from the input message content.
2. It dispatches the content to the selected provider adapter.
3. The adapter normalizes the provider response into flagged, scores, and reason.
4. If flagged is true, the policy blocks with reason_code: external-moderation.flagged.
5. A missing credential, timeout, network error, invalid status, or malformed response blocks with policy.external_moderation_unavailable.

Best practices

• Use secret_key_ref.env. Do not use inline secrets in YAML.
• Start with one provider. Add providers only when they are necessary.
• Set fail_closed: true explicitly and test provider reliability before rollout.
• Do not configure webhook. The active moderation runtime has no webhook provider.
• Scope categories only when the provider adapter supports the category names you want.

Next steps

• Safety Filter — Local content safety controls
• Prompt Injection Detection — Built-in prompt injection detection
• PII Detector — Built-in PII detection
• DLP Filter — Custom regex and term controls