Master Policy Chains with the CLI

Policy chains are the backbone of Keeptrusts gateway enforcement. Every request that passes through the kt gateway is evaluated against an ordered sequence of policies — first in the input phase (before the LLM call), then in the output phase (after the response arrives). This guide shows you how to build, compose, test, and optimize chains for production use.

Use this page when

• You are building or modifying the ordered policy chain in policy-config.yaml.
• You need to understand input/output phases, short-circuit behavior, or chain ordering.
• You want to compose reusable policy fragments with the includes directive.

Primary audience

• Primary: Technical Engineers configuring gateway policy enforcement
• Secondary: Security Engineers reviewing policy coverage, AI Agents generating policy configs

How policy chains work

A policy chain is an ordered list of policy rules evaluated sequentially. Each rule inspects the request or response, and either passes, blocks, redacts, or escalates depending on its configuration.

Request → Input Chain → [pass?] → LLM Provider → Output Chain → [pass?] → Response
              │                                        │
              └─ block/escalate ← 409                  └─ redact/block ← modified response

The gateway evaluates policies in the order they appear in your configuration file. Once a policy triggers a block action, the chain short-circuits — no further policies are evaluated, and a 409 Conflict is returned immediately.

Defining a policy chain

Policy chains live in your policy-config.yaml file. Each policy has a type, an optional phase, and action-specific parameters.

# policy-config.yaml
version: "1"
policies:
  # Input phase — evaluated before the LLM call
  - name: prompt-injection-guard
    type: prompt_injection
    phase: input
    action: block
    threshold: 0.85
    message: "Prompt injection detected — request blocked."

  - name: pii-input-redaction
    type: pii_redaction
    phase: input
    action: redact
    entity_types:
      - email
      - phone_number
      - ssn
    replacement: "[REDACTED]"

  - name: topic-restriction
    type: topic_filter
    phase: input
    action: block
    blocked_topics:
      - weapons
      - illegal_activities

  # Output phase — evaluated after the LLM responds
  - name: output-pii-scan
    type: pii_redaction
    phase: output
    action: redact
    entity_types:
      - credit_card
      - ssn

  - name: disclaimer-injection
    type: disclaimer
    phase: output
    action: append
    text: "AI-generated content. Verify before acting."

Chain ordering and evaluation

The order of policies within each phase matters:

1. Input policies are evaluated top-to-bottom before the upstream call.
2. Output policies are evaluated top-to-bottom after the provider responds.
3. Within each phase, a block action short-circuits the remaining chain.
4. redact and append actions modify the payload but do not stop evaluation.

Short-circuit behavior

When a policy triggers action: block, the gateway:

• Stops evaluating the remaining chain immediately.
• Returns HTTP 409 Conflict with the configured message.
• Records a decision event with outcome: blocked and the triggering policy name.
• Does not forward the request to the LLM provider (input phase) or return the response to the caller (output phase).

Place your most critical safety policies (prompt injection, topic restrictions) first in the input chain to minimize latency on blocked requests.

policies:
  # Fast, critical checks first
  - name: prompt-injection-guard
    type: prompt_injection
    phase: input
    action: block
    threshold: 0.85

  # Slower, enrichment-style checks later
  - name: pii-input-redaction
    type: pii_redaction
    phase: input
    action: redact
    entity_types: [email, phone_number]

Composing reusable chain fragments

For organizations managing multiple gateways or environments, extract common policy groups into separate YAML files and include them via the includes directive.

# fragments/pii-standard.yaml
- name: pii-redaction-standard
  type: pii_redaction
  phase: input
  action: redact
  entity_types:
    - email
    - phone_number
    - ssn
    - credit_card

- name: pii-output-standard
  type: pii_redaction
  phase: output
  action: redact
  entity_types:
    - ssn
    - credit_card

# policy-config.yaml
version: "1"
includes:
  - fragments/pii-standard.yaml
  - fragments/compliance-base.yaml
policies:
  - name: custom-topic-filter
    type: topic_filter
    phase: input
    action: block
    blocked_topics:
      - insider_trading

This pattern lets you maintain a library of vetted policy fragments and compose environment-specific configurations without duplication.

Testing chains with kt policy lint

Before deploying a policy chain, validate the config and run the pack tests that describe the behaviors you expect:

# Validate syntax and schema
kt policy lint --file policy-config.yaml

# Run the local chain tests generated by kt init
kt policy test --json

The validation and test workflow checks:

• YAML syntax and schema conformance.
• Policy names and chain entries are recognized.
• Required parameters are present for each policy block.
• Provider and routing references resolve correctly.
• The tests in tests/ still match the blocking, redaction, and pass-through behavior you expect.

CI pipeline integration

Add chain validation to your CI pipeline to catch policy regressions before deployment:

# .github/workflows/policy-lint.yml
name: Policy Chain Validation
on:
  pull_request:
    paths:
      - 'policies/**'
      - 'policy-config.yaml'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install kt CLI
        run: curl -fsSL https://get.keeptrusts.com | sh
      - name: Validate policy chain
        run: |
          kt policy lint --file policy-config.yaml
          kt policy test --json

Monitoring chain performance

Once deployed, monitor how your chains behave in production:

# Tail live events to see which policies trigger
kt events tail --filter "outcome=blocked"

# View policy-level latency breakdown
kt events tail --format detailed --filter "gateway_id=gw-prod-01"

Each decision event includes the full chain evaluation trace — which policies passed, which triggered, and the latency of each step.

Business outcomes

Outcome	How policy chains help
Prevent data leakage	PII redaction in input and output phases strips sensitive data before it reaches the LLM or the end user
Block prompt injection	Input-phase injection detection stops adversarial prompts before they reach the model
Enforce regulatory compliance	Topic filters block conversations about prohibited subjects (ITAR, insider trading, medical advice)
Reduce incident response time	Short-circuit behavior ensures blocked requests fail fast with clear policy attribution
Standardize across teams	Reusable fragments enforce consistent baselines while allowing team-specific customization

For AI systems

• Canonical terms: policy chain, input phase, output phase, short-circuit, action: block|redact|escalate|append, phase: input|output, includes directive, policy fragments, 409 Conflict.
• Policy types referenced: prompt_injection, pii_redaction, topic_filter, disclaimer.
• Config keys: policies[] array with name, type, phase, action, threshold, entity_types, blocked_topics, text.
• Chain evaluation order: input policies top-to-bottom → LLM call → output policies top-to-bottom; block short-circuits remaining chain.
• Best next pages: Config Validation, Declarative Config Patterns, Live Monitoring.

For engineers

• Place critical safety policies (prompt injection, topic restriction) first in the input chain for fast blocking and minimal latency.
• Use includes: to extract common policy groups into fragment files for reuse across environments.
• Validate chains with kt policy lint --file policy-config.yaml && kt policy test --json before deployment.
• Monitor deployed chains with kt events tail --format detailed to see per-policy evaluation traces.
• A block action returns HTTP 409 and stops chain evaluation; redact and append modify payload but don’t stop.

For leaders

• Policy chains enforce defense-in-depth: multiple rules evaluate sequentially, catching threats that a single rule might miss.
• Short-circuit behavior ensures blocked requests fail fast — no wasted LLM spend on prohibited content.
• Reusable fragments standardize policy baselines across teams while allowing team-specific customization.
• Chain ordering directly impacts latency; placing fast checks first minimizes overhead on high-volume traffic.

Next steps

• Validate & Lint AI Policies Before Deployment — deep-dive into kt policy lint
• Declarative Config Patterns for Enterprise AI — advanced config composition
• Monitor AI Traffic in Real-Time — observe chain behavior in production