vault-kv-search

vault-kv-search is a command-line tool for recursively searching for secrets within HashiCorp Vault's Key-Value (KV) stores (versions 1 and 2). It helps you quickly find where a specific value, key, or path is located across many secrets, making it an essential utility for auditing and managing your Vault environment.

• Features
• Installation
• Usage
  • Prerequisites
  • Command Flags
  • Examples
• Development
  • Building from Source
  • Running Tests
• License

• Recursive Search: Traverses nested paths in Vault to find secrets.
• Multi-Target Search: Search within secret values, keys, or paths.
• Regex & Case-Insensitive Support: Use regular expressions (-r) and case-insensitive matching (-i) for flexible search patterns.
• Bounded Concurrency & Rate Limiting: Configurable worker pool (-c) and crawling delay (-d) for fast, safe searches.
• Graceful Permission Handling: Automatically skips paths returning 403 Permission Denied and reports skipped counts in the summary.
• Match Highlighting: Highlights matched substrings in terminal output (respecting NO_COLOR and --no-color).
• Interactive Guided Prompt: Run with no arguments in a terminal (or --interactive) for a guided store and query prompt.
• KV v1 and v2 Support: Works seamlessly with both versions of the KV secrets engine.
• Multiple Output Formats: Choose between human-readable text and structured json output.
• Cross-Platform: Builds for Linux, macOS, and Windows.
• Search All Stores: Can automatically discover and search all mounted KV stores.

brew install xbglowx/tap/vault-kv-search

Homebrew keeps the formula updated when a new release is published.

You can download the latest pre-compiled binaries for your operating system from the GitHub Releases page.

1. Download the appropriate binary for your system (e.g., vault-kv-search-linux-amd64).
2. Make the binary executable: chmod +x vault-kv-search-*
3. (Optional) Move it to a directory in your PATH for easy access: sudo mv vault-kv-search-* /usr/local/bin/vault-kv-search

The tool requires a Vault server address and authentication token, configured via CLI flags (--vault-addr, --vault-token), environment variables (VAULT_ADDR, VAULT_TOKEN), or ~/.vault-token:

export VAULT_ADDR="https://your-vault-server:8200"
export VAULT_TOKEN="s.YourVaultToken"

You may also pass --skip-verify or set VAULT_SKIP_VERIFY=true if your Vault instance uses a self-signed certificate, and NO_COLOR=1 (or pass --no-color) to disable ANSI color output.

Usage:
  vault-kv-search [flags] [search-path] substring

Flags:
  -c, --concurrency int      Number of concurrent Vault workers (default 10)
  -d, --delay int            Crawling delay in milliseconds (default 15)
  -e, --exit-code            Return exit code 1 when no matches are found
  -h, --help                 help for vault-kv-search
  -i, --ignore-case          Perform case-insensitive matching
      --interactive          Launch interactive guided search prompt
  -j, --json                 Output as JSON
  -k, --kv-version int       KV version (1,2). Autodetect if not defined
      --no-color             Disable colored output and match highlighting
  -r, --regex                Enable searching regex substring
      --search strings       Which Vault objects to search against. Choices are any and all of the following 'key,value,path'. Can be specified multiple times or once using format CSV. Defaults to 'value' (default [value])
  -s, --showsecrets          Show secrets values
      --skip-verify          Skip TLS certificate verification (overrides VAULT_SKIP_VERIFY)
  -t, --timeout int          Vault client timeout in seconds (default 30)
  -a, --vault-addr string    Vault server address (overrides VAULT_ADDR)
      --vault-token string   Vault authentication token, @file, or file path (overrides VAULT_TOKEN and ~/.vault-token)

1. Search values for a substring:

   vault-kv-search secret/production/ "api.example.com"

2. Search keys for a substring:

   vault-kv-search --search=key secret/ "username"

3. Search both keys and values:

   vault-kv-search --search=key --search=value secret/ "database"

4. Search using a regular expression:

   vault-kv-search --regex secret/ "^db-"

5. Search for a secret by its path (name):

   vault-kv-search --search=path secret/ "ssh-keys"

6. Search all mounted KV stores at once: This requires permissions to list mounts.

   vault-kv-search "sensitive-data"

7. Show the secret value in the output:

   vault-kv-search --showsecrets secret/ "password123"

8. Output results in JSON format:

   vault-kv-search --json secret/ "user@example.com"

9. Case-insensitive search with custom worker concurrency:

   vault-kv-search -i -c 20 secret/ "apikey"

10. Return non-zero exit code (1) when no matches are found (for scripts/CI):

    vault-kv-search --exit-code secret/ "deprecated-host"

11. Launch interactive guided search prompt:

    vault-kv-search --interactive

12. Specify Vault address and token via CLI flags (literal token, @file, or file path):

    vault-kv-search -a https://vault.example.com:8200 --vault-token @~/.vault-token-prod secret/ "db-host"

Prerequisites:

• Go version specified in go.mod
• Make

To build the binary from the source code:

make vault-kv-search

The compiled binary will be available in the root of the project directory.

Tests use testcontainers-go to automatically start and stop Vault containers, providing complete isolation and eliminating the need for manual container management.

Prerequisites:

• Docker (Docker Desktop, Colima, or similar)

make test

If you're using Colima instead of Docker Desktop, you need to set the following environment variables:

export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
export TESTCONTAINERS_RYUK_DISABLED=true
make test

You can add these exports to your shell profile (~/.zshrc or ~/.bashrc) to make them persistent.

This project is licensed under the MIT License. See the LICENSE file for details.