deputy

README

Deputy

Deputy enables dependency management at scale.

[!WARNING] This is an early, experimental project. Things will change, and some edges are sharp. If you try it, please share feedback in issues.

• Inventory dependencies across ecosystems, bring your own plugins for custom sources.
• Scan dependencies using vulnerability sources like OSV to produce actionable findings.
• Generate SBOMs (CycloneDX / SPDX via Protobom) for supply chain visibility.
• Diff dependency changes between Git refs, helping code reviews and audits.
• Triage and prioritize findings with optional agent assistance.
• Create remediation plans and optionally apply them automatically.
• Enforce policies in CI and at download-time via a package proxy.

Deputy aims to provide core dependency management primitives along with a unified toolchain, so you can focus on what matters: your code and policies that protect it. The tool is designed for extensibility, performance, and usability at scale; whether you’re an individual developer, a security team, or an enterprise organization. The goal is to empower you to manage dependencies effectively, reduce risk, and maintain a secure software supply chain with minimal friction.

Supported Targets

• Local and remote Git repositories
• Local directories
• Container images (remote registries, local Docker daemon, tarballs)
• SBOM files (CycloneDX / SPDX / Protobom)
• PURLs (Package URLs) for single-package queries
• Dockerfiles (static analysis)

Supported Ecosystems

Deputy scans dependencies across 15 ecosystems via OSV-SCALIBR and custom extractors:

Ecosystem	Scan	Proxy	Lockfiles / Manifests
Go	✓	✓	go.mod, go.sum, Go binaries
npm	✓	✓	package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock
PyPI	✓	✓	requirements.txt, Pipfile.lock, poetry.lock, uv.lock, pdm.lock, setup.py, Conda environments
RubyGems	✓	✓	Gemfile.lock, gems.locked, *.gemspec
Maven	✓	—	pom.xml, gradle.lockfile, JAR/WAR/EAR archives
Cargo	✓	—	Cargo.lock, Cargo.toml, Rust binaries
NuGet	✓	—	packages.lock.json, packages.config, *.deps.json
Hex	✓	—	mix.lock
Pub	✓	—	pubspec.lock
CocoaPods	✓	—	Podfile.lock, Package.resolved
Packagist	✓	—	composer.lock
GitHub Actions	✓	—	.github/workflows/*.yml
Haskell	✓	—	cabal.project.freeze, stack.yaml.lock
R	✓	—	renv.lock
C++	✓	—	conan.lock

Proxy support is available for Go, npm, PyPI, and RubyGems—ecosystems with standardized registry protocols for download-time policy enforcement

Documentation

• Start here: Documentation index
• Getting started: Getting started
• Concepts: Concepts
• Commands: Command reference
• Guides: Guides
• Reference (config/logging): Reference

Quick start

# Diff dependency changes at HEAD in the current repo
$ deputy

# Scan the current repo at HEAD
$ deputy scan

# Turn findings into a remediation plan (and optionally apply it)
$ deputy fix
$ deputy fix --apply .

# Verify dependency changes between refs (default behavior when running `deputy` inside a repo)
$ deputy diff main WORKING

# Generate an SBOM
$ deputy sbom --format spdx-json --output sbom.spdx.json

GitHub Actions

Deputy provides composable GitHub Actions for CI/CD integration. Scan results upload to GitHub's Security > Code scanning alerts tab via SARIF.

name: Security Scan
on: [push, pull_request]

permissions:
  security-events: write  # Required for SARIF upload
  contents: read

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: picatz/deputy/actions/setup@main
      - uses: picatz/deputy/actions/scan@main
        with:
          upload-sarif: true
          policy: policy/ci/security-gate.yaml  # Optional: enforce policies

Action	Purpose
setup	Install Deputy CLI (required first)
scan	Vulnerability scanning + SARIF upload
sbom	SBOM generation (CycloneDX/SPDX)
diff	Dependency change analysis for PRs
proxy	Block vulnerable packages at install time

Starter CI policies (policy/ci/) — review and customize for your needs:

• security-gate.yaml — Block critical vulns; block high when fixes exist
• pr-review.yaml — Stricter checks for new dependencies in PRs
• release-gate.yaml — Production release requirements

Reusable workflows for standardized security across repos:

• scan.yml — Basic vulnerability scanning
• pr-gate.yml — PR security enforcement with diff
• release-sbom.yml — SBOM generation on release

See the GitHub Actions Guide for workflow recipes, permissions reference, and advanced patterns.

Installation

Go install

$ go install github.com/picatz/deputy@latest

Pin a specific version for reproducibility: go install github.com/picatz/deputy@vX.Y.Z

Build from source

$ git clone https://github.com/picatz/deputy.git
$ cd deputy
$ go build -o deputy .
$ ./deputy --version

How Deputy fits together

flowchart LR
  subgraph Input
    Target[(Repo / Dir / SBOM)]
  end

  subgraph Core
    Inv[Inventory]
  end

  subgraph Commands
    Scan[scan]
    SBOM[sbom]
    Fix[fix]
    Triage[triage]
    Diff[diff]
    Proxy[proxy]
  end

  subgraph Policies
    Policy[CEL policies]
  end

  Target --> Inv
  Inv --> Scan
  Inv --> SBOM
  Inv --> Diff
  Scan --> Fix
  Scan --> Triage

  Policy -.-> Scan
  Policy -.-> SBOM
  Policy -.-> Fix
  Policy -.-> Triage
  Policy -.-> Proxy

  classDef source fill:#e3f2fd,stroke:#1565c0
  classDef process fill:#e8f5e9,stroke:#2e7d32
  classDef control fill:#fff3e0,stroke:#e65100

  class Target source
  class Inv,Scan,SBOM,Fix,Triage,Diff,Proxy process
  class Policy control

Legend: Dashed lines indicate policy enforcement paths.

Commands

Command	What it’s for	Docs
scan	Find known vulnerabilities via OSV (repos/dirs/SBOMs)	Reference
fix	Turn findings into upgrade commands / a plan (optionally apply)	Reference
triage	Summarize and prioritize findings (optional agent help)	Reference
diff	Compare dependency changes between Git refs	Reference
sbom	Emit CycloneDX/SPDX SBOMs at any Git ref	Reference
list	Dump normalized PURLs for quick auditing/scripting	Reference
policy	Lint/test/eval/bundle policies; authoring tools (LSP)	Reference
proxy	Policy-enforcing package proxy (Go/npm/PyPI/RubyGems)	Reference

Policies and enforcement

Deputy’s core design idea is: write policies once and reuse them everywhere (scan, diff, sbom, fix, triage, and proxy).

• Policy framework overview
• Policy bundle spec
• Policy examples
• Policy authoring LSP

# Lint policies before enforcement
$ deputy policy lint policy/examples/*.yaml

# Enforce a policy during scanning
$ deputy scan --policy policy/examples/severity-guardrail.yaml

Proxy (prevent risky dependencies)

If you want preventive controls (not just reactive scanning), run Deputy as a proxy and enforce policies at download time.

• Proxy command reference
• Proxy rollout guide

$ deputy proxy template > proxy.yaml
$ deputy proxy serve --config proxy.yaml

Configuration

• Example config (.deputy.yaml.example)
• Configuration reference
• Logging reference

Contributing

See the contributing guide.

License

MIT. See the LICENSE.