supply-chain-guard

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

[![npm version](https://img.shields.io/npm/v/supply-chain-guard?logo=npm)](https://www.npmjs.com/package/supply-chain-guard)
[![npm downloads](https://img.shields.io/npm/dw/supply-chain-guard?logo=npm&label=weekly%20downloads)](https://www.npmjs.com/package/supply-chain-guard)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?logo=typescript)](https://www.typescriptlang.org/)
[![CI](https://img.shields.io/github/actions/workflow/status/homeofe/supply-chain-guard/ci.yml?branch=main&label=CI&logo=github)](https://github.com/homeofe/supply-chain-guard/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/homeofe/supply-chain-guard/badge)](https://scorecard.dev/viewer/?uri=github.com/homeofe/supply-chain-guard)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/14934/badge)](https://www.bestpractices.dev/projects/14934)
[![AAHP Verify](https://github.com/homeofe/supply-chain-guard/actions/workflows/aahp-verify.yml/badge.svg)](https://github.com/homeofe/supply-chain-guard/actions/workflows/aahp-verify.yml)
[![AAHP conformant](https://img.shields.io/badge/AAHP-conformant-5b47d6)](https://github.com/homeofe/AAHP)
[![Last commit](https://img.shields.io/github/last-commit/homeofe/supply-chain-guard?logo=github)](https://github.com/homeofe/supply-chain-guard/commits/main)
[![scanned by supply-chain-guard](https://github.com/homeofe/supply-chain-guard/actions/workflows/self-scan.yml/badge.svg?branch=main)](https://github.com/homeofe/supply-chain-guard/actions/workflows/self-scan.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

![supply-chain-guard scanning a malicious npm package: risk gauges, GlassWorm incident correlation, and a remediation plan](assets/demo.gif)

## Start in 30 seconds

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

```bash
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:

```yaml
- uses: actions/checkout@v4
- uses: homeofe/supply-chain-guard@v6.3.0
```

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

```bash
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](https://www.npmjs.com/package/supply-chain-guard),
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:

```bash
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](#quickstart),
[GitHub Action](#github-action), [For AI Coding Agents (MCP)](#for-ai-coding-agents-mcp).

## Contents

- [Background](#background)
- [What It Detects](#what-it-detects)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Output Formats](#output-formats)
- [CI Exit Code Control](#ci-exit-code-control)
- [Filtering](#filtering)
- [Internal Disclosure](#internal-disclosure)
- [Policy Configuration](#policy-configuration-v44)
- [Baseline Diffing](#baseline-diffing-v44)
- [Example Output](#example-output)
- [Ecosystem Coverage](#ecosystem-coverage)
- [How It Compares](#how-it-compares)
- [GitHub Action](#github-action)
- [For AI Coding Agents (MCP)](#for-ai-coding-agents-mcp)
- [Live Threat Feed](#live-threat-feed)
- [Install Guard](#install-guard)
- [Adding Custom Patterns](#adding-custom-patterns)
- [Architecture](#architecture)
- [EU Compliance (CRA / NIS2)](#eu-compliance-cra--nis2)
- [Show that you scan](#show-that-you-scan)
- [Contributing](#contributing)
- [Changelog](#changelog)
- [License](#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](https://blog.elvatis.com/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:

<!-- ecosystem-list:begin (generated by scripts/generate-coverage-table.mjs; edit src/ecosystem-coverage.json) -->
- 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.
<!-- ecosystem-list:end -->

- The files read per ecosystem are in [Ecosystem Coverage](#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

### 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)

### Infrastructure & CI/CD
- GitHub Actions: unpinned actions, secrets exfiltration, encoded payloads, curl piping
- Agentic workflows (GitLost class): AI-agent steps and gh-aw `.github/workflows/*.md` that ingest untrusted issue/PR text, hold a cross-repo token, and can post publicly - the prompt-injection data-leak posture
- Dockerfile / Containerfile hardening: curl pipe, base images on a moving channel tag or without a
  digest, hardcoded secrets, SUID bits. These rules read Dockerfile instructions only
  (see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#base-image-pinning-decision-record)); known-malicious
  images are matched separately in Dockerfiles and in every YAML `image:` value (Compose, Kubernetes,
  workflow containers), see [Ecosystem Coverage](#ecosystem-coverage)
- Terraform/IaC: inline scripts, e