Vault Secrets Management¶

HashiCorp Vault integration for secure secrets management in RawDigs Core App.

Overview¶

Vault provides centralized secrets management with:

🔐 Encrypted Storage: All secrets encrypted at rest and in transit
🔑 Access Control: Fine-grained policies for secret access
📝 Audit Logging: Complete audit trail of all secret operations
🌍 Multi-Environment: Separate namespaces for dev/staging/prod
🔄 Secret Rotation: Support for dynamic and rotated credentials
💻 Web UI: User-friendly interface at http://localhost:8200

Quick Start¶

1. Start Vault¶

./vendor/bin/sail up -d vault

2. Initialize Vault¶

./scripts/vault-init.sh

This creates: - KV secrets engine at secret/ - Three environments: development, staging, production - Admin policy with full access - Developer policy with read-only production access - Two users: admin (admin-change-me) and developer (dev-change-me) - Audit logging enabled

3. Access Web UI¶

Navigate to http://localhost:8200

Login credentials: - Username: admin - Password: admin-change-me (⚠️ change this immediately!)

Secret Organization¶

Secrets are organized by environment:

secret/
├── development/
│   ├── app              # Application secrets
│   ├── database         # Database credentials
│   └── services         # Third-party service keys
├── staging/
│   ├── app
│   ├── database
│   └── services
└── production/
    ├── app
    ├── database
    └── services

Using Vault¶

Web UI (Recommended)¶

Login: http://localhost:8200 with userpass method
Navigate: Click "secret/" → select environment → select secret
View/Edit: Click secret name to view, "Create new version" to edit
Create: Click "Create secret" button

CLI Commands¶

# Login
docker exec rawdigs-core-app-vault-1 vault login -method=userpass username=admin

# Read a secret
docker exec rawdigs-core-app-vault-1 vault kv get secret/development/app

# Write a secret
docker exec rawdigs-core-app-vault-1 vault kv put secret/development/app \
  APP_KEY="base64:your-key" \
  APP_SECRET="your-secret"

# List secrets in environment
docker exec rawdigs-core-app-vault-1 vault kv list secret/development

# Delete a secret
docker exec rawdigs-core-app-vault-1 vault kv delete secret/development/app

Laravel Integration (Coming Soon)¶

// config/vault.php
return [
    'driver' => 'vault',
    'endpoint' => env('VAULT_ADDR', 'http://vault:8200'),
    'token' => env('VAULT_TOKEN'),
];

// Usage in code
$apiKey = Vault::get('secret/production/services/stripe_key');

Backup & Restore¶

Create Backup¶

# Basic backup
./scripts/vault-backup.sh

# Encrypted backup (recommended for production)
export GPG_RECIPIENT="your-email@example.com"
export ENCRYPT_BACKUP=true
./scripts/vault-backup.sh

Backups are stored in backups/vault/ and include: - All secrets from dev/staging/prod - Policies - Auth methods - Audit device configuration

Restore Backup¶

# Extract backup
cd backups/vault
tar -xzf vault-backup-YYYYMMDD_HHMMSS.tar.gz

# Or for encrypted backups
gpg --decrypt vault-backup-YYYYMMDD_HHMMSS.tar.gz.gpg | tar -xz

# Manually restore secrets using vault CLI or UI

User Management¶

Create New User¶

docker exec rawdigs-core-app-vault-1 vault write auth/userpass/users/john \
  password="secure-password" \
  policies="developer"

Update Password¶

docker exec rawdigs-core-app-vault-1 vault write auth/userpass/users/admin/password \
  password="new-secure-password"

List Users¶

docker exec rawdigs-core-app-vault-1 vault list auth/userpass/users

Access Policies¶

Admin Policy (Full Access)¶

# Full access to all secrets
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

Developer Policy (Read-Only Production)¶

# Full access to dev and staging
path "secret/development/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

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

# Read-only access to production
path "secret/production/*" {
  capabilities = ["read", "list"]
}

Create Custom Policy¶

# Create policy file
cat > my-policy.hcl <<EOF
path "secret/development/myapp/*" {
  capabilities = ["read", "list"]
}
EOF

# Upload policy
docker exec -i rawdigs-core-app-vault-1 vault policy write my-policy - < my-policy.hcl

Production Deployment¶

Security Checklist¶

[ ] Change default admin password
[ ] Change VAULT_ROOT_TOKEN in .env
[ ] Enable TLS/SSL (HTTPS)
[ ] Use external database storage (not file)
[ ] Configure auto-unseal (AWS KMS, Azure Key Vault, etc.)
[ ] Set up regular automated backups
[ ] Enable GPG encryption for backups
[ ] Restrict network access (firewall rules)
[ ] Review and audit policies regularly
[ ] Enable MFA for sensitive operations
[ ] Set up monitoring and alerting

Production Configuration¶

Update docker/vault/config/vault.hcl:

storage "postgresql" {
  connection_url = "postgres://vault:password@db:5432/vault?sslmode=require"
}

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

seal "awskms" {
  region     = "us-east-1"
  kms_key_id = "your-kms-key-id"
}

CI/CD Integration¶

GitHub Actions Example¶

- name: Get secrets from Vault
  run: |
    export VAULT_TOKEN="${{ secrets.VAULT_TOKEN }}"
    docker run --rm \
      -e VAULT_ADDR=https://vault.example.com \
      -e VAULT_TOKEN=$VAULT_TOKEN \
      vault:latest \
      vault kv get -format=json secret/production/app | \
      jq -r '.data.data | to_entries[] | "export \(.key)=\(.value)"' >> $GITHUB_ENV

Troubleshooting¶

Vault is Sealed¶

# Check status
docker exec rawdigs-core-app-vault-1 vault status

# Unseal (requires unseal keys from initialization)
docker exec rawdigs-core-app-vault-1 vault operator unseal

Permission Denied¶

Verify your token has the correct policy attached
Check policy permissions with vault token capabilities
Review audit logs for denied requests

Can't Connect to Vault¶

# Check if container is running
docker ps | grep vault

# Check container logs
docker logs rawdigs-core-app-vault-1

# Verify network connectivity
docker exec rawdigs-core-app-laravel.test-1 curl http://vault:8200/v1/sys/health

Best Practices¶

Never Commit Secrets: Keep secrets in Vault, not in code or .env files
Use Least Privilege: Grant minimum necessary permissions
Rotate Regularly: Change passwords and tokens periodically
Audit Everything: Review audit logs regularly for suspicious activity
Backup Often: Automate daily backups with retention policy
Encrypt Backups: Always use GPG encryption for backup files
Test Restores: Regularly test backup restoration procedures
Document Access: Maintain a record of who has access to what
Use Policies: Define clear policies for different roles/teams
Monitor Usage: Set up alerts for unusual access patterns

Additional Resources¶

Support¶

For issues or questions: 1. Check container logs: docker logs rawdigs-core-app-vault-1 2. Review Vault audit logs in docker/vault/logs/ 3. Consult HashiCorp Vault documentation 4. Contact DevOps team

⚠️ Security Warning: This is a development setup. For production, implement additional security measures including TLS, external storage, auto-unseal, and network isolation.