DEV Community

ANKUSH CHOUDHARY JOHAL
ANKUSH CHOUDHARY JOHAL

Posted on • Originally published at johal.in

Supercharge secrets management Gitleaks for Vault: A Practical Guide

#supercharge #secrets #management #gitleaks

Supercharge Secrets Management: Gitleaks for Vault Practical Guide

Secrets management is a critical pillar of modern DevOps security. Hardcoded credentials, API keys, and tokens in code repositories remain a top attack vector, with breaches often tracing back to leaked secrets in public or private Git repos. Two tools stand out in this space: Gitleaks, a fast, lightweight secrets scanner for Git repos, and HashiCorp Vault, the industry-standard secrets management solution. This guide walks you through integrating Gitleaks with Vault to automate leak detection, centralize secret storage, and supercharge your overall secrets management workflow.

Prerequisites

Before starting, ensure you have the following:

  • Basic familiarity with Git, CLI tools, and DevOps workflows
  • HashiCorp Vault installed (or access to a running Vault instance, version 1.10+)
  • Gitleaks installed (v8.18+ recommended)
  • A Git repository to test scanning (can be a local test repo)
  • jq (JSON processor) installed for parsing Vault API responses

What is Gitleaks?

Gitleaks is an open-source, Go-based tool designed to scan Git repositories for hardcoded secrets. It supports scanning entire commit histories, specific branches, or staged changes, and uses a customizable ruleset to detect common secret patterns (AWS keys, Stripe tokens, SSH keys, etc.). Gitleaks can run locally, in CI/CD pipelines, or as a pre-commit hook, making it a flexible choice for shift-left security.

What is HashiCorp Vault?

HashiCorp Vault is a unified secrets management platform that secures, stores, and controls access to tokens, passwords, certificates, and API keys. Vault provides encryption as a service, dynamic secrets generation, and fine-grained access policies, eliminating the need to hardcode secrets in code or config files. It integrates with most cloud providers, DevOps tools, and identity providers.

Why Integrate Gitleaks with Vault?

While Gitleaks detects leaked secrets, it doesn’t manage or rotate them. Vault solves the root cause by providing a secure home for secrets, but it doesn’t scan existing repos for leaks. Integrating the two creates a closed-loop workflow:

  • Gitleaks scans repos for hardcoded secrets
  • Detected secrets are validated against Vault to check if they’re active
  • Leaked active secrets are automatically revoked or rotated in Vault
  • Developers are alerted to replace hardcoded secrets with Vault references

Step 1: Set Up HashiCorp Vault

First, initialize and unseal your Vault instance (skip if using a managed Vault service):

# Start Vault dev server (for testing only; use production mode for live environments)
vault server -dev -dev-root-token-id="root"

# Export Vault address and token
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='root'

# Enable the KV v2 secrets engine (for storing secrets)
vault secrets enable kv-v2

# Create a policy for Gitleaks to read secret metadata (least privilege)
vault policy write gitleaks-policy - < gitleaks-vault-token.txt
Enter fullscreen mode Exit fullscreen mode

Save the generated token from gitleaks-vault-token.txt – you’ll use this later for Gitleaks to authenticate to Vault.

Step 2: Install and Configure Gitleaks

Install Gitleaks via your package manager or download a release binary from the Gitleaks GitHub repo:

# macOS (Homebrew)
brew install gitleaks

# Linux (wget)
wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz
tar -xzf gitleaks_8.18.0_linux_x64.tar.gz
sudo mv gitleaks /usr/local/bin/

# Verify installation
gitleaks version
Enter fullscreen mode Exit fullscreen mode

Create a custom Gitleaks config to add Vault-specific rules and output formatting for Vault integration:

# gitleaks-vault-config.toml
[rules.vault-token]
description = "HashiCorp Vault Token"
regex = '''(hvs\.[a-zA-Z0-9]{20,})'''
tags = ["vault", "secret"]
severity = "HIGH"

[rules.aws-key]
description = "AWS Access Key"
regex = '''AKIA[0-9A-Z]{16}'''
tags = ["aws", "secret"]
severity = "CRITICAL"

[extend]
# Use default Gitleaks rules as base
path = "https://raw.githubusercontent.com/gitleaks/gitleaks/master/config/gitleaks.toml"
Enter fullscreen mode Exit fullscreen mode

Step 3: Integrate Gitleaks with Vault

Now configure Gitleaks to send detected secrets to Vault for validation. We’ll use a Gitleaks post-scan hook script to check if detected secrets exist in Vault, and revoke them if active:

# gitleaks-vault-hook.sh
#!/bin/bash

# Load Vault token and address
VAULT_TOKEN=$(cat gitleaks-vault-token.txt)
VAULT_ADDR="http://127.0.0.1:8200"

# Parse Gitleaks JSON output (passed via stdin)
gitleaks_output=$(cat)

# Check if any secrets were found
if [ -z "$gitleaks_output" ]; then
  echo "No secrets detected."
  exit 0
fi

# Loop through detected secrets
echo "$gitleaks_output" | jq -c '.[]' | while read -r secret; do
  secret_value=$(echo "$secret" | jq -r '.match')
  secret_rule=$(echo "$secret" | jq -r '.rule')
  file_path=$(echo "$secret" | jq -r '.file')

  echo "Detected secret: $secret_rule in $file_path"

  # If the secret is a Vault token, check if it's active
  if [[ "$secret_rule" == "vault-token" ]]; then
    # Validate token against Vault
    token_valid=$(curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/auth/token/lookup" -d "{\"token\": \"$secret_value\"}" | jq -r '.data.id // empty')

    if [ -n "$token_valid" ]; then
      echo "Active Vault token detected! Revoking..."
      curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/auth/token/revoke" -d "{\"token\": \"$secret_value\"}" | jq -r '.data.id // empty'
      echo "Token revoked successfully."
    fi
  fi

  # For other secrets, check if they exist in Vault KV
  # (Adjust path based on your Vault KV structure)
  secret_exists=$(curl -s -H "X-Vault-Token: $VAULT_TOKEN" "$VAULT_ADDR/v1/kv/data/$secret_rule" | jq -r '.data.data.value // empty')

  if [[ "$secret_exists" == "$secret_value" ]]; then
    echo "Secret matches active Vault entry. Consider rotating."
  fi
done
Enter fullscreen mode Exit fullscreen mode

Make the hook script executable:

chmod +x gitleaks-vault-hook.sh
Enter fullscreen mode Exit fullscreen mode

Step 4: Run a Test Scan

Create a test Git repo with a fake secret to verify the integration:

# Create test repo
mkdir test-repo && cd test-repo
git init
echo "hvs.CAESIJY7v8Z7x8Z7x8Z7x8Z7x8Z7x8Z7x8Z7x8Z7x8" > fake-vault-token.txt
git add . && git commit -m "Add fake secret"

# Run Gitleaks scan with custom config and hook
gitleaks detect --source . --config gitleaks-vault-config.toml --report-format json | ./gitleaks-vault-hook.sh
Enter fullscreen mode Exit fullscreen mode

You should see output indicating the fake Vault token was detected, validated, and revoked if active.

Step 5: Automate the Workflow in CI/CD

To enforce secrets scanning in your pipeline, add Gitleaks to your CI/CD config (example for GitHub Actions):

# .github/workflows/gitleaks-vault-scan.yml
name: Gitleaks Vault Scan
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Scan full commit history

      - name: Install Gitleaks
        run: |
          wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.0/gitleaks_8.18.0_linux_x64.tar.gz
          tar -xzf gitleaks_8.18.0_linux_x64.tar.gz
          sudo mv gitleaks /usr/local/bin/

      - name: Run Gitleaks Scan and Vault Hook
        env:
          VAULT_ADDR: ${{ secrets.VAULT_ADDR }}
          VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }}
        run: |
          gitleaks detect --source . --config gitleaks-vault-config.toml --report-format json | ./gitleaks-vault-hook.sh

      - name: Fail Pipeline on Detected Secrets
        if: failure()
        run: exit 1
Enter fullscreen mode Exit fullscreen mode

Store your Vault address and Gitleaks token as GitHub Secrets to avoid hardcoding them in the workflow.

Step 6: Monitor and Alert on Leaks

Integrate Gitleaks scan results with your monitoring stack (Prometheus, Datadog, Slack) to alert teams when secrets are detected:

  • Configure Gitleaks to send scan reports to a SIEM or log aggregator
  • Use Vault audit logs to track secret access and revocation events
  • Set up Slack/Email alerts for critical severity leaks

Best Practices

  • Follow least privilege: Only grant Gitleaks the minimum Vault permissions needed
  • Use dynamic secrets: Replace hardcoded secrets with Vault dynamic secrets where possible
  • Scan pre-commit: Add Gitleaks as a pre-commit hook to catch secrets before they’re committed
  • Regularly update rules: Keep Gitleaks rules and Vault policies up to date
  • Test revocation: Periodically test leaked secret revocation to ensure the workflow works

Conclusion

Integrating Gitleaks with HashiCorp Vault creates a powerful, automated secrets management workflow that detects leaks early, revokes active compromised secrets, and guides developers to use Vault for secure secret storage. By shifting left with Gitleaks and centralizing secrets in Vault, you reduce the risk of credential-based breaches and streamline compliance with security standards like SOC2 and GDPR. Start small with a test repo, then roll out the integration to your entire organization’s repos for maximum impact.

Top comments (0)