Commands Reference

Commands Reference

Global flags

These flags work with any command:

Flag	Short	Description
--help	-h	Show help
--version	-V	Show version
--verbose	-v	Show debug output
--quiet	-q	Only show errors
--no-color		Disable ANSI colors
--json	-j	Machine-readable JSON output

---

vexes scan

Enumerate dependencies from lockfiles, query OSV.dev, and report known vulnerabilities.

Options

Flag	Description	Default
--path <dir>	Target directory	Current working directory
--ecosystem <name>	Filter to one ecosystem: npm, pypi, cargo, brew	All detected
--severity <level>	Minimum severity to report: critical, high, moderate, low	moderate
--fix	Show upgrade commands for fixable vulnerabilities	Off
--cached	Use cached results without freshness check	Off

Supported lockfiles

Ecosystem	Lockfiles	Manifests (fallback)
npm	package-lock.json (v1, v2, v3)	package.json (lower confidence)
PyPI	Pipfile.lock, poetry.lock	requirements.txt, pyproject.toml
Cargo	Cargo.lock
Homebrew	Brewfile.lock.json	Brewfile

JSON output schema

{
  "version": "0.1.0",
  "timestamp": "2026-03-31T...",
  "command": "scan",
  "complete": true,
  "summary": { "total": 124, "vulnerable": 3, "critical": 1, "high": 1, "moderate": 1, "low": 0 },
  "warnings": [],
  "vulnerabilities": [
    {
      "id": "GHSA-xxxx",
      "displayId": "GHSA-xxxx",
      "aliases": ["CVE-2024-xxxx"],
      "summary": "Description of the vulnerability",
      "severity": "CRITICAL",
      "package": "express",
      "version": "4.17.1",
      "ecosystem": "npm",
      "fixed": ">= 4.19.2",
      "url": "https://osv.dev/vulnerability/GHSA-xxxx",
      "references": []
    }
  ]
}

---

vexes analyze

Deep behavioral analysis of the dependency supply chain using the 4-layer detection engine.

Options

Flag	Description	Default
--path <dir>	Target directory	cwd
--ecosystem <name>	Filter: npm, pypi	All detected
--deep	Download + AST-inspect actual package source code	Off
--explain <pkg>	Detailed breakdown for a specific package
--strict	Exit code 1 on any signal (for CI)	Off
--verbose	Show all signals including LOW	Off

Risk scoring

Composite scores account for context:

• New packages (< 30 days): 2x weight
• Single maintainer: 1.5x weight
• Known-good packages (esbuild, sharp, etc.): 0.2x weight
• 3+ unique signals: 1.5x multiplier
• 5+ unique signals: 2x multiplier

Risk levels: NONE (0), LOW (> 0), MODERATE (>= 5), HIGH (>= 15), CRITICAL (>= 30)

---

vexes fix

Generate verified fix recommendations. Every recommended version is cross-checked against OSV.

Options

Flag	Description	Default
--path <dir>	Target directory	cwd
--json	Machine-readable output	Off

How verification works

1. Scan for vulnerabilities (same as vexes scan)
2. Extract ALL fix versions from OSV advisory ranges
3. Sort candidates: prefer the highest version
4. Cross-check each candidate against OSV -- is it safe?
5. Verify the version exists on the registry
6. Generate the exact install command

If all known fix versions are themselves vulnerable, vexes checks the latest tag as a fallback.

Currently supports: npm. PyPI and Cargo support is planned.

---

vexes guard

Pre-install protection via lockfile diffing. Analyzes new/changed packages before they execute.

Usage

vexes guard -- npm install <package>

Options

Flag	Description
--setup	Install shell wrappers that auto-intercept npm install
--uninstall	Remove shell wrappers
--force	Override HIGH-risk warnings (CRITICAL findings still block)
--path <dir>	Target directory

Decision matrix

Finding	TTY	Non-TTY (CI)	--force
CRITICAL	Block	Block	Block
HIGH	Prompt y/N	Block	Allow
UNKNOWN	Allow with warning	Allow with warning	Allow
Clean	Allow	Allow	Allow

Shell wrappers

vexes guard --setup adds a shell function that intercepts npm install:

npm() {
  if [[ "$1" == "install" || "$1" == "i" || "$1" == "add" ]]; then
    command npx @penumbraforge/vexes guard -- npm "$@"
  else
    command npm "$@"
  fi
}

Supports bash, zsh, and fish. Remove with vexes guard --uninstall.

---

vexes monitor

Continuous dependency monitoring for CI and development.

CI mode

vexes monitor --ci                      # GitHub Actions annotations
vexes monitor --ci --severity critical  # Only fail on critical
vexes monitor --ci --sarif              # SARIF for GitHub Advanced Security
vexes monitor --ci --json               # Machine-readable JSON

Watch mode

vexes monitor --watch                   # Watch lockfiles + poll OSV
vexes monitor --watch --interval 5      # Poll every 5 minutes

Watch mode:

• Monitors lockfiles for changes using fs.watch
• Periodically polls OSV for new vulnerabilities
• Alerts when new/changed packages have vulnerabilities
• Runs until Ctrl+C

SARIF output

SARIF (Static Analysis Results Interchange Format) output conforms to the OASIS 2.1.0 specification and integrates with GitHub Code Scanning:

- name: Security scan
  run: npx @penumbraforge/vexes monitor --ci --sarif > results.sarif
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif