Pyspector Security Audit

PySpector Security Audit

Drive an end-to-end Python codebase security audit with PySpector: install, verify, learn the CLI, recon the codebase, scan with the right flags, verify, report.

PySpector is a Rust-core, Python-CLI SAST tool with a flow-sensitive, inter-procedural taint engine. Its ruleset spans regex (secrets/config), AST (anti-patterns), and graph/taint (data-flow vulnerability chains), plus optional AI/LLM-specific rules and dependency CVE checks. Full project context: https://github.com/ParzivalHack/PySpector

Workflow overview

1. Check for an existing install; install if missing (including Rust)
2. Confirm the install actually works
3. Read pyspector --help and pyspector scan --help to get the real, current flag set. Never assume flags from this document alone
4. Recon the target codebase to decide which optional rulesets apply
5. Run the scan(s) with the right flags
6. Statically re-verify the findings that matter before reporting anything
7. Produce the report (HTML for a human, JSON if something downstream will parse it) and only show the user verified true positives

Treat steps 3 and 4 as mandatory even if you already "know" PySpector's flags from a previous run. The tool evolves, and --help output is ground truth. Never fabricate a flag that didn't show up in --help.

Step 1: Check for / install PySpector

Check first:

pyspector --version || pip show pyspector

If it's missing, PySpector's own docs say the supported path is PyPI, not manual OS-specific binary downloads. There's no separate per-OS release artifact to fetch; pip install pyspector builds/pulls the right thing for the current platform. So "install it based on the OS the agent is running on" in practice means: pick the right shell/venv invocation for the OS, not a different download URL.

Rust toolchain (hard requirement). PySpector's Rust core means rustc and cargo must be present, the project's own FAQ states this explicitly. Check first, install only if missing.

On Linux/macOS:

cargo --version || (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y && source "$HOME/.cargo/env")

On Windows: first check whether rustc/cargo are already available. If not, check whether a rustup-init.exe installer is already present on the system (e.g. in the user's Downloads folder or a known path); if it is, run it. If no installer is present and you don't have shell access to the user's machine to download and run one yourself, don't try to fetch and execute an installer silently: direct the user to https://rustup.rs/ and ask them to download and run it themselves, then confirm back with you once it's done so you can proceed to verification.

Python. PySpector supports Python 3.9 to 3.14. The project recommends a dedicated venv (3.14 if available, but any supported version works):

python3 -m venv venv
source venv/bin/activate   # Windows: .\venv\Scripts\Activate.ps1
pip install --upgrade pip
pip install pyspector

If a venv isn't appropriate for the environment you're in (e.g. an ephemeral agent sandbox), a plain pip install pyspector --break-system-packages (Linux) or pip install pyspector is fine. The venv is a recommendation for the human workflow, not a functional requirement for the scan itself.

Step 2: Verify the install

Don't proceed on faith. Confirm all of:

rustc --version
cargo --version
python3 --version
pyspector --version

If any of these fail, stop and fix it before scanning. A broken Rust toolchain in particular will surface as a cryptic scan failure later rather than a clean error at install time.

Step 3: Learn the current CLI

Always run these before scanning, even if you recall the flags from a previous session, and treat their output as the only source of truth for what flags exist and what they do:

pyspector --help
pyspector scan --help

Do not hardcode or assume a flag list. Parse whatever the live output actually shows: available options, their exact spelling, defaults, and descriptions. If something in this skill (like the decision rules below referencing --ai or --supply-chain) doesn't match what --help shows, trust --help.

Two commands surfaced by pyspector --help are interactive-only and out of scope for this skill's autonomous workflow:

• pyspector triage <report.json>: an interactive TUI for a human to mark findings as false positives and save a .pyspector_baseline.json. Don't invoke this yourself; if the user wants to triage findings interactively, tell them to run it themselves in their own terminal. If a baseline file already exists in the repo root from a prior human triage session, subsequent scans will pick it up automatically and suppress previously dismissed findings.
• pyspector watch <path>: continuous re-scan on file change, meant for a human to run in their own terminal during active development. Don't invoke this yourself; if relevant, tell the user they can run it themselves.

Step 4: Recon the codebase before choosing flags

Before scanning, spend a short pass understanding what you're actually looking at, then pick flags accordingly using whatever flags Step 3 actually confirmed exist. Don't just run a bare default scan.

Checks to run:

# Age / maturity signals
git log -1 --format=%cd 2>/dev/null   # last commit date, if it's a git repo
find . -name "requirements*.txt" -o -name "pyproject.toml" -o -name "Pipfile*" -o -name "poetry.lock" | head

# Dependency pinning style (unpinned or very old pins : higher supply-chain risk)
cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null

# AI/LLM usage signals
grep -RIl -E "openai|anthropic|langchain|llama[_-]index|transformers|litellm|ollama|cohere|google\.generativeai|vertexai" --include="*.py" . 2>/dev/null | head

Decision rules (apply these, and combine flags freely, they're not mutually exclusive):

• Any signal of LLM/AI usage (imports above, or the codebase is a model-serving/agent project) : add the AI ruleset flag. Running it even when unsure is fine; the cost of an unnecessary ruleset is low.
• Old codebase, unpinned/loosely-pinned dependencies, no lockfile, or clear supply-chain risk signals : the supply-chain CVE check flag is a good fit. This flag contacts the OSV.dev database directly to check dependencies against known CVEs, so it's not purely local and can very slightly increase scan time, on the order of a few seconds at most even on large codebases with many dependencies.
• When it's genuinely unclear whether supply-chain checking is warranted : don't default to including it. Ask the user first, and mention that it queries OSV.dev and may add a small amount of time (up to a few seconds on large projects with many dependencies) to the scan.
• Large codebases : not a concern by default. PySpector's Rust core comfortably handles very large codebases (hundreds of thousands of lines) at high throughput, so don't hesitate to run a full scan regardless of size.
• First scan of a given codebase vs. later scans : PySpector caches the AST it builds during a scan, so the first scan of a given codebase will always take somewhat longer than later ones. Subsequent scans are substantially faster, even after the source has changed somewhat in the meantime. If you're re-scanning something you already scanned earlier in the session, mention that it should be quicker this time; if it's a first scan, mention that this initial pass is expected to take a bit longer than future ones.

Set severity threshold based on intent: for a genuine security audit, use the lowest severity threshold (see what --help shows as the default/lowest option) to see everything, then let the verification step (Step 6) do the filtering. Don't pre-filter by raising the severity threshold, since that would hide true positives from your own verification pass, not just noise.