pydepspy 0.1.0

Security scanner for Python dependencies - detects typosquats, CVEs, malicious hooks, unused deps, and metadata anomalies

PyDepSpy - Python Dependency Security Scanner

PyDepSpy is a production-ready CLI tool that scans Python project dependencies for security vulnerabilities and suspicious packages. It runs 5 independent detection engines in parallel across your dependency tree, detecting typosquats, CVEs, malicious install hooks, unused dependencies, and metadata anomalies.

Why PyDepSpy?

✅ 5 Detection Engines - Comprehensive scanning:

• Typosquat Detection: Finds packages similar to popular ones (e.g., requets instead of requests)
• CVE Scanner: Queries OSV.dev for known vulnerabilities
• Malicious Hooks: AST-scans setup.py for suspicious install-time code execution
• Ghost Dependencies: Identifies unused declared dependencies (security surface area)
• Metadata Auditor: Flags red flags in PyPI metadata (no homepage, brand new packages, suspicious emails)

✅ Parallel Execution - Scans 50 packages in ~3 seconds (not 50 seconds)

✅ Local Caching - Second scan of same project is instant (24-hour TTL on API responses)

✅ Beautiful Output - Rich terminal tables with color-coded severity

✅ Multiple Formats - Terminal, JSON, and SARIF (GitHub Code Scanning)

✅ CI/CD Ready - Exit code 1 on CRITICAL/HIGH findings, composable in pipelines

Installation

pip install pydepspy

Or from source:

git clone https://github.com/tanuj437/pydepspy.git
cd pydepspy
pip install -e .

Quick Start

# Scan current project
pydepspy scan

# Scan a specific directory
pydepspy scan --project /path/to/project

# Output as JSON
pydepspy scan --format json

# Save to file
pydepspy scan --output report.json

# Use SARIF for GitHub Code Scanning
pydepspy scan --format sarif --output results.sarif

Usage

Basic Scan

$ pydepspy scan
🔍 Scanning .
✓ No issues found across 24 packages

With Findings

$ pydepspy scan
🔍 Scanning .

┏━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ Severity ┃ Package       ┃ Type              ┃ Message            ┃
┡━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ CRITICAL │ requets       │ TYPOSQUAT         │ Possible typosquat │
│ HIGH     │ django        │ CVE               │ CVE-2024-XXXXX     │
│ MEDIUM   │ unused-pkg    │ UNUSED            │ Never imported     │
└──────────┴───────────────┴───────────────────┴────────────────────┘

3 CRITICAL • 1 HIGH • 1 MEDIUM across 24 packages

Command Line Options

Options:
  --project PATH         Path to Python project [default: current directory]
  --format TEXT          Output format: text, json, sarif [default: text]
  --output FILE          Write output to file instead of stdout
  --cache / --no-cache   Use local cache for API responses [default: cache enabled]
  --help                 Show help message

Exit Codes

• 0 - No CRITICAL or HIGH findings
• 1 - One or more CRITICAL or HIGH findings detected
• Other - Error occurred during scanning

This makes PyDepSpy composable in CI pipelines:

pydepspy scan || exit 1  # Fail the build if issues found

Output Formats

Terminal (Default)

Beautiful, human-readable Rich tables with color-coded severity.

JSON

Structured output for programmatic processing:

{
  "version": "1.0",
  "findings": [
    {
      "package": "malicious-pkg",
      "severity": "CRITICAL",
      "type": "TYPOSQUAT",
      "message": "Possible typosquat of: requests",
      "cve_id": null,
      "fix": null
    }
  ],
  "statistics": {
    "total": 1,
    "by_severity": {"CRITICAL": 1, "HIGH": 0, "MEDIUM": 0, "LOW": 0}
  }
}

SARIF

For GitHub Code Scanning integration:

pydepspy scan --format sarif --output results.sarif

Then upload to GitHub:

gh codeql database upload-results results.sarif --repository=...

Supported Formats

PyDepSpy automatically detects and parses dependencies from:

• requirements.txt - Standard pip format
• pyproject.toml - PEP 621 and Poetry format
• setup.py - Setuptools install_requires
• Pipfile / Pipfile.lock - Pipenv format

Caching

API responses are cached locally at ~/.pydepspy/cache.db with a 24-hour TTL:

# Use cache (default)
pydepspy scan

# Disable cache
pydepspy scan --no-cache

# Clear cache
rm ~/.pydepspy/cache.db

Second scans of the same project are instant! 🚀

Development

Setup

git clone https://github.com/tanuj437/pydepspy.git
cd pydepspy
pip install -e ".[dev]"

Run Tests

pytest
pytest --cov=pydepspy

Run Linters

black pydepspy tests
ruff check pydepspy tests
mypy pydepspy

Architecture

PyDepSpy uses a modular, detector-based architecture:

• Parsers - Extract dependencies from various formats
• Detectors - Independent scanning engines that return standardized Finding objects
• Aggregator - Deduplicates and scores findings
• Reporters - Render output in different formats
• Cache - SQLite-backed with TTL
• CLI - Click-based entry point

Each detector runs concurrently via asyncio.gather() for maximum performance.

Roadmap

v0.1.0 (Current)

• ✅ Typosquat detection
• ✅ CVE scanner
• ✅ Install hook inspector
• ✅ Ghost dependency finder
• ✅ Metadata auditor
• ✅ Terminal, JSON, SARIF output
• ✅ Caching

v0.2.0 (Planned)

• --fix flag for auto-upgrading vulnerable packages
• GitHub Actions integration
• More metadata anomaly checks
• Custom rule support
• Real-time PyPI monitoring

License

MIT License - see LICENSE file

Contributing

Contributions welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/something)
3. Add tests
4. Submit a PR

Acknowledgments

• OSV.dev - Free vulnerability database
• PyPI Simple API - Package metadata
• Rich - Beautiful terminal output
• Click - CLI framework

Contact

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: [e-mail]

---

Made with ❤️ for Python security