vulguard 1.0.0__tar.gz

vulguard-1.0.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 - 2026-06-14
+
+### Added
+
+- Initial release of vulguard.
+- Lightweight security scanning for source code vulnerabilities.
+- Highlights risky patterns and guides developers toward safer implementations.
+- GitHub Actions **Tests** workflow for automated formatting check, linting, and test runs (with 80% coverage gate) on every push and pull request.
+- Async retry mechanism with exponential back-off and full jitter (`vulguard/retry.py`).
+- `--version` / `-V` CLI flag to display the installed package version.
+- Concurrent file inspection using `asyncio.gather()` for improved throughput.
+- `_inspect_and_persist()` helper decomposing per-file inspection and database persistence.
+- `_inspect_all()` helper orchestrating concurrent per-file inspection tasks.
+- `_run_inspection()` helper orchestrating file collection, inspection, and report writing.
+- `_setup_db_session()` helper encapsulating database initialisation and session creation.
+- `_write_reports()` helper encapsulating JSON and HTML report writing.
+- Additional configuration keys in `config.ini` for model name, timeout, and retry back-off settings (`max-attempts`, `base-delay`, `max-delay`).
+- Typed accessors in the `Config` class for model, timeout, and retry back-off configuration (`get_model`, `get_timeout`, `get_max_attempts`, `get_base_delay`, `get_max_delay`).
+- Expanded test suite covering `retry.py` and additional cases for `cli.py` and `inspector.py`.
+

vulguard-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ron Webb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vulguard-1.0.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: vulguard
+Version: 1.0.0
+Summary: 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.
+License: MIT License
+         
+         Copyright (c) 2026 Ron Webb
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Author: Ron Webb
+Author-email: ron@ronella.xyz
+Requires-Python: >=3.14
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click (>=8.0.0,<9.0.0)
+Requires-Dist: env-dir-bootstrap (>=1.0.0,<2.0.0)
+Requires-Dist: github-copilot-sdk (>=1.0.1,<2.0.0)
+Requires-Dist: logenrich (>=1.0.1,<2.0.0)
+Requires-Dist: rich (>=15.0.0,<16.0.0)
+Project-URL: Repository, https://github.com/rcw3bb/vulguard
+Description-Content-Type: text/markdown
+
+# vulguard 1.0.0
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
+
+> 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](https://github.com/features/copilot) subscription (used for AI-powered inspection)
+
+## Installation
+
+```bash
+pip install vulguard
+```
+
+## Usage
+
+```bash
+vulguard [OPTIONS] COMMAND [ARGS]...
+```
+
+### `inspect` — Scan files or directories
+
+```bash
+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
+
+```bash
+# 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
+```
+
+## 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:
+
+```bash
+# 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
+
+```mermaid
+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
+
+```bash
+poetry install
+```
+
+### Format and Lint
+
+```bash
+poetry run black vulguard; poetry run pylint vulguard
+```
+
+Pylint must score **10.00/10** before committing.
+
+### Run Tests
+
+```bash
+poetry run pytest --cov=vulguard tests --cov-report html
+```
+
+Maintain **≥80 %** coverage.
+
+### Fixture-based integration smoke test
+
+```bash
+poetry run vulguard inspect tests/fixtures --ext py --format html
+```
+
+## Publishing to PyPI
+
+### Prerequisites
+
+- A [PyPI](https://pypi.org/) account with an API token.
+
+### Configure the token
+
+```bash
+poetry config pypi-token.pypi <your-token>
+```
+
+### Build and publish
+
+```bash
+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](CHANGELOG.md)
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Author
+
+Ron Webb
+

vulguard-1.0.0/README.md

@@ -0,0 +1,161 @@
+# vulguard 1.0.0
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](CHANGELOG.md)
+
+> 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](https://github.com/features/copilot) subscription (used for AI-powered inspection)
+
+## Installation
+
+```bash
+pip install vulguard
+```
+
+## Usage
+
+```bash
+vulguard [OPTIONS] COMMAND [ARGS]...
+```
+
+### `inspect` — Scan files or directories
+
+```bash
+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
+
+```bash
+# 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
+```
+
+## 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:
+
+```bash
+# 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
+
+```mermaid
+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
+
+```bash
+poetry install
+```
+
+### Format and Lint
+
+```bash
+poetry run black vulguard; poetry run pylint vulguard
+```
+
+Pylint must score **10.00/10** before committing.
+
+### Run Tests
+
+```bash
+poetry run pytest --cov=vulguard tests --cov-report html
+```
+
+Maintain **≥80 %** coverage.
+
+### Fixture-based integration smoke test
+
+```bash
+poetry run vulguard inspect tests/fixtures --ext py --format html
+```
+
+## Publishing to PyPI
+
+### Prerequisites
+
+- A [PyPI](https://pypi.org/) account with an API token.
+
+### Configure the token
+
+```bash
+poetry config pypi-token.pypi <your-token>
+```
+
+### Build and publish
+
+```bash
+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](CHANGELOG.md)
+
+See [CHANGELOG.md](CHANGELOG.md) for the full release history.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Author
+
+Ron Webb

vulguard-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "vulguard"
+version = "1.0.0"
+description = "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."
+authors = [
+    {name = "Ron Webb", email = "ron@ronella.xyz"}
+]
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.14"
+
+dependencies = [
+    "rich (>=15.0.0,<16.0.0)",
+    "click (>=8.0.0,<9.0.0)",
+    "logenrich (>=1.0.1,<2.0.0)",
+    "env-dir-bootstrap (>=1.0.0,<2.0.0)",
+    "github-copilot-sdk (>=1.0.1,<2.0.0)"
+]
+
+[project.urls]
+Repository = "https://github.com/rcw3bb/vulguard"
+
+[dependency-groups]
+dev = [
+    "black (>=26.5.1,<27.0.0)",
+    "pylint (>=4.0.5,<5.0.0)",
+    "pytest (>=9.0.3,<10.0.0)",
+    "pytest-cov (>=7.1.0,<8.0.0)",
+    "pytest-asyncio (>=1.4.0,<2.0.0)"
+]
+
+[tool.poetry]
+packages = [{include = "vulguard"}]
+include = ["vulguard/logging.ini", "vulguard/config.ini", "vulguard/prompts/system-prompt.md", "CHANGELOG.md"]
+
+[tool.poetry.scripts]
+vulguard = "vulguard.cli:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

vulguard-1.0.0/vulguard/__init__.py

@@ -0,0 +1,22 @@
+"""
+vulguard - 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.
+
+:author: Ron Webb
+:since: 1.0.0
+"""
+
+from env_dir_bootstrap import EnvDirBootstrap
+
+__version__ = "1.0.0"
+
+_bootstrapper = EnvDirBootstrap(
+    env_var="VULGUARD_CONFIG_DIR",
+    resources=["logging.ini", "config.ini"],
+    package="vulguard",
+)
+
+_bootstrapper.setup()
+
+CONF_DIR = str(_bootstrapper.get_dir())