safepip-scanner 1.4.1

Python package security scanner — detects typosquats, CVEs, malicious code, and supply-chain risks before install

🛡 safepip

Python package security scanner — catches attacks before anything installs.

---

What is safepip?

safepip scans Python packages for security risks before any code downloads or runs. It catches typosquatting attacks, malicious packages, CVEs, and supply-chain risks in real time — with no API key, no cloud service, and no changes to your existing workflow.

pip install safepip-scanner
safepip watch enable        # intercepts every pip install system-wide

After that, pip install X is automatically scanned in CMD, PowerShell, and Admin CMD.

---

Features

	Feature	Description
🔍	Typosquat Detection	Levenshtein + keyboard proximity against 8,000+ real packages
🦠	Known Threat DB	70+ confirmed malicious packages, auto-updated from live feed
📋	CVE Analysis	Real-time OSV.dev lookups — critical / high / medium / low
🔬	Static Code Analysis	Scans wheel contents for exec chains, credential leaks, shells
📈	Release Anomaly	Burst patterns, dormancy breaks, maintainer reputation
📦	SBOM Generation	CycloneDX 1.4 — accepted by GitHub, FOSSA, Snyk
🎯	Watch Mode	Intercepts every pip install system-wide (all terminal types)
📊	Dashboard	Local browser UI at localhost:7676 with charts and history
⚡	Zero API Key	Fully functional without any paid plan or cloud account
🤖	AI Upgrade	Set ANTHROPIC_API_KEY for Claude-powered deep analysis

---

Installation

pip install safepip-scanner

Or from source:

git clone https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1
cd safepip
pip install -e .

---

Quick Start

# Scan before installing
safepip scan requests
safepip scan langchian          # ✕ BLOCK — typosquat of langchain
safepip scan requirements.txt   # scan a whole file

# Scan and install if safe
safepip install flask

# System-wide interception
safepip watch enable            # every pip install X is now scanned
safepip watch status            # check CMD + PowerShell coverage

# Generate SBOM
safepip sbom requests numpy flask --output sbom.json

---

Example Outputs

✅ Safe Package

$ safepip scan requests

[safepip] requests v2.34.2 | score=0 | LOW | INSTALL | 0.87s
  [LOW] Info: 'requests' is a well-known, widely-trusted PyPI package
  RULE: allowlist: 'requests' is trusted

⚠ Warning — CVEs Found

$ safepip scan pycrypto

[safepip] pycrypto v2.6.1 | score=52 | MEDIUM | WARN | 5.1s
  [HIGH] Code: 1 critical CVE — CVE-2018-6594, CVE-2013-7459
  [HIGH] Code: Install hook abuse in setup.py: os.system("chmod 0755 configure")
  [HIGH] Code: exec/eval on non-constant argument in setup.py
  Decision: ⚠ WARN  — review findings before installing

✕ Blocked — Typosquat Attack

$ safepip scan langchian

[safepip] langchian v0.2.5 | score=100 | HIGH | BLOCK | 3.4s
  [HIGH] Supply Chain: Confirmed threat: typosquat targeting 'langchain'
  [HIGH] Code: Outbound network call in splitter.py
  [MED]  Code: High release velocity: 1.2 releases/day (4 total)
  Decision: ✕ BLOCK

📦 SBOM Generation

$ safepip sbom requests flask numpy --output sbom.json

safepip sbom — scanning 3 package(s)
  requests → score 0 INSTALL
  flask    → score 0 INSTALL
  numpy    → score 0 INSTALL
✓ SBOM written to sbom.json
  CycloneDX SBOM — 3 components, 0 blocked, 0 warned

---

Commands

# Scanning
safepip scan <package> [packages...]    # scan one or more packages
safepip scan requirements.txt           # auto-reads requirements files
safepip scan sklearn cv2 PIL            # resolves aliases automatically
safepip scan-file requirements.txt      # explicit file scan shorthand
safepip install <package>               # scan then install if safe
safepip batch requirements.txt          # batch with summary table
safepip audit                           # scan all installed packages

# SBOM
safepip sbom <packages> -o sbom.json    # CycloneDX 1.4 SBOM

# Watch mode
safepip watch enable                    # intercept all pip install calls
safepip watch disable                   # remove all shims and aliases
safepip watch status                    # show CMD + PowerShell coverage

# Dashboard
safepip dashboard                       # open at http://localhost:7676

# Maintenance
safepip update                          # refresh live threat feed
safepip history                         # view scan history
safepip history --verdict HIGH          # filter by verdict
safepip history --stats                 # aggregate stats

---

Package Aliases

These common import names are resolved automatically:

Import	PyPI package
sklearn	scikit-learn
cv2	opencv-python
PIL	pillow
bs4	beautifulsoup4
yaml	pyyaml
dotenv	python-dotenv
jwt	pyjwt

safepip scan sklearn cv2 PIL    # automatically resolved

---

Watch Mode — All Terminals

safepip watch enable installs interception in three layers:

Layer	Covers	Method
PowerShell alias	PS5, PS7, Windows Terminal	function pip {} in profile
pip.bat shim	CMD, Windows Terminal (CMD)	Written beside pip.exe
UAC elevation	Administrator CMD, Admin PS	UAC prompt → system-level shim

safepip watch enable
# Open a new terminal (CMD or PowerShell)
pip install colourama    # ✕ BLOCK — intercepted automatically
pip install requests     # ✓ INSTALL — scanned and cleared
pip list                 # → passes through unchanged

---

Scoring

Score	Verdict	Action
0–30	🟢 LOW	INSTALL
31–65	🟡 MEDIUM	WARN
66–100	🔴 HIGH	BLOCK

Key contributors:

• +55–85 — Not on PyPI or known threat database
• +40 — Likely typosquat (≥75% name similarity)
• +20/12/6 — CVE severity (critical/high/medium) per CVE
• +30 — Critical static code finding (exec+base64, reverse shell)
• +30 — Latest release yanked
• +15 — Package age < 3 months
• –20 — Trusted package (numpy, requests, django, flask…)

---

Detection Pipeline

Each scan runs 7 stages before any code executes:

1. PyPI metadata      → version, age, author, deps, license
2. Typosquat check    → Levenshtein + keyboard proximity + homoglyph
3. CVE lookup         → OSV.dev realtime (critical/high/medium/low)
4. Download stats     → pypistats.org reputation tier
5. Release anomaly    → burst patterns, dormancy breaks, velocity
6. Code scan          → wheel/sdist inspection (no install)
7. Risk scoring       → rule-based (or Claude AI if key is set)

---

CI/CD Integration

Exit codes

Flag	Exit 0	Exit 1
(default)	All INSTALL	Any WARN or BLOCK
--fail-on-high	INSTALL + WARN	Any BLOCK
--fail-on-warn	INSTALL only	Any WARN or BLOCK

# Strict: fail build on any WARN or BLOCK
safepip scan-file requirements.txt --fail-on-warn

# Lenient: fail build only on confirmed HIGH-risk packages
safepip scan-file requirements.txt --fail-on-high

# Generate SBOM artifact
safepip sbom -r requirements.txt --output sbom.json

# SARIF for GitHub Security tab
safepip batch requirements.txt --sarif results.sarif

# HTML report for download artifact
safepip scan-file requirements.txt --html security-report.html

# JSON output for custom tooling
safepip scan requests --json | jq '{pkg: .package, ok: (.decision == "INSTALL")}'

GitHub Actions example:

name: Dependency Security Scan

on: [push, pull_request]

jobs:
  safepip:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install safepip
        run: pip install safepip-scanner

      - name: Update threat database
        run: safepip update-db

      - name: Scan dependencies (fail on HIGH)
        run: safepip scan-file requirements.txt --fail-on-high

      - name: Generate HTML report
        if: always()   # run even if scan fails
        run: safepip scan-file requirements.txt --html security-report.html --output plain

      - name: Upload HTML report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: security-report
          path: security-report.html

      - name: Generate SBOM
        run: safepip sbom -r requirements.txt --output sbom.json

      - name: Upload SBOM
        uses: actions/upload-artifact@v4
        with:
          name: sbom
          path: sbom.json

      - name: Upload SARIF to GitHub Security tab
        if: always()
        run: safepip batch requirements.txt --sarif results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

---

Configuration

Create .safepip.yml in your project root:

block_on_high: true
warn_new_packages: true
new_package_months: 6

allowlist:
  - requests
  - numpy

blocklist:
  - colourama
  - setup-tools

---

Claude AI Mode

For enhanced AI-powered analysis:

export ANTHROPIC_API_KEY=sk-ant-...
safepip scan requests    # "Engine: Claude AI" shown in header

Without a key, the local rule-based scorer handles everything.

---

Architecture

safe_pip/
├── scanner.py           Core 7-stage scan pipeline
├── typosquat.py         Name similarity engine
├── osv.py              CVE lookups (OSV.dev)
├── code_scanner.py      Static analysis of wheel/sdist
├── release_analyzer.py  Release velocity + maintainer reputation
├── local_scorer.py      Rule-based risk scoring
├── threat_feed.py       Live threat DB (GitHub-sourced, 24h cache)
├── sbom.py             CycloneDX 1.4 SBOM generation
├── dashboard.py         Local HTTP dashboard
├── watch.py            System-wide pip interceptor
├── policy.py           Configurable rules (.safepip.yml)
├── display.py          Rich terminal output
├── db.py               SQLite scan history
└── cli.py              Click CLI entry point

---

Contributing

git clone https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1
cd safepip
pip install -e ".[dev]"
pytest tests/

See CONTRIBUTING.md for guidelines.

---

License

MIT — see LICENSE

---

Changelog

See CHANGELOG.md for release history.