supply-guard

SupplyGuard

Supply chain security scanner that detects what vulnerability scanners miss.

Zero dependencies. Works offline. Single binary.

SupplyGuard complements tools like Trivy, Grype, and Snyk by focusing on threats they don't catch: malicious packages, suspicious install scripts, typosquatting, IOC matches, and policy violations.

Why

In March 2026, the Axios npm package (100M+ weekly downloads) was compromised via account hijacking. The malicious version included a RAT payload that self-destructed after execution. Traditional CVE scanners didn't detect it because it wasn't a vulnerability — it was a supply chain attack.

SupplyGuard is built to catch exactly these kinds of threats.

What it detects

Check	ID	Description
Lockfile integrity	SG001	Missing, corrupted, or out-of-sync lockfiles
Install scripts	SG002	Lifecycle scripts (postinstall, preinstall) with suspicious patterns
IOC matching	SG003	Known malicious packages, C2 domains, and suspicious maintainer emails
Dependency age	SG004	Packages published less than N days ago
Phantom deps	SG005	Dependencies in manifest but never imported in source
Typosquatting	SG006	Package names suspiciously similar to popular packages
Provenance	SG007	Missing integrity hashes, checksums, or SLSA/Sigstore attestations
Config hardening	SG008	Insecure package manager configuration
Actions pinning	SG009	GitHub Actions using tags instead of SHA pins
Network calls	SG010	Scripts making network requests, using exec APIs, or contacting C2 domains
Version ranges	SG011	Permissive or unbounded version ranges in dependency manifests
CI install audit	SG012	Unsafe install commands in CI workflows (e.g. npm install instead of npm ci)

Supported ecosystems

• npm (package.json, package-lock.json, .npmrc)
• pip/PyPI (requirements.txt, poetry.lock, pyproject.toml, .pth files)
• Cargo (Cargo.toml, Cargo.lock, build.rs)
• NuGet (.csproj, packages.lock.json)
• Maven (pom.xml)
• Gradle (build.gradle, verification-metadata.xml)

Quick start

# Scan current directory
supply-guard scan

# Scan a specific project
supply-guard scan /path/to/project

# JSON output for CI parsing
supply-guard scan -o json -q

# SARIF output for GitHub Code Scanning / VS Code
supply-guard scan -o sarif

# Markdown output for PR comments and AI chat
supply-guard scan -o markdown -q

# Auto-fix patches (pipe to git apply)
supply-guard scan -o diff -q > fixes.patch && git apply fixes.patch

# Fail CI on critical or high findings
supply-guard scan --fail-on critical,high

# Only show new findings vs. a baseline
supply-guard scan -o json -q > baseline.json
# ... later ...
supply-guard scan --baseline baseline.json -o json -q

# Watch mode (re-scans on file changes)
supply-guard scan --watch

# Initialize hardening config in your project
supply-guard init

# Install AI agent integration files (Cursor rules, MCP configs, AGENTS.md, SKILL.md)
supply-guard agents install

# Install only Cursor-specific files
supply-guard agents install --cursor

# Check which agent files are installed
supply-guard agents list

# Generate a PR comment from a saved scan
supply-guard report scan-result.json -f pr-comment

Installation

Quick install (recommended)

Linux / macOS:

curl -sSf https://raw.githubusercontent.com/AlbertoMZCruz/supply-guard/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/AlbertoMZCruz/supply-guard/main/install.ps1 | iex

Auto-detects OS and architecture, verifies checksums, and adds to PATH.

GitHub Releases

Download pre-built binaries for Linux, macOS, and Windows (amd64/arm64) from GitHub Releases.

Docker

docker run --rm -v $(pwd):/project ghcr.io/albertomzcruz/supply-guard scan /project

From source

go install github.com/AlbertoMZCruz/supply-guard/cmd/supply-guard@latest

Configuration

Create supplyguard.yaml in your project root (or run supply-guard init):

output: table

fail_on:
  - critical
  - high

ecosystems:
  npm:
    enabled: true
  pip:
    enabled: true

checks:
  dependency_age_days: 7
  # Version range strictness: exact, conservative, permissive
  version_range_strictness: conservative
  # Disable specific checks by ID (SG001-SG012)
  # disabled:
  #   - SG005

# Ignore packages entirely (all checks)
ignore:
  - some-trusted-internal-package

# Granular ignore rules (all non-empty fields must match)
# ignore_rules:
#   - check: SG002
#     package: esbuild
#     reason: "trusted build tool"
#   - check: SG009
#     file: ".github/workflows/sonarcloud.yml"
#     reason: "pinning managed by Renovate"

CI/CD Integration

GitHub Actions

- name: Install supply-guard
  run: curl -sSf https://raw.githubusercontent.com/AlbertoMZCruz/supply-guard/main/install.sh | sh

- name: Supply chain security scan
  run: supply-guard scan --fail-on critical,high -o sarif > results.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Docker (any CI)

docker run --rm -v $(pwd):/project ghcr.io/albertomzcruz/supply-guard scan /project --fail-on critical,high

Works with GitHub Actions, Azure DevOps, GitLab CI, Jenkins, and Bitbucket Pipelines. SupplyGuard auto-detects CI environments and adapts output accordingly.

Security features

• Safe file reading: All file reads go through safefile.ReadFile with O_NOFOLLOW (symlink race prevention), 50 MB size cap, and LimitReader enforcement.
• Bounded directory walking: safefile.WalkDir enforces max depth (20) and file count (50,000) limits to prevent resource exhaustion from malicious repos.
• Terminal escape protection: All untrusted data in table output is sanitized to prevent ANSI escape injection from malicious package names.
• Config injection warning: Detects when a scanned repo plants a supplyguard.yaml that could disable checks. Use --config to specify a trusted path, or set SUPPLYGUARD_TRUST_PROJECT_CONFIG=true to suppress.
• HTTPS-only updates: The update command enforces HTTPS and blocks redirect downgrades.
• Updatable threat intelligence: supply-guard update downloads the latest IOC database to ~/.config/supplyguard/iocs.json, which is automatically preferred over the embedded data.

AI/Agent integration

SupplyGuard is designed to be first-class AI-agent friendly. It can be used by any AI coding assistant via CLI, MCP server, or agent guidance files.

Quick setup

Install all agent integration files into your project with a single command:

supply-guard agents install

This creates:

File	Purpose
.cursor/rules/supply-guard.mdc	Auto-triggers scanning on dependency file edits
.cursor/mcp.json	Registers SupplyGuard as MCP server in Cursor
.vscode/mcp.json	Registers SupplyGuard as MCP server in VS Code / Copilot
AGENTS.md	Agent instructions for Codex and GitHub Copilot
SKILL.md	Cursor skill definition

Select specific integrations with flags:

supply-guard agents install --cursor   # Cursor rule + MCP config + SKILL.md
supply-guard agents install --vscode   # VS Code MCP config
supply-guard agents install --docs     # AGENTS.md + SKILL.md

MCP configs are merged non-destructively: existing servers in .cursor/mcp.json or .vscode/mcp.json are preserved.

Check install status with supply-guard agents list.

MCP Server

The supply-guard mcp command starts a Model Context Protocol server over stdio, allowing AI agents to call SupplyGuard as typed tools without parsing CLI output.

Setup in Cursor

Add to your MCP configuration (.cursor/mcp.json or Settings > MCP Servers):

{
  "mcpServers": {
    "supply-guard": {
      "command": "supply-guard",
      "args": ["mcp"]
    }
  }
}

Setup in VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "supply-guard": {
      "type": "stdio",
      "command": "supply-guard",
      "args": ["mcp"]
    }
  }
}

Setup in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "supply-guard": {
      "command": "supply-guard",
      "args": ["mcp"]
    }
  }
}

Prerequisite: The supply-guard binary must be installed and available in your PATH. See Installation.

MCP tools

Once configured, the following tools are available to your AI agent:

Tool	Description	Example usage
scan	Run a full or targeted scan on a directory	scan({ directory: ".", format: "markdown" })
explain_finding	Deep-dive on why a check matters, with real-world attack examples	explain_finding({ check_id: "SG006", package: "lod4sh" })
suggest_fix	Step-by-step remediation instructions for a finding	suggest_fix({ check_id: "SG009", file: ".github/workflows/ci.yml" })
list_checks	List all 12 security checks with descriptions and ecosystems	list_checks({})
get_policy	Read the active SupplyGuard policy configuration	get_policy({})
install_agent_files	Install agent integration files into a project	install_agent_files({ directory: ".", files: ["cursor-rule"] })

MCP resources

Resource URI	Description
supplyguard://checks	All check IDs with descriptions (JSON)
supplyguard://policy/{dir}	Active policy configuration for a directory (JSON)

Report command

Generate formatted reports from a saved JSON scan result:

# Save scan results
supply-guard scan -o json -q > scan-result.json

# GitHub PR comment (collapsible sections by severity)
supply-guard report scan-result.json -f pr-comment

# Executive summary for stakeholders
supply-guard report scan-result.json -f executive-summary

# Git commit message for security fixes
supply-guard report scan-result.json -f commit-message

# Developer action items
supply-guard report scan-result.json -f developer-brief

Output formats

Format	Flag	Best for
table	-o table	Human terminal display (default)
json	-o json	Programmatic parsing, automation
sarif	-o sarif	GitHub Code Scanning, IDE integration
markdown	-o markdown	AI chat display, PR comments
diff	-o diff	Auto-applying fixes via git apply
stream-json	-o stream-json	Real-time NDJSON event streaming

CLI flags reference

Flag	Short	Description
--output	-o	Output format (table, json, sarif, markdown, diff, stream-json)
--quiet	-q	Suppress banners, warnings, and decorations
--fail-on		Fail with exit 1 on these severities (e.g. critical,high)
--baseline		Path to previous scan JSON, shows only new findings
--watch		Watch for file changes and re-scan continuously
--config		Path to trusted config file

Exit codes

Code	Meaning
0	Success, no findings
1	Findings exceed --fail-on severity threshold
2	Scanner error (bad config, invalid path, etc.)
10	Critical findings present
11	High findings present (no critical)
12	Medium findings present (no critical/high)

Fix suggestions

Every finding includes a machine-actionable fix field (when available) with:

• type — replace, delete, add, config_change, or command
• file, line — target location
• old_content, new_content — for deterministic text replacements
• description — human-readable instructions when the fix requires judgment

Use --output diff to generate git apply-compatible patches from all fixable findings.

Baseline diffing

Compare scans across time using stable fingerprints:

# Initial scan
supply-guard scan -o json -q > baseline.json

# After changes, show only NEW findings
supply-guard scan --baseline baseline.json -o json -q

Each finding has a fingerprint field (SHA-256 prefix of check_id + file + package + version) for deduplication.

Agent guidance files

SupplyGuard ships files that AI agents auto-discover:

File	Auto-discovered by	Purpose
AGENTS.md	OpenAI Codex, GitHub Copilot	CLI reference, workflows, project layout
SKILL.md	Cursor Skills	When to use, how to invoke, how to interpret results
.cursor/rules/supply-guard.mdc	Cursor	Auto-triggers when editing dependency files
schema/scan-result.schema.json	Any JSON-aware agent	Formal schema for validating JSON output

Design principles

• Offline-first: All IOC data is embedded in the binary. Works without internet.
• Zero trust: Does not depend on npm audit, pip-audit, or any external tool.
• Complementary: Does not scan for CVEs (Trivy/Grype do that). Detects behavioral threats.
• Fail-open by default: Reports findings locally without blocking. Use --fail-on in CI to gate.
• Zero config needed: supply-guard scan . works out of the box with secure defaults.

Updating threat intelligence

The embedded IOC database covers known threats at build time. To get the latest:

supply-guard update

This saves the updated database to ~/.config/supplyguard/iocs.json. SupplyGuard automatically uses the disk version when available, falling back to the embedded data if not.

License

MIT