Metadata-Version: 2.4
Name: safepip-scanner
Version: 1.4.1
Summary: Python package security scanner — detects typosquats, CVEs, malicious code, and supply-chain risks before install
Author: safepip contributors
License: MIT
Project-URL: Homepage, https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1
Project-URL: Documentation, https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1#readme
Project-URL: Repository, https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1
Project-URL: Bug Tracker, https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1/issues
Keywords: pip,security,pypi,malware,typosquat,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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
Classifier: Topic :: System :: Installation/Setup
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: anthropic>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: build>=0.10; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

<div align="center">

# 🛡 safepip

**Python package security scanner — catches attacks before anything installs.**

[![PyPI version](https://img.shields.io/pypi/v/safepip-scanner.svg)](https://pypi.org/project/safepip-scanner/)
[![Python](https://img.shields.io/pypi/pyversions/safepip-scanner.svg)](https://pypi.org/project/safepip-scanner/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-605%20passing-brightgreen.svg)]()
[![No API Key](https://img.shields.io/badge/API%20key-not%20required-success.svg)]()
[![CI](https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1/actions/workflows/ci.yml/badge.svg)](https://github.com/busupallinaveen-hash/safepip-scanner-v1.4.1/actions)

</div>

---

## 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.

```bash
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

```bash
pip install safepip-scanner
```

Or from source:

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

---

## Quick Start

```bash
# 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

```bash
# 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` |

```bash
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 |

```bash
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 |

```bash
# 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:

```yaml
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:

```yaml
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:

```bash
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

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT — see [LICENSE](LICENSE)

---

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for release history.
