Quick Start

Prerequisites

Python 3.12 or higher
pip (included with Python)
git (optional, required for --changed-only)

Installation

From PyPI

pip install vigil-ai-cli

From source (development)

git clone https://github.com/org/vigil.git
cd vigil
python3.12 -m venv .venv
source .venv/bin/activate    # Linux/macOS
# .venv\Scripts\activate     # Windows
pip install -e ".[dev]"

Verify the installation

vigil --version
# vigil, version 0.3.0

First scan

Run vigil on your project directory:

vigil scan src/

Example output when there are no issues:

  vigil v0.3.0 — scanned 42 files

  No findings.

  -------------------------------------------------
  42 files scanned in 0.5s
  0 findings

Example output with findings:

  vigil v0.3.0 — scanned 42 files

  X CRITICAL  DEP-001  requirements.txt:14
    Package 'python-jwt-utils' does not exist in pypi.
    This is likely a hallucinated dependency from an AI agent.
    -> Suggestion: Remove 'python-jwt-utils' and find the correct package name.

  X HIGH      AUTH-005  src/main.py:8
    CORS configured with '*' allowing requests from any origin.
    -> Suggestion: Restrict CORS to specific trusted origins.

  -------------------------------------------------
  42 files scanned in 1.2s
  2 findings: 1 critical, 1 high
  analyzers: dependency, auth

Basic concepts

What is a finding

A finding is a security issue detected by vigil. Each finding has:

rule_id: Unique identifier for the rule (e.g., DEP-001, AUTH-005)
severity: Severity level (critical, high, medium, low, info)
message: Description of the problem found
location: File and line where it was detected
suggestion: Concrete recommendation to fix it

Severity levels

Level	Meaning	Exit code
`critical`	Must be fixed before merge. Immediate security risk.	1
`high`	Should be fixed before merge. Significant risk.	1
`medium`	Should be fixed, not necessarily before merge.	0*
`low`	Informational, good practice.	0*
`info`	Informational only, not a problem.	0*

*By default, vigil fails (exit code 1) with high or higher findings. This can be changed with --fail-on.

Category	Prefix	What it detects
Dependency Hallucination	`DEP-`	Packages that don’t exist, typosquatting, suspiciously new packages
Auth & Permission	`AUTH-`	Unprotected endpoints, open CORS, insecure JWT, cookies without flags
Secrets & Credentials	`SEC-`	Placeholder secrets, hardcoded credentials, connection strings
Test Quality	`TEST-`	Tests without asserts, trivial assertions, skipped tests without reason

Exit codes

Code	Meaning
`0`	No findings above the threshold
`1`	Findings found above the threshold
`2`	Runtime error (invalid config, network error, etc.)

What is active now

In the current version (v0.3.0), three analyzers are fully functional:

Dependency Analyzer (DEP-001 through DEP-007)

Detects packages that don’t exist in PyPI/npm (slopsquatting)
Detects names similar to popular packages (typosquatting)
Verifies that pinned versions exist
Detects suspiciously new packages without a source repository

Auth Analyzer (AUTH-001 through AUTH-007)

Detects endpoints without authentication middleware
Detects CORS configured with *
Detects JWT with excessive lifetime or hardcoded secret
Detects cookies without security flags
Detects non timing-safe password comparison

Secrets Analyzer (SEC-001 through SEC-006)

Detects placeholders copied from documentation or .env.example
Detects secrets with low entropy (generated by AI)
Detects connection strings with embedded credentials
Detects environment variables with sensitive defaults

# Full scan (deps + auth + secrets)
vigil scan src/

# Dependencies only
vigil deps

# Static checks only (no HTTP)
vigil scan src/ --offline

The Test Quality analyzer will be implemented in the next phase.

Next steps

Generate a configuration file: vigil init
Explore all rules: vigil rules
Analyze dependencies only: vigil deps --verify
Analyze test quality only: vigil tests tests/
Integrate vigil into your CI/CD: see CI/CD Integration
Check active analyzers: see Analyzers
See the full CLI reference: see CLI Reference