High-Performance Python/Rust Graph-Based SAST Framework

PySpector is a State-of-the-Art Static Analysis Security Testing (SAST) framework, built in Rust for next-gen performances, made for modern Python projects and large codebases. Unlike traditional linters, PySpector utilizes a Flow-Sensitive, Inter-Procedural Taint Engine to track untrusted data across complex function boundaries and control flow structures.

By compiling the core analysis engine to a native binary, PySpector avoids the performance limitations of traditional Python-only tools. This makes it well-suited for CI/CD pipelines and local development environments where speed and scalability matter.

PySpector is designed to be both comprehensive and intuitive, offering a multi-layered analysis approach that goes beyond simple pattern matching to understand the structure and data flow of your Python application.

Table of Contents

• Quick Demo
• Getting Started
• Key Features
• Core Engine Architecture
• How It Works
• Performance Benchmarks
• Usage
• Triaging and Baselining
• Automation and Integration
• SARIF Output and Security Tool Integration
• Frequently Asked Questions

Quick Demo

https://github.com/user-attachments/assets/0fe03961-0b62-4964-83ba-849f2357efba

Getting Started

Prerequisites

• Python: Python 3.9 – 3.14 supported (Python 3.9 or newer, up to 3.14).
• Rust: The Rust compiler (rustc) and Cargo package manager are required. You can easily install the Rust toolchain via rustup and verify your installation by running cargo --version.

Installation

It is highly recommended to install PySpector in a dedicated Python 3.14 venv.

Create a Virtual Environment:

• Linux (Bash):

bash # Download Python 3.14 python3.14 -m venv venv source venv/bin/activate

• Windows (PowerShell):

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

With PySpector now officially on PyPI🎉, installation is as simple as running:

pip install pyspector

Key Features

• Flow-Sensitive Analysis: Utilizes a Control Flow Graph (CFG) to track variable states sequentially, accurately distinguishing between safe and vulnerable code paths.

• Inter-Procedural Taint Tracking: Propagates untrusted data across function boundaries using global fixed-point iteration and function summaries.

• Context-Aware Summaries: Sophisticated mapping of which function parameters flow to return values, allowing for high-precision tracking through complex utility functions.

• Multi-Engine Hybrid Scanning:

• Regex Engine: High-speed scanning for secrets, hardcoded credentials, and configuration errors.

• AST Engine: Deep structural pattern matching to find Python-specific anti-patterns.

• Graph Engine: Advanced CFG and Call-Graph-based data flow analysis for complex vulnerability chains.

• Fastest Market Performances: Core analysis engine implemented in Rust with Rayon for multi-threaded parallelization (allowing PySpector to scan 71% faster than Bandit, and 16.6x faster than Semgrep).

• AI-Agent Security: Specialized rulesets designed to identify prompt injection, insecure tool use, and data leakage in LLM-integrated Python applications.

Core Engine Architecture

PySpector v0.1.5 represents a shift from partially-static pattern matching, to a full graph-based analysis engine:

1. AST Parsing: Python source is converted into a structured JSON AST, for semantic analysis.
2. Call Graph Construction: PySpector builds a project-wide map of function definitions, and call sites to enable cross-file analysis.
3. CFG Generation: Each function is decomposed into a Control Flow Graph (CFG), allowing the engine to understand the order of operations and conditional Python logic.
4. Fixed-Point Taint Propagation: Using a Worklist Algorithm, the engine propagates "taint" from defined Sources to Sinks, while respecting Sanitizers that clean the data along the way.

How It Works

PySpector's hybrid architecture is key to its performance and effectiveness.

• Python CLI Orchestration: The process begins with the Python-based CLI. It handles command-line arguments, loads the configuration and rules, and prepares the target files for analysis. For each Python file, it uses the native ast module to generate an Abstract Syntax Tree, which is then serialized to JSON.

• Invocation of the Rust Core: The serialized ASTs, along with the ruleset and configuration, are passed to the compiled Rust core. The handoff from Python to Rust is managed by the pyo3 library.

• Parallel Analysis in Rust: The Rust engine takes over and performs the heavy lifting. It leverages the rayon crate to execute file scans and analysis in parallel, maximizing the use of available CPU cores. It builds a complete call graph of the application to understand inter-file function calls, which is essential for the taint analysis module.

• Results and Reporting: Once the analysis is complete, the Rust core returns a structured list of findings to the Python CLI. The Python wrapper then handles the final steps of filtering the results based on the severity threshold and the baseline file, and generating the report in the user-specified format.

This architecture combines the best of both worlds: a flexible, user-friendly interface in Python and a high-performance, memory-safe analysis engine in Rust :)

Performance Benchmarks

Performance benchmarks demonstrate PySpector's competitive advantages in SAST scanning speed while maintaining comprehensive security analysis.

Performance benchmarks were executed in a deterministic and controlled environment using automated stress-testing scripts, ensuring repeatable and unbiased measurements

Benchmark Results

Comparative analysis across major Python codebases (Django, Flask, Pandas, Scikit-learn, Requests) shows:

Metric	PySpector	Bandit	Semgrep
Throughput	25,607 lines/sec	14,927 lines/sec	1,538 lines/sec
Performance Advantage	71% faster than Bandit	Baseline	16.6x slower
Memory Usage	1.4 GB average	111 MB average	277 MB average
CPU Utilization	120% (multi-core)	100% (single-core)	40%

Key Performance Characteristics

• Speed: Delivers 71% faster scanning than traditional tools through Rust-powered parallel analysis
• Scalability: Maintains high throughput on large codebases (500k+ lines of code)
• Resource Profile: Optimized for modern multi-core environments with adequate memory allocation
• Consistency: Stable performance across different project types and sizes

System Requirements for Optimal Performance

• Minimum: 2 CPU cores, 2 GB RAM
• Recommended: 4+ CPU cores, 4+ GB RAM for large codebases
• Storage: SSD recommended for large repository scanning

Benchmark Methodology

Performance testing conducted on:

• Test Environment: Debian-based Linux VM (2 cores, 4GB RAM)
• Test Projects: 5 major Python repositories (13k-530k lines of code)
• Measurement: Average of multiple runs with CPU settling periods
• Comparison: Head-to-head against Bandit and Semgrep using identical configurations

Benchmark data available in the project repository for transparency and reproducibility.

Usage

PySpector is operated through a straightforward command-line interface.

Running a Scan

The primary command is scan, which can target a local file, a directory, or even a remote Git repository.

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

Examples:

• Scan a single file

pyspector scan /path/to/your/project

• Scan a local directory and save the report as HTML:

pyspector scan /path/to/your/project -o report.html -f html

• Scan a public GitHub repository:

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

Wizard Mode for Beginners

• Use the --wizard flag to enter the guided scan mode, perfect for 1st time users and beginners or students:

pyspector scan --wizard

Watching for Changes

The watch command continuously monitors a directory or file and re-runs the scan whenever a .py file is created, modified, or deleted, ideal for real-time feedback during development.

```bash pyspector watch [PATH]