Skip to content

USAGE.md

Latest commit

 

History

History
519 lines (369 loc) · 9.56 KB

USAGE.md

File metadata and controls

519 lines (369 loc) · 9.56 KB

Usage Guide

This guide provides step-by-step instructions for using the asr tool.

Table of Contents

  1. Initial Setup
  2. Basic Workflow
  3. Advanced Usage
  4. CI/CD Integration
  5. Common Scenarios

Initial Setup

1. Install the Tool

Quick install (recommended):

curl -fsSL https://raw.githubusercontent.com/kelleyblackmore/Automatic-Secret-Rotation/main/install.sh | bash

Or build from source:

git clone https://github.com/kelleyblackmore/Automatic-Secret-Rotation.git
cd Automatic-Secret-Rotation
cargo build --release
sudo cp target/release/asr /usr/local/bin/

Or use the Makefile:

git clone https://github.com/kelleyblackmore/Automatic-Secret-Rotation.git
cd Automatic-Secret-Rotation
make install

2. Set Up HashiCorp Vault

If you don't have Vault set up yet:

# Start Vault in dev mode (for testing only)
vault server -dev

# In another terminal, set environment variables
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='your-dev-token'

# Enable KV v2 secrets engine
vault secrets enable -version=2 -path=secret kv

3. Create Configuration

Generate a sample configuration:

asr init

Edit rotator-config.toml with your Vault details.

4. Create Initial Secrets

Create some test secrets in Vault:

# Using vault CLI
vault kv put secret/app/database password=initial-password-123

# Or using asr
# (Note: write command would need to be added - for now use vault CLI)

Basic Workflow

Step 1: Flag Secrets for Rotation

Mark which secrets should be automatically rotated:

# Flag with default 6-month period
asr flag app/database

# Flag with custom 3-month period
asr flag app/api-key --period 3

# Flag multiple secrets
asr flag app/smtp-password --period 6
asr flag app/oauth-secret --period 12

Step 2: Check Rotation Status

See which secrets need rotation:

asr scan

Output:

Secrets needing rotation:
  - app/database
  - app/api-key

Step 3: Rotate Secrets

Manual Rotation

Step 3: Rotate Secrets

Manual Rotation

Rotate a specific secret:

asr rotate app/database

Output:

Successfully rotated secret at: app/database
New secret value: aB3$xY9*...

Automatic Rotation

Rotate all secrets that are due:

# Dry run first
asr auto --dry-run

# Perform rotation
asr auto

# Rotate and update environment variables
asr auto --update-env

Step 4: Password Generation & Environment Management

Generate New Password

Create a new password and store it in Vault:

# Just generate and store
asr gen-password myapp/database

# Generate and update environment variable
asr gen-password --env-var DB_PASSWORD myapp/database

# Custom length
asr gen-password --env-var API_KEY --length 48 myapp/api

Sync Vault to Environment

Update your local environment with secrets from Vault:

# Update environment variable
asr update-env --env-var DB_PASSWORD myapp/database

# Custom key name
asr update-env --env-var TOKEN --key token myapp/github

# Reload shell to apply changes
source ~/.bashrc

Advanced Usage

Using Configuration Files

Create different configs for different environments:

# Development
asr -c config-dev.toml scan

# Production
asr -c config-prod.toml auto

Using Environment Variables

Skip the config file entirely:

export VAULT_ADDR="https://vault.company.com:8200"
export VAULT_TOKEN="hvs.your-token"
export VAULT_MOUNT="secret"

asr scan

Override Config with CLI

Override specific values:

asr \
  --vault-addr https://vault.company.com:8200 \
  --vault-token hvs.token \
  --vault-mount secret \
  scan

Reading Secrets

View secret contents:

asr read app/database

Output:

Secret data:
  password: current-password-value

Listing Secrets

List all secrets in a path:

# List root
asr list

# List specific path
asr list app/

CI/CD Integration

GitHub Actions

  1. Add secrets to your GitHub repository:

    • VAULT_ADDR: Your Vault server URL
    • VAULT_TOKEN: Your Vault token

  2. Create .github/workflows/rotate-secrets.yml:

name: Rotate Secrets
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly

jobs:
  rotate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Install tool
        run: cargo install --path .
      - name: Rotate
        env:
          VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
          VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }}
        run: asr auto

GitLab CI

Add to .gitlab-ci.yml:

rotate-secrets:
  stage: maintenance
  image: rust:latest
  only:
    - schedules
  before_script:
    - cargo install --path .
  script:
    - asr auto
  variables:
    VAULT_ADDR: $VAULT_ADDR
    VAULT_TOKEN: $VAULT_TOKEN

Jenkins

Create a Jenkins Pipeline job with this Jenkinsfile:

pipeline {
    agent any
    triggers {
        cron('0 0 * * 0')
    }
    environment {
        VAULT_ADDR = credentials('vault-addr')
        VAULT_TOKEN = credentials('vault-token')
    }
    stages {
        stage('Rotate') {
            steps {
                sh 'cargo install --path .'
                sh 'asr auto'
            }
        }
    }
}

Common Scenarios

Scenario 1: First-Time Setup

You have existing secrets and want to start rotating them:

# 1. Flag all your secrets
asr flag app/db-password --period 6
asr flag app/api-key --period 3
asr flag app/jwt-secret --period 6

# 2. Verify they're flagged
asr scan

# 3. Initial rotation (if needed)
asr rotate app/db-password

# 4. Set up automation (GitHub Actions, etc.)

Scenario 2: Regular Maintenance

Weekly automated rotation check:

#!/bin/bash
# Weekly cron job

# Check what needs rotation
echo "Checking for secrets needing rotation..."
asr scan

# Rotate if needed
echo "Performing automatic rotation..."
asr auto

Scenario 3: Emergency Rotation

A secret was compromised and needs immediate rotation:

# Rotate immediately
asr rotate app/compromised-secret

# Update the secret in your application
# (Application-specific steps)

# Verify rotation
asr read app/compromised-secret

Scenario 4: Bulk Flagging

Flag all secrets in a namespace:

# List all secrets
asr list app/

# Flag them (you'll need to do this for each)
for secret in $(vault kv list -format=json secret/metadata/app/ | jq -r '.[]'); do
  asr flag "app/${secret}" --period 6
done

Scenario 5: Different Rotation Periods

Different types of secrets need different rotation periods:

# Critical secrets: 1 month
asr flag critical/root-password --period 1
asr flag critical/master-key --period 1

# Normal secrets: 6 months
asr flag app/db-password --period 6
asr flag app/api-key --period 6

# Low-priority secrets: 12 months
asr flag dev/test-token --period 12

Scenario 6: Testing Before Production

Test rotation with dry-run:

# See what would be rotated
asr auto --dry-run

# If looks good, proceed
asr auto

Scenario 7: Environment Variable Automation

Automatically sync secrets to your development environment:

# Generate a new database password and update env var
asr gen-password --env-var DB_PASSWORD myapp/database

# Rotate secrets and update all environment variables
asr auto --update-env

# Reload shell
source ~/.bashrc

# Your app can now use the env vars
echo $DB_PASSWORD
echo $MYAPP_DATABASE  # Auto-named from path

Scenario 8: Password Management Workflow

Complete workflow for managing passwords with environment integration:

# 1. Generate initial password
asr gen-password --env-var APP_SECRET --length 32 myapp/secret

# 2. Flag for rotation every 3 months
asr flag myapp/secret --period 3

# 3. Later, when it needs rotation (or manually)
asr rotate myapp/secret

# 4. Update environment variable with new value
asr update-env --env-var APP_SECRET myapp/secret

# 5. Or do both in one step during auto-rotation
asr auto --update-env

Troubleshooting

Issue: "Failed to connect to Vault"

Solution:

# Check Vault is running
vault status

# Verify VAULT_ADDR
echo $VAULT_ADDR

# Test connection
curl $VAULT_ADDR/v1/sys/health

Issue: "Permission denied"

Solution:

# Check your token capabilities
vault token capabilities secret/data/app/database

# Should show: ["create", "read", "update"]

Issue: "Secret not found"

Solution:

# List secrets to find the correct path
asr list

# Or use vault CLI
vault kv list secret/

Issue: "Metadata update failed"

Solution:

# Ensure you're using KV v2 (not v1)
vault secrets list

# Should show version 2 for your mount

Best Practices

  1. Start with Dry Runs: Always test with --dry-run first
  2. Monitor Logs: Enable verbose logging with RUST_LOG=debug
  3. Backup First: Back up secrets before rotation
  4. Test in Dev: Test rotation in development environment first
  5. Gradual Rollout: Start with non-critical secrets
  6. Document Secret Usage: Know which applications use which secrets
  7. Coordinate Rotations: Plan rotations during maintenance windows
  8. Use Appropriate Periods: Balance security with operational overhead

Next Steps

  • Set up monitoring for rotation failures
  • Create alerting for secrets approaching rotation
  • Integrate with secret distribution to applications
  • Implement automated testing of rotated secrets