vigil Documentation
Welcome to the documentation for vigil, the security scanner for AI-generated code.
Table of Contents
| Document | Description |
|---|---|
| Quick Start | Installation, first scan, and basic concepts |
| CLI Reference | All commands, flags, and options available |
| Configuration | .vigil.yaml file, strategies, overrides, and config merge |
| Rules Catalog | Complete catalog of all 26 rules with vulnerable code examples |
| Output Formats | Human, JSON, JUnit XML, and SARIF 2.1.0 |
| CI/CD Integration | GitHub Actions, GitLab CI, pre-commit hooks, and quality gates |
| Docker | Container usage, reference Dockerfile, and best practices |
| Security | Threat model, what vigil detects, OWASP alignment, and limitations |
| Analyzers | Technical reference for implemented analyzers (Dependency, Auth, Secrets) |
| Architecture | Internal structure, engine flow, analyzer protocol |
| Best Practices | Recommendations for teams using AI agents to generate code |
| Compliance & Enterprise Usage | Alignment with OWASP, CRA, SOC 2, ISO 27001, NIST, and enterprise pipeline usage |
| Contributing | Guide for contributing to the project, development setup, and testing |
Project Status
vigil is in active development. The current version (v0.3.0) includes:
- Full CLI with 5 subcommands (
scan,deps,tests,init,rules) - Analysis engine with support for multiple analyzers
- Dependency Analyzer active — detects hallucinated packages, typosquatting, nonexistent versions (DEP-001, DEP-002, DEP-003, DEP-005, DEP-007)
- Auth Analyzer active — detects unprotected endpoints, permissive CORS, insecure JWT, cookies without flags, timing attacks (AUTH-001 through AUTH-007)
- Secrets Analyzer active — detects placeholders, low-entropy secrets, connection strings, env defaults, values copied from .env.example (SEC-001 through SEC-004, SEC-006)
- 26 rules defined across 4 categories (18 implemented, 8 pending)
- 4 output formats (human, JSON, JUnit XML, SARIF 2.1.0)
- Configuration system with YAML, presets, and CLI overrides
- 961 unit tests (~98% coverage)
The remaining analyzer (Test Quality) will be implemented in the next phase.