# HashiCorp Vault — Secrets Management & Encryption Platform

> Vault is the industry-standard secrets management platform. Store API keys, database credentials, certificates with dynamic secrets, encryption as a service, and fine-grained access control.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Dev mode (not for production)
docker run -d --name vault --cap-add IPC_LOCK 
  -p 8200:8200 
  -e VAULT_DEV_ROOT_TOKEN_ID=my-root-token 
  -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 
  hashicorp/vault:latest
```

Open `http://localhost:8200` — login with your root token.

## Intro

**HashiCorp Vault** is the industry-standard secrets management platform for storing, accessing, and distributing sensitive data like API keys, passwords, certificates, and encryption keys. It provides a unified interface to any secret while providing tight access control, detailed audit logs, and advanced features like dynamic secrets and encryption as a service.

With 35.4K+ GitHub stars, Vault is used by enterprises and startups worldwide to eliminate hard-coded credentials, rotate secrets automatically, and ensure compliance with security standards.

## What Vault Does

- **Secret Storage**: Securely store static secrets (API keys, passwords) with versioning
- **Dynamic Secrets**: Generate short-lived credentials on-demand for databases, AWS, etc.
- **Encryption as a Service**: Encrypt/decrypt data without storing encryption keys in your app
- **Certificate Management**: PKI for issuing TLS certificates and managing cert lifecycles
- **Identity-Based Access**: Integrate with LDAP, AD, OIDC, Kubernetes, AWS IAM for auth
- **Audit Logging**: Detailed audit trail of every secret access
- **Secret Rotation**: Automatic rotation of database passwords and cloud credentials
- **Token-Based Auth**: Time-limited, scoped access tokens
- **Policy-Based Access**: Fine-grained permissions via HCL policies
- **Namespaces**: Multi-tenant secret isolation (Enterprise)

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Applications │────▶│  Vault       │────▶│  Storage     │
│ (Auth Method)│     │  Server      │     │  Backend     │
└──────────────┘     │  (Go)        │     │  (Raft/S3/   │
                     └──────┬───────┘     │  Consul/etc) │
                            │             └──────────────┘
                     ┌──────┴───────┐
                     │  Secret      │
                     │  Engines     │
                     │  (KV/DB/PKI) │
                     └──────────────┘
```

## Self-Hosting

### Docker Compose (Production)

```yaml
services:
  vault:
    image: hashicorp/vault:latest
    ports:
      - "8200:8200"
    cap_add:
      - IPC_LOCK
    volumes:
      - ./config:/vault/config
      - vault-data:/vault/data
      - vault-logs:/vault/logs
    command: server
    environment:
      VAULT_ADDR: http://127.0.0.1:8200
      VAULT_API_ADDR: http://127.0.0.1:8200

volumes:
  vault-data:
  vault-logs:
```

### Config File

```hcl
# config/vault.hcl
ui = true

storage "raft" {
  path    = "/vault/data"
  node_id = "node1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = 0
  tls_cert_file = "/vault/config/cert.pem"
  tls_key_file  = "/vault/config/key.pem"
}

api_addr     = "https://vault.yourdomain.com:8200"
cluster_addr = "https://vault.yourdomain.com:8201"
```

### Initialization

```bash
# Initialize (only once)
vault operator init
# Outputs:
# Unseal Key 1: xxxxx
# Unseal Key 2: xxxxx
# Unseal Key 3: xxxxx
# Unseal Key 4: xxxxx
# Unseal Key 5: xxxxx
# Initial Root Token: s.xxxxxxxxx

# Unseal (need 3 of 5 keys)
vault operator unseal key1
vault operator unseal key2
vault operator unseal key3

# Login with root token
vault login
```

## Key Features

### KV (Key-Value) Secrets

```bash
# Enable KV v2 engine
vault secrets enable -path=secret kv-v2

# Write secret
vault kv put secret/myapp/db 
  username=admin 
  password=super-secret 
  host=db.example.com

# Read secret
vault kv get secret/myapp/db

# Get specific version
vault kv get -version=2 secret/myapp/db
```

### Dynamic Database Credentials

```bash
# Configure database secrets engine
vault secrets enable database

vault write database/config/my-postgres 
  plugin_name=postgresql-database-plugin 
  allowed_roles="readonly" 
  connection_url="postgresql://{{username}}:{{password}}@postgres:5432/mydb" 
  username="vaultuser" 
  password="vaultpass"

# Create role that generates temporary credentials
vault write database/roles/readonly 
  db_name=my-postgres 
  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"

# Get temporary credentials
vault read database/creds/readonly
# Returns: username, password, lease_id, ttl=1h
```

Now your app gets fresh credentials every hour, eliminating static passwords.

### Encryption as a Service

```bash
# Enable transit engine
vault secrets enable transit
vault write -f transit/keys/myapp

# Encrypt data (app never sees the key)
vault write transit/encrypt/myapp plaintext=$(echo "sensitive data" | base64)
# Returns: vault:v1:encrypted-blob

# Decrypt data
vault write transit/decrypt/myapp ciphertext="vault:v1:encrypted-blob"
# Returns: decoded plaintext
```

Your app can encrypt data without ever touching encryption keys.

### Authentication Methods

```bash
# Enable Kubernetes auth
vault auth enable kubernetes

vault write auth/kubernetes/config 
  kubernetes_host="https://kubernetes.default.svc" 
  kubernetes_ca_cert=@/var/run/secrets/kubernetes.io/serviceaccount/ca.crt

# Allow specific Kubernetes service account to access secrets
vault write auth/kubernetes/role/myapp 
  bound_service_account_names=myapp 
  bound_service_account_namespaces=default 
  policies=myapp-policy 
  ttl=1h
```

Supported auth methods:
- Tokens (default)
- Kubernetes (service accounts)
- AWS IAM / EC2
- LDAP / Active Directory
- OIDC / OAuth
- JWT
- GitHub
- Username/Password

### Policies

```hcl
# myapp-policy.hcl
path "secret/data/myapp/*" {
  capabilities = ["read", "list"]
}

path "database/creds/myapp-readonly" {
  capabilities = ["read"]
}

path "transit/encrypt/myapp" {
  capabilities = ["update"]
}
```

```bash
vault policy write myapp-policy myapp-policy.hcl
```

## Vault vs Alternatives

| Feature | Vault | AWS Secrets Manager | Infisical | Doppler |
|---------|-------|-------------------|-----------|---------|
| Open Source | BSL | No | Yes | No |
| Self-hosted | Yes | No | Yes | No |
| Dynamic secrets | Yes | Limited | Yes | No |
| Encryption service | Yes | KMS | Basic | No |
| PKI | Yes | Limited | No | No |
| Multi-cloud | Yes | AWS only | Yes | Yes |
| Secret rotation | Yes | Yes | Yes | Yes |

## FAQ

**Q: Is Vault's learning curve steep?**
A: Relatively steep. Vault is powerful but has many concepts (seal/unseal, policies, auth methods, secret engines). Start with KV storage, then gradually learn dynamic secrets and advanced features. The official docs and tutorials are excellent.

**Q: How do I avoid manual unseal in production?**
A: Use the auto-unseal configuration. You can use AWS KMS, Azure Key Vault, GCP KMS, or the Transit engine (another Vault instance) as the unseal key store, enabling automatic unseal after service restarts.

**Q: What if I lose the keys?**
A: If you lose enough unseal keys (default is 3-of-5), a sealed Vault cannot be recovered. Always distribute unseal keys among different people or store them in different locations, and periodically rehearse the recovery process.

## Sources & Credits

- GitHub: [hashicorp/vault](https://github.com/hashicorp/vault) — 35.4K+ ⭐ | BSL
- Website: [vaultproject.io](https://vaultproject.io)

---
Source: https://tokrepo.com/en/workflows/hashicorp-vault-secrets-management-encryption-platform-d359a6e1
Author: HashiCorp