vigilo 0.1.0__tar.gz

vigilo-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,25 @@
+---
+name: Bug report
+about: Create a report to help us improve Vigilo
+title: '[BUG] '
+labels: 'bug'
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Sample Code to Reproduce**
+Code snippet where the false positive, false negative, or crash occurred:
+
+```python
+# Paste snippet here
+```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Vigilo Version & Environment**
+- Vigilo version (`vigilo --version`):
+- Python version (`python --version`):
+- Operating System:

vigilo-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,27 @@
+---
+name: Feature / Detector request
+about: Suggest an idea, detector, or rule for Vigilo
+title: '[FEAT] '
+labels: 'enhancement'
+assignees: ''
+---
+
+**Is your feature request related to a problem or new CWE? Please describe.**
+A clear and concise description of the security pattern or feature.
+
+**Target CWE (if applicable)**
+- CWE-ID: (e.g. CWE-79, CWE-918)
+- Vulnerable APIs:
+
+**Example Vulnerable Code**
+```python
+# Code that should be detected
+```
+
+**Example Safe Code (to prevent False Positives)**
+```python
+# Code that should NOT be detected
+```
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.

vigilo-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Description
+
+Provide a brief summary of the changes introduced in this PR.
+
+## Type of Change
+
+- [ ] New vulnerability detector (CWE)
+- [ ] Bug fix / False positive reduction
+- [ ] Documentation update
+- [ ] Performance improvement
+- [ ] Infrastructure / CI update
+
+## Checklist
+
+- [ ] My code follows the code style and formatting (`ruff check .`, `ruff format .`).
+- [ ] Static type checking passes (`mypy src`).
+- [ ] I have added tests that prove my fix or detector works (`python -m unittest discover -s tests`).
+- [ ] All new and existing tests pass.
+- [ ] Updated relevant documentation or `CHANGELOG.md` if applicable.

vigilo-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }} (Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      - name: Lint and format check with ruff
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Type check with mypy
+        run: |
+          mypy src
+
+      - name: Run test suite
+        run: |
+          python -m unittest discover -s tests

vigilo-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,149 @@
+name: Release & Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build-pypi:
+    name: Build sdist & wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build and twine
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build distribution packages
+        run: python -m build
+
+      - name: Verify packages with twine
+        run: twine check --strict dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [build-pypi]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/vigilo
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  build-executables:
+    name: Build Standalone Binary (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            bin_name: vigilo-linux-x86_64
+            ext: ""
+          - os: macos-latest
+            bin_name: vigilo-macos
+            ext: ""
+          - os: windows-latest
+            bin_name: vigilo-windows-x86_64
+            ext: ".exe"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies & PyInstaller
+        run: |
+          python -m pip install --upgrade pip
+          pip install pyinstaller .
+
+      - name: Build binary with PyInstaller
+        run: |
+          pyinstaller --onefile --clean --name vigilo src/vigilo/cli.py
+
+      - name: Rename and move binary (Unix)
+        if: runner.os != 'Windows'
+        run: |
+          mkdir -p bin_dist
+          mv dist/vigilo bin_dist/${{ matrix.bin_name }}${{ matrix.ext }}
+          chmod +x bin_dist/${{ matrix.bin_name }}${{ matrix.ext }}
+
+      - name: Rename and move binary (Windows)
+        if: runner.os == 'Windows'
+        shell: bash
+        run: |
+          mkdir -p bin_dist
+          mv dist/vigilo.exe bin_dist/${{ matrix.bin_name }}${{ matrix.ext }}
+
+      - name: Upload binary artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.os }}
+          path: bin_dist/
+
+  create-github-release:
+    name: Create GitHub Release
+    needs: [build-pypi, build-executables]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download PyPI dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: release-assets/
+
+      - name: Download all binary artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: binary-*
+          path: release-binaries/
+          merge-multiple: true
+
+      - name: Assemble release assets & compute checksums
+        run: |
+          mkdir -p release-assets/
+          cp release-binaries/* release-assets/ || true
+          cd release-assets
+          sha256sum * > SHA256SUMS.txt
+          cat SHA256SUMS.txt
+
+      - name: Publish GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release-assets/*
+          generate_release_notes: true

vigilo-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Type checker / linter caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Internal dev tracking docs (kept locally, not public)
+DECISIONS.md
+WORKFLOW.md
+TIMELINE.md
+TECH_STACK.md

vigilo-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2026-09-05
+
+### Added
+- **Core Engine:**
+  - Fast AST parsing and safe file discovery with default exclude rules.
+  - `FlowAnalyzer` providing local scope tracking, constant evaluation, and parameter taint discrimination.
+  - Extensible `BaseDetector` architecture.
+- **Vulnerability Detectors:**
+  - `VIGILO-001` (CWE-89): SQL Injection detector for raw, formatted, and unparameterized SQL queries.
+  - `VIGILO-002` (CWE-78): OS Command Injection detector for `subprocess.*(shell=True)` and `os.system`/`os.popen`.
+  - `VIGILO-003` (CWE-94): Code Injection detector for `eval()`, `exec()`, and `compile()`.
+  - `VIGILO-004` (CWE-502): Unsafe Deserialization detector for `pickle`, `marshal`, and unsafe `yaml.load()`.
+  - `VIGILO-005` (CWE-22): Path Traversal detector for dynamic file opening and filesystem access.
+- **Command-Line Interface:**
+  - `vigilo scan <path>` and `vigilo <path>` alias commands.
+  - ANSI colored text output report with line markers, confidence tags, and fix guidance.
+  - Structured `--format json` output option for CI/CD integrations.
+  - Severity threshold filtering (`--min-severity`).
+  - Glob exclusion flags (`--exclude`).
+  - Standard exit codes (0 = clean, 1 = vulnerabilities found, 2 = error).
+- **Public Python API:**
+  - `vigilo.scan(path, min_severity, exclude_patterns)` convenience function.
+  - Re-exported data models: `Scanner`, `ScanConfig`, `Finding`, `Severity`, `Location`, `DetectorMeta`.

vigilo-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,62 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at sanjiv215@users.noreply.github.com. All
+complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+
+[homepage]: https://www.contributor-covenant.org

vigilo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Vigilo
+
+Thank you for contributing to Vigilo! This document outlines our development workflows and guidelines.
+
+---
+
+## Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/Sanjiv215/VIGILO-Python-Package.git
+   cd VIGILO-Python-Package
+   ```
+
+2. **Create a virtual environment (Python 3.10+):**
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate
+   ```
+
+3. **Install in editable mode with development dependencies:**
+   ```bash
+   pip install -e .[dev]
+   ```
+
+---
+
+## Running Tests & Quality Checks
+
+Ensure all tests, linters, and type checkers pass before submitting a Pull Request:
+
+```bash
+# Run unit tests
+python -m unittest discover -s tests
+
+# Run linter and check formatting
+ruff check .
+ruff format --check .
+
+# Run static type checker
+mypy src
+```
+
+---
+
+## Adding a New Vulnerability Detector
+
+To add a new vulnerability detector:
+
+1. **Create a new detector file** in `src/vigilo/detectors/<detector_name>.py`:
+   - Subclass `BaseDetector` from `vigilo.detectors.base`.
+   - Define class attribute `meta = DetectorMeta(id="VIGILO-XXX", name="...", cwe=..., description="...", severity=Severity.HIGH)`.
+   - Implement `run(tree, file_path, source) -> list[Finding]`.
+   - Use `FlowAnalyzer.is_dynamic()` or `FlowAnalyzer.is_constant()` to eliminate false positives.
+
+2. **Register the detector** in `src/vigilo/detectors/__init__.py`:
+   - Add the detector class to `ALL_DETECTORS`.
+
+3. **Add comprehensive unit tests** in `tests/detectors/test_<detector_name>.py`:
+   - Include test cases for **True Positives** (flawed code that must trigger).
+   - Include test cases for **True Negatives** (safe idioms that must NOT trigger).
+
+---
+
+## Commit Message Convention
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` New features or detectors
+- `fix:` Bug fixes
+- `docs:` Documentation updates
+- `test:` Adding or updating tests
+- `chore:` Maintenance, dependency updates, packaging
+- `ci:` CI/CD workflow updates
+- `refactor:` Code improvements without feature changes

vigilo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjiv - Vigilo
+
+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.

vigilo-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.5
+Name: vigilo
+Version: 0.1.0
+Summary: A fast, zero-configuration static security scanner that detects known vulnerability patterns in Python codebases.
+Author: Sanjiv
+License: MIT
+License-File: LICENSE
+Keywords: cwe,sast,security,security-tools,static-analysis,vigilo,vulnerability-scanner
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Vigilo
+
+[![CI](https://github.com/Sanjiv215/VIGILO-Python-Package/actions/workflows/ci.yml/badge.svg)](https://github.com/Sanjiv215/VIGILO-Python-Package/actions)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![PyPI version](https://img.shields.io/pypi/v/vigilo.svg)](https://pypi.org/project/vigilo/)
+
+**Vigilo** is a fast, zero-configuration static security scanner for Python. It detects exploitable vulnerability patterns (CWEs) in first-party code using AST traversal combined with local data-flow analysis to minimize false positives.
+
+Runs across **Linux**, **macOS**, and **Windows** — either via `pip` or as a standalone binary with **no Python installation required**.
+
+---
+
+## Why Vigilo?
+
+- **High-Signal over High-Noise:** Traditional linters (like Bandit) flag safe string constants and standard library calls indiscriminately. Vigilo uses local data-flow analysis to distinguish harmless constants from untrusted dynamic inputs.
+- **Zero Configuration:** Drop it directly into your workflow or CI pipeline with `vigilo scan .` or `vigilo .`. No YAML rule authoring or database setup required.
+- **Zero Runtime Dependencies:** Built strictly on Python's standard library. Lightweight and instantaneous.
+- **First-Party Code Focus:** While tools like `pip-audit` scan third-party dependencies for CVEs, Vigilo scans *your* code for logic and injection flaws.
+
+---
+
+## Installation & Quickstart
+
+### Option A: Install via PyPI (Python 3.10+)
+
+```bash
+pip install vigilo
+```
+
+### Option B: Standalone Executable (No Python Required)
+
+Pre-built standalone single-file executables are available for Linux, macOS, and Windows on the [Releases Page](https://github.com/Sanjiv215/VIGILO-Python-Package/releases):
+
+- **Linux (x86_64):** `vigilo-linux-x86_64`
+- **macOS:** `vigilo-macos`
+- **Windows (x86_64):** `vigilo-windows-x86_64.exe`
+
+#### Verifying Checksums
+
+Every release includes a `SHA256SUMS.txt` file to verify binary integrity:
+
+```bash
+# Verify checksum on Linux/macOS
+sha256sum -c SHA256SUMS.txt
+```
+
+> **Note on Antivirus Alerts:** Standalone executables are bundled with PyInstaller. Some heuristic antivirus engines or Windows SmartScreen may occasionally flag newly published PyInstaller binaries as unfamiliar. This is a known false positive with packed binaries. You can verify the integrity using the SHA256 checksum or install via `pip install vigilo` to run from source.
+
+---
+
+## Usage
+
+Scan the current directory:
+
+```bash
+vigilo scan .
+```
+
+Or use the shortcut alias:
+
+```bash
+vigilo .
+```
+
+Generate structured JSON output for CI/CD pipelines:
+
+```bash
+vigilo scan . --format json
+```
+
+Filter by minimum severity:
+
+```bash
+vigilo scan . --min-severity high
+```
+
+Exclude specific directories or glob patterns:
+
+```bash
+vigilo scan . --exclude "tests/*" --exclude "migrations/*"
+```
+
+### Python API
+
+```python
+from vigilo import scan
+
+findings = scan("src/")
+
+for finding in findings:
+    print(f"[{finding.severity.upper()}] {finding.detector.id} {finding.detector.name}")
+    print(f"  Location: {finding.location}")
+    print(f"  Fix: {finding.fix_hint}")
+```
+
+---
+
+## Supported Detectors
+
+| ID | CWE | Vulnerability | Severity | Target APIs |
+|---|---|---|---|---|
+| **`VIGILO-001`** | CWE-89 | SQL Injection | `HIGH` | `db.execute()`, `cursor.execute()`, `text()`, `raw()` |
+| **`VIGILO-002`** | CWE-78 | OS Command Injection | `HIGH` | `subprocess.*(shell=True)`, `os.system()`, `os.popen()` |
+| **`VIGILO-003`** | CWE-94 | Code Injection | `HIGH` | `eval()`, `exec()`, `compile()` |
+| **`VIGILO-004`** | CWE-502 | Unsafe Deserialization | `HIGH` | `pickle.loads()`, `yaml.load()`, `marshal.loads()` |
+| **`VIGILO-005`** | CWE-22 | Path Traversal | `HIGH` | `open()`, `os.open()`, `io.open()` |
+
+---
+
+## CLI Reference
+
+```
+usage: vigilo [-h] [--version] {scan} ... [target] [--format {text,json}]
+              [--min-severity {low,medium,high}] [--exclude EXCLUDE] [--no-color]
+
+Options:
+  target                Directory or file to scan (default: '.')
+  --format, -f          Output report format: 'text' or 'json' (default: 'text')
+  --min-severity, -s    Minimum severity threshold: 'low', 'medium', 'high' (default: 'low')
+  --exclude, -e         Exclude path matching glob pattern (repeatable)
+  --no-color            Disable ANSI terminal coloring
+  --version, -V         Show version and exit
+  --help, -h            Show help and exit
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Clean — no vulnerabilities found at or above `--min-severity` |
+| `1` | Vulnerabilities detected |
+| `2` | Execution or path error |
+
+---
+
+## Contributing
+
+We welcome contributions! Please review our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).
+
+---
+
+## License
+
+Distributed under the [MIT License](LICENSE). Copyright (c) 2026 Sanjiv - Vigilo.