ChainBreaker

      _           _       _                    _             
     | |         (_)     | |                  | |            
  ___| |__   __ _ _ _ __ | |__  _ __ ___  __ _| | _____ _ __ 
 / __| '_ \ / _` | | '_ \| '_ \| '__/ _ \/ _` | |/ / _ \ '__|
| (__| | | | (_| | | | | | |_) | | |  __/ (_| |   <  __/ |   
 \___|_| |_|\__,_|_|_| |_|_.__/|_|  \___|\__,_|_|\_\___|_|   
                                                             
                                                             

Supply Chain Attack Detection Tool for npm and PyPI

---

ChainBreaker detects supply chain attacks in npm and PyPI packages before they reach your codebase. It analyzes packages for typosquatting, malicious code patterns, suspicious maintainers, version anomalies, and license compliance issues.

Features

Feature	Description
Typosquat Detection	Finds packages impersonating popular libraries via character substitution, keyboard proximity, and phonetic similarity
Malicious Code Analysis	Detects obfuscation, reverse shells, cryptominers, data exfiltration, and suspicious install scripts
Maintainer Reputation	Flags disposable emails, new accounts, and package takeover patterns
Version Anomaly Detection	Catches suspicious version jumps, downgrades, and pre-release abuse
Dependency Analysis	Scans dependency trees for known vulnerabilities and dependency confusion risks
License Compliance	Detects viral licenses (GPL, AGPL, SSPL) and license changes between versions
Lockfile Diffing	Compare lockfiles to detect unauthorized dependency changes
SBOM Generation	Generate SPDX and CycloneDX Software Bill of Materials
CI/CD Integration	GitHub Actions + GitLab CI with SARIF output for GitHub Security tab

Installation

pip install chainbreaker

Or from source:

git clone https://github.com/s1d9e/chainbreaker.git
cd chainbreaker
pip install -e .

Usage

Scan a project

# Auto-detect ecosystem and scan
chainbreaker scan ./my-project

# Scan npm project with JSON output
chainbreaker scan ./my-app --registry npm --format json --output report.json

# Scan PyPI project, fail on high severity
chainbreaker scan ./my-lib --registry pypi --fail-on high

Inspect a remote package

# Check an npm package
chainbreaker inspect lodash --registry npm

# Check a PyPI package with specific version
chainbreaker inspect requests --registry pypi --version 2.28.0

# Output as SARIF for GitHub Security tab
chainbreaker inspect event-stream --registry npm --format sarif --output results.sarif

Lockfile analysis

# Analyze a lockfile
chainbreaker lockfile ./package-lock.json

# Diff two lockfiles
chainbreaker diff old-lock.json new-lock.json

Generate SBOM

# Generate SPDX SBOM
chainbreaker sbom ./my-project --format spdx --output sbom.spdx.json

# Generate CycloneDX SBOM
chainbreaker sbom ./my-project --format cyclonedx --output sbom.cdx.json

Initialize CI/CD

# Generate GitHub Actions + GitLab CI configs
chainbreaker init

Cache management

chainbreaker cache stats
chainbreaker cache cleanup
chainbreaker cache clear

Output Formats

Format	Flag	Description
rich	--format rich	Beautiful terminal output with colors (default)
json	--format json	Machine-readable JSON
csv	--format csv	Spreadsheet-compatible CSV
sarif	--format sarif	SARIF 2.1.0 for GitHub Security tab

Analyzers

ChainBreaker includes 6 specialized analyzer modules:

Analyzer	What it catches
typosquat	Package impersonation, character substitution, keyboard typos
malicious	eval/exec, obfuscation, reverse shells, cryptominers, data exfil
maintainer	Disposable emails, new accounts, package takeover
version	Major version jumps, downgrades, version gaps
dependency	Known CVEs, dependency confusion, deep dependency chains
license	Viral licenses (GPL/AGPL/SSPL), missing licenses, license changes

Running specific analyzers

chainbreaker scan ./my-project --analyzers typosquat,malicious

Configuration

ChainBreaker uses a YAML configuration file at ~/.chainbreaker/config.yaml:

chainbreaker:
  cache:
    enabled: true
    ttl: 3600

  scan:
    max_depth: 5
    timeout: 30

  analyzers:
    typosquat:
      enabled: true
      similarity_threshold: 0.8
    malicious:
      enabled: true
    license:
      enabled: true
      viral_licenses:
        - "GPL-2.0"
        - "GPL-3.0"
        - "AGPL-3.0"

Docker

# Build
docker build -t chainbreaker .

# Scan a local directory
docker run -v /path/to/project:/project chainbreaker scan /project

# Output SARIF
docker run -v /path/to/project:/project chainbreaker scan /project --format sarif --output /project/results.sarif

CI/CD Integration

GitHub Actions

# Generate workflow file
chainbreaker init --path .

# This creates .github/workflows/chainbreaker.yml

The workflow will:

• Scan on push/PR to main/master
• Run weekly schedule scans
• Upload SARIF results to GitHub Security tab
• Fail on critical/high severity findings

GitLab CI

chainbreaker init --path .
# Creates .gitlab-ci.yml

Project Structure

chainbreaker/
├── chainbreaker/
│   ├── __init__.py          # Version info
│   ├── __main__.py          # python -m chainbreaker
│   ├── main.py              # Typer CLI app
│   ├── core/                # Infrastructure layer
│   │   ├── http.py          # Async HTTP client
│   │   ├── cache.py         # SQLite cache
│   │   ├── errors.py        # Custom exceptions
│   │   ├── output.py        # Rich/JSON/CSV/SARIF output
│   │   ├── config.py        # Pydantic config
│   │   └── ratelimit.py     # Token bucket rate limiter
│   ├── analyzers/           # 6 analysis modules
│   │   ├── registry.py      # Base class + registry
│   │   ├── typosquat/       # Typosquat detection
│   │   ├── malicious/       # Malicious code patterns
│   │   ├── maintainer/      # Maintainer reputation
│   │   ├── version/         # Version anomaly detection
│   │   ├── dependency/      # Dependency tree analysis
│   │   └── license/         # License compliance
│   ├── scanners/            # Registry scanners
│   │   ├── npm.py           # npm registry API
│   │   ├── pypi.py          # PyPI JSON API
│   │   ├── lockfile.py      # Lockfile diffing
│   │   └── sbom.py          # SBOM generation
│   ├── ui/                  # Presentation layer
│   │   ├── theme.py         # Cyberpunk theme
│   │   ├── splash.py        # ASCII art banner
│   │   ├── table.py         # Rich tables
│   │   ├── tree.py          # Dependency tree viz
│   │   └── progress.py      # Progress bars
│   └── integrations/        # CI/CD integration
│       ├── github_actions.py
│       └── gitlab_ci.py
├── tests/                   # Test suite
├── pyproject.toml
├── Dockerfile
├── Makefile
└── README.md

Development

# Setup
git clone https://github.com/s1d9e/chainbreaker.git
cd chainbreaker
make dev

# Run tests
make test

# Lint
make lint

# Format
make format

How it works

1. Detection: ChainBreaker auto-detects the ecosystem (npm/PyPI) from project files
2. Fetch: Package metadata is fetched from registry APIs with rate limiting and caching
3. Analysis: 6 specialized analyzers scan the package for different attack vectors
4. Report: Findings are presented with severity levels, evidence, and recommendations

Supported Ecosystems

Ecosystem	Registry API	Lockfiles	Manifest Files
npm	registry.npmjs.org	package-lock.json, yarn.lock	package.json
PyPI	pypi.org	poetry.lock, requirements.txt	pyproject.toml, setup.py

Security

ChainBreaker is a detection tool, not a prevention tool. It helps you identify risks, but the final decision to use a package is yours.

If you find a security vulnerability in ChainBreaker itself, please report it responsibly via GitHub Issues.

License

MIT License - see LICENSE for details.

---

Made with ♥ by s1d9e