DEV Community

Alain Airom
Alain Airom

Posted on

Locating the Hidden: Using HashiCorp Vault Radar 📡 to Audit Your Local Machine for Risks

Prevent yourself sending sensitive information proactively!


We’ve all been there: you’re deep in the flow of building a solution, confidently hardcoding a temporary API key or database password locally just to get the “thing” working. We tell ourselves we’ll scrub the code before the final push, but in the rush to deploy to the cloud or sync with Git, those “temporary” secrets often slip through the cracks. This false sense of security has led to catastrophic data breaches and exposed infrastructures across the industry. HashiCorp Vault Radar serves as your final line of defense, scanning your environment to detect those hidden vulnerabilities and stopping sensitive “stuff” from ever going public, ensuring your confidence is backed by actual security.


Stopping the Leak: An Introduction to HashiCorp Vault Radar


In the modern DevSecOps landscape, a single “git push” can become a multi-million dollar mistake. As development cycles accelerate, the risk of accidentally embedding sensitive data — passwords, API keys, or private certificates — directly into source code increases exponentially. Once a secret is committed to a repository’s history, it is no longer secret.

What is Vault Radar?

Vault Radar is a specialized security product within the HashiCorp Cloud Platform (HCP) designed to automate the detection and identification of unmanaged secrets. While HashiCorp Vault is famous for managing secrets, Vault Radar is the “lookout” that finds the ones you forgot to protect.

It acts as a continuous scanning engine that looks beyond just active code; it dives deep into your version control history to identify risks that might have been buried years ago.

What Does it Scan For?

Vault Radar isn’t just a regex-based secret hunter. It provides a multi-layered approach to identifying risks:

  • Secrets: It identifies passwords, tokens, and keys. Crucially, it can distinguish between an inactive string and an active secret, helping teams prioritize the most critical threats.
  • Personally Identifiable Information (PII): As global privacy regulations (like GDPR and CCPA) tighten, Vault Radar helps identify sensitive user data that shouldn’t be in your codebase.
  • Non-Inclusive Language (NIL): It helps maintain brand integrity and community standards by flagging non-inclusive terms in your documentation and code.

How It Fits Into Your Workflow

Vault Radar doesn’t just wait for a security audit to run. It integrates directly into the developer lifecycle:

  1. Real-Time Scanning: It scans as you work, checking new commits and pull requests (PRs).
  2. Historical Deep Scans: It analyzes the entire Git history of a repository to find “zombie” secrets.
  3. Prioritized Remediation: Using a sophisticated severity ranking (from Info to Critical), it tells security teams exactly what needs immediate attention based on whether a secret is active and where it is located.

Why Does It Matter?

Traditional secret scanning often results in “alert fatigue” — hundreds of false positives that developers eventually ignore. Vault Radar addresses this by using advanced hashing (like Argon2id) and context-aware rules to ensure that when it flags a risk, it’s a risk worth fixing.

By catching secrets before they reach production — and cleaning up the ones that already did — Vault Radar bridges the gap between development speed and enterprise-grade security.


How to use Vault-Radar Locally on your own Machine?

Vault Radar Local Intallation

Hereafter the procedure I implemented on my local machine.

  • macOS
# Using Homebrew
brew tap hashicorp/tap
brew install hashicorp/tap/vault-radar
Enter fullscreen mode Exit fullscreen mode
  • Linux
# Download the binary
wget https://releases.hashicorp.com/vault-radar/0.10.0/vault-radar_0.10.0_linux_amd64.zip
​
# Unzip
unzip vault-radar_0.10.0_linux_amd64.zip
​
# Move to PATH
sudo mv vault-radar /usr/local/bin/
​
# Make executable
sudo chmod +x /usr/local/bin/vault-radar
Enter fullscreen mode Exit fullscreen mode
  • Verify Installation
vault-radar --version
Enter fullscreen mode Exit fullscreen mode

Step 1: Get Your HCP Project ID

  • Sign in or create a free account
  • Once logged in, either you create OR you’ll see your organization and projects
  • Click on your project name
  • Look at the URL in your browser — it will look like:
https://portal.cloud.hashicorp.com/orgs/YOUR-ORG/projects/YOUR-PROJECT-ID
Enter fullscreen mode Exit fullscreen mode

Copy the YOUR-PROJECT-ID part (it's a UUID like

a1b2c3d4-e5f6-7890-abcd-ef1234567890
Enter fullscreen mode Exit fullscreen mode

Alternative method:

  • In your project, click the ⚙️ Settings icon in the left sidebar
  • The Project ID is displayed at the top of the settings page

Create a Service Principal (for Client ID and Secret)

  • In your HCP project, click Access control (IAM) in the left sidebar
  • Click the Service principals tab
  • Click Create service principal
  • Give it a name (e.g., “vault-radar-scanner”)
  • Assign it the Contributor role (or a custom role with Vault Radar permissions)
  • Click Save

🚨 CRITICAL — Client Secret is Only Shown Once! 🚨

  • After clicking Save, a popup/modal will immediately appear with:
  • Client ID (you can view this later)
  • Client Secret (⚠️ ONLY SHOWN NOW — cannot be retrieved later!)

You MUST copy the Client Secret immediately!

┌─────────────────────────────────────────────┐
│  Service Principal Created                  │
├─────────────────────────────────────────────┤
│  Client ID:                                 │
│  abc123def456ghi789jkl012mno345pq          │
│  [Copy]                                     │
│                                             │
│  Client Secret: (shown only once)           │
│  aBcDeFgHiJkLmNoPqRsTuVwXyZ123456...       │
│  [Copy]                                     │
│                                             │
│  ⚠️  Save this secret now. You won't be     │
│     able to see it again.                   │
└─────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode
  • Click the [Copy] button next to the Client Secret or manually select and copy the entire secret string.

🫣 What if I closed the popup without copying the secret?

If you missed copying the Client Secret, you have two options:

Option A: Create a New Service Principal

  • Go back to Access control (IAM) → Service principals
  • Create a new service principal (give it a different name like “vault-radar-scanner-2”)
  • This time, copy the Client Secret immediately
  • Optionally, delete the old service principal you can’t use
    Option B: Generate a New Key for Existing Service Principal

  • Go to Access control (IAM) → Service principals

  • Click on your existing service principal

  • Look for Keys or Client credentials section

  • Click Generate new key or Create key

  • Copy the new Client Secret immediately (the old one will be invalidated).

Step 3: Set Environment Variables

Method 1: Direct Export (Quick Test)

# Replace with your actual values from steps 1 and 2
export HCP_PROJECT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
export HCP_CLIENT_ID="abc123def456ghi789jkl012mno345pq"
export HCP_CLIENT_SECRET="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz12"
Enter fullscreen mode Exit fullscreen mode

Method 2: Using a .env File (Recommended)

  • Create a .env file in your project directory:
# .env file
export HCP_PROJECT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
export HCP_CLIENT_ID="abc123def456ghi789jkl012mno345pq"
export HCP_CLIENT_SECRET="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz12"
Enter fullscreen mode Exit fullscreen mode
  • Important: Add .env to your .gitignore to avoid committing secrets:
echo ".env" >> .gitignore
Enter fullscreen mode Exit fullscreen mode
  • Load the .env file before running vault-radar:
# Source the .env file to load variables into your current shell
source .env

# Or use this shorthand
. .env

# Now run vault-radar
vault-radar scan folder -p . -o results.json -f json
Enter fullscreen mode Exit fullscreen mode

Note: The .env file only affects the current terminal session. You need to run source .env each time you open a new terminal, or add the exports to your shell profile for persistence.

Step 4: Persist Environment Variables (Optional but Recommended)

To avoid setting these every time you open a terminal, add them to your shell profile:

  • For Bash users:
# Add to ~/.bashrc or ~/.bash_profile
echo 'export HCP_PROJECT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"' >> ~/.bashrc
echo 'export HCP_CLIENT_ID="abc123def456ghi789jkl012mno345pq"' >> ~/.bashrc
echo 'export HCP_CLIENT_SECRET="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz12"' >> ~/.bashrc
​
# Reload configuration
source ~/.bashrc
Enter fullscreen mode Exit fullscreen mode
  • For Zsh users (macOS default):
# Add to ~/.zshrc
echo 'export HCP_PROJECT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"' >> ~/.zshrc
echo 'export HCP_CLIENT_ID="abc123def456ghi789jkl012mno345pq"' >> ~/.zshrc
echo 'export HCP_CLIENT_SECRET="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz12"' >> ~/.zshrc
​
# Reload configuration
source ~/.zshrc
Enter fullscreen mode Exit fullscreen mode
  • For temporary use (current session only):
# Just export them in your current terminal
export HCP_PROJECT_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
export HCP_CLIENT_ID="abc123def456ghi789jkl012mno345pq"
export HCP_CLIENT_SECRET="aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890AbCdEfGhIjKlMnOpQrStUvWxYz12"
Enter fullscreen mode Exit fullscreen mode

Step 5: Verify Authentication

# Check if environment variables are set correctly
echo "Project ID: $HCP_PROJECT_ID"
echo "Client ID: $HCP_CLIENT_ID"
echo "Client Secret: ${HCP_CLIENT_SECRET:0:10}..." # Shows only first 10 chars for security

# Verify all three are set and not empty
if [ -z "$HCP_PROJECT_ID" ] || [ -z "$HCP_CLIENT_ID" ] || [ -z "$HCP_CLIENT_SECRET" ]; then
    echo "❌ Error: One or more HCP environment variables are not set"
else
    echo "✅ All HCP environment variables are set"
fi

# Test with a simple scan
vault-radar scan folder -p . -o test-scan.json -f json
Enter fullscreen mode Exit fullscreen mode

Common Authentication Errors

Error: HCP_PROJECT_ID environment variable must be set

  • You haven’t exported the variables in your current terminal session
  • If using a .env file, you forgot to run source .env
  • Solution: Run source .env or export the variables directly
    Error: 404 Not Found or failed to get config options

  • Vault Radar is not enabled in your HCP project

  • The project ID may be incorrect

Go to HCP console → Your project
Look for “Vault Radar” in the left sidebar
Click “Enable” or “Get Started” if you see it
Complete any setup steps
If you don’t see Vault Radar, check your HCP tier/subscription
Verify your HCP_PROJECT_ID is correct (check the URL or project settings)
Error: oauth2: "unauthorized" "Authentication failed."

  • Your HCP_CLIENT_ID or HCP_CLIENT_SECRET is incorrect
  • The service principal may have been deleted or disabled
  • The credentials may have expired or been rotated

Verify your credentials in HCP console
Check that HCP_CLIENT_ID is a long alphanumeric string (not just your username or org name)
Generate a new key for your service principal if needed
Make sure you copied the entire Client Secret (they’re very long!)

Error: failed to get OAuth token

  • Network connectivity issues
  • HCP service may be temporarily unavailable
  • Firewall or proxy blocking access to HCP

Check your internet connection and try again

Debugging Steps:

# 1. Verify variables are loaded
env | grep HCP

# 2. Check the format of your credentials
echo "Project ID length: ${#HCP_PROJECT_ID}"  # Should be 36 (UUID format)
echo "Client ID length: ${#HCP_CLIENT_ID}"    # Should be 32+
echo "Client Secret length: ${#HCP_CLIENT_SECRET}"  # Should be 60+

# 3. If using .env file, make sure you sourced it
source .env

# 4. Try the scan again
vault-radar scan folder -p . -o test-scan.json -f json
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Authentication

Can’t find Service Principals in HCP?

  • Make sure you’re in a project (not just the organization view)
  • You need appropriate permissions — contact your HCP organization admin if you can’t create service principals

Lost your Client Secret?

  • The Client Secret is only displayed once when you create the service principal or generate a new key
  • You cannot view it again in the HCP console

Create a new service principal (recommended if you’re unsure)
Generate a new key for the existing service principal (invalidates the old secret)
Check if you saved it in a password manager or .env file

Using multiple HCP projects?

  • You can switch between projects by changing the HCP_PROJECT_ID variable
  • Consider creating separate service principals for each project

Scanning your machine using Vault-Radar

Now that all the requirements are set we can begin scanning!

Scan Current Directory

# Scan all files in current directory (requires output file)
vault-radar scan folder -p . -o results.json -f json
Enter fullscreen mode Exit fullscreen mode

Scan Specific Files

# Scan .env file
vault-radar scan folder -p .env -o env-scan.json -f json

# Scan YAML files
vault-radar scan folder -p config.yaml -o config-scan.json -f json
Enter fullscreen mode Exit fullscreen mode

Scanning Local Files

  • Basic scan
# Scan current directory recursively
vault-radar scan folder -p . -o results.json

# Scan specific directory
vault-radar scan folder -p /path/to/project -o scan-results.json
Enter fullscreen mode Exit fullscreen mode
  • Scan with Output
# Scan and save results to JSON
vault-radar scan folder -p . -o results.json -f json

# Scan and save results to CSV
vault-radar scan folder -p . -o results.csv -f csv

# Scan and save results to SARIF format
vault-radar scan folder -p . -o results.sarif -f sarif
Enter fullscreen mode Exit fullscreen mode
  • Scan .envFiles
# Scan specific .env file
vault-radar scan folder -p .env -o env-scan.json -f json

# Scan current directory (will include .env files)
vault-radar scan folder -p . -o scan-results.json -f json
Enter fullscreen mode Exit fullscreen mode
  • Scan YAML Configuration Files
# Scan current directory (will include YAML files)
vault-radar scan folder -p . -o results.json -f json

# Scan specific config file
vault-radar scan folder -p config/application.yaml -o config-scan.json -f json
Enter fullscreen mode Exit fullscreen mode

Configuration

  • Create a configuration YAML file (create .vault-radar.yaml in your project root)
# .vault-radar.yaml
scan:
  # Paths to scan
  paths:
    - .

  # File patterns to include
  include:
    - "*.env"
    - "*.yaml"
    - "*.yml"
    - "*.json"
    - "*.py"
    - "*.js"
    - "*.ts"

  # Directories to exclude
  exclude:
    - "node_modules"
    - "venv"
    - ".git"
    - "__pycache__"
    - "dist"
    - "build"

  # Output format (json, sarif, csv)
  output_format: json

  # Output file
  output_file: vault-radar-results.json

# Risk levels to report (critical, high, medium, low)
risk_levels:
  - critical
  - high
  - medium

# Custom patterns (optional)
custom_patterns:
  - name: "Custom API Key"
    pattern: "custom_api_[a-zA-Z0-9]{32}"
    risk: high
Enter fullscreen mode Exit fullscreen mode
  • Using Configuration Values: while vault-radar doesn’t support a --config flag, you can use the configuration file as a reference and pass the values as command-line arguments:
# Example using values from .vault-radar.yaml
vault-radar scan folder \
  -p . \
  -o vault-radar-results.json \
  -f json
Enter fullscreen mode Exit fullscreen mode

Output Formats

  • JSON Output request
vault-radar scan folder -p . -o results.json -f json
Enter fullscreen mode Exit fullscreen mode
  • The JSON output file
{
  "findings": [
    {
      "type": "AWS Access Key",
      "file": ".env",
      "line": 5,
      "risk": "critical",
      "value": "AKIA****************",
      "description": "AWS Access Key ID detected"
    },
    {
      "type": "Generic API Key",
      "file": "config.yaml",
      "line": 12,
      "risk": "high",
      "value": "sk_live_***************",
      "description": "API key pattern detected"
    }
  ],
  "summary": {
    "total_files_scanned": 45,
    "total_findings": 2,
    "critical": 1,
    "high": 1,
    "medium": 0,
    "low": 0
  }
}
Enter fullscreen mode Exit fullscreen mode
  • SARIF Output (for CI/CD)
vault-radar scan folder -p . -o results.sarif -f sarif
Enter fullscreen mode Exit fullscreen mode
  • Default CSV Output
vault-radar scan folder -p . -o results.csv -f csv
# or simply (csv is default)
vault-radar scan folder -p . -o results.csv
Enter fullscreen mode Exit fullscreen mode

Detected Secret Types

What does vault radar actually do scan?

Cloud Provider Keys

  • AWS Access Keys
  • Azure Storage Keys
  • Google Cloud API Keys
  • IBM Cloud API Keys

API Keys & Tokens

  • GitHub Personal Access Tokens
  • GitLab Tokens
  • Slack Tokens
  • Stripe API Keys
  • SendGrid API Keys

Database Credentials

  • PostgreSQL connection strings
  • MySQL passwords
  • MongoDB URIs
  • Redis passwords

Private Keys

  • RSA Private Keys
  • SSH Private Keys
  • PGP Private Keys

Generic Secrets

  • JWT Tokens
  • Bearer Tokens
  • API Keys (generic patterns)
  • Passwords in configuration files

Recommended — Common Use Cases

Scan Before Commit

#!/bin/bash
# pre-commit-scan.sh

# Ensure HCP credentials are set
if [ -z "$HCP_PROJECT_ID" ]; then
    echo "Error: HCP_PROJECT_ID not set"
    exit 1
fi

echo "Scanning for secrets..."
vault-radar scan folder -p . -o scan-results.json -f json

if [ $? -ne 0 ]; then
    echo "❌ Secrets detected! Please remove them before committing."
    cat scan-results.json
    exit 1
fi

echo "✅ No secrets detected."
Enter fullscreen mode Exit fullscreen mode

CI/CD Integration

# .github/workflows/security-scan.yml
name: Security Scan

on: [push, pull_request]

jobs:
  scan-secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Vault Radar
        run: |
          wget https://releases.hashicorp.com/vault-radar/0.10.0/vault-radar_0.10.0_linux_amd64.zip
          unzip vault-radar_0.10.0_linux_amd64.zip
          sudo mv vault-radar /usr/local/bin/

      - name: Scan for secrets
        env:
          HCP_PROJECT_ID: ${{ secrets.HCP_PROJECT_ID }}
          HCP_CLIENT_ID: ${{ secrets.HCP_CLIENT_ID }}
          HCP_CLIENT_SECRET: ${{ secrets.HCP_CLIENT_SECRET }}
        run: |
          vault-radar scan folder -p . -o results.sarif -f sarif

      - name: Upload results
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif
Enter fullscreen mode Exit fullscreen mode

Scan Multiple Directories

#!/bin/bash
# scan-all.sh

directories=("src" "config" "scripts" "tests")

for dir in "${directories[@]}"; do
    echo "Scanning $dir..."
    vault-radar scan folder -p "$dir" -o "scan-$dir.json"
done
Enter fullscreen mode Exit fullscreen mode

Baseline Comparison

# First scan - establish baseline
vault-radar scan folder -p . -o baseline.json -f json

# Later scan - compare against baseline (only new secrets reported)
vault-radar scan folder -p . -o new-findings.json -f json -b baseline.json
Enter fullscreen mode Exit fullscreen mode

Best Practices

Some tips and habits to have in mind.

  • Regular Scanning
# Add to crontab for daily scans
0 2 * * * cd /path/to/project && vault-radar scan folder -p . -o daily-scan.jsonLinks & resources
Enter fullscreen mode Exit fullscreen mode
  • Exclude False Positives: Create .vault-radar-ignore
# Ignore test files with dummy secrets
tests/fixtures/test-secrets.env
tests/mock-data.yaml

# Ignore documentation examples
docs/examples/*.md
Enter fullscreen mode Exit fullscreen mode
  • Integrate with Git Hooks
# .git/hooks/pre-commit
#!/bin/bash

vault-radar scan folder -p . -o pre-commit-scan.json -f json

if [ $? -ne 0 ]; then
    echo "Secrets detected!"
    cat pre-commit-scan.json
    exit 1
fi
Enter fullscreen mode Exit fullscreen mode
  • Remediation Workflow 🔥 When secrets are found:

Rotate the exposed secret immediately
Remove from code and use environment variables
Update .gitignore to prevent future commits
Consider using HashiCorp Vault for secret management
Scan git history for the secret:

git log -p | grep -i "secret_pattern"
Enter fullscreen mode Exit fullscreen mode
  • Example: Scanning This Project;
# Scan the current project for secrets
vault-radar scan folder -p /Users/alainairom/Devs/ibm-cos \
  -o ibm-cos-scan.json \
  -f json

# View results
cat ibm-cos-scan.json | jq '.findings'

# Count findings by risk level
cat ibm-cos-scan.json | jq '.summary'
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

  • Issue: Authentication Error
# Error: HCP_PROJECT_ID environment variable must be set
Enter fullscreen mode Exit fullscreen mode

Solution;

# Set required environment variables
export HCP_PROJECT_ID="your-project-id"
export HCP_CLIENT_ID="your-client-id"
export HCP_CLIENT_SECRET="your-client-secret"

# Verify they are set
env | grep HCP

# Try scanning again
vault-radar scan folder -p . -o results.json -f json
Enter fullscreen mode Exit fullscreen mode
  • Issue: Too Many Results
# Use baseline to track only new secrets
vault-radar scan folder -p . -o current.json -f json -b previous.json

# Limit number of secrets reported
vault-radar scan folder -p . -o results.json -f json -l 50
Enter fullscreen mode Exit fullscreen mode
  • Issue: Slow Scanning
# Scan specific directories only
vault-radar scan folder -p src -o src-scan.json -f json
vault-radar scan folder -p config -o config-scan.json -f json

# Skip activeness checks for faster scanning
vault-radar scan folder -p . -o results.json -f json --skip-activeness

Enter fullscreen mode Exit fullscreen mode
  • Issue: Need Quiet Output
# Disable UI output (summary not logged to stdout)
vault-radar scan folder -p . -o results.json -f json --disable-ui
Enter fullscreen mode Exit fullscreen mode

Integration with Vault

  • After finding secrets with Vault Radar, migrate them to HashiCorp Vault:
# 1. Scan for secrets
vault-radar scan folder -p . -o findings.json

# 2. Extract secrets from findings
cat findings.json | jq -r '.findings[] | .file + ":" + (.line|tostring)'

# 3. Store in Vault (manual or scripted)
vault kv put secret/myapp/config \
  api_key="value-from-env-file" \
  db_password="value-from-config"

# 4. Update code to use Vault
# See VAULT_CONFIGURATION.md for integration details
Enter fullscreen mode Exit fullscreen mode

Command Reference

# Basic scan (requires output file)
vault-radar scan folder -p <path> -o <output-file>

# With format (csv, json, or sarif)
vault-radar scan folder -p <path> -o <output-file> -f json

# With baseline comparison
vault-radar scan folder -p <path> -o <output-file> -b previous-scan.json

# With limit on number of secrets
vault-radar scan folder -p <path> -o <output-file> -l 100

# Disable UI output
vault-radar scan folder -p <path> -o <output-file> --disable-ui

# Skip activeness checks
vault-radar scan folder -p <path> -o <output-file> --skip-activeness

# Scan git repository
vault-radar scan repo -u <git-url>

# Version
vault-radar --version

# Help
vault-radar --help
vault-radar scan folder --help
Enter fullscreen mode Exit fullscreen mode

Conclusion

Ultimately, securing your online applications begins long before the code reaches a production environment; it starts on your local machine. By integrating Vault Radar into your local development workflow, you transform a potentially “catastrophic” oversight into a proactive defense. Scanning locally allows you to catch hardcoded passwords, AWS keys, and PII in .env or YAML files before they are ever committed to a repository's history. This "shift-left" approach ensures that even if you confidently—but mistakenly—presume your code is clean, the radar identifies those hidden risks for you. Embracing this local-first security habit is the most effective way to prevent accidental leaks and ensure that your transition to the cloud is as secure as it is seamless.

>>> Thanks for reading <<<

Links and Resources

Top comments (0)