Vigil — An Open-Source Dependency Vulnerability Scanner

Source: Dev.to

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

Vigil is a lightweight, open‑source CLI tool that scans dependency files using the OSV database and generates evidence‑ready reports in HTML and JSON.

GitHub:

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 or proprietary databases

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

• 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 and severity (when available)
• References and remediation guidance
• Generation timestamp (UTC)
• Scanner version and 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

Contains metadata and detailed per‑package vulnerability entries.

Architecture Overview

Core components:

• 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

Emphasis on:

• Dependency visibility
• Vulnerability identification
• Evidence‑ready reporting
• Transparent tooling

Design Philosophy

• Open data only
• No hidden services
• Reproducible results
• Human‑readable and machine‑readable output
• Minimal setup
• 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, contributions are welcome.

GitHub:

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