vigil

Security scanner for AI-generated code. Fast, deterministic, no LLMs required.

vigil is a CLI static analysis tool that detects vulnerabilities and risk patterns specific to code generated by AI agents — problems that Semgrep, Snyk, and CodeQL were not designed to catch.

It detects hallucinated dependencies (slopsquatting), insecure auth patterns, hardcoded placeholder secrets, and empty test theater. It's a complement to your existing security tools, not a replacement.

Status: v1.0.0 — Stable release. All 4 analyzers, 4 output formats, 24 of 26 rules implemented. 1706 tests, 97% coverage. Exhaustive QA with 164 manual tests across 18 phases.

The Problem

• 20% of packages recommended by LLMs don't exist in any registry (University of Texas/Virginia Tech, 2025)
• 58% of hallucinated package names are repeatable — attackers can register them (Socket Research, 2025)
• 45% of LLM-generated code contains security flaws (Veracode, 2025)

Existing scanners check for known CVEs in real packages. vigil checks whether the packages even exist, whether secrets are just copy-pasted placeholders, and whether tests actually assert anything.

Quick Start

# Install
pip install vigil-ai-cli

# Scan your project
vigil scan src/

# Check dependencies only
vigil deps --verify

# Analyze test quality
vigil tests tests/

# Generate config
vigil init --strategy standard

# List all rules
vigil rules

What It Detects

Dependency Hallucination (CAT-01)

Verifies that every dependency actually exists in PyPI/npm and isn't suspicious.

Auth & Permission Patterns (CAT-02)

Detects insecure authentication patterns commonly generated by AI agents.

Secrets & Credentials (CAT-03)

Detects secrets that AI agents copy from examples or generate insecurely.

Test Quality (CAT-06)

Detects test theater — tests that pass but verify nothing.

Output Formats

# Terminal (default)
vigil scan src/

# JSON (programmatic)
vigil scan src/ --format json --output report.json

# SARIF (GitHub/GitLab Code Scanning)
vigil scan src/ --format sarif --output report.sarif

# JUnit XML (CI dashboards)
vigil scan src/ --format junit --output report.xml

CI/CD Integration

GitHub Actions

- name: Security scan (vigil)
  run: |
    pip install vigil-ai-cli
    vigil scan src/ --format sarif --output vigil.sarif
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: vigil.sarif

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/org/vigil
    rev: v1.0.0
    hooks:
      - id: vigil
        args: [scan, --changed-only]

Configuration

Generate a config file with vigil init:

vigil init                    # standard defaults
vigil init --strategy strict  # stricter thresholds
vigil init --strategy relaxed # more permissive

This creates .vigil.yaml in your project root. See .vigil.example.yaml for all available options.

Key Options

# Minimum severity to fail (exit code 1)
fail_on: "high"   # critical | high | medium | low

# Languages to scan
languages: [python, javascript]

# Dependency checks
deps:
  verify_registry: true
  min_age_days: 30
  similarity_threshold: 0.85
  offline_mode: false

# Disable or adjust specific rules
rules:
  DEP-004:
    severity: "low"
  AUTH-003:
    enabled: false

CLI Reference

vigil scan [PATHS] [OPTIONS]    Scan code for AI-generated security issues
vigil deps [PATH] [OPTIONS]     Check dependencies for hallucinated packages
vigil tests [PATHS] [OPTIONS]   Analyze test quality
vigil init [PATH] [OPTIONS]     Generate .vigil.yaml configuration
vigil rules                     List all available rules

Exit Codes

Common Flags

What vigil Is NOT

• Not a replacement for Semgrep/Snyk/SonarQube. It's a complement. Use them together.
• Not a vulnerability database (SCA). It doesn't track CVEs. For that, use Snyk or Trivy.
• Not AI-powered. It's deterministic: static rules, heuristics, registry verification. No API costs, no hallucinations of its own.
• Not specific to any AI agent. Works the same whether code came from Cursor, Claude Code, Copilot, or ChatGPT.

OWASP Alignment

Requirements

• Python 3.12+
• No external services required (registry checks are optional with --offline)

Development

# Clone and setup
git clone https://github.com/org/vigil.git
cd vigil
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (1706 tests)
pytest tests/ -v

# Run with coverage (97% global)
pytest tests/ -v --cov=vigil

# Lint
ruff check src/ tests/

License

MIT