Policy Lifecycle

verdictan policy manages two different kinds of policy, with different commands for each. A policy config controls what a gateway does with model requests. An IAM policy document controls who can do what in Verdictan itself.

Document	What it holds	Commands
Policy config	Provider routing, policy chain, runtime behavior, and tests, in policy-config.yaml	lint, test, push, deploy
IAM policy document	allow and deny statements on actions and resource VDTs	lint, diff, apply, evaluate, export

verdictan policy lint --mode auto detects which kind a file is. The other commands don't: never apply a policy config or push an IAM document.

Before you start

• Set VERDICTAN_API_TOKEN, or sign in with verdictan auth login.
• Link the target gateway to an agent.
• Grant gateways:read, agents:read, and agents:deploy for the target resources.
• Grant gateways:admin to create a configuration, or gateways:deploy to add a version to an existing configuration.
• For IAM documents, use a role with permission to read and change IAM policies.

Configuration targeting rules can require additional permissions for the resources named in the YAML file.

Deploy a policy config

Use CLI 0.1.14 or later for this procedure.

verdictan policy push validates your file, saves a configuration version, and updates the deployment for the gateway's agent. The command uses the existing agent deployment API. It does not confirm that a gateway has applied the version.

1. Check your local config:

   verdictan config validate --file policy-config.yaml
   verdictan policy lint --mode runtime --file policy-config.yaml
   verdictan policy test --pack-dir .
   verdictan gateway check --config policy-config.yaml

2. Copy your test gateway's ID from Gateways in the Console.

3. Push the file:

   verdictan policy push \
     --file policy-config.yaml \
     --gateway-id "$GATEWAY_ID" \
     --change-detail "Enable reviewed DLP chain"

The gateway must have one linked agent. If it has several agents, add --agent <agent-name-or-id> to select one. If no agent is linked, link an agent before you push.

The command updates the agent-wide deployment record. With --gateway-id, it assigns the version only to that linked gateway. Other linked gateways keep their assigned version. With --agent alone, it assigns the version to all gateways linked to that agent.

The command uses the agent's current configuration when one exists. Otherwise, it finds or creates a configuration with the agent's name. Use --configuration to select a different configuration by name or ID.

Flag	Meaning
--file <path>	The config file. Default: policy-config.yaml.
--gateway-id <id>	Select one linked gateway for the rollout. Required unless you supply --agent.
--agent <name-or-id>	Select an agent. With no gateway ID, update all its linked gateways.
--configuration <name-or-id>	Select an existing configuration, or create one with this name.
--change-detail <text>	Store a description with the version and deployment.
--json	Print the status, agent, configuration, version, and rollout gateway IDs as JSON.
--legacy-gateway-version	Save a gateway-scoped version with the previous behavior. This does not update a connected gateway.

The command also accepts --config, --api-url, and --profile.

If the content and target assignment already match, the command returns unchanged without writing a new version or deployment. An existing version with matching content is reused.

Verify the rollout

Connected gateways pull their assigned configuration at startup and about every 30 seconds.

With gateway 0.1.14 or later, open Gateways and check Sync for each target. Wait for In sync. See Verify the deployment for the other states and their reporting periods. This check compares configuration reports. Send the test request below to verify the rule itself.

1. Keep the gateway running.
2. Wait up to about 30 seconds for the next pull.
3. Look for connected read model refresh applied updated config in the gateway log.
4. Record the new config_sha256 from the log. The gateway reports the complete runtime config hash.
5. Send a test request that exercises your changed rule.
6. Check the response and recorded decision.

A successful push confirms the API assignment. It does not prove that the gateway has applied the config. An unchanged result also refers to the API assignment.

To update another gateway linked to the same agent, repeat the push with that gateway's ID. The command can reuse the saved version.

Previous gateway-scoped commands

verdictan policy push --legacy-gateway-version --gateway-id <id> only saves a gateway-scoped version and changes its current pointer. Connected gateways do not read that saved version. The command prints a warning.

verdictan policy deploy uses the older gateway-scoped rollout API. Do not use it to publish a configuration to a connected agent. Use policy push through the agent, or deploy from Configurations in the Console.

Reconcile IAM policy documents

An IAM policy file holds one policy or a bundle. Each policy has statements with an allow or deny effect, action patterns, resource VDT patterns, and optional conditions. The workflow is: export a baseline, preview the change, test a decision, then apply.

1. Export what's live now, as a baseline you can review and roll back to:

   verdictan policy export --file iam-policies.yaml
   verdictan policy export --file evidence-policies.yaml --name "Evidence Reader" --format yaml

   Flag	Meaning
   --file <path>	The destination file. Required.
   --format <yaml|json>	Output format. Defaults to the file extension.
   --policy-id <id>, --name <name>	Export only these policies; repeat for more. Without them, everything is exported.

2. Lint your edited file and preview the changes:

   verdictan policy lint --mode abac --file iam-policies.yaml
   verdictan policy diff --file iam-policies.yaml

   diff compares the file with the live policies and prints a plan without changing anything. Without --prune, remote policies missing from the file are left alone.

   Flag	Meaning
   --file <path>	The policy document or bundle. Required.
   --prune	Also plan deletion of remote policies that aren't in the file.
   --json	Print the plan as JSON.

3. Test a decision against your file:

   verdictan policy evaluate \
     --file iam-policies.yaml \
     --action events:read \
     --resource-vrn 'vdt:verdictan:events:eu:org_example:events'

   evaluate asks the control plane's simulator about policy logic only. It doesn't account for the caller's authentication, role assignments, or real resource context.

   Flag	Meaning
   --action <action>	The action to test. Required.
   --resource-vrn <vdt>	The resource VDT to test. Required.
   --file <path>	Test the statements in a local file.
   --policy-id <id>, --name <name>	Test remote policies instead; repeat for more. Don't combine with --file.
   --caller-attrs <json>, --resource-attrs <json>, --request-attrs <json>	Attributes for the simulator.
   --json	Print the simulator response as JSON.

4. Apply the reviewed changes:

   verdictan policy apply --file iam-policies.yaml

   In a terminal, apply prints the plan and asks for confirmation. It computes a fresh plan from live state, so in automation save diff --json output, review it, and then run apply --yes --json.

   Flag	Meaning
   --file <path>	The policy document or bundle. Required.
   --prune	Delete remote policies that aren't in the file. Run diff --prune first and review each deletion.
   --yes	Skip the confirmation prompt.
   --json	Print the plan and result as JSON, without a prompt.

The IAM commands also accept --config, --api-url, --profile, and --region.

warning

A deny statement or a wildcard resource can change access for many people at once. Keep IAM documents in their own path, use stable policy names and statement IDs, and grant only what's needed.

Verify the reconciliation

1. With --json, check that applied is true and failed is empty. JSON mode exits 0 even when individual operations fail.
2. Run verdictan policy diff --file iam-policies.yaml again. The plan should be empty.
3. Run verdictan policy evaluate for one action you expect to be allowed and one you expect to be denied.

Troubleshooting

Symptom	Cause	Fix
push reports several linked agents	The gateway has more than one agent	Add --agent <agent-id> to select the intended agent.
push returns unchanged	The saved content and selected gateway assignments match	Check the gateway log and send a test request to verify runtime behavior.
apply prints aborted — no changes applied	The prompt got an answer other than yes	Review the plan and run it again.
apply --json exits 0 but failed has entries	JSON mode reports failures only in the result	Fix each failed entry and apply again.
apply removed policies you wanted	--prune deletes remote policies missing from the file	Export a baseline before any prune, and review diff --prune first.

Next steps

• verdictan policy lint: lint rules for each document kind.
• verdictan policy test: write tests to run before a push.
• IAM, Members, Teams, and Roles: attach IAM policies to roles.
• verdictan control: manage IAM policies with other control-plane resources in one manifest.