Capability
An operation such as read, create, update, delete, list, sudo, or patch.
Chapter contract
Prerequisites:
Chapter 4 complete; know the exact operation and redacted API path being tested.
User-visible outcome:
Priya can diagnose an expected 403 from path and capability evidence instead of requesting broad access.
Learning objectives
- Map an operation to the exact policy path and capability.
- Use token capabilities and audit correlation safely.
- Distinguish 400, 403, and 404 before editing policy.
Consumer flow
Ownership boundary
| Owner | Consumer-facing responsibility |
|---|---|
| You own | Defines consumption, validation, reload, and stop-using behavior. |
| Platform team owns | Provides trusted runtime identity, protected delivery, network, and telemetry. |
| Vault owns | Operates auth mounts, policies, engines, audit, and recovery. |
Core concepts
Path rule
A policy stanza matching API paths, not CLI wording.
Default deny
Anything not explicitly allowed is denied.
Audit correlation
Matching a client failure to server audit metadata by time and request context.
Commands and configuration
source learn-vault/.runtime/learner.env
vault token capabilities lockbox-kv/data/orders-api
vault token capabilities lockbox-kv/metadata/orders-api
vault kv metadata get -format=json lockbox-kv/orders-api | jq '.data.current_version'Secret-safety stop
Stop: Do not solve a 403 by attaching an admin policy. Prove the exact path and capability first.
Failure drill
| Symptom | 403 permission denied on a KV read. |
|---|---|
| Likely causes | Policy covers the friendly path instead of KV v2 data, role mapping is wrong, or list targets the wrong route. |
| Inspect safely | Query capabilities for the exact API path and capture status plus timestamp. |
| Do not print | Token, request payload, secret response, or raw audit record. |
Break it / fix it
Break it: Attempt the intentionally denied KV delete.
Show diagnosis and fix
Fix it: Query capabilities for the exact API path; retain the narrow read policy.
Escalate with time, endpoint, auth path, role, mount, namespace when relevant, status code, request ID, and sanitized error class. Never attach a credential or response body.
Try it
Bootstrap boundary
labs/bootstrap owns the disposable server, auth mounts, policies, roles, and engines; learner actions begin after setup.
Cost:
$0; local containers only
Starting state:
Run labs/bootstrap/setup.sh and source .runtime/learner.env unless the chapter lab says AppRole alone is sufficient.
User actions:
Prove an allowed metadata operation and a denied delete, then inspect the bootstrap policy source.
source learn-vault/.runtime/learner.env
test "$(vault token capabilities lockbox-kv/metadata/orders-api)" = read
if vault kv delete lockbox-kv/orders-api >/dev/null 2>&1; then
echo "unexpected delete permission"; exit 1
else
echo "delete denied as expected"
fi
sed -n '/lockbox-kv\/metadata/,/}/p' learn-vault/labs/bootstrap/policies/lockbox-learner.hclSuccess criteria:
Complete every item in the Verify section using metadata-only evidence; no secret value appears in terminal output or tracked files.
Troubleshooting:
Use the Failure drill and Break it / fix it evidence fields. Stop before broadening policy, weakening identity or TLS checks, or copying secret-bearing diagnostics.
Verify
- Metadata reports read capability.
- Delete is denied and the KV value remains.
- The policy uses the KV v2 metadata route.
Evidence rule: retain only status, policy names, TTLs, versions, timestamps, fingerprints, and error classes. Never retain secret values.
Cleanup
No Vault data changed. Unset VAULT_TOKEN if the shell will be shared.
Project Lockbox increment
The Lockbox access request names exact API paths and capabilities, making review and diagnosis reproducible.
Quick check
What happens when no policy matches?
Deny.
Why can lockbox-kv/orders-api fail?
KV v2 operations include data or metadata path segments.
Where is list granted for KV v2?
On the metadata path.
What belongs in a change request?
Identity role, exact redacted API path, capability, and reason.
Gotchas
- CLI verbs do not map one-to-one to capabilities.
- List paths often need a trailing slash or metadata route.
- A 404 can intentionally conceal existence.
Recap and next
A good 403 investigation narrows the contract; it does not widen policy until the error disappears.