HashiCorp Vault Compatibility

WSB is designed for OpenBao but is fully compatible with HashiCorp Vault. The API surface used by WSB (KV v2, Database Secrets Engine, Transit Engine) is identical between OpenBao and Vault.

Configuration

Set WSB_BACKEND_TYPE=vault to use Vault. The connector is the same as openbao — only the label differs (for audit trail clarity).

Environment Variables

Variable	Default	Description
WSB_BACKEND_TYPE	env	Set to vault for Vault KV v2, database for Database Secrets Engine
WSB_VAULT_ENDPOINT	—	Vault server URL (e.g., https://vault.example.com:8200)
WSB_VAULT_TOKEN	—	Vault authentication token
WSB_VAULT_MOUNT	secret	KV v2 mount path
WSB_VAULT_DATABASE_MOUNT	database	Database Secrets Engine mount path
WSB_TRANSIT_MOUNT	transit	Transit Secrets Engine mount path
WSB_TRANSIT_ENABLED	false	Enable Transit encrypt/decrypt endpoints

KV v2 (Static Secrets)

export WSB_BACKEND_TYPE=vault
export WSB_VAULT_ENDPOINT=https://vault.example.com:8200
export WSB_VAULT_TOKEN=hvs.your-token-here
export WSB_VAULT_MOUNT=secret

WSB reads secrets via GET /v1/{mount}/data/{path} — the standard Vault KV v2 API.

Database Secrets Engine (Dynamic Credentials)

export WSB_BACKEND_TYPE=database
export WSB_VAULT_ENDPOINT=https://vault.example.com:8200
export WSB_VAULT_TOKEN=hvs.your-token-here
export WSB_VAULT_DATABASE_MOUNT=database

WSB generates dynamic credentials via GET /v1/{mount}/creds/{role} and automatically renews leases at 2/3 TTL via PUT /v1/sys/leases/renew.

Vault setup (one-time):

# Enable the database secrets engine
vault secrets enable database

# Configure the database connection
vault write database/config/mydb \
    plugin_name=postgresql-database-plugin \
    connection_url="postgresql://{{username}}:{{password}}@db.example.com:5432/mydb" \
    allowed_roles="readonly,readwrite" \
    username="vault_admin" \
    password="vault_password"

# Create a role
vault write database/roles/readonly \
    db_name=mydb \
    creation_statements="CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}'; GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" \
    default_ttl="1h" \
    max_ttl="24h"

Agents request secrets by role name (e.g., secret_ref: "readonly"). WSB generates a temporary username/password pair with automatic lease management.

Transit Secrets Engine (Encryption-as-a-Service)

export WSB_TRANSIT_ENABLED=true
export WSB_TRANSIT_MOUNT=transit

Transit does not expose secrets — data never leaves WSB unencrypted. Agents call WSB's transit endpoints, and WSB proxies to Vault's Transit engine.

Vault setup (one-time):

# Enable the transit secrets engine
vault secrets enable transit

# Create an encryption key
vault write -f transit/keys/my-key

# Optionally configure key type
vault write transit/keys/my-key type=aes256-gcm96

WSB Transit API:

# Encrypt
curl -X POST http://localhost:8082/v1/transit/encrypt \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent-v1",
    "key_name": "my-key",
    "plaintext": "sensitive data"
  }'

# Decrypt
curl -X POST http://localhost:8082/v1/transit/decrypt \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-agent-v1",
    "key_name": "my-key",
    "ciphertext": "vault:v1:..."
  }'

Both operations are authorized via APDP Cedar policies using tool: "transit.encrypt" or tool: "transit.decrypt" with resource: "{key_name}".

Enforcement Modes

WSB supports three enforcement modes, all compatible with Vault:

Mode	Variable	Behavior
Observe	WSB_ENFORCEMENT_MODE=observe	Log all access, block nothing. Ideal for initial rollout.
Soft Enforce	WSB_ENFORCEMENT_MODE=soft_enforce	Block known violations, allow unknown tools with warnings.
Full Enforce	WSB_ENFORCEMENT_MODE=full_enforce	Block all unauthorized access. Production mode.

Start with observe mode to understand agent access patterns before enforcing.

Authentication

WSB uses token-based authentication with Vault. For production deployments, consider:

• AppRole auth: Generate tokens via vault write auth/approle/login role_id=... secret_id=...
• Kubernetes auth: Use vault write auth/kubernetes/login role=wsb jwt=... for K8s deployments
• Token renewal: Ensure the token has a sufficient TTL or configure automatic renewal

WSB does not manage Vault token lifecycle — provide a valid token via WSB_VAULT_TOKEN.

API Compatibility

WSB uses these Vault HTTP API endpoints:

Engine	Endpoint	Method
KV v2	/v1/{mount}/data/{path}	GET
KV v2 (list)	/v1/{mount}/metadata/	LIST
KV v2 (health)	/v1/sys/health	GET
Database	/v1/{mount}/creds/{role}	GET
Database (list)	/v1/{mount}/roles	LIST
Database (check)	/v1/{mount}/roles/{role}	GET
Transit (encrypt)	/v1/{mount}/encrypt/{key}	POST
Transit (decrypt)	/v1/{mount}/decrypt/{key}	POST
Leases (renew)	/v1/sys/leases/renew	PUT

These endpoints are stable across Vault 1.x and OpenBao 2.x.