supply-chain-guard

Open-source supply-chain security scanner that runs locally and offline. It matches known-malicious packages, extensions, plugins, providers, container images and CI actions in 15 ecosystems, with tested matchers ready for more (see Ecosystem Coverage), reading manifests and lockfiles at any depth of a repository, including the transitive dependencies a lockfile pins; and it analyses what you install for malware behavior: GlassWorm, Vidar, Shai-Hulud, fake AI tool repos, account takeovers and 350+ threat indicators in all. It generates CycloneDX 1.6 SBOMs with real dependency inventories, grades SLSA provenance (parses and structurally validates in-toto/DSSE attestations), and correlates findings into attack-chain incidents. Supports EU Cyber Resilience Act SBOM and component-documentation work, and NIS2 supply chain risk-management measures.

Start in 30 seconds

Scan a project. No account, no configuration, and the scan itself makes no network request:

npx supply-chain-guard scan .

It exits 1 on a high finding or a scan that could not examine everything, and 2 on a critical finding, so it can gate a script as it is. To add the historical package catalog, run npx supply-chain-guard feed refresh with network access in the directory you scan from. The catalog is cached there in .scg-cache and belongs to the installed version, so refresh again after an upgrade.

Gate every pull request:

- uses: actions/checkout@v4
- uses: homeofe/supply-chain-guard@v6.3.2

Let your AI coding agent check a package before it installs it (MCP):

npm install -g supply-chain-guard
claude mcp add supply-chain-guard supply-chain-guard mcp

Every release is published to npm from this repository's CI with a signed SLSA provenance attestation, and the Action installs that exact version. Each GitHub Release also carries the tarball with that provenance as a Sigstore bundle (.sigstore.json). To check one yourself:

gh attestation verify supply-chain-guard-X.Y.Z.tgz \
  --bundle supply-chain-guard-X.Y.Z.tgz.sigstore.json \
  --repo homeofe/supply-chain-guard --digest-alg sha512

Everything else, from output formats to policies, is further down: Quickstart, GitHub Action, For AI Coding Agents (MCP).

Contents

• Background
• What It Detects
• Installation
• Quickstart
• Output Formats
• CI Exit Code Control
• Filtering
• Internal Disclosure
• Policy Configuration
• Baseline Diffing
• Example Output
• Ecosystem Coverage
• How It Compares
• GitHub Action
• For AI Coding Agents (MCP)
• Live Threat Feed
• Install Guard
• Adding Custom Patterns
• Architecture
• EU Compliance (CRA / NIS2)
• Show that you scan
• Contributing
• Changelog
• License

Background

For a deep dive into how GlassWorm infiltrates the software supply chain and the detection techniques behind this tool, read the blog post: How GlassWorm Gets In and How We Locked It Out.

What It Detects

Known-Malicious Packages and Components

Package, extension, plugin and image identities are matched against the threat feed. This list is generated from the indicators that actually ship, so an ecosystem is only named as covered once there is something to match:

• Known-malicious indicators ship for 15 ecosystems: npm, PyPI, RubyGems, Composer (PHP), NuGet (.NET), Cargo (Rust), Go modules, Maven / Gradle / SBT / Bazel, Dart / Flutter (pub), Terraform / OpenTofu providers, Container images, GitHub Actions, VS Code / Open VSX extensions, Browser extensions (Chrome, Edge, Firefox) and JetBrains plugins.
• Homebrew has a tested matcher and ships an indicator, but is not counted: its one indicator (the compromised Trivy tap release 0.69.4) needs a version, and only the legacy Brewfile.lock.json records one; current Homebrew writes no lock file, so a Brewfile alone cannot match it.
• Matchers are built and tested, but no malicious package is publicly known yet, for 8 more: Swift Package Manager, CocoaPods, Hex (Elixir / Erlang), CRAN (R), Conan (C / C++), Terraform / OpenTofu modules, Helm charts and Ansible Galaxy. They report the day an indicator is published, through the importer or a curated entry.

• The files read per ecosystem are in Ecosystem Coverage.
• Manifests and lockfiles are read wherever they sit in the tree, so a monorepo service or a .NET project in src/App/ is covered, and a lockfile's transitive dependencies are matched, not only direct ones.
• A version pin fires only on the exact malicious release; a hijacked legitimate package is never blocked by name. Registry-specific identities stay separate (Marketplace vs Open VSX, Chrome vs Edge, public vs private registries), and a commit SHA or image digest matches under any repository name.

Malware Campaigns

• GlassWorm campaign markers and Solana blockchain C2
• Vidar/GhostSocks infostealers (April 2026 Claude Code leak campaign)
• Shai-Hulud self-replicating npm worm
• XZ Utils backdoor (CVE-2024-3094), SolarWinds SUNBURST, Codecov, ua-parser-js, coa/rc
• Fake AI tool repos (Claude Code, Copilot, Cursor, ChatGPT, OpenClaw lures)

Code-Level Threats

• Obfuscated execution: eval+atob, eval+Buffer.from, template literal eval, dynamic import()
• Invisible Unicode, RTL override, SVG script injection, steganography
• Shannon entropy analysis for encoded payloads
• Proxy handler traps, WebAssembly from external sources
• Scan-coverage transparency: files above the 5 MB content-scan limit are surfaced as FILE_TOO_LARGE_SKIPPED (info severity, never affects exit codes) instead of being silently skipped - padding a payload past the limit no longer hides it from the report
• Executable scripts without an extension are read in the language their shebang names (#!/bin/sh, #!/usr/bin/env node, python3, ruby, perl and others), and an extensionless file named like a git hook (pre-commit, pre-push, ...) is read as shell even without one, so hooks under scripts/hooks/ or .husky/ and bin/ launchers in a directory scan or an npm tarball are content-scanned. *.bats suites are read as bash and, like *.test.ts, count as test files, and Perl source is read as .pl/.pm too. A file with no extension, no shebang and no hook name is still not read

Supply Chain Attacks

• Install hook deep analysis (secret harvesting, download-exec chains, binary blobs)
• Levenshtein-based typosquatting detection against top 100 npm packages with known-safe whitelist
• Dependency confusion and namespace squatting
• Starjacking: in npm <pkg> mode, corroborates a package's claimed repository against the repo's own package.json and flags a repo borrowed from an unrelated popular project to inherit its stars/trust (conservative: monorepos, forks, related names, and unfetchable repos are not flagged)
• Known-bad version blocklist (axios, ua-parser-js, coa, rc, event-stream, node-ipc, colors, faker)
• Publishing anomaly detection (maintainer changes, version gaps, script additions)