VulnReach Package Usage

April 3, 2026 ยท View on GitHub

This guide is for the Python package/CLI workflow (pip install vulnreach).

1. Install

1.1 Prerequisites

  • Python 3.11+
  • git
  • trivy on PATH

Install Trivy:

  • macOS: brew install trivy
  • Debian/Ubuntu: sudo apt-get install trivy

1.2 Install package

pip install vulnreach

Verify:

vulnreach --version
vulnreach --help

Expected commands:

  • scan
  • fix-plan
  • replay
  • explain

2. Dependencies

Required for package mode

  • Python runtime + package deps (installed by pip install vulnreach)
  • trivy

Optional (graceful skip if missing)

  • semgrep
  • tainter

Required only for dynamic runtime scanning

  • Docker + Docker Compose
  • Explicit opt-in env:
    • VULNREACH_ALLOW_DOCKER_DAEMON=true
  • If running containerized runtime profile:
    • DOCKER_HOST=tcp://docker-socket-proxy:2375 (set by runtime compose profile)

3. Startup Modes

3.1 Local standalone mode (default)

No server URL set:

vulnreach scan --repo-path ./labs/python_vuln_app

Storage:

  • SQLite by default at ~/.vulnreach/vulnreach.db

Override DB path:

SQLITE_PATH=/tmp/vulnreach.db vulnreach scan --repo-path ./labs/python_vuln_app

3.2 Client mode (talk to running server)

Set URL and token:

export VULNREACH_URL=http://localhost:8000
export VULNREACH_TOKEN=<jwt>

VULNREACH_TOKEN can be either:

  • JWT from POST /login, or
  • API token (API key) created via POST /api-keys or UI Settings -> API Keys.

Then run:

vulnreach scan --repo-url https://github.com/your-org/your-repo --wait

4. Core Usage

4.1 Scan

vulnreach scan --repo-path ./labs/python_vuln_app

With policy-style exit behavior:

vulnreach scan --repo-path ./labs/python_vuln_app --fail-on CONFIRMED

4.2 Fix plan

vulnreach fix-plan --scan-id <scan_id>
vulnreach fix-plan --scan-id <scan_id> --format markdown
vulnreach fix-plan --scan-id <scan_id> --format json

4.3 Explain a CVE

vulnreach explain CVE-2021-33503 --scan-id <scan_id>

4.4 Replay call graph

vulnreach replay CVE-2021-33503 --scan-id <scan_id>
vulnreach replay CVE-2021-33503 --scan-id <scan_id> --format mermaid

5. Useful Environment Variables

VariablePurposeDefault
SQLITE_PATHLocal standalone DB path~/.vulnreach/vulnreach.db
VULNREACH_URLEnable client modeunset
VULNREACH_TOKENAPI auth token (JWT or API key) for client modeunset
VULNREACH_USERNAMEAuto-login username (client mode)unset
VULNREACH_PASSWORDAuto-login password (client mode)unset
VULNREACH_ALLOW_DOCKER_DAEMONExplicit opt-in for dynamic Docker scanningunset (false)
DOCKER_HOSTDocker endpoint (runtime profile)unset

6. Quick Troubleshooting

  • Error: Provide --repo-path or --repo-url:
    • pass one of --repo-path or --repo-url.
  • trivy not found:
    • install trivy and retry.
  • API error 401 in client mode:
    • refresh token or set correct VULNREACH_TOKEN.
  • Dynamic scan skipped with daemon opt-in reason:
    • set VULNREACH_ALLOW_DOCKER_DAEMON=true intentionally.