External Moderation

The external-moderation policy sends content to a third-party moderation provider and blocks when the provider flags the content. The gateway currently supports nine providers:

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

By default the policy runs in the input phase. You can attach it to a response stage with conditional chain metadata when needed.

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: KEEPTRUSTS_OPENAI_API_KEY
    categories:
      - violence
      - self-harm
    threshold: 0.5
    timeout_ms: 3000
    fail_closed: true

Fields

Property	Type	Default	Description
provider	enum	webhook	One of the nine provider values listed above.
secret_key_ref	object	—	Secret reference in object form, typically secret_key_ref.env.
endpoint	string	—	Provider endpoint URL when the provider needs 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	false	Block on provider failure instead of allowing through.
webhook_headers	object	{}	Extra headers for provider: webhook.
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 omitted	Optional language hint for provider: presidio.
presidio_entities	string[]	[]	Optional Presidio entity filter list.
guard_name	string	—	Guard 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	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 already have them
embedding-endpoint	endpoint and reference_texts; optionally embedding_model and secret_key_ref
webhook	endpoint; optionally secret_key_ref and webhook_headers
presidio	endpoint; presidio_language is optional because the adapter defaults to en
guardrails-ai	endpoint and guard_name
dynamo-ai	endpoint and policy_id
lakera	secret_key_ref.env; endpoint is optional

Webhook verdict mapping

Webhook providers can return either:

• flagged: true|false
• or a textual verdict / action

Keeptrusts treats these webhook verdicts as blocking: deny, block, blocked, reject, rejected, flagged, and review.

It treats these as allow: allow, none, or flagged: false.

{
  "verdict": "deny",
  "reason": "prompt injection candidate",
  "scores": {
    "prompt_injection": 0.97
  }
}

How It Works

1. The gateway joins the current 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. If the provider errors or times out, fail_closed decides whether the request is blocked or allowed.

Best Practices

• Use secret_key_ref.env instead of inline secrets in YAML.
• Start with a single provider, then layer providers only if you need the extra operational complexity.
• Use fail_closed: true only after you understand provider reliability and timeout behavior.
• 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 injection detection
• PII Detector — Built-in PII detection
• DLP Filter — Custom regex and term controls