| Crates.io | pysentry |
| lib.rs | pysentry |
| version | 0.3.14 |
| created_at | 2025-08-07 03:14:18.493354+00 |
| updated_at | 2026-01-21 14:45:54.565525+00 |
| description | Security vulnerability auditing for Python packages |
| homepage | |
| repository | https://github.com/nyudenkov/pysentry |
| max_upload_size | |
| id | 1784628 |
| size | 1,393,494 |
Help to test and improve | Latest PySentry - pip-audit benchmark
Please, send feedback to nikita@pysentry.com
A fast, reliable security vulnerability scanner for Python projects, written in Rust.
PySentry audits Python projects for known security vulnerabilities by analyzing dependency files (uv.lock, poetry.lock, Pipfile.lock, pylock.toml, pyproject.toml, Pipfile, requirements.txt) and cross-referencing them against multiple vulnerability databases. It provides comprehensive reporting with support for various output formats and filtering options.
uv.lock, poetry.lock, Pipfile.lock, pylock.toml, pyproject.toml, Pipfile, and requirements.txt filesuv and pip-tools for accurate requirements.txt constraint solvingChoose the installation method that works best for you:
Run directly without installing (requires uv):
uvx pysentry-rs /path/to/project
This method:
For Python 3.9-3.14 on Linux, macOS, and Windows:
pip install pysentry-rs
Then use it with Python:
python -m pysentry /path/to/project
# or directly if scripts are in PATH
pysentry-rs /path/to/project
If you have Rust installed:
cargo install pysentry
Download the latest release for your platform:
pysentry-linux-x64.tar.gzpysentry-linux-x64-musl.tar.gzpysentry-linux-arm64.tar.gzpysentry-macos-x64.tar.gzpysentry-macos-arm64.tar.gzpysentry-windows-x64.zip# Example for Linux x64
curl -L https://github.com/nyudenkov/pysentry/releases/latest/download/pysentry-linux-x64.tar.gz | tar -xz
./pysentry-linux-x64/pysentry --help
git clone https://github.com/nyudenkov/pysentry
cd pysentry
cargo build --release
The binary will be available at target/release/pysentry.
| Installation Method | Linux (x64) | Linux (ARM64) | macOS (x64) | macOS (ARM64) | Windows (x64) |
|---|---|---|---|---|---|
| uvx | ✅ | ✅ | ✅ | ✅ | ✅ |
| PyPI (pip) | ✅ | ✅ | ✅ | ✅ | ✅ |
| Crates.io (cargo) | ✅ | ✅ | ✅ | ✅ | ✅ |
| GitHub Releases | ✅ | ✅ | ✅ | ✅ | ✅ |
| From Source | ✅ | ✅ | ✅ | ✅ | ✅ |
Supported Python Versions: 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 Supported Architectures: x86_64 (x64), ARM64 (aarch64)
pysentry (when installed via cargo or binary releases)pysentry-rs (when installed via pip or uvx)Both variants support identical functionality. The resolver tools (uv, pip-tools) must be available in your current environment regardless of which PySentry variant you use.
To scan requirements.txt files, PySentry requires an external dependency resolver to convert version constraints (e.g., flask>=2.0,<3.0) into exact versions for vulnerability scanning.
Install a supported resolver:
# uv (recommended - fastest, Rust-based)
pip install uv
# pip-tools (widely compatible, Python-based)
pip install pip-tools
Environment Requirements:
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
pysentry /path/to/project
Auto-detection: PySentry automatically detects and prefers: uv > pip-tools. Without a resolver, only uv.lock and poetry.lock files can be scanned.
# Using uvx (recommended for occasional use)
uvx pysentry-rs
uvx pysentry-rs /path/to/python/project
# Using installed binary
pysentry
pysentry /path/to/python/project
# Automatically detects project type (uv.lock, poetry.lock, Pipfile.lock, pyproject.toml, Pipfile, requirements.txt)
pysentry /path/to/project
# Force specific resolver
pysentry --resolver uv /path/to/project
pysentry --resolver pip-tools /path/to/project
# Exclude extra dependencies (only check main dependencies)
pysentry --exclude-extra
# Filter by severity (only show high and critical)
pysentry --severity high
# Output to JSON file
pysentry --format json --output audit-results.json
# Using uvx for comprehensive audit (extras included by default)
uvx pysentry-rs --format sarif --output security-report.sarif
# Use specific vulnerability sources (all sources used by default)
uvx pysentry-rs --sources pypa /path/to/project
uvx pysentry-rs --sources pypa --sources osv /path/to/project
# Generate markdown report
uvx pysentry-rs --format markdown --output security-report.md
# Control CI exit codes - only fail on critical vulnerabilities
uvx pysentry-rs --fail-on critical
# Or with installed binary (extras included by default)
pysentry --format sarif --output security-report.sarif
pysentry --sources pypa,osv --direct-only
pysentry --format markdown --output security-report.md
# Ignore specific vulnerabilities
pysentry --ignore CVE-2023-12345 --ignore GHSA-xxxx-yyyy-zzzz
# Ignore unfixable vulnerabilities (only while they have no fix available)
pysentry --ignore-while-no-fix CVE-2025-8869
# Disable caching for CI environments
pysentry --no-cache
# Verbose output for debugging
pysentry --verbose
# Scan multiple requirements files
pysentry --requirements requirements.txt --requirements requirements-dev.txt
# Check only direct dependencies from requirements.txt
pysentry --direct-only --resolver uv
# Ensure resolver is available in your environment
source venv/bin/activate # Activate your virtual environment first
pysentry /path/to/project
# Debug requirements.txt resolution
pysentry --verbose --resolver uv /path/to/project
# Use longer resolution cache TTL (48 hours)
pysentry --resolution-cache-ttl 48 /path/to/project
# Clear resolution cache before scanning
pysentry --clear-resolution-cache /path/to/project
# Development environment - only fail on critical vulnerabilities
pysentry --fail-on critical --format json --output security-report.json
# Staging environment - fail on high+ vulnerabilities
pysentry --fail-on high --sources pypa,osv --format sarif --output security.sarif
# Production deployment - strict security (fail on medium+, default)
pysentry --sources pypa,pypi,osv --format json --output prod-security.json
# Generate markdown report for GitHub issues/PRs
pysentry --format markdown --output SECURITY-REPORT.md
# Comprehensive audit with all sources and full reporting (extras included by default)
pysentry --sources pypa,pypi,osv --format json --fail-on low
# CI environment with fresh resolution cache
pysentry --clear-resolution-cache --sources pypa,osv --format sarif
# CI with resolution cache disabled
pysentry --no-resolution-cache --format json --output security-report.json
PySentry integrates seamlessly with pre-commit to automatically scan for vulnerabilities before commits.
Add PySentry to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/pysentry/pysentry-pre-commit
rev: v0.3.14
hooks:
- id: pysentry # default pysentry settings
repos:
- repo: https://github.com/pysentry/pysentry-pre-commit
rev: v0.3.14
hooks:
- id: pysentry
args: ["--sources", "pypa,osv", "--fail-on", "high"]
Pre-commit will automatically install PySentry, uv and pip-tools via PyPI.
PySentry supports TOML-based configuration files for persistent settings management. Configuration files follow a hierarchical discovery pattern:
.git root):
.pysentry.toml (highest priority)pyproject.toml [tool.pysentry] section (lower priority, convenient for existing Python projects)~/.config/pysentry/config.toml (Linux/macOS)/etc/pysentry/config.toml (Unix systems)Priority: When both .pysentry.toml and pyproject.toml exist in the same directory, .pysentry.toml takes precedence. This allows you to override pyproject.toml settings when needed.
version = 1
[defaults]
format = "json"
severity = "medium"
fail_on = "high"
scope = "all"
direct_only = false
[sources]
enabled = ["pypa", "osv"]
[resolver]
type = "uv"
fallback = "pip-tools"
[cache]
enabled = true
resolution_ttl = 48
vulnerability_ttl = 72
[output]
quiet = false
verbose = false
color = "auto"
[ignore]
ids = ["CVE-2023-12345", "GHSA-xxxx-yyyy-zzzz"]
while_no_fix = ["CVE-2025-8869"]
[http]
timeout = 120
connect_timeout = 30
max_retries = 3
retry_initial_backoff = 1
retry_max_backoff = 60
show_progress = true
You can configure PySentry directly in your pyproject.toml using the [tool.pysentry] section:
[project]
name = "my-project"
version = "1.0.0"
[tool.pysentry]
version = 1
[tool.pysentry.defaults]
format = "json"
severity = "medium"
fail_on = "high"
scope = "main"
direct_only = false
[tool.pysentry.sources]
enabled = ["pypa", "osv"]
[tool.pysentry.resolver]
type = "uv"
fallback = "pip-tools"
[tool.pysentry.cache]
enabled = true
resolution_ttl = 48
vulnerability_ttl = 72
[tool.pysentry.output]
quiet = false
verbose = false
color = "auto"
[tool.pysentry.ignore]
ids = ["CVE-2023-12345"]
while_no_fix = ["CVE-2025-8869"]
[tool.pysentry.http]
timeout = 120
connect_timeout = 30
max_retries = 3
Benefits of pyproject.toml configuration:
Keep all project configuration in a single file
No additional config files to manage
Works seamlessly with existing Python project tooling
Graceful fallback: Invalid [tool.pysentry] sections log a warning and continue to next configuration source
| Variable | Description | Example |
|---|---|---|
PYSENTRY_CONFIG |
Override config file path (supports .pysentry.toml or pyproject.toml) |
PYSENTRY_CONFIG=/path/to/pyproject.toml |
PYSENTRY_NO_CONFIG |
Disable all config file loading | PYSENTRY_NO_CONFIG=1 |
| Option | Description | Default |
|---|---|---|
--format |
Output format: human, json, sarif, markdown |
human |
--severity |
Minimum severity: low, medium, high, critical |
low |
--fail-on |
Fail (exit non-zero) on vulnerabilities ≥ severity | medium |
--sources |
Vulnerability sources: pypa, pypi, osv (multiple) |
pypa,pypi,osv |
--exclude-extra |
Exclude extra dependencies (dev, optional, etc) | false |
--direct-only |
Check only direct dependencies | false |
--detailed |
Show full vulnerability descriptions instead of truncated | false |
--ignore |
Vulnerability IDs to ignore (repeatable) | [] |
--ignore-while-no-fix |
Ignore vulnerabilities only while no fix is available | [] |
--output |
Output file path | stdout |
--no-cache |
Disable all caching | false |
--cache-dir |
Custom cache directory | Platform-specific |
--resolution-cache-ttl |
Resolution cache TTL in hours | 24 |
--no-resolution-cache |
Disable resolution caching only | false |
--clear-resolution-cache |
Clear resolution cache on startup | false |
--verbose |
Enable verbose output | false |
--quiet |
Suppress non-error output | false |
--resolver |
Dependency resolver: auto, uv, pip-tools |
auto |
--requirements |
Additional requirements files (repeatable) | [] |
PySentry uses an intelligent multi-tier caching system for optimal performance:
{CACHE_DIR}/pysentry/vulnerability-db/{CACHE_DIR}/pysentry/dependency-resolution/uv/pip-tools--resolution-cache-ttl)~/.cache/pysentry/~/Library/Caches/pysentry/%LOCALAPPDATA%\pysentry\Finding Your Cache Location: Run with --verbose to see the actual cache directory path being used.
--cache-dir to specify alternative location# Disable all caching
pysentry --no-cache
# Disable only resolution caching (keep vulnerability cache)
pysentry --no-resolution-cache
# Set resolution cache TTL to 48 hours
pysentry --resolution-cache-ttl 48
# Clear resolution cache on startup (useful for CI)
pysentry --clear-resolution-cache
# Custom cache directory
pysentry --cache-dir /tmp/my-pysentry-cache
To manually clear all caches:
# Linux
rm -rf ~/.cache/pysentry/
# macOS
rm -rf ~/Library/Caches/pysentry/
# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry"
To clear only resolution cache:
# Linux
rm -rf ~/.cache/pysentry/dependency-resolution/
# macOS
rm -rf ~/Library/Caches/pysentry/dependency-resolution/
# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\pysentry\dependency-resolution"
PySentry has support for uv.lock files:
Full support for Poetry lock files:
Key Features:
Full support for Pipenv lock files with exact version resolution:
Key Features:
Support for Pipfile specification files using external dependency resolvers:
Key Features:
pip-compile, widely compatibleResolution Workflow:
Pipfile in your project (when Pipfile.lock is not present)uv or pip-tools) in current environmentNote: When both Pipfile and Pipfile.lock are present, PySentry prioritizes the lock file for better accuracy. Consider using pipenv lock to generate a lock file for the most precise vulnerability scanning.
Advanced support for requirements.txt files using external dependency resolvers:
Key Features:
flask>=2.0,<3.0) to exact versions using mature external toolspip-compile, widely compatiblerequirements.txt, requirements-dev.txt, requirements-test.txt, etc.Resolution Workflow:
requirements.txt files in your projectuv or pip-tools) in current environmentEnvironment Setup:
# Ensure resolver is available in your environment
source venv/bin/activate # Activate virtual environment
pip install uv # Install preferred resolver
pysentry /path/to/project # Run security scan
Support for projects without lock files:
pyproject.tomluv or pip-tools) to convert version constraints to exact versions for accurate vulnerability scanningPySentry uses all three vulnerability sources by default for comprehensive coverage.
Most comfortable to read.
GitHub-friendly format with structured sections and severity indicators. Perfect for documentation, GitHub issues, and security reports.
{
"summary": {
"total_dependencies": 245,
"vulnerable_packages": 2,
"total_vulnerabilities": 3,
"by_severity": {
"critical": 1,
"high": 1,
"medium": 1,
"low": 0
}
},
"vulnerabilities": [...]
}
Compatible with GitHub Security tab, VS Code, and other security tools.
PySentry is designed for speed and efficiency:
The resolution cache provides dramatic performance improvements for requirements.txt files:
uv or pip-toolsPySentry leverages external resolvers with intelligent caching:
git clone https://github.com/nyudenkov/pysentry
cd pysentry
cargo build --release
cargo test
src/
├── main.rs # CLI interface
├── lib.rs # Library API
├── cache/ # Caching system
├── dependency/ # Dependency scanning
├── output/ # Report generation
├── parsers/ # Project file parsers
├── providers/ # Vulnerability data sources
├── types.rs # Core type definitions
└── vulnerability/ # Vulnerability matching
Error: "No lock file or pyproject.toml found"
# Ensure you're in a Python project directory
ls pyproject.toml uv.lock poetry.lock requirements.txt
# Or specify the path explicitly
pysentry /path/to/python/project
Error: "No dependency resolver found" or "uv resolver not available"
# Install a supported resolver in your environment
pip install uv # Recommended - fastest
pip install pip-tools # Alternative
# Verify resolver is available
uv --version
pip-compile --version
# If using virtual environments, ensure resolver is installed there
source venv/bin/activate
pip install uv
pysentry /path/to/project
Error: "Failed to resolve requirements"
# Check your requirements.txt syntax
cat requirements.txt
# Try different resolver
pysentry --resolver pip-tools # if uv fails
pysentry --resolver uv # if pip-tools fails
# Ensure you're in correct environment
which python
which uv # or which pip-compile
# Debug with verbose output
pysentry --verbose /path/to/project
Error: "Failed to fetch vulnerability data"
# Check network connectivity
curl -I https://osv-vulnerabilities.storage.googleapis.com/
# Try with different or multiple sources
pysentry --sources pypi
pysentry --sources pypa,osv
# For slow or unstable networks, increase timeout and retries
# Create/edit .pysentry.toml in your project:
[http]
timeout = 300 # 5 minute timeout
max_retries = 5 # More retry attempts
retry_max_backoff = 120 # Longer backoff delays
# Then run again
pysentry
Network timeout errors:
PySentry includes automatic retry with exponential backoff for network issues. If you still experience timeouts:
# Increase timeout values in config
pysentry config init --output .pysentry.toml
# Edit .pysentry.toml and adjust [http] section
Rate limiting (HTTP 429 errors):
PySentry automatically handles rate limiting. If rate limits persist:
[http]
max_retries = 5 # More attempts
retry_initial_backoff = 5 # Longer initial wait
retry_max_backoff = 300 # Up to 5 minute backoff
Slow requirements.txt resolution
# Use faster uv resolver instead of pip-tools
pysentry --resolver uv
# Install uv for better performance (2-10x faster)
pip install uv
# Or use uvx for isolated execution
uvx pysentry-rs --resolver uv /path/to/project
Requirements.txt files not being detected
# Ensure requirements.txt exists
ls requirements.txt
# Specify path explicitly
pysentry /path/to/python/project
# Include additional requirements files
pysentry --requirements requirements-dev.txt --requirements requirements-test.txt
# Check if higher-priority files exist (they take precedence)
ls uv.lock poetry.lock Pipfile.lock pyproject.toml Pipfile requirements.txt
Performance Issues
# Clear all caches and retry
rm -rf ~/.cache/pysentry # Linux
rm -rf ~/Library/Caches/pysentry # macOS
pysentry
# Clear only resolution cache (if vulnerability cache is working)
rm -rf ~/.cache/pysentry/dependency-resolution/ # Linux
rm -rf ~/Library/Caches/pysentry/dependency-resolution/ # macOS
pysentry
# Clear resolution cache via CLI
pysentry --clear-resolution-cache
# Use verbose mode to identify bottlenecks
pysentry --verbose
# Disable caching to isolate issues
pysentry --no-cache
Resolution Cache Issues
# Clear stale resolution cache after environment changes
pysentry --clear-resolution-cache
# Disable resolution cache if causing issues
pysentry --no-resolution-cache
# Extend cache TTL for stable environments
pysentry --resolution-cache-ttl 168 # 1 week
# Check cache usage with verbose output
pysentry --verbose # Shows cache hits/misses
# Force fresh resolution (ignores cache)
pysentry --clear-resolution-cache --no-resolution-cache