Vigil — An Open-Source Dependency Vulnerability Scanner

Modern software depends heavily on open-source packages. While this accelerates development, it also introduces supply chain risk when vulnerabilities in dependencies go unnoticed.

To address this problem, I built Vigil — a lightweight, open-source CLI tool that scans dependency files using the OSV database and generates evidence-ready reports in HTML and JSON.

GitHub: https://github.com/0x5A65726F677275/Vigil

Why Vigil?

Many existing scanners:

• Require paid subscriptions
  


• Use proprietary vulnerability feeds
  


• Hide implementation details
  


• Generate reports that are difficult to archive or audit
  

Vigil focuses on:

• Open vulnerability data (OSV.dev)
  


• Transparent implementation
  


• Local-first design
  


• Self-contained HTML reports
  


• Machine-readable JSON output
  


• CI/CD compatibility
  

No SaaS dependency. No proprietary databases. Just open data and reproducible results.

Supported Ecosystems

Python

• requirements.txt


• 
  pyproject.toml ([project.dependencies])


• 
  pip freeze input (--from-freeze)

Node.js

• package.json


• package-lock.json


• yarn.lock


• pnpm-lock.yaml

Lockfiles are preferred when available to ensure accurate resolved versions.

Quick Start

Install directly from GitHub:

pip install "git+https://github.com/0x5A65726F677275/Vigil.git"

Run a scan:

vigil scan requirements.txt

This generates:

• Terminal output
  


• 
  scan-report.html
  


• 
  scan-report.json
  

Open the HTML file in your browser for a structured report.

Example Commands

Scan default requirements file:

vigil scan

Scan installed packages:

pip freeze | vigil scan - --from-freeze

Fail CI if vulnerabilities exist:

vigil scan --fail-on-vuln

Force fresh OSV queries:

vigil scan --no-cache

Terminal-only mode:

vigil scan --report none

Output Design

Terminal Output

• Colored summary


• Per-package vulnerability details


• CVE / OSV IDs


• Short descriptions


• Remediation hints

HTML Report

The generated HTML report is:

• Fully self-contained (no external CSS or JS)


• Print and PDF friendly


• Structured by package


• Includes:
  
  
  
  
  • Total packages scanned
  
  
  • Packages with vulnerabilities
  
  
  • Total vulnerability count
  
  
  • CVE/OSV IDs
  
  
  • Severity (when available)
  
  
  • References
  
  
  • Remediation guidance
  
  
  • Generation timestamp (UTC)
  
  
  • Scanner version
  
  
  • Data source attribution (OSV)
  
  
  
  
  
  

Designed for audit, compliance documentation, and security review.

JSON Report

Structured for:

• CI/CD pipelines


• Automation workflows


• Compliance tooling


• Custom dashboards

Includes metadata and detailed per-package vulnerability entries.

Architecture Overview

Core components include:

• CLI interface


• Dependency parsers (Python + Node)


• OSV API client


• Local SQLite cache


• Reporter (Terminal + HTML + JSON)


• Jinja2-based HTML template

The repository also includes:

• Pytest test suite


• GitHub Actions workflows


• Docker support


• Architecture documentation


• Contribution guidelines


• Metrics documentation

Minimal dependencies. Clear structure. Easy to review.

CI and Docker Support

GitHub Actions

Example workflows:

• Run scan on push and pull request


• Generate HTML + JSON reports


• Upload reports as workflow artifacts

Docker Usage

docker build -t vigil .

docker run --rm -v "$(pwd):/work" -w /work vigil

Reports are written into the mounted directory.

Alignment with Supply Chain Security Guidance

Vigil was built with reference to:

• Executive Order 14028 (Improving the Nation’s Cybersecurity)


• NIST Secure Software Development Framework (SP 800-218)


• CISA software supply chain security guidance

The emphasis is on:

• Dependency visibility
  


• Vulnerability identification
  


• Evidence-ready reporting
  


• Transparent tooling
  

Design Philosophy

1. Open data only
   


2. No hidden services
   


3. Reproducible results
   


4. Human-readable and machine-readable output
   


5. Minimal setup
   


6. Small-team friendly
   

Project Status

• Release: 0.2.x
  


• License: MIT
  


• Early-stage project
  


• Open to feedback and contributions
  

If you work in DevSecOps, open-source security, supply chain risk management, or compliance engineering, I welcome your thoughts and contributions.

GitHub: https://github.com/0x5A65726F677275/Vigil

Building resilient software supply chains requires practical, transparent tooling. Vigil is a focused step in that direction.