Metadata-Version: 2.4
Name: vigil-ai-cli
Version: 0.2.0
Summary: Security scanner for AI-generated code
License: MIT
Keywords: security,ai,linter,sast,slopsquatting
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: structlog>=24.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# 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:** v0.2.0 — Core engine, CLI, and Dependency Analyzer complete with QA audit. Auth, Secrets, and Test Quality analyzers under active development.

## The Problem

- **20%** of packages recommended by LLMs don't exist in any registry ([University of Texas/Virginia Tech, 2025](https://arxiv.org/abs/2406.10279))
- **58%** of hallucinated package names are repeatable — attackers can register them ([Socket Research, 2025](https://socket.dev/blog/when-ai-invents-code-dependencies))
- **45%** of LLM-generated code contains security flaws ([Veracode, 2025](https://www.veracode.com/blog/managing-appsec/veracodes-state-software-security-report-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

```bash
# 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.

| Rule | Severity | Description |
|------|----------|-------------|
| DEP-001 | CRITICAL | Package does not exist in registry (hallucinated) |
| DEP-002 | HIGH | Package was created less than 30 days ago |
| DEP-003 | HIGH | Package name is very similar to a popular package (typosquatting) |
| DEP-004 | MEDIUM | Package has very few weekly downloads |
| DEP-005 | MEDIUM | Package has no linked source repository |
| DEP-006 | HIGH | Import in code for a module not in declared dependencies |
| DEP-007 | CRITICAL | Specified version does not exist in registry |

### Auth & Permission Patterns (CAT-02)

Detects insecure authentication patterns commonly generated by AI agents.

| Rule | Severity | Description |
|------|----------|-------------|
| AUTH-001 | HIGH | Sensitive endpoint without authentication middleware |
| AUTH-002 | HIGH | DELETE/PUT endpoint without authorization |
| AUTH-003 | MEDIUM | JWT with lifetime exceeding 24 hours |
| AUTH-004 | CRITICAL | Hardcoded JWT secret with placeholder value |
| AUTH-005 | HIGH | CORS configured with `*` (allow all origins) |
| AUTH-006 | MEDIUM | Cookie without httpOnly/secure/sameSite flags |
| AUTH-007 | MEDIUM | Password comparison without timing-safe function |

### Secrets & Credentials (CAT-03)

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

| Rule | Severity | Description |
|------|----------|-------------|
| SEC-001 | CRITICAL | Placeholder secret from .env.example or docs |
| SEC-002 | CRITICAL | Hardcoded secret with low entropy |
| SEC-003 | CRITICAL | Connection string with embedded credentials |
| SEC-004 | HIGH | Sensitive env variable with hardcoded default |
| SEC-005 | HIGH | Secret file not listed in .gitignore |
| SEC-006 | CRITICAL | Value copied verbatim from .env.example |

### Test Quality (CAT-06)

Detects test theater — tests that pass but verify nothing.

| Rule | Severity | Description |
|------|----------|-------------|
| TEST-001 | HIGH | Test function without any assertions |
| TEST-002 | MEDIUM | Trivial assertion (`assert x is not None`, `assertTrue(True)`) |
| TEST-003 | MEDIUM | Test catches all exceptions without verifying type |
| TEST-004 | LOW | Skipped test without justification |
| TEST-005 | MEDIUM | API test that doesn't verify status code |
| TEST-006 | MEDIUM | Mock returns exactly what implementation would calculate |

## Output Formats

```bash
# 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

```yaml
- 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

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

## Configuration

Generate a config file with `vigil init`:

```bash
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](.vigil.example.yaml) for all available options.

### Key Options

```yaml
# 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

| Code | Meaning |
|------|---------|
| 0 | No findings above threshold |
| 1 | Findings found above threshold |
| 2 | Execution error |

### Common Flags

| Flag | Description |
|------|-------------|
| `--format, -f` | Output format: `human`, `json`, `junit`, `sarif` |
| `--output, -o` | Write output to file |
| `--fail-on` | Minimum severity to fail: `critical`, `high`, `medium`, `low` |
| `--category, -C` | Only run specific categories |
| `--rule, -r` / `--exclude-rule, -R` | Include/exclude specific rules |
| `--language, -l` | Only scan specific languages |
| `--offline` | Skip HTTP requests to registries |
| `--changed-only` | Only scan files changed since last commit |
| `--verbose, -v` | Verbose output |

## 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

| OWASP Risk | vigil Coverage |
|---|---|
| LLM02 — Sensitive Information Disclosure | SEC-001 to SEC-006 |
| LLM03 — Supply Chain Vulnerabilities | DEP-001 to DEP-007 |
| LLM06 — Excessive Agency | AUTH-001 to AUTH-007 |

## Requirements

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

## Development

```bash
# 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 (632 tests)
pytest tests/ -v

# Run with coverage (~94%)
pytest tests/ -v --cov=vigil

# Lint
ruff check src/ tests/
```

## License

MIT
