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 は最優先）
path "secret/data/app/prod/*" {
  capabilities = ["deny"]
}

# 管理操作用（sudo が必要な sys/ 配下）
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/update）
vault kv put secret/app api_key=abc123

# 読み取り（read）
vault kv get secret/app

# 削除（delete）
vault kv delete secret/app

# 一覧（list）: 末尾のスラッシュに注意
vault kv list secret/

# 自分のトークンが特定パスで持つ権限を確認
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

# チームAは team-a/ 配下にフル権限
path "secret/data/team-a/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# ただし本番サブパスは明示拒否
path "secret/data/team-a/prod/*" {
  capabilities = ["deny"]
}

# 一覧だけ許可したい汎用閲覧者
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

# 認証メソッド管理
path "sys/auth/*" {
  capabilities = ["sudo", "create", "read", "update", "delete", "list"]
}

# シークレットエンジン管理
path "sys/mounts/*" {
  capabilities = ["sudo", "create", "read", "update", "delete", "list"]
}

# 認証メソッドの有効化（例）
vault auth enable userpass

# KV エンジンの有効化（例）
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

# 現在ログイン中のトークンでのパス評価
vault token capabilities secret/data/app

# 明示トークンで評価（別トークンを指定）
vault token capabilities s.XXXXXXXX secret/data/app

# API で自己トークンの capabilities を確認
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)

# 閲覧＋一覧のみ
path "secret/data/app/*" {
  capabilities = ["read", "list"]
}

# 管理操作は別ポリシーで限定的に付与
path "sys/auth/userpass" {
  capabilities = ["sudo", "create", "read", "update"]
}

Check Your Understanding

Frequently Asked Questions