pysentry-rs 0.3.13__cp310-cp310-manylinux_2_28_aarch64.whl

pysentry_rs-0.3.13.dist-info/METADATA

@@ -0,0 +1,939 @@
+Metadata-Version: 2.4
+Name: pysentry-rs
+Version: 0.3.13
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+License-File: LICENSE
+Summary: Security vulnerability auditing tool for Python packages
+Author-email: nyudenkov <nyudenkov@pm.me>
+License: GPL-3.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/nyudenkov/pysentry
+Project-URL: Repository, https://github.com/nyudenkov/pysentry
+Project-URL: Issues, https://github.com/nyudenkov/pysentry/issues
+
+# 🐍 PySentry
+
+[![OSV Integration](https://img.shields.io/badge/OSV-Integrated-blue)](https://google.github.io/osv.dev/)
+[![PyPI Downloads](https://static.pepy.tech/badge/pysentry-rs/week)](https://pepy.tech/projects/pysentry-rs)
+
+[Help to test and improve](https://github.com/nyudenkov/pysentry/issues/12) | [Latest PySentry - pip-audit benchmark](benchmarks/results/latest.md)
+
+Please, send feedback to nikita@pysentry.com
+
+A fast, reliable security vulnerability scanner for Python projects, written in Rust.
+
+## Overview
+
+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.
+
+## Key Features
+
+- **Multiple Project Formats**: Supports `uv.lock`, `poetry.lock`, `Pipfile.lock`, `pylock.toml`, `pyproject.toml`, `Pipfile`, and `requirements.txt` files
+- **External Resolver Integration**: Leverages `uv` and `pip-tools` for accurate requirements.txt constraint solving
+- **Multiple Data Sources** (all sources used by default):
+  - PyPA Advisory Database
+  - PyPI JSON API
+  - OSV.dev (Open Source Vulnerabilities)
+- **Flexible Output for different workflows**: Human-readable, JSON, SARIF, and Markdown formats
+- **Performance Focused**:
+  - Written in Rust for speed
+  - Async/concurrent processing
+  - Multi-tier intelligent caching (vulnerability data + resolved dependencies)
+- **Comprehensive Filtering**:
+  - Severity levels (low, medium, high, critical)
+  - Dependency scopes (main only vs all [optional, dev, prod, etc] dependencies)
+  - Direct vs. transitive dependencies
+- **Enterprise Ready**: SARIF output for IDE/CI integration
+
+## Installation
+
+Choose the installation method that works best for you:
+
+### ⚡ Via uvx (Recommended for occasional use)
+
+Run directly without installing (requires [uv](https://docs.astral.sh/uv/)):
+
+```bash
+uvx pysentry-rs /path/to/project
+```
+
+This method:
+
+- Runs the latest version without installation
+- Automatically manages Python environment
+- Perfect for CI/CD or occasional security audits
+- No need to manage package versions or updates
+
+### 📦 From PyPI (Python Package)
+
+For Python 3.9-3.14 on Linux, macOS, and Windows:
+
+```bash
+pip install pysentry-rs
+```
+
+Then use it with Python:
+
+```bash
+python -m pysentry /path/to/project
+# or directly if scripts are in PATH
+pysentry-rs /path/to/project
+```
+
+### ⚡ From Crates.io (Rust Package)
+
+If you have Rust installed:
+
+```bash
+cargo install pysentry
+```
+
+### 💾 From GitHub Releases (Pre-built Binaries)
+
+Download the latest release for your platform:
+
+- **Linux x64**: `pysentry-linux-x64.tar.gz`
+- **Linux x64 (musl)**: `pysentry-linux-x64-musl.tar.gz`
+- **Linux ARM64**: `pysentry-linux-arm64.tar.gz`
+- **macOS x64**: `pysentry-macos-x64.tar.gz`
+- **macOS ARM64**: `pysentry-macos-arm64.tar.gz`
+- **Windows x64**: `pysentry-windows-x64.zip`
+
+```bash
+# 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
+```
+
+### 🔧 From Source
+
+```bash
+git clone https://github.com/nyudenkov/pysentry
+cd pysentry
+cargo build --release
+```
+
+The binary will be available at `target/release/pysentry`.
+
+### Requirements
+
+- **For uvx**: Python 3.9-3.14 and [uv](https://docs.astral.sh/uv/) installed
+- **For binaries**: No additional dependencies
+- **For Python package**: Python 3.9-3.14
+- **For Rust package and source**: Rust 1.79+
+
+### Platform Support
+
+| 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)
+
+
+### CLI Command Names
+
+- **Rust binary**: `pysentry` (when installed via cargo or binary releases)
+- **Python package**: `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.
+
+### Requirements.txt Support Prerequisites
+
+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:**
+
+```bash
+# uv (recommended - fastest, Rust-based)
+pip install uv
+
+# pip-tools (widely compatible, Python-based)
+pip install pip-tools
+```
+
+**Environment Requirements:**
+
+- Resolvers must be available in your current environment
+- If using virtual environments, activate your venv before running PySentry:
+  ```bash
+  source venv/bin/activate  # Linux/macOS
+  venv\Scripts\activate     # Windows
+  pysentry /path/to/project
+  ```
+- Alternatively, install resolvers globally for system-wide availability
+
+**Auto-detection:** PySentry automatically detects and prefers: `uv` > `pip-tools`. Without a resolver, only `uv.lock` and `poetry.lock` files can be scanned.
+
+## Quick Start
+
+### Basic Usage
+
+```bash
+# 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
+```
+
+### Advanced Usage
+
+```bash
+# 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
+```
+
+### Advanced Requirements.txt Usage
+
+```bash
+# 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
+```
+
+### CI/CD Integration Examples
+
+```bash
+# 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
+```
+
+## Pre-commit Integration
+
+PySentry integrates seamlessly with [pre-commit](https://pre-commit.com/) to automatically scan for vulnerabilities before commits.
+
+### Setup
+
+Add PySentry to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/pysentry/pysentry-pre-commit
+    rev: v0.3.13
+    hooks:
+      - id: pysentry # default pysentry settings
+```
+
+### Advanced Configuration
+
+```yaml
+repos:
+  - repo: https://github.com/pysentry/pysentry-pre-commit
+    rev: v0.3.13
+    hooks:
+      - id: pysentry
+        args: ["--sources", "pypa,osv", "--fail-on", "high"]
+```
+
+### Installation Requirements
+
+Pre-commit will automatically install PySentry, uv and pip-tools via PyPI.
+
+## Configuration
+
+PySentry supports TOML-based configuration files for persistent settings management. Configuration files follow a hierarchical discovery pattern:
+
+1. **Project-level** (in current or parent directories, walking up to `.git` root):
+   - `.pysentry.toml` (highest priority)
+   - `pyproject.toml` `[tool.pysentry]` section (lower priority, convenient for existing Python projects)
+2. **User-level**: `~/.config/pysentry/config.toml` (Linux/macOS)
+3. **System-level**: `/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.
+
+### Configuration File Example (.pysentry.toml)
+
+```toml
+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
+```
+
+### pyproject.toml Configuration
+
+You can configure PySentry directly in your `pyproject.toml` using the `[tool.pysentry]` section:
+
+```toml
+[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
+
+
+### Environment Variables
+
+| 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`                      |
+
+### Command Line Options
+
+| 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)                | `[]`              |
+
+### Cache Management
+
+PySentry uses an intelligent multi-tier caching system for optimal performance:
+
+#### Vulnerability Data Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/vulnerability-db/`
+- **Purpose**: Caches vulnerability databases from PyPA, PyPI, OSV
+- **TTL**: 24 hours (configurable per source)
+- **Benefits**: Avoids redundant API calls and downloads
+
+#### Resolution Cache
+
+- **Location**: `{CACHE_DIR}/pysentry/dependency-resolution/`
+- **Purpose**: Caches resolved dependencies from `uv`/`pip-tools`
+- **TTL**: 24 hours (configurable via `--resolution-cache-ttl`)
+- **Benefits**: Dramatically speeds up repeated scans of requirements.txt files
+- **Cache Key**: Based on requirements content, resolver version, Python version, platform
+
+#### Platform-Specific Cache Locations
+
+- **Linux**: `~/.cache/pysentry/`
+- **macOS**: `~/Library/Caches/pysentry/`
+- **Windows**: `%LOCALAPPDATA%\pysentry\`
+
+**Finding Your Cache Location**: Run with `--verbose` to see the actual cache directory path being used.
+
+#### Cache Features
+
+- **Atomic Updates**: Prevents cache corruption during concurrent access
+- **Custom Location**: Use `--cache-dir` to specify alternative location
+- **Selective Clearing**: Control caching behavior per cache type
+- **Content-based Invalidation**: Automatic cache invalidation on content changes
+
+#### Cache Control Examples
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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"
+```
+
+## Supported Project Formats
+
+### uv.lock Files (Recommended)
+
+PySentry has support for `uv.lock` files:
+
+- Exact version resolution
+- Complete dependency graph analysis
+- Source tracking
+- Dependency classification (main, dev, optional) including transitive dependencies
+
+### poetry.lock Files
+
+Full support for Poetry lock files:
+
+- **Exact Version Resolution**: Scans exact dependency versions locked by Poetry
+- **Lock-File Only Analysis**: Relies purely on the lock file structure, no pyproject.toml parsing needed
+- **Complete Dependency Tree**: Analyzes all resolved dependencies including transitive ones
+- **Dependency Classification**: Distinguishes between main dependencies and optional groups (dev, test, etc.)
+- **Source Tracking**: Supports PyPI registry, Git repositories, local paths, and direct URLs
+
+**Key Features:**
+
+- No external tools required
+- Fast parsing with exact version information
+- Handles Poetry's dependency groups and optional dependencies
+- Perfect for Poetry-managed projects with established lock files
+
+### Pipfile.lock Files
+
+Full support for Pipenv lock files with exact version resolution:
+
+- **Exact Version Resolution**: Scans exact dependency versions locked by Pipenv
+- **Lock-File Only Analysis**: Relies purely on the lock file structure, no Pipfile parsing needed
+- **Complete Dependency Tree**: Analyzes all resolved dependencies including transitive ones
+- **Dependency Classification**: Distinguishes between default dependencies and development groups
+
+**Key Features:**
+
+- No external tools required
+- Fast parsing with exact version information
+- Handles Pipenv's dependency groups (default and develop)
+- Perfect for Pipenv-managed projects with established lock files
+
+### Pipfile Files (External Resolution)
+
+Support for Pipfile specification files using external dependency resolvers:
+
+**Key Features:**
+
+- **Dependencies Resolution**: Converts version constraints from Pipfile to exact versions using mature external tools
+- **Multiple Resolver Support**:
+  - **uv**: Rust-based resolver, extremely fast and reliable (recommended)
+  - **pip-tools**: Python-based resolver using `pip-compile`, widely compatible
+- **Auto-detection**: Automatically detects and uses the best available resolver in your environment
+- **Dependency Groups**: Supports both default packages and dev-packages sections
+- **Complex Constraint Handling**: Supports version ranges, Git dependencies, and environment markers
+
+**Resolution Workflow:**
+
+1. Detects `Pipfile` in your project (when `Pipfile.lock` is not present)
+2. Auto-detects available resolver (`uv` or `pip-tools`) in current environment
+3. Resolves version constraints to exact dependency versions
+4. Scans resolved dependencies for vulnerabilities
+5. Reports findings with dependency group classification
+
+**Note**: 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.
+
+### requirements.txt Files (External Resolution)
+
+Advanced support for `requirements.txt` files using external dependency resolvers:
+
+**Key Features:**
+
+- **Dependencies Resolution**: Converts version constraints (e.g., `flask>=2.0,<3.0`) to exact versions using mature external tools
+- **Multiple Resolver Support**:
+  - **uv**: Rust-based resolver, extremely fast and reliable (recommended)
+  - **pip-tools**: Python-based resolver using `pip-compile`, widely compatible
+- **Auto-detection**: Automatically detects and uses the best available resolver in your environment
+- **Multiple File Support**: Combines `requirements.txt`, `requirements-dev.txt`, `requirements-test.txt`, etc.
+- **Dependency Classification**: Distinguishes between direct and transitive dependencies
+- **Isolated Execution**: Resolvers run in temporary directories to prevent project pollution
+- **Complex Constraint Handling**: Supports version ranges, extras, environment markers, and conflict resolution
+
+**Resolution Workflow:**
+
+1. Detects `requirements.txt` files in your project
+2. Auto-detects available resolver (`uv` or `pip-tools`) in current environment
+3. Resolves version constraints to exact dependency versions
+4. Scans resolved dependencies for vulnerabilities
+5. Reports findings with direct vs. transitive classification
+
+**Environment Setup:**
+
+```bash
+# 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
+```
+
+### pyproject.toml Files (External Resolution)
+
+Support for projects without lock files:
+
+- Parses version constraints from `pyproject.toml`
+- **Resolver Required**: Like requirements.txt, needs external resolvers (`uv` or `pip-tools`) to convert version constraints to exact versions for accurate vulnerability scanning
+- Limited dependency graph information compared to lock files
+- Works with both Poetry and PEP 621 formats
+
+## Vulnerability Data Sources
+
+PySentry uses all three vulnerability sources by default for comprehensive coverage.
+
+### PyPA Advisory Database
+
+- Comprehensive coverage of Python ecosystem
+- Community-maintained vulnerability database
+- Regular updates from security researchers
+
+### PyPI JSON API
+
+- Official PyPI vulnerability data
+- Real-time information
+- Limited to packages hosted on PyPI
+
+### OSV.dev
+
+- Cross-ecosystem vulnerability database
+- Google-maintained infrastructure
+
+## Output Formats
+
+### Human-Readable (Default)
+
+Most comfortable to read.
+
+### Markdown
+
+GitHub-friendly format with structured sections and severity indicators. Perfect for documentation, GitHub issues, and security reports.
+
+### JSON
+
+```json
+{
+  "summary": {
+    "total_dependencies": 245,
+    "vulnerable_packages": 2,
+    "total_vulnerabilities": 3,
+    "by_severity": {
+      "critical": 1,
+      "high": 1,
+      "medium": 1,
+      "low": 0
+    }
+  },
+  "vulnerabilities": [...]
+}
+```
+
+### SARIF (Static Analysis Results Interchange Format)
+
+Compatible with GitHub Security tab, VS Code, and other security tools.
+
+## Performance
+
+PySentry is designed for speed and efficiency:
+
+- **Concurrent Processing**: Vulnerability data fetched in parallel from multiple sources
+- **Multi-tier Caching**: Intelligent caching for both vulnerability data and resolved dependencies
+- **Efficient Matching**: In-memory indexing for fast vulnerability lookups
+- **Streaming**: Large databases processed without excessive memory usage
+
+### Resolution Cache Performance
+
+The resolution cache provides dramatic performance improvements for requirements.txt files:
+
+- **First scan**: Standard resolution time using `uv` or `pip-tools`
+- **Subsequent scans**: Near-instantaneous when cache is fresh (>90% time savings)
+- **Cache invalidation**: Automatic when requirements content, resolver, or environment changes
+- **Content-aware**: Different cache entries for different Python versions and platforms
+
+### Requirements.txt Resolution Performance
+
+PySentry leverages external resolvers with intelligent caching:
+
+- **uv resolver**: 2-10x faster than pip-tools, handles large dependency trees efficiently
+- **pip-tools resolver**: Reliable fallback, slower but widely compatible
+- **Isolated execution**: Prevents project pollution while maintaining security
+- **Resolution caching**: Eliminates repeated resolver calls for unchanged requirements
+
+## Development
+
+### Building from Source
+
+```bash
+git clone https://github.com/nyudenkov/pysentry
+cd pysentry
+cargo build --release
+```
+
+### Running Tests
+
+```bash
+cargo test
+```
+
+### Project Structure
+
+```
+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
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Error: "No lock file or pyproject.toml found"**
+
+```bash
+# 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"**
+
+```bash
+# 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"**
+
+```bash
+# 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"**
+
+```bash
+# 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:
+```
+
+```toml
+[http]
+timeout = 300           # 5 minute timeout
+max_retries = 5         # More retry attempts
+retry_max_backoff = 120 # Longer backoff delays
+```
+
+```bash
+# Then run again
+pysentry
+```
+
+**Network timeout errors:**
+
+PySentry includes automatic retry with exponential backoff for network issues. If you still experience timeouts:
+
+```bash
+# 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:
+
+```toml
+[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**
+
+```bash
+# 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**
+
+```bash
+# 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**
+
+```bash
+# 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**
+
+```bash
+# 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
+```
+
+## Acknowledgments
+
+- Inspired by [pip-audit](https://github.com/pypa/pip-audit) and [uv #9189 issue](https://github.com/astral-sh/uv/issues/9189)
+- Originally was a command for [uv](https://github.com/astral-sh/uv)
+- Vulnerability data from [PyPA](https://github.com/pypa/advisory-database), [PyPI](https://pypi.org/), and [OSV.dev](https://osv.dev/)
+