depsec Documentation

Installation

depsec requires Python 3.10+ and works on Linux, macOS, and Windows.

Basic Install

$ pip install depsec

This installs depsec with Tier 1 (heuristics) and Tier 2 (AST analysis) support. No additional configuration is needed.

With AI Support

# Install with the Anthropic SDK for Tier 3 AI analysis
$ pip install depsec[ai]

# Set your API key
$ export ANTHROPIC_API_KEY=sk-...

Usage

depsec is a drop-in replacement for pip install. It sits between you and pip, analyzing every package before it touches your system.

Commands

depsec install [packages...] [options]

Resolve, analyze, and install packages. This is the primary command.

$ depsec install flask requests
Resolving 12 packages...

Analyzing flask (3.0.0)          ✓ Safe
Analyzing requests (2.31.0)      ✓ Safe
Analyzing jinja2 (3.1.2)         ✓ Safe
Analyzing reqeusts (1.0.0)       ✗ Blocked — Typosquat of 'requests' (distance: 2)
  → Setup.py contains: subprocess.Popen, base64.b64decode

11 packages safe · 0 warnings · 1 blocked

Exits with code 1 if any packages are blocked (unless --allow-blocked is used).

depsec audit [packages...] [options]

Analyze packages without installing them. This runs the same analysis pipeline as install but never installs anything. Designed for CI pipelines and security reviews.

$ depsec audit -r requirements.txt

Exits with code 1 if any packages would be blocked. This makes it ideal for use in CI/CD pipelines as a quality gate.

depsec verify

Run a self-integrity check on depsec's own installation. This command verifies that depsec itself has not been tampered with.

Reports:

• Installed version
• SHA-256 hashes of all installed .py files
• Dependency versions
• Installation source (pip, pipx, etc.)

Exit Codes

Analysis Pipeline

depsec uses a 3-tier analysis pipeline. Each tier adds depth, and packages only proceed to higher tiers if earlier tiers flag potential issues.

Tier 1 Static Heuristics

Less than 100ms per package. Runs on every package.

Tier 2 AST Analysis

Less than 1 second per package. Parses Python source with the ast module -- no code is ever executed.

Tier 3 AI Analysis

2-10 seconds per package. Only triggered when Tiers 1-2 find issues.

When a package is flagged by earlier tiers, depsec sends the relevant source files to Claude for deeper adversarial security analysis. The AI reviews code behavior, not claims -- the system prompt explicitly instructs the model to ignore comments or strings that attempt to influence the assessment.

The AI analysis includes hardening against prompt injection:

• Source code is scanned for prompt injection patterns before being sent to the model
• Detected patterns are flagged with inline warnings so the model treats them as untrusted
• Response parser rejects "clearance" findings that match phrases like "code is safe"
• If the AI returns zero findings despite Tier 1-2 flags, a disagreement finding is generated at HIGH severity

Risk Scoring

Each finding has a severity level that maps to a numeric score. The package risk score is the maximum severity score across all findings.

The risk score determines the outcome:

Configuration

depsec reads configuration from ~/.depsec/config.toml. All settings have sensible defaults -- depsec works out of the box with no configuration file.

# General behavior mode
[general]
mode = "block"  # "block", "warn", "audit-only"

# Analysis settings
[analysis]
enable_ai = true            # Enable Tier 3 AI analysis
ai_provider = "anthropic"
ai_model = "claude-sonnet-4-20250514"
max_ai_analysis_time = 30   # Seconds before AI analysis times out

# Risk score thresholds
[thresholds]
block_score = 0.8           # Risk score >= this blocks installation
warn_score = 0.4            # Risk score >= this shows warnings

# Package lists
[allowlist]
packages = ["requests", "flask", "django"]
curated_list = "top-5000"   # Popular package list for typosquat checks

# Always block these packages
[denylist]
packages = ["colourama"]

Configuration Options

[general]

[analysis]

[thresholds]

[allowlist]

[denylist]

Architecture

depsec intercepts the package installation flow by using pip install --dry-run --report to resolve dependencies without installing anything, then downloads packages to a staging directory for analysis before allowing installation.

The Pip Bridge

depsec does not reimplement dependency resolution. It delegates to pip using pip install --dry-run --report <tmpfile>, which resolves the full dependency tree (including transitive dependencies) without installing anything. The JSON report is parsed into PackageInfo objects with name, version, SHA-256 hash, and download URL.

Packages are downloaded to a temporary staging directory. After analysis, approved packages are installed using pip install --no-index --find-links <staging_dir>, ensuring pip installs from local files only.

Module Overview

depsec/cli/

• main.py -- Entry point and command group
• install_cmd.py -- Install command with analysis gate
• audit_cmd.py -- Audit-only command for CI
• verify_cmd.py -- Self-integrity verification

depsec/pip_bridge/

• resolver.py -- Dependency resolution via pip --dry-run --report
• downloader.py -- Package download to staging directory
• installer.py -- Final installation from local files

depsec/analysis/

• pipeline.py -- Orchestrator, runs all tiers sequentially
• models.py -- Data models (PackageInfo, Finding, AnalysisResult)
• typosquat.py -- Tier 1: Typosquatting detection
• cve_checker.py -- Tier 1: CVE lookup via OSV API
• metadata.py -- Tier 1: PyPI metadata analysis
• ast_scanner.py -- Tier 2: AST-based source code scanning
• ai_analyzer.py -- Tier 3: LLM-powered analysis

depsec/config/

• settings.py -- Settings dataclass with TOML loading
• defaults.py -- Default configuration values

depsec/cache/

• store.py -- SQLite-backed cache keyed on package SHA-256

Security Model

A security tool is a high-value target. If an attacker compromises depsec, they can suppress findings for malicious packages, giving users a false sense of security. depsec applies defense-in-depth to its own supply chain.

Defense Layers

Self-Verification

Run depsec verify at any time to check depsec's own integrity. This command hashes every installed .py file and reports the installed version, dependency versions, and installation source.

$ depsec verify

CI/CD Integration

Use depsec audit in your CI/CD pipeline to catch malicious or vulnerable dependencies before they reach production. The command exits with code 1 if any packages would be blocked, making it a natural fit for pipeline quality gates.

GitHub Actions

name: CI
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install depsec
        run: pip install depsec
      - name: Audit dependencies
        run: depsec audit -r requirements.txt

GitLab CI

audit:
  image: python:3.12
  script:
    - pip install depsec
    - depsec audit -r requirements.txt