README

VaultCheck

A PHP CLI tool that audits environment variable and secrets hygiene across your project. Think of it as a spell-checker for your .env files it catches security problems before they become incidents.

  CRITICAL  [E008]  APP_DEBUG=true in a production environment exposes stack traces.
  CRITICAL  [G008]  STRIPE_KEY: current value was found in git history  never rotated.
  HIGH      [E007]  APP_KEY is empty. Laravel cannot encrypt sessions without it.
  MEDIUM    [E011]  Duplicate key 'DB_PASSWORD' on line 14 (first seen on line 8).
  LOW       [C001]  Environment variable 'LEGACY_KEY' is defined but never referenced.

  5 finding(s): 2 CRITICAL, 1 HIGH, 1 MEDIUM, 1 LOW

Requirements

• PHP 8.2+
• git binary (for G001–G008 git history checks)

Installation

Via Composer (recommended):

composer global require jcadima/vaultcheck

Find the Composer global bin directory

composer global config bin-dir --absolute

You'll get a path like:

/home/yourusername/.config/composer/vendor/bin

Make vaultcheck available in your terminal

You need to add this directory to your PATH so your shell can find vaultcheck anywhere.

Add this line at the end of your shell profile: ~/.zshrc or ~/.bashrc, replacing yourusername with your actual username

export PATH="$PATH:/home/yourusername/.config/composer/vendor/bin"

Apply the changes

source ~/.bashrc or source ~/.zshrc

VPS / server alternative — symlink to /usr/local/bin (no shell profile changes needed):

sudo ln -sf "$(composer global config bin-dir)/vaultcheck" /usr/local/bin/vaultcheck

This makes vaultcheck available to all users and works in cron jobs, scripts, and CI pipelines without any PATH configuration.

Verify the install:

vaultcheck --version
vaultcheck audit /path/to/your/project

Via Docker Compose (local build):

git clone https://github.com/jcadima/vaultcheck.git
cd vaultcheck

# Build and start the container
docker compose -f docker-compose-local.yml up -d --build

# Install dependencies (once)
docker compose -f docker-compose-local.yml exec vaultcheck composer install

# Run the audit against a target project
docker compose -f docker-compose-local.yml exec vaultcheck php bin/vaultcheck audit /path/to/project

# Stop when done
docker compose -f docker-compose-local.yml down

From source:

git clone https://github.com/jcadima/vaultcheck.git
cd vaultcheck && composer install
php bin/vaultcheck audit /path/to/your/project

Usage

vaultcheck audit : Run a full security audit

By default, only CRITICAL and HIGH findings are shown — the genuine red flags that need immediate action. Lower-severity findings are still detected and a count is printed at the bottom. Use --min-severity to reveal them when you're ready to dig deeper.

# Scan current directory (shows CRITICAL + HIGH only by default)
vaultcheck audit

# Scan a specific path
vaultcheck audit /path/to/project

# See MEDIUM findings too (e.g. weak secrets, missing .env.example keys)
vaultcheck audit --min-severity=MEDIUM

# Show all findings including LOW-priority items
vaultcheck audit --min-severity=LOW

# Show only the most critical issues
vaultcheck audit --min-severity=CRITICAL

# Output as JSON (useful for CI pipelines and dashboards)
vaultcheck audit --output=json

# Output as Markdown (useful for reports and documentation)
vaultcheck audit --output=markdown

# Exit with code 1 if any MEDIUM or higher finding exists (for CI/CD gates)
vaultcheck audit --strict

# Skip git history scanning (faster for local dev)
vaultcheck audit --skip-history

# Scan entire git history instead of just the last 500 commits
vaultcheck audit --full-history

Valid values for --min-severity: CRITICAL, HIGH (default), MEDIUM, LOW, INFO.

vaultcheck keys : List all environment variables and their status

vaultcheck keys /path/to/project

Key              Status           Value (masked)   References
APP_KEY          MISSING_DEFAULT  ba**********h=   0 ref(s)
DB_PASSWORD      UNUSED           ch**me           3 ref(s)
UNDEFINED_KEY    EMPTY            (empty)          —

vaultcheck snapshot - Save a baseline

# Save current state (key hashes + findings)
vaultcheck snapshot /path/to/project

# Include git history checks in the snapshot
vaultcheck snapshot --include-history /path/to/project

Saves to .vaultcheck/snapshot.json. Secret values are never stored — only SHA-256 hashes.

vaultcheck drift : Detect what changed since the snapshot

vaultcheck drift /path/to/project

Key Changes:
  [+] NEW     STRIPE_KEY  (added)
  [=] same    APP_KEY
  [~] CHANGED DB_PASSWORD (value changed)

Finding Changes:
  [+] NEW     [CRITICAL] G002  Stripe key found in history
  [-] RESOLVED [HIGH]    E015  .env.bak backup file found

vaultcheck fix : Auto-fix safe issues

# Preview what would be fixed (no changes applied)
vaultcheck fix --safe --dry-run /path/to/project

# Apply all safe fixes with confirmation prompt
vaultcheck fix --safe /path/to/project

# Apply without confirmation
vaultcheck fix --safe --yes /path/to/project

CI/CD Integration

Add VaultCheck to your pipeline to block deployments if secrets hygiene regresses:

# GitHub Actions example
- name: Audit secrets hygiene
  run: |
    composer global require jcadima/vaultcheck
    vaultcheck audit --strict --skip-history

The --strict flag causes the process to exit with code 1 if any MEDIUM or higher finding exists, failing the pipeline step.

Check Reference

Environment (E001–E015)

Codebase (C001–C005)

Permissions (P001–P004)

Consistency (X001–X005)

Strength (S001–S006)

Git History (G001–G008)

License

MIT