verdictan policy lint

verdictan policy lint checks one document before you publish it. In runtime mode, it checks a policy config against the declarative config schema and the cross-field rules of the gateway. In abac mode, it checks the statements of an IAM policy document. The command runs locally and does not call the API.

Validate a gateway configuration

verdictan policy lint --mode runtime --file policy-config.yaml

When the file passes, the command prints nothing and exits with 0. When it fails, it prints one line for each error to standard error, then stops with policy lint failed (<n> error(s)) and exit code 2. Fix the reported fields and run the command again.

To start from a file that passes, run verdictan init. For IAM policy documents, use --mode abac.

Usage

verdictan policy lint [--file <path>] [--mode <auto|runtime|abac>]

Options

Flag	Description
--file <path>	Document to check. The default is policy-config.yaml.
--mode <auto|runtime|abac>	Lint mode. The default is auto.

In auto mode, the command reads the file and selects abac when the top level has a policies array, a statements key, or a Statement key. Otherwise it selects runtime. It parses a .json file as JSON and every other file as YAML.

Examples

# Lint the default policy config, with mode detection
verdictan policy lint

# Lint a policy config in runtime mode
verdictan policy lint --mode runtime --file configs/production.yaml

# Lint an IAM policy bundle
verdictan policy lint --mode abac --file iam-policies.yaml

A minimal policy config that passes runtime lint:

policy-config.yaml

pack:
  name: "my-project"
  version: "0.1.0"
  enabled: true

policies:
  chain:
    - prompt-injection

An IAM policy bundle that passes ABAC lint:

iam-policies.yaml

policies:
  - name: Evidence Reader
    statements:
      - sid: ReadEvents
        effect: allow
        actions: ["events:read"]
        resources: ["vdt:verdictan:events:eu:org_example:events"]

The two-target example in verdictan gateway run also passes runtime lint.

Checks

Runtime mode checks a policy config in this order:

1. The file has a .yaml or .yml extension, and it parses as YAML.
2. The document matches the declarative config schema. The schema rejects top-level keys that it does not define.
3. Cross-field rules: for example, each policies.chain entry is a known policy kind, each policy.<kind> field is a key that the policy reads, removed fields are absent, and references between providers, routes, consumer groups, and tests resolve.

Runtime mode reports all errors together, in sorted order.

ABAC mode accepts one policy object, a list of policies, or a bundle with a policies array. It checks that:

• Each policy has a non-empty name and a statements value.
• Each statement document has at least one statement.
• Each statement uses only sid, effect, actions, resources, and conditions, or their forms Sid, Effect, Action, Resource, and Condition.
• effect is allow or deny, in any letter case.
• Each action is *, a known action, or <namespace>:* for a known namespace.
• Each resource is * or starts with vdt:verdictan:.
• Condition operators and their values have the supported shape.

ABAC mode prefixes each error with the policy name, for example policy "Broken": statement 1 must use effect allow or deny.

Limits and failure behavior

Condition	Result
Runtime mode on a file without a .yaml or .yml extension	Error: policy config must be YAML (expected .yaml or .yml), exit 2.
The file does not exist	Error: failed to read <path>: ..., exit 2.
--mode with another value	The argument parser rejects it with invalid value '<value>' for '--mode <MODE>', exit 2.
An IAM document linted in runtime mode	The schema check fails. Use --mode abac or --mode auto.

• When the document does not match the schema at the top level, runtime lint can report one long error. That error repeats the whole document as JSON and ends with is not valid under any of the schemas listed in the 'oneOf' keyword. Check for unknown top-level keys and misspelled section names.
• Lint checks the document only. It does not resolve provider credentials, run tests, or contact the control plane. Use verdictan gateway check and verdictan policy test for those checks.
• Lint and verdictan config validate apply different rules. For example, lint rejects unknown top-level keys, and config validate accepts them. Run both in CI.
• A pass does not prove correct routing or fallback behavior. See Provider Configuration before you enable more provider targets.

Next steps

• verdictan policy test: run behavior tests against the policy chain.
• verdictan config validate: check that the gateway loads the file, with JSON output for CI.
• Policy Lifecycle: publish and roll out the config after lint.
• Manage Configuration in a File: keep the config in version control.