vulguard 1.1.1

A lightweight 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.

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

Option	Default	Description
PATHS	(required)	One or more files or directories to scan (recursive).
--ext TEXT	(all files)	Comma-separated extensions to inspect, e.g. py,js,ts.
--output-dir PATH	<cwd>/reports	Directory where reports are written.
--report TEXT	vulguard-report	Base filename for the report (no extension appended).
--format [json|html]	json	Report format. Selecting html also produces a JSON file.
--db-dir PATH	~/.vulguard	Directory for the SQLite session database.

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

Exit Codes

Code	Meaning
0	Inspection completed — no vulnerabilities found.
1	Inspection completed — one or more vulnerabilities detected.

This makes it straightforward to fail a CI pipeline step when security issues are present.

Severity Levels

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

Level	Description
CRITICAL	Immediate exploitation risk — e.g., SQL injection, command injection, hardcoded secrets/passwords/tokens, authentication bypass, remote code execution.
MAJOR	High-risk issues that can lead to data exposure or unauthorized access — e.g., logging entire request payloads or sensitive user data, logging full exception objects or stack traces, insecure deserialization, path traversal, cross-site scripting without output encoding, CSRF on state-changing endpoints.
MINOR	Lower-risk issues that could become vulnerabilities under certain conditions — e.g., overly verbose error messages, weak cryptography (MD5/SHA1 for security purposes), missing input validation, use of deprecated security APIs, storing sensitive data in cookies without Secure/HttpOnly flags.
NONE	No security vulnerabilities detected. Files with this severity are excluded from 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

Section	Key	Default	Description
model	model	claude-sonnet-4.6	GitHub Copilot model used for inspection.
model	timeout	300	Per-file inspection timeout in seconds.
retry	max-attempts	5	Maximum number of retry attempts on transient errors.
retry	base-delay	0.5	Initial back-off delay in seconds.
retry	max-delay	10.0	Maximum back-off delay in seconds.

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