depgate 0.9.0

DepGate detects and prevents dependency confusion and supply-chain risks. (Hard fork of Apiiro's Dependency Combobulator)

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
• 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

Package Manager	Language	Manifest Files
npm	JavaScript/TypeScript	package.json
PyPI	Python	requirements.txt, pyproject.toml
Maven	Java/Kotlin/Scala	pom.xml
NuGet	.NET/C#	.csproj, packages.config, project.json

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.

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