pysentry-rs 0.2.0__cp313-cp313-macosx_11_0_arm64.whl → 0.2.2__cp313-cp313-macosx_11_0_arm64.whl

pysentry/__init__.py

@@ -1,182 +1,19 @@
-"""pysentry: Security vulnerability auditing tool for Python packages."""
+"""pysentry-rs: Security vulnerability auditing tool for Python packages."""
 
-from ._internal import audit_python, audit_with_options, check_resolvers, check_version
+from ._internal import get_version, run_cli
 
-__version__ = "0.2.0"
-__all__ = [
-    "audit_python",
-    "audit_with_options",
-    "check_resolvers",
-    "check_version",
-    "main",
-]
+__version__ = get_version()
+__all__ = ["get_version", "run_cli", "main"]
 
 
 def main():
-    """CLI entry point."""
+    """CLI entry point that provides the exact same interface as the Rust binary."""
     import sys
-    import argparse
-
-    # Handle subcommands manually to match Rust CLI structure exactly
-    if len(sys.argv) > 1:
-        if sys.argv[1] == "resolvers":
-            # Resolvers subcommand
-            parser = argparse.ArgumentParser(
-                prog="pysentry resolvers",
-                description="Check available dependency resolvers",
-            )
-            parser.add_argument(
-                "-v", "--verbose", action="store_true", help="Enable verbose output"
-            )
-
-            args = parser.parse_args(sys.argv[2:])
-            try:
-                result = check_resolvers(args.verbose)
-                print(result)
-            except Exception as e:
-                print(f"Error: {e}", file=sys.stderr)
-                sys.exit(1)
-            return
-
-        elif sys.argv[1] == "check-version":
-            # Check-version subcommand
-            parser = argparse.ArgumentParser(
-                prog="pysentry-rs check-version",
-                description="Check if a newer version is available",
-            )
-            parser.add_argument(
-                "-v", "--verbose", action="store_true", help="Enable verbose output"
-            )
-
-            args = parser.parse_args(sys.argv[2:])
-            try:
-                result = check_version(args.verbose)
-                print(result)
-            except Exception as e:
-                print(f"Error: {e}", file=sys.stderr)
-                sys.exit(1)
-            return
-        elif sys.argv[1] in ["-h", "--help"]:
-            # Show main help
-            pass
-        elif sys.argv[1] in ["-V", "--version"]:
-            print(f"pysentry-rs {__version__}")
-            return
-
-    # Main parser for audit command (default) and help
-    parser = argparse.ArgumentParser(
-        prog="pysentry-rs",
-        description="Security vulnerability auditing for Python packages",
-        usage="pysentry-rs [OPTIONS] [PATH] [COMMAND]",
-    )
-
-    # Add version argument
-    parser.add_argument(
-        "-V", "--version", action="version", version=f"pysentry-rs {__version__}"
-    )
-
-    # Main audit arguments
-    parser.add_argument(
-        "path",
-        nargs="?",
-        default=".",
-        metavar="PATH",
-        help="Path to the project directory to audit [default: .]",
-    )
-    parser.add_argument(
-        "--format",
-        choices=["human", "json", "sarif"],
-        default="human",
-        help="Output format [default: human] [possible values: human, json, sarif]",
-    )
-    parser.add_argument(
-        "--severity",
-        choices=["low", "medium", "high", "critical"],
-        default="low",
-        help="Minimum severity level to report [default: low] [possible values: low, medium, high, critical]",
-    )
-    parser.add_argument(
-        "--ignore",
-        action="append",
-        dest="ignore_ids",
-        metavar="ID",
-        help="Vulnerability IDs to ignore (can be specified multiple times)",
-    )
-    parser.add_argument(
-        "-o", "--output", metavar="FILE", help="Output file path (defaults to stdout)"
-    )
-    parser.add_argument(
-        "--all",
-        action="store_true",
-        help="Include ALL dependencies (main + dev, optional, etc)",
-    )
-    parser.add_argument(
-        "--direct-only",
-        action="store_true",
-        help="Only check direct dependencies (exclude transitive)",
-    )
-    parser.add_argument("--no-cache", action="store_true", help="Disable caching")
-    parser.add_argument("--cache-dir", metavar="DIR", help="Custom cache directory")
-    parser.add_argument(
-        "--source",
-        choices=["pypa", "pypi", "osv"],
-        default="pypa",
-        help="Vulnerability data source [default: pypa] [possible values: pypa, pypi, osv]",
-    )
-    parser.add_argument(
-        "--resolver",
-        choices=["uv", "pip-tools"],
-        default="uv",
-        help="Dependency resolver for requirements.txt files [default: uv] [possible values: uv, pip-tools]",
-    )
-    parser.add_argument(
-        "--requirements-files",
-        nargs="+",
-        metavar="FILE",
-        help="Specific requirements files to audit (disables auto-discovery)",
-    )
-    parser.add_argument(
-        "-v", "--verbose", action="store_true", help="Enable verbose output"
-    )
-    parser.add_argument(
-        "-q", "--quiet", action="store_true", help="Suppress non-error output"
-    )
-
-    # Add custom help text for commands
-    parser.epilog = """
-Commands:
-  resolvers      Check available dependency resolvers
-  check-version  Check if a newer version is available
-  help           Print this message or the help of the given subcommand(s)
-"""
-
-    args = parser.parse_args()
 
     try:
-        # Main audit functionality - convert --all to dev/optional
-        dev = args.all
-        optional = args.all
-
-        result = audit_with_options(
-            path=args.path,
-            format=args.format,
-            source=args.source,
-            min_severity=args.severity,
-            ignore_ids=args.ignore_ids,
-            output=args.output,
-            dev=dev,
-            optional=optional,
-            direct_only=args.direct_only,
-            no_cache=args.no_cache,
-            cache_dir=args.cache_dir,
-            resolver=args.resolver,
-            requirements_files=args.requirements_files,
-            verbose=args.verbose,
-            quiet=args.quiet,
-        )
-
-        if not args.output:
-            print(result)
+        # Pass all arguments directly to the Rust CLI - this ensures perfect compatibility
+        exit_code = run_cli(sys.argv)
+        sys.exit(exit_code)
 
     except Exception as e:
         print(f"Error: {e}", file=sys.stderr)

{pysentry_rs-0.2.0.dist-info → pysentry_rs-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysentry-rs
-Version: 0.2.0
+Version: 0.2.2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
@@ -26,6 +26,8 @@ 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/)
+
 [Help to test and improve](https://github.com/nyudenkov/pysentry/issues/12)
 
 A fast, reliable security vulnerability scanner for Python projects, written in Rust.
@@ -42,11 +44,11 @@ PySentry audits Python projects for known security vulnerabilities by analyzing
   - PyPA Advisory Database (default)
   - PyPI JSON API
   - OSV.dev (Open Source Vulnerabilities)
-- **Flexible Output**: Human-readable, JSON, and SARIF formats
+- **Flexible Output for different workflows**: Human-readable, JSON, SARIF, and Markdown formats
 - **Performance Focused**:
   - Written in Rust for speed
   - Async/concurrent processing
-  - Intelligent caching system
+  - 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)
@@ -197,7 +199,7 @@ pysentry --resolver uv /path/to/project
 pysentry --resolver pip-tools /path/to/project
 
 # Include all dependencies (main + dev + optional)
-pysentry --all
+pysentry --all-extras
 
 # Filter by severity (only show high and critical)
 pysentry --severity high
@@ -210,14 +212,22 @@ pysentry --format json --output audit-results.json
 
 ```bash
 # Using uvx for comprehensive audit
-uvx pysentry-rs --all --format sarif --output security-report.sarif
+uvx pysentry-rs --all-extras --format sarif --output security-report.sarif
+
+# Check multiple vulnerability sources concurrently
+uvx pysentry-rs --sources pypa,osv,pypi /path/to/project
+uvx pysentry-rs --sources pypa --sources osv --sources pypi
 
-# Check only direct dependencies using OSV database
-uvx pysentry-rs --direct-only --source osv
+# 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
-pysentry --all --format sarif --output security-report.sarif
-pysentry --direct-only --source osv
+pysentry --all-extras --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
@@ -244,41 +254,140 @@ 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
+pysentry --sources pypa,pypi,osv --all-extras --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
 ```
 
 ## Configuration
 
 ### Command Line Options
 
-| Option           | Description                                           | Default             |
-| ---------------- | ----------------------------------------------------- | ------------------- |
-| `--format`       | Output format: `human`, `json`, `sarif`               | `human`             |
-| `--severity`     | Minimum severity: `low`, `medium`, `high`, `critical` | `low`               |
-| `--source`       | Vulnerability source: `pypa`, `pypi`, `osv`           | `pypa`              |
-| `--all`          | Include all dependencies (main + dev + optional)      | `false`             |
-| `--direct-only`  | Check only direct dependencies                        | `false`             |
-| `--ignore`       | Vulnerability IDs to ignore (repeatable)              | `[]`                |
-| `--output`       | Output file path                                      | `stdout`            |
-| `--no-cache`     | Disable caching                                       | `false`             |
-| `--cache-dir`    | Custom cache directory                                | `~/.cache/pysentry` |
-| `--verbose`      | Enable verbose output                                 | `false`             |
-| `--quiet`        | Suppress non-error output                             | `false`             |
-| `--resolver`     | Dependency resolver: `auto`, `uv`, `pip-tools`        | `auto`              |
-| `--requirements` | Additional requirements files (repeatable)            | `[]`                |
+| 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`            |
+| `--all-extras`             | Include all dependencies (main + dev + optional)        | `false`           |
+| `--direct-only`            | Check only direct dependencies                          | `false`           |
+| `--ignore`                 | Vulnerability IDs to ignore (repeatable)                | `[]`              |
+| `--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 caching system to avoid redundant API calls:
+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
 
-- **Default Location**: `~/.cache/pysentry/` (or system temp directory)
-- **TTL-based Expiration**: Separate expiration for each vulnerability source
 - **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
 
-To clear the cache:
+#### 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
@@ -376,6 +485,10 @@ Support for projects without lock files:
 
 Most comfortable to read.
 
+### Markdown
+
+GitHub-friendly format with structured sections and severity indicators. Perfect for documentation, GitHub issues, and security reports.
+
 ### JSON
 
 ```json
@@ -403,26 +516,28 @@ Compatible with GitHub Security tab, VS Code, and other security tools.
 
 PySentry is designed for speed and efficiency:
 
-- **Concurrent Processing**: Vulnerability data fetched in parallel
-- **Smart Caching**: Reduces API calls and parsing overhead
+- **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 for optimal 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
-
-### Benchmarks
-
-Typical performance on a project with 100+ dependencies:
-
-- **Cold cache**: 15-30 seconds
-- **Warm cache**: 2-5 seconds
-- **Memory usage**: ~50MB peak
+- **Resolution caching**: Eliminates repeated resolver calls for unchanged requirements
 
 ## Development
 
@@ -510,8 +625,9 @@ pysentry --verbose /path/to/project
 # Check network connectivity
 curl -I https://osv-vulnerabilities.storage.googleapis.com/
 
-# Try with different source
-pysentry --source pypi
+# Try with different or multiple sources
+pysentry --sources pypi
+pysentry --sources pypa,osv
 ```
 
 **Slow requirements.txt resolution**
@@ -546,12 +662,43 @@ ls uv.lock poetry.lock pyproject.toml
 **Performance Issues**
 
 ```bash
-# Clear cache and retry
-rm -rf ~/.cache/pysentry
+# 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

pysentry_rs-0.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+pysentry/__init__.py,sha256=uSo2bKZNbcRd1bEXOzF3MuxrEapECowrIHG0t_DERa8,611
+pysentry/_internal.cpython-313-darwin.so,sha256=Rdqk-Kd_Zv7n-zRmw0wjVgeUUtKG2DFd83DtwnLqe_I,9928464
+pysentry_rs-0.2.2.dist-info/METADATA,sha256=q5sPtpWGSajB12VZieJeNdCuLctHUe-fx9MZw-cQG8U,23331
+pysentry_rs-0.2.2.dist-info/WHEEL,sha256=BEq5B3wYswoCWPV13YmTFE5pEXWgkinJwNC6mhIE-oI,104
+pysentry_rs-0.2.2.dist-info/entry_points.txt,sha256=3bJguekVEbXTn-ceDCWJaSIZScquPPP1Ux9TPVHHanE,44
+pysentry_rs-0.2.2.dist-info/licenses/LICENSE,sha256=TAMtDCoJuavXz7pCEklrzjH55sdvsy5gKsXY9NsImwY,34878
+pysentry_rs-0.2.2.dist-info/RECORD,,

pysentry/__main__.py

@@ -1,6 +0,0 @@
-"""Main entry point for pysentry when run as a module."""
-
-from . import main
-
-if __name__ == "__main__":
-    main()

pysentry_rs-0.2.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pysentry/__init__.py,sha256=kDa2q8nWFR120mhgRaTBxmI8Yxf26tsE5Pdk8tg35VI,5898
-pysentry/__main__.py,sha256=FJdFFQuSE8TYsZtY_vb00oCE2nvq9hB6MhMLBxnn7Ns,117
-pysentry/_internal.cpython-313-darwin.so,sha256=APKC5kmEcyPjPwpswx0fms9Kjco3B1FDtwk4eOzv8C8,6238592
-pysentry_rs-0.2.0.dist-info/METADATA,sha256=JAISzKEXYsg9sS29nTxu1NwyVZVZp1_vCKpxdQ2jLhE,17816
-pysentry_rs-0.2.0.dist-info/WHEEL,sha256=BEq5B3wYswoCWPV13YmTFE5pEXWgkinJwNC6mhIE-oI,104
-pysentry_rs-0.2.0.dist-info/entry_points.txt,sha256=3bJguekVEbXTn-ceDCWJaSIZScquPPP1Ux9TPVHHanE,44
-pysentry_rs-0.2.0.dist-info/licenses/LICENSE,sha256=TAMtDCoJuavXz7pCEklrzjH55sdvsy5gKsXY9NsImwY,34878
-pysentry_rs-0.2.0.dist-info/RECORD,,