Metadata-Version: 2.4
Name: pip-check-safety
Version: 1.0.0
Summary: Scan pip packages for security risks before and after installation
Author: Pip Check Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/pip-check-safety/pip-check-safety
Keywords: security,pip,package,safety,malware,scanner,audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# pip-check-safety

Scan pip packages for security risks before and after installation.

## Features

- **Pre-installation checks**: Scan packages before you install them
- **Typosquatting detection**: Catch packages trying to impersonate popular libraries
- **Code scanning**: Detect suspicious patterns like crypto miners, data exfiltration, obfuscation
- **Environment audits**: Scan all your installed packages at once
- **Requirements scanning**: Check your requirements.txt before deployment

## Installation

```bash
pip install pip-check-safety
```

## Usage

### Check a package before installing

```bash
pip-check requests
```

### Deep scan (downloads and analyzes source code)

```bash
pip-check --deep some-package
```

### Audit all installed packages

```bash
pip-check --audit
```

### Check a requirements file

```bash
pip-check -r requirements.txt
```

### JSON output for CI/CD

```bash
pip-check --json requests
pip-check --audit --json
```

## What it checks

### PyPI Metadata
- Package age (brand new packages are higher risk)
- Download count (low downloads = less community vetting)
- Author information
- Source repository presence

### Typosquatting
- Levenshtein distance to popular packages
- Common character swaps (0/o, 1/l, rn/m)
- Hyphen/underscore variations
- Suspicious suffixes (-official, -secure, etc.)

### Code Patterns (deep scan)
- Dynamic code execution (exec, eval)
- Network exfiltration (socket connections, HTTP requests)
- Obfuscation (base64, marshal, ROT encoding)
- System access (subprocess, os.system)
- Credential theft patterns
- Crypto mining indicators
- Persistence mechanisms

## Exit Codes

- `0` - No issues or low risk only
- `1` - Medium risk findings
- `2` - High risk findings
- `3` - Critical risk findings

Use exit codes in CI/CD pipelines:

```bash
pip-check --audit
if [ $? -ge 2 ]; then
    echo "High-risk packages detected!"
    exit 1
fi
```

## Python API

```python
from pip_check import PyPIChecker, TyposquatDetector, CodeScanner, EnvironmentAuditor

# Check a single package
checker = PyPIChecker()
report = checker.check("requests")
report.print_report()

# Detect typosquatting
detector = TyposquatDetector()
report = detector.check("reqeusts")  # typo
print(report.findings)

# Scan installed package code
scanner = CodeScanner()
report = scanner.scan_installed("some-package")

# Audit entire environment
auditor = EnvironmentAuditor(deep_scan=True)
reports = auditor.audit_all()
auditor.print_summary(reports)
```

## License

MIT
