Skip to main content

Quick Start

Get started with PySentry in minutes.

Basic Usage​

# 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, pylock.toml, 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

# Only fail on high and critical vulnerabilities
pysentry --fail-on high

# Output to JSON file
pysentry --format json --output audit-results.json

Advanced Usage​

# 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 --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

# Fail on unmaintained packages (archived, deprecated, or quarantined)
pysentry --forbid-unmaintained

# Fail only on quarantined packages (malware/compromised)
pysentry --forbid-quarantined

# Check maintenance status for direct dependencies only
pysentry --forbid-unmaintained --maintenance-direct-only

# Don't fail on vulnerabilities with unknown severity
pysentry --no-fail-on-unknown

# Disable caching for CI environments
pysentry --no-cache

# Force colors for piped output or log capture
pysentry --color always

# Disable colors (useful in plain-text environments or scripts)
pysentry --color never

# Compact output with table layout (default)
pysentry --compact

# Compact output with traditional text layout
pysentry --compact --display text

# Verbose output for debugging (-v for warnings, -vv for info, -vvv for debug)
pysentry -v
pysentry -vv

Requirements.txt Usage​

# Scan multiple requirements files
pysentry --requirements-files requirements.txt 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

Understanding Output​

PySentry reports vulnerabilities with:

  • Package name and version: The affected dependency
  • Dependency type: [direct] or [transitive] tag on each vulnerability entry
  • Vulnerability ID: CVE, GHSA, or PYSEC identifier
  • Severity: Critical, High, Medium, Low, or Unknown
  • Description: Brief explanation of the vulnerability
  • Fix version: Recommended version to upgrade to (when available)
  • Source file: Which dependency file contains the vulnerable package

Exit Codes​

CodeMeaning
0No vulnerabilities found at or above the --fail-on threshold
1Vulnerabilities found at or above the --fail-on threshold, or error during execution

Note: Both vulnerability detection and errors result in exit code 1. Use verbose output (-v) to distinguish between them.

Next Steps​