depwarden 0.1.0

Escape Dependency Hell — Scan, audit, and fix your Python dependencies in one command.

🛡️ depwarden

Escape Dependency Hell — Scan, audit, and fix your Python dependencies in one command.

What is depwarden?

depwarden is a CLI tool that scans your Python project's dependencies for:

• 🔒 Security vulnerabilities — CVE scanning via the OSV.dev database with clickable advisory links
• 📦 Dependency bloat — how many sub-dependencies each package pulls in
• 📊 Health scoring — 0-100 project health rating with letter grades (A-F)
• 🗑️ Unused dependencies — packages declared but never imported (project-wide)
• ❓ Missing dependencies — modules imported but not declared
• 💡 Smart suggestions — modern alternatives for common packages
• 🛠️ Actionable next steps — copy-paste commands to fix every issue
• 🔗 Clickable CVE links — Ctrl+Click vulnerability IDs to open full advisories in your browser

Quick Start

pip install depwarden

# Basic scan (security + bloat)
depwarden scan .

# Full scan (includes unused/missing detection)
depwarden scan . --full

# JSON output for CI/CD pipelines
depwarden scan . --format json

# Fail CI if HIGH+ vulnerabilities found
depwarden scan . --fail-on high

# Exclude specific directories from scanning
depwarden scan . --full --exclude migrations --exclude scripts

Example Output

╭───────────────────────────────────────╮
│ 🛡️  depwarden — Escape Dependency Hell │
╰───────────────────────────────────────╯
  📂 Project: /home/user/myproject
  📦 Dependencies scanned: 7

╭────────── 📊 Health Score ──────────╮
│   100 / 100    Grade: A             │
╰─────────────────────────────────────╯

          📦 Dependency Weight (Top 10)
┏━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┓
┃ Package  ┃ Version ┃ Pulls In ┃ Status ┃
┡━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━┩
│ typer    │ 0.24.1  │        7 │ ✅ OK  │
│ httpx    │ 0.28.1  │        7 │ ✅ OK  │
│ pydantic │ 2.12.5  │        4 │ ✅ OK  │
│ rich     │ 14.3.3  │        2 │ ✅ OK  │
└──────────┴─────────┴──────────┴────────┘

  ✅ No issues found — dependencies are healthy!

Why depwarden?

AI IDEs catch import errors in your editor. depwarden catches dependency health issues in your CI/CD pipeline — where no IDE exists.

Feature	pip-audit	deptry	safety	depwarden
CVE scanning	✅	❌	✅	✅
Clickable CVE links	❌	❌	❌	✅
Bloat analysis	❌	❌	❌	✅
Unused detection	❌	✅	❌	✅
Health score	❌	❌	❌	✅
Interactive loader	❌	❌	❌	✅
CVE ignore list	✅	❌	❌	✅
Free, no API key	✅	✅	❌	✅

Configuration

depwarden can be configured via pyproject.toml so you don't need to pass flags every time:

[tool.depwarden]
# Directories to exclude from import scanning
exclude = ["tests", "docs", "migrations", "scripts"]

# Automatically fail CI at this severity level
fail_on = "high"

# Whether to include dev dependencies in analysis
include_dev_deps = true

# Packages to ignore in unused dependency detection
# Useful for CLI tools (uvicorn), meta-packages (langchain), or runtime-only deps
ignore_unused = ["uvicorn", "gunicorn", "langchain"]

# Specific vulnerability IDs to ignore (accepted risk)
# Use the exact GHSA/PYSEC/CVE ID shown in the scan output
ignore_vulns = ["PYSEC-2022-43012", "GHSA-r9hx-vwmv-q579"]

Default Excludes

When running --full scans, depwarden automatically skips these directories to avoid false positives from test fixtures and example code:

• tests/, test/ — test directories
• docs/ — documentation
• examples/ — example/demo code
• benchmarks/ — performance benchmarks
• scripts/ — utility scripts

You can override these defaults in [tool.depwarden] or add more via --exclude.

CLI Reference

depwarden scan [PATH] [OPTIONS]

Arguments:
  PATH                    Path to the project (default: current dir)

Options:
  --full                  Include unused/missing dependency detection
  --format, -f TEXT       Output format: 'rich' or 'json' (default: rich)
  --fail-on TEXT          Exit code 1 on issues. Values:
                            Security: critical, high, medium, low
                            Quality:  unused, bloat, any
  --no-security           Skip vulnerability scanning (useful offline)
  --no-bloat              Skip bloat analysis
  --exclude, -e TEXT      Directories to exclude (can be repeated)

depwarden version          Show version info

CI/CD Integration

GitHub Actions

name: Dependency Health Check
on: [push, pull_request]

jobs:
  depwarden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install depwarden
      - run: pip install -r requirements.txt
      - run: depwarden scan . --full --fail-on high

GitLab CI

depwarden:
  stage: test
  image: python:3.12-slim
  script:
    - pip install depwarden
    - pip install -r requirements.txt
    - depwarden scan . --full --fail-on high --format json
  allow_failure: false

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: depwarden
        name: depwarden
        entry: depwarden scan . --fail-on critical
        language: python
        additional_dependencies: [depwarden]
        always_run: true
        pass_filenames: false

Exit Codes

Code	Meaning
0	All healthy, no issues
1	Issues found (vulnerabilities, unused deps, etc.)
2	Configuration error (bad path, missing deps file)

How It Works

1. Reads your pyproject.toml, requirements.txt, or setup.cfg
2. Queries the OSV.dev database for known CVEs (free, no API key)
3. Analyzes each dependency's sub-dependency tree for bloat
4. Scans all .py files using Python's AST to find actual imports (with --full)
5. Compares declared vs. imported to find unused and missing dependencies
6. Scores your project 0-100 and outputs a beautiful terminal report or JSON

Interactive Experience

depwarden features a custom loading animation during scans:

[ •_• ] Contacting OSV.dev vulnerability database...
[ o_o ] Calculating transitive dependency bloat...
[ O_O ] Parsing Abstract Syntax Trees...
[ -_- ] Finalizing health scores...

Vulnerability IDs in the output are clickable hyperlinks — Ctrl+Click (or Cmd+Click on Mac) any CVE/GHSA ID to open the full advisory in your browser.

Supported Dependency Files

• pyproject.toml (PEP 621 + Poetry formats, including optional/dev dependencies)
• requirements.txt (including -r recursive includes)
• setup.cfg

License

MIT