DepGate — Dependency Supply‑Chain Risk & Confusion Checker

DepGate is a modular CLI that detects dependency confusion and related supply‑chain risks across npm, Maven, PyPI, and NuGet projects. It analyzes dependencies from manifests, checks public registries, and flags potential risks with a simple, scriptable interface.

DepGate is a fork of Apiiro's "Dependency Combobulator", maintained going forward by cognitivegears. See Credits & Attribution below.

Features

• Multiple ecosystems: npm, PyPI, Maven, NuGet
• Pluggable analysis: compare, heuristics, policy, and linked levels
• Repository verification: Discovers and validates upstream source repositories
• OpenSourceMalware integration: Optional malicious package detection
• Registry proxy server: Drop-in registry replacement with policy enforcement
• Flexible inputs: Single package, manifest scan, or list from file
• Structured outputs: Human-readable logs plus CSV/JSON exports for CI
• Designed for automation: Predictable exit codes and quiet/log options

Quick Start

Option 1: Run without installation (using uvx):

# Single package (npm)
uvx depgate scan -t npm -p left-pad

# Scan a project directory (Maven)
uvx depgate scan -t maven -d ./my-project

# Heuristics analysis with JSON output
uvx depgate scan -t pypi -a heur -o results.json

Option 2: Install first (using pipx or pip):

# Install
pipx install depgate
# or: pip install depgate

# Then use depgate directly
depgate scan -t npm -p left-pad
depgate scan -t maven -d ./my-project
depgate scan -t pypi -a heur -o results.json

Installation

Requirements

• Python 3.10+
• Network access for registry lookups (when running analysis)
• OpenSourceMalware API token (optional, for malicious package detection)

Install

Using uv (development):

uv venv && source .venv/bin/activate
uv sync

From PyPI:

# Install globally
pip install depgate

# Install in isolated environment
pipx install depgate

# Run without installation (requires uv)
uvx depgate --help

Note: After installation via pip or pipx, you can use depgate directly. Without installation, use uvx depgate.

Basic Usage

Input Methods

• Single package (-p, --package): Analyze one package

  depgate scan -t npm -p left-pad
  depgate scan -t maven -p org.apache.commons:commons-lang3
  

• Directory scan (-d, --directory): Scan project for dependencies

  depgate scan -t npm -d ./my-project
  depgate scan -t pypi -d ./my-project
  

• File list (-l, --load_list): Analyze packages from a file

  depgate scan -t npm -l packages.txt
  

See Supported Package Managers for format details and examples.

Analysis Levels

• compare (or comp): Basic presence and metadata checks
• heuristics (or heur): Adds scoring and risk signals
• policy (or pol): Declarative rule-based evaluation
• linked: Repository linkage verification

See Analysis Levels for detailed explanations.

Supported Package Managers

See Supported Package Managers for complete details, lock file support, package formats, and examples.

Major Modes

CLI Scan Mode (Primary)

The primary mode for dependency analysis:

depgate scan -t <ecosystem> -p <package> -a <level> -o <output>

MCP Server Mode (Experimental)

DepGate includes an MCP server that exposes analysis capabilities via three tools:

• Lookup_Latest_Version - Resolve latest stable versions
• Scan_Project - Analyze project dependencies
• Scan_Dependency - Analyze single dependencies

See MCP Server for setup, tools, and client examples.

Proxy Server Mode

DepGate can act as a registry proxy, intercepting package manager requests and evaluating packages against policies:

# Start proxy server with policy enforcement
depgate proxy --port 8080 --config policy.yml

# Increase max request body size (bytes) for publishes/uploads
depgate proxy --port 8080 --config policy.yml --client-max-size 52428800

# Configure npm to use proxy
npm config set registry http://localhost:8080

# All npm install commands are now evaluated
npm install lodash  # Allowed or blocked based on policy

The proxy supports three decision modes:

• block: Return 403 for policy violations (default)
• warn: Allow but log violations
• audit: Allow all, log for review

See Proxy Server for setup and configuration.

Output Formats

DepGate supports multiple output formats:

• stdout: Human-readable logs (default)
• JSON: Structured data for programmatic use
• CSV: Tabular format for spreadsheets

depgate scan -t npm -p left-pad -a heur -o results.json
depgate scan -t npm -p left-pad -a heur -o results.csv

See Output Formats for complete schema and field descriptions.

Configuration

DepGate supports configuration via YAML files, environment variables, and CLI arguments. Configuration can customize:

• Registry URLs
• HTTP behavior
• Heuristics weights
• Policy rules
• OpenSourceMalware settings

See Configuration for details and examples.

Additional Features

OpenSourceMalware Integration

Optional malicious package detection via OpenSourceMalware.com API:

DEPGATE_OSM_API_TOKEN=token depgate scan -t npm -p package-name -a heur

See OpenSourceMalware Integration for setup and usage.

Policy Rules

Declarative rule-based evaluation with allow/deny decisions:

depgate scan -t npm -d ./project -a policy -c policy.yml

See Policy Configuration for schema and examples.

Repository Discovery

Automatic discovery and validation of upstream source repositories:

depgate scan -t npm -p left-pad -a linked

See Repository Discovery for discovery sources and version matching.

Version Resolution

Ecosystem-aware version resolution with strict prerelease policies. See Version Resolution for details per ecosystem.

CLI Options

Main Options

• -t, --type {npm,pypi,maven,nuget}: Package manager
• -p/‑d/‑l: Input source (mutually exclusive)
• -a, --analysis {compare,comp,heuristics,heur,policy,pol,linked}: Analysis level
• -o, --output <path>: Output file path
• -f, --format {json,csv}: Output format (auto-detected from extension)
• -c, --config <path>: Configuration file (YAML/JSON/YML)
• --set KEY=VALUE: Override configuration values
• --loglevel {DEBUG,INFO,WARNING,ERROR,CRITICAL}: Logging level
• --logfile <path>: Log to file
• -q, --quiet: Suppress stdout output
• -r, --recursive: Recursively scan directories
• --error-on-warnings: Exit with non-zero code if risks detected

OpenSourceMalware Options

• --osm-disable: Disable OpenSourceMalware checks
• --osm-api-token <token>: API token
• --osm-token-command <cmd>: Command to retrieve token
• --osm-base-url <url>: Override API URL
• --osm-cache-ttl <seconds>: Cache TTL
• --osm-auth-method {header,query}: Authentication method
• --osm-max-retries <count>: Maximum retries

Run depgate scan --help for complete option list.

Exit Codes

• 0: Success (no risks or informational only)
• 1: File/IO error (or policy denial, or linked analysis failure)
• 2: Connection error
• 3: Risks found and --error-on-warnings set

Note: For -a linked, exits with 0 only when all packages are linked; otherwise 1.

Documentation

Detailed Guides

• Supported Package Managers - Complete package manager reference
• Analysis Levels - Understanding analysis types
• Configuration - YAML config and environment variables
• Policy Configuration - Policy rules and schema
• OpenSourceMalware - Malicious package detection
• Repository Discovery - Repository discovery and version matching
• Version Resolution - Ecosystem-specific resolution semantics
• MCP Server - MCP server setup and tools
• Proxy Server - Registry proxy for policy enforcement
• Output Formats - CSV and JSON schemas

Contributing

See AGENTS.md for repository layout, development commands, and linting guidelines.

Lint:

uv run pylint src

Credits & Attribution

DepGate is a fork of "Dependency Combobulator" originally developed by Apiiro and its contributors: https://github.com/apiiro/combobulator - see CONTRIBUTORS.md.

Licensed under the Apache License 2.0. See LICENSE and NOTICE.