Vault Capabilities: CRUD+LIST and Real-World Policy Design

Vault access control is decided by the Capabilities you grant inside a policy. It looks like plain CRUD on the surface, but it actually has its own rules around evaluation order and sudo protection, and shows up constantly in both the exam and real-world work.

Based on the official documentation, this article covers create/read/update/delete/list/sudo/deny end-to-end: least-privilege design, wildcard usage, and verification commands.

Vault ACL Capabilities Overview

Vault policies define permissions by granting Capabilities per path. The main ones are create, read, update, delete, list, sudo, and deny. Evaluation sums the capabilities from all matching policies, and if even one deny is present, the request is unconditionally rejected.

sudo is a privileged capability required for certain administrative endpoints (such as those under sys/) that ordinary read/write cannot reach. list is a dedicated listing capability and is separate from read.

• create: allows writes that correspond to new resource creation
• read: allows reading a value
• update: allows updating existing values and various write operations (some implementations require it together with create)
• delete: allows delete operations
• list: allows enumerating key names and paths (cannot be substituted by read)
• sudo: allows operations on sudo-protected endpoints such as sys/ (must be paired with create/update/read as needed)

Capability evaluation flow (simplified)

Least-privilege policy example (HCL)

path "secret/data/app/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# Deny a specific subpath explicitly (deny always wins)
path "secret/data/app/prod/*" {
  capabilities = ["deny"]
}

# For administrative operations (under sys/, needs sudo)
path "sys/auth/*" {
  capabilities = ["sudo", "create", "read", "update", "delete", "list"]
}

CRUD + LIST: Practical Usage Patterns

The biggest gotcha is that listing uses list and reading uses read, and the two are separate. Having read does not let you list paths, and having only list does not let you read values.

Write operations may split between create and update depending on the implementation. Check the target backend's requirements at design time, and when in doubt, grant create and update as a set. Deletion requires delete.

• Read-only: grant read only (do not include list)
• Browse and list: grant both read and list
• Full write: grant create and update together (add delete as needed)
• Least privilege: keep paths as narrow as possible and use deny to reject explicitly

Typical CLI operations and required permissions

# Create and update
vault kv put secret/app api_key=abc123

# Read
vault kv get secret/app

# Delete
vault kv delete secret/app

# List: mind the trailing slash
vault kv list secret/

# Check what your own token can do on a given path
vault token capabilities secret/data/app

Path Specification and Wildcard Design

Vault policies are evaluated per path, and when multiple path blocks match, the capabilities are summed. The longest match wins, but deny always takes top priority and rejects the request.

Combine broad wildcards with narrow exception rules (such as deny) to balance team-level delegation with blocking sensitive subpaths.

• Leverage longest match to override exception paths
• Set prefixes per team or per application
• deny is powerful; watch out for unintended denials in test environments
• Split list-only and read-only policies and grant them separately

Combining wildcards with exception rules

# Team A gets full rights under team-a/
path "secret/data/team-a/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# But the production subpath is denied explicitly
path "secret/data/team-a/prod/*" {
  capabilities = ["deny"]
}

# A general viewer who should only be able to list
path "secret/data/*" {
  capabilities = ["list"]
}

Operations Involving sys/ and sudo

Administrative operations such as enabling/disabling secret engines and auth methods run against endpoints under sys/ and require sudo. sudo alone is not enough — pair it with create/update/read/delete according to the target operation.

For operator policies, grant sudo only on the narrow sys/ paths covering the operator's scope, and use it with the shortest-lived tokens possible for safety.

• Enable secret engine: sys/mounts/* (sudo + create)
• Enable auth method: sys/auth/* (sudo + create)
• Configuration change / disable: sudo + update/delete on the relevant sys/ path
• Avoid mistakes: do not grant sudo broadly via wildcards

Operator policy and execution example

# Managing auth methods
path "sys/auth/*" {
  capabilities = ["sudo", "create", "read", "update", "delete", "list"]
}

# Managing secrets engines
path "sys/mounts/*" {
  capabilities = ["sudo", "create", "read", "update", "delete", "list"]
}

# Enable an auth method (example)
vault auth enable userpass

# Enable the KV engine (example)
vault secrets enable -path=secret kv

Permission Verification and Troubleshooting

When permissions are not working as expected, start by checking your own token's capabilities. Use the CLI vault token capabilities command or the sys/capabilities-self API to get the evaluation result instantly.

To avoid information leakage, Vault sometimes returns 404 when permissions are insufficient. Because this makes it hard to distinguish missing resources from missing permissions, checking capabilities directly is the most effective approach.

• Use capabilities-self to verify the evaluation for the current token
• Treat 404 as a possible permission gap and revisit the policy immediately
• Check whether a deny is mixed in anywhere, starting from the longest paths
• Be mindful of how longest match wins and verify exception paths first

Verification command examples

# Evaluate the path for the token you are logged in with
vault token capabilities secret/data/app

# Evaluate for a specific token instead
vault token capabilities s.XXXXXXXX secret/data/app

# Check the capabilities of your own token over the API
curl \
  --header "X-Vault-Token: $VAULT_TOKEN" \
  --request POST \
  --data '{"paths":["secret/data/app"]}' \
  $VAULT_ADDR/v1/sys/capabilities-self

Associate Exam Checkpoints

list and read are separate; listing always requires list. deny always takes top priority — even a single occurrence anywhere rejects the request. sudo is required for administrative paths like sys/ and must be granted together with create/update etc., not alone.

Wildcards, longest match, summing across multiple policies, and verification via capabilities-self are recurring exam themes. Follow least privilege by keeping paths narrow, and override exceptions with deny or with more specific paths.

• list for enumeration, read for data retrieval; grant both if both are needed
• deny has top priority — during debugging, first check whether a deny exists
• sudo is for administrative operations — do not over-broaden the target sys/ path
• Granting create and update as a set is the safe default (absorbs implementation differences)
• Use capabilities-self and token capabilities for instant verification

Minimal verification policy (smallest example aligned to the checklist)

# Read plus list only
path "secret/data/app/*" {
  capabilities = ["read", "list"]
}

# Grant administrative operations narrowly, via a separate policy
path "sys/auth/userpass" {
  capabilities = ["sudo", "create", "read", "update"]
}

Check Your Understanding

Frequently Asked Questions