Trace taint across your entire codebase. Before attackers do.

Installation

PySpector ships on PyPI as a hybrid Python/Rust package. The Python CLI orchestrates scans; the Rust core performs the analysis.

Prerequisites

Create a virtual environment

# Download Python 3.14, then:
$ python3.14 -m venv venv
$ source venv/bin/activate

# Download Python 3.14 from the Microsoft Store, then:
PS> python3.14 -m venv venv
PS> .\venv\Scripts\Activate.ps1
# or, depending on the installation source:
PS> .\venv\bin\Activate.ps1

Install from PyPI

$ pip install pyspector

Your first scan

The primary command is scan. It accepts a local file, a directory, or a remote Git repository.

$ pyspector scan [PATH or --url REPO_URL] [OPTIONS]

Common invocations

# Scan a local file or directory
$ pyspector scan /path/to/your/project

# Scan and save the report as HTML
$ pyspector scan /path/to/your/project -o report.html -f html

# Scan a public GitHub repository directly
$ pyspector scan --url https://github.com/username/repo.git

Wizard mode

New to SAST, or running PySpector in a classroom? The --wizard flag launches a guided, interactive scan setup, ideal for first-time users and students.

$ pyspector scan --wizard

Reading the results

Findings are reported with a severity, a rule ID, the file and line, and (for graph-engine findings) the full taint path from source to sink. Severities map to the following scale:

Use a severity threshold to keep noise out of CI, and the triage workflow to baseline accepted findings.

Taint analysis concepts

PySpector's graph engine models your application as data flowing between three kinds of program points. Understanding them makes findings (and false-positive triage) much easier to reason about.

How a finding is produced

1. Parse: each Python file is converted to a JSON AST by the CLI and handed to the Rust core via pyo3.
2. Map: the engine builds a project-wide call graph, so a value returned by a helper in utils.py is connected to its caller in views.py.
3. Model: every function becomes a Control Flow Graph: the analysis knows that an if branch which sanitizes input makes that branch safe, while the else branch may not be.
4. Propagate: a worklist algorithm iterates to a global fixed point, pushing taint through assignments, calls, and returns using context-aware function summaries.
5. Report: any taint that reaches a sink without passing a sanitizer becomes a finding, with the complete source → sink path attached.

CLI reference

PySpector exposes four top-level commands: scan, watch, triage, and plugin.

pyspector scan

pyspector watch

Continuous watch mode: PySpector runs a full initial scan, then re-scans whenever a .py file is created, modified, or deleted, printing only the NEW and RESOLVED findings after each pass.

$ pyspector watch ./src --severity MEDIUM --debounce 2

pyspector triage

pyspector plugin

Configuration file (pyspector.toml)

Project-level settings live under [tool.pyspector] and are loaded with -c pyspector.toml. Anything you set merges on top of the defaults:

[tool.pyspector]
severity = "MEDIUM"
exclude  = [".venv", "node_modules", "migrations", "*/generated/*"]

Sensible exclusions ship by default (.venv, .git, __pycache__, build, dist, node_modules, vendor, and common test-fixture patterns). PySpector also writes a .pyspector_cache directory next to the scan target: an incremental AST cache (plain JSON, never pickle) that makes repeat scans dramatically faster. It is safe to delete at any time and should stay out of version control.

Scan modes

AI / LLM security mode

Use --ai when scanning projects that integrate with Large Language Models or agent frameworks. The specialized ruleset targets the failure modes unique to AI applications: prompt injection paths, insecure tool invocation, and unintended data leakage into prompts or logs.

$ pyspector scan /path/to/your/project --ai

Supply-chain mode

Use --supply-chain to check the dependencies declared by your project against known CVEs: a fast first pass on the code you import rather than the code you wrote.

$ pyspector scan /path/to/your/project --supply-chain

Remote repository mode

Point PySpector at any public GitHub or GitLab repository and it will clone and analyze it in one step, useful for auditing third-party packages before adoption, or for security research at scale. The URL host is validated, so only github.com and gitlab.com repositories are accepted.

$ pyspector scan --url https://github.com/username/repo.git

Reports & SARIF

Select the output format with -f and a destination with -o. Three formats are supported, each suited to a different consumer:

SARIF 2.1.0 output

SARIF (Static Analysis Results Interchange Format) is the lingua franca of security tooling. PySpector results integrate directly with GitHub Code Scanning, GitHub Advanced Security, and any SAST aggregation platform.

{
  "version": "2.1.0",
  "runs": [{
    "tool": {
      "driver": {
        "name": "PySpector",
        "informationUri": "https://github.com/ParzivalHack/PySpector"
      }
    },
    "results": [{
      "ruleId": "PYSEC001",
      "level": "warning",
      "message": { "text": "Potential command injection detected" }
    }]
  }]
}

# Generate SARIF, then upload to GitHub Code Scanning
$ pyspector scan ./project -f sarif -o report.sarif

Triage & baselining

Real codebases accumulate accepted risk. The triage workflow lets you review findings once, mark them as ignored, and never see them again in subsequent scans.

# 1. Generate a JSON report
$ pyspector scan /path/to/your/project -o report.json -f json

# 2. Open the interactive triage TUI
$ pyspector triage report.json

Inside the TUI

The baseline file is loaded automatically on subsequent scans, so already-reviewed findings stay suppressed across your whole team and CI pipeline. Commit it alongside your code.

Plugin system

Plugins post-process findings, generate custom artifacts, or orchestrate follow-up actions after every scan. They run in-process once the Rust core returns the final issue list, so they see exactly the same normalized data that drives the built-in reports.

Lifecycle

1. Discovery: plugin files live in the repository's PySpector/plugins directory and are discovered automatically.
2. Registration: trusted plugins are recorded in plugin_registry.json with their checksum and metadata.
3. Validation: before execution, PySpector validates plugin configuration, statically inspects the source for dangerous APIs, and verifies the on-disk checksum.
4. Execution: the plugin is initialized, receives the full findings list, and may emit additional files or data. cleanup() is always called at the end.

Managing plugins from the CLI

$ pyspector plugin list                              # discovered plugins, trust status, version, author
$ pyspector plugin trust plugin_name                 # validate, checksum, mark as trusted
$ pyspector plugin info plugin_name                  # metadata + checksum verification
$ pyspector plugin install path/to/plugin.py --trust
$ pyspector plugin remove legacy_plugin

Only trusted plugins are executed automatically. When you trust a plugin, PySpector calculates its SHA256 checksum and stores the version, author, and description it declares via PluginMetadata. If the file is modified later, you are warned before it runs again.

Running plugins during a scan

$ pyspector scan vulnerableapp.py --plugin aipocgen --plugin-config ./PySpector/pluginconfig/aipocgen.json

The configuration file is a JSON object whose keys match plugin names. Each plugin receives only its own block:

{
  "aipocgen": {
    "api_key": "YOUR-GROQ-KEY",
    "model": "llama-3.3-70b",
    "severity_filter": ["HIGH", "CRITICAL"],
    "max_pocs": 5,
    "output_dir": "pocs",
    "dry_run": false
  }
}

Security model

• AST-based static inspection blocks dangerous constructs (eval, exec, subprocess.*) and warns on sensitive-but-acceptable calls like open.
• Trust workflow: a plugin must be explicitly trusted before it can run; validation warnings are surfaced in the CLI.
• Checksum verification: each trusted plugin has a stored SHA256 hash; any change is flagged before execution.
• Argument isolation: sys.argv is reset so Click-based plugins can't accidentally consume the parent CLI arguments.
• Structured error handling: exceptions are caught, traced, and reported without aborting the main scan; cleanup() still runs.

Authoring plugins

Create a Python file in ~/.pyspector/plugins/<name>.py and subclass PySpectorPlugin:

from pathlib import Path
from typing import Any, Dict, List

from pyspector.plugin_system import PySpectorPlugin, PluginMetadata


class MyPlugin(PySpectorPlugin):
    @property
    def metadata(self) -> PluginMetadata:
        return PluginMetadata(
            name="my_plugin",
            version="0.1.0",
            author="Your Name",
            description="Summarises HIGH severity findings",
            category="reporting",
        )

    def validate_config(self, config: Dict[str, Any]) -> tuple[bool, str]:
        if "output_file" not in config:
            return False, "output_file is required"
        return True, ""

    def initialize(self, config: Dict[str, Any]) -> bool:
        self.output = Path(config["output_file"]).resolve()
        return True

    def process_findings(self, findings, scan_path, **kwargs) -> Dict[str, Any]:
        highs = [f for f in findings if f.get("severity") == "HIGH"]
        self.output.write_text(f"{len(highs)} HIGH findings\n", encoding="utf-8")
        return {
            "success": True,
            "message": f"Summarised {len(highs)} HIGH findings",
            "output_files": [str(self.output)],
        }

Required interface

Best practices

• Store API keys and long-lived secrets in environment variables and read them during initialize; give helpful errors when credentials are missing.
• Keep side-effects inside the scan directory. When scanning a single file, scan_path is that file, so switch to scan_path.parent before writing outputs.
• Validate configuration early with validate_config; PySpector surfaces the message in the CLI without executing the plugin.
• Return meaningful message values and populate output_files so automation can pick up generated artifacts.
• Support a dry_run switch (see the bundled aipocgen plugin) for air-gapped testing.

Writing custom rules

Rules define what the engine looks for. They live as TOML files in src/pyspector/rules/, are loaded at runtime, and are applied uniformly across every scanned file. There are three kinds:

A minimal AST rule looks like this:

[[rule]]
id          = "PY200"
description = "Use of eval() detected."
severity    = "High"
remediation = "Avoid eval(). Use ast.literal_eval or explicit parsing."
ast_match   = "Call(func.id=eval)"

Useful fields when authoring rules:

New rules are welcome through the contribution flow below. Include a clear description, a severity, and helpful remediation advice with every rule you add.

CI/CD & automation

PySpector is built for pipelines: fast enough to run on every commit, SARIF-native for platform integration, and shipped with helper scripts for local guardrails.

GitHub Code Scanning

Generate SARIF in your workflow and upload it so findings appear directly in pull requests and the repository security dashboard:

name: PySpector
on: [push, pull_request]
jobs:
  sast:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - uses: dtolnay/rust-toolchain@stable
      - run: pip install pyspector
      - run: pyspector scan . -f sarif -o report.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: report.sarif

Git pre-commit hook

Block commits that introduce new HIGH or CRITICAL issues. The setup script creates an executable .git/hooks/pre-commit that scans staged Python files:

# From the root of your Git repository:
$ ./scripts/setup_hooks.sh

# Bypass for a specific commit if you must:
$ git commit --no-verify

pre-commit framework

If your team uses the pre-commit framework, add PySpector as a local hook so it runs on staged Python files alongside your other checks:

repos:
  - repo: local
    hooks:
      - id: pyspector
        name: PySpector SAST
        entry: pyspector
        args: ["scan", "."]
        language: system
        types: [python]

The bundled ./scripts/setup_hooks.sh takes the stricter route: it installs a raw Git hook that scans only the staged files with --severity HIGH and blocks the commit on any HIGH or CRITICAL finding (bypass with git commit --no-verify).

Scheduled scans with cron

For continuous monitoring outside CI, an interactive script generates the right crontab entry for your project:

$ ./scripts/setup_cron.sh

REST API & Docker

PySpector also ships a small Rust HTTP service (pyspector-api, built on actix-web) that exposes scanning over the network. It accepts POST /scan on port 10000 with a JSON body and is rate-limited (12 requests/second, burst of 5):

$ curl -X POST http://localhost:10000/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "...", "ai": false, "json_output": true}'

The body takes either url (a public repo to clone) or path (a server-side directory), plus the ai and json_output booleans. A Dockerfile is included to build and run the service in a container:

$ docker build -t pyspector-api .
$ docker run -p 10000:10000 pyspector-api

Contributing

Every contribution helps make Python code safer: bug reports, feature ideas, new detection rules, documentation, and improvements to the Python or Rust core are all welcome. The full guide lives in CONTRIBUTING.md, and the project follows a Contributor Covenant code of conduct.

Development setup

You need Python 3.9+ (3.14 recommended) and the Rust toolchain via rustup. Installing in editable mode compiles the Rust engine and lets you iterate without reinstalling:

# Fork PySpector, then clone your fork:
$ git clone https://github.com/YOURUSERNAME/PySpector.git
$ cd PySpector
$ python3.14 -m venv venv && source venv/bin/activate
$ pip install -e .   # compiles the Rust core
$ pyspector --help

Before opening a PR

Run the test suite and the quality gates; the same checks run in CI and as pre-commit hooks:

$ python -m unittest discover tests/unit -v   # unit tests
$ ruff check src/ && ruff format src/          # lint + format
$ mypy src/                                    # type checks

Then create a feature branch, commit with a clear message (the repo uses conventional commits, e.g. feat: add rule for insecure cookie settings), push to your fork, and open a pull request describing what you changed. Adding new detection rules (see Writing custom rules) is one of the highest-impact ways to contribute.

Frequently asked questions