Vulguard

A lightweight CLI security tool that automatically scans source code for vulnerabilities, highlights risky patterns, and guides developers toward safer implementations to strengthen their applications' overall security posture.

Prerequisites

• Python >=3.14
• An active GitHub Copilot subscription (used for AI-powered inspection)

Installation

pip install vulguard

Usage

vulguard [OPTIONS] COMMAND [ARGS]...

inspect — Scan files or directories

vulguard inspect [OPTIONS] PATHS...

Examples

# Scan all Python files in src/ and write a JSON report to ./reports
vulguard inspect src/ --ext py

# Scan multiple paths and produce an HTML report
vulguard inspect src/ tests/ --ext py,js --format html --output-dir reports

# Use a custom report name and database directory
vulguard inspect src/ --report my-scan --db-dir /tmp/vg-db

# Fail CI only on CRITICAL or MAJOR findings; MINOR is still reported
vulguard inspect src/ --severities CRITICAL,MAJOR

Exit Codes

By default all non-NONE severities (CRITICAL, MAJOR, MINOR) trigger exit code 1. Use --severities to restrict which levels count, for example to only fail a CI step on CRITICAL or MAJOR findings while still having MINOR issues appear in the report.

Severity Levels

Each inspected file is assigned one of four severity levels. Only files with a non-NONE severity are included in the report.

Configuration

On first run, vulguard bootstraps a configuration directory and copies its default config.ini and logging.ini there. You can override the location with the VULGUARD_CONFIG_DIR environment variable:

# Windows (PowerShell)
$env:VULGUARD_CONFIG_DIR = "C:\Users\you\.vulguard"

# macOS / Linux
export VULGUARD_CONFIG_DIR="$HOME/.vulguard"

config.ini settings

Development

Prerequisites

• Poetry 2.2+

Architecture

graph TD
    CLI["cli.py\n(Click entry point)"]
    Inspector["inspector.py\n(GitHub Copilot SDK)"]
    DB["db.py\n(SQLite persistence)"]
    Report["report.py\n(JSON / HTML output)"]
    Config["config.py\n(config.ini reader)"]
    Prompt["prompts/system-prompt.md\n(security prompt)"]

    CLI -->|"collects files\norchestrates"| Inspector
    CLI --> Config
    Inspector --> Prompt
    CLI -->|"persists results"| DB
    CLI -->|"reads session"| DB
    CLI -->|"builds & writes"| Report

Setup

poetry install

Format and Lint

poetry run black vulguard; poetry run pylint vulguard

Pylint must score 10.00/10 before committing.

Run Tests

poetry run pytest --cov=vulguard tests --cov-report html

Maintain ≥80 % coverage.

Fixture-based integration smoke test

poetry run vulguard inspect tests/fixtures --ext py --format html

Publishing to PyPI

Prerequisites

• A PyPI account with an API token.

Configure the token

poetry config pypi-token.pypi <your-token>

Build and publish

poetry publish --build

This builds the source distribution and wheel, then uploads them to PyPI in one step.

Note: PyPI releases are immutable. Once a version is published, it cannot be overwritten.
To fix a mistake, yank the release via the PyPI web UI and publish a new version.

Changelog

See CHANGELOG.md for the full release history.

License

This project is licensed under the MIT License.

Author

Ron Webb