Software Supply Chain Security Guide

A software supply chain attack compromises something you trust, a dependency, a build system, a maintainer account, a signing key or a vendor's update channel, so that malicious code arrives through the front door with a valid signature. SolarWinds, 3CX, xz utils, tj-actions and the Shai-Hulud npm worms all worked this way, and many of the npm and PyPI compromises in NHI Mgmt Group's breach database began with a stolen publishing token. This guide is the umbrella view: the threats at each stage from source to deployment, the controls for each, SBOM and VEX, signing and provenance, vendor software assurance, and how US and EU policy has changed. It is for application security, platform and procurement teams, and links to NHI Mgmt Group's deeper guides on open source, SLSA provenance and AI supply chains rather than repeating them.

Key takeaways

• Most attacks ride stolen identities. Maintainer accounts, npm and PyPI publishing tokens, CI bot tokens and signing keys are the usual entry point; treat them as privileged non-human credentials.
• Use the SLSA threat model as the map. Its nine threats, A to I, cover producer, source, build, publication, distribution, package selection and usage, and show which controls SLSA does and does not address.
• Verify, do not just sign. Signatures and provenance only help when the consumer checks them against an expected identity, source repository and builder at install or deploy time.
• SBOMs need VEX and a process. CISA's 2026 Minimum Elements add hash, licence, tool and generation context fields, but an SBOM is only useful if it is ingested, matched to advisories and paired with exploitability statements.
• US federal policy moved to risk-based. As of October 2026, OMB M-26-05 (23 January 2026) rescinded the mandatory self-attestation memos; the CISA attestation form is optional, while the EU Cyber Resilience Act's obligations are phasing in.

Threats across the supply chain

SLSA v1.2, the current approved version, labels supply chain threats A to I. MITRE ATT&CK covers the same ground as T1195 Supply Chain Compromise, with T1195.001 Compromise Software Dependencies and Development Tools and T1195.002 Compromise Software Supply Chain, and MITRE CAPEC groups the attack patterns under CAPEC-437 Supply Chain, including CAPEC-184 Software Integrity Attack, CAPEC-439 Manipulation During Distribution and CAPEC-444 Development Alteration.

SLSA also lists build dependency threats (its example is a compromised tar that backdoors built binaries), availability threats such as a deleted dependency, and verification threats such as tampered expectations or weak hashes. It recommends SHA-256 or stronger.

Source and maintainer account compromise

The identity behind a commit or a publish is the weakest link in most recent incidents. The Shai-Hulud first wave used stolen npm tokens to republish packages with a credential stealer that then spread itself, and the reviewdog/action-setup compromise led to tj-actions/changed-files, where a stolen bot token was used to point release tags at malicious code.

• Phishing-resistant MFA for maintainers and admins: on the repository host and every package registry account, including former employees' and contributors' accounts, which must be removed promptly.
• No long-lived publishing tokens: use OIDC-based trusted publishing from CI (supported by PyPI and npm) so no static token exists to steal. Where tokens remain, scope them to one package, set expiry and store them in a secrets manager. See the Secrets Management Guide.
• Branch and tag protection: required reviews, required status checks, no force pushes, and protected or immutable release tags. SLSA v1.2's Source track ties levels to these controls: Source L2+ addresses altered history and replaced tag content, L3+ skipped required checks, and L4 changes submitted without review or modified after review.
• Commit signing and metadata: signed commits help, but SLSA lists forged commit metadata as a separate threat. Rely on the repository host's verified push identity, not author fields.
• Bot and CI tokens: GitHub Apps and workflow tokens with the minimum permissions, short lifetimes and owners. See the CI/CD Pipeline Identity Security Guide.

Build and CI/CD integrity

A build system holds source, secrets and signing authority at once, which makes it the highest-value target. Mandiant found that the 3CX DesktopApp compromise (version 18.12.416 and earlier) began with a tampered X_TRADER installer downloaded from Trading Technologies' website, calling it "the first time Mandiant has seen a software supply chain attack lead to another software supply chain attack". The Codecov breach modified a CI script that customers downloaded and ran, and the TeamCity CVE-2023-42793 exploitation turned build servers into footholds.

• Ephemeral, isolated builders: each build runs in a fresh environment that cannot influence other builds, with provenance generated by the build platform rather than the build steps (SLSA Build L2 and L3). See the SLSA and Build Provenance Guide.
• Pin third-party actions and images by digest: a tag such as @v4 can be moved; a full commit SHA cannot.
• Separate build from release: signing keys and publishing credentials available only to protected release jobs on protected branches, never to pull request workflows from forks.
• Reproducible checks: the xz utils backdoor's build-time trigger shipped only in release tarballs, not in the Git repository. Build from source tags, and compare published artefacts against what the source produces where builds are reproducible.
• Egress control on build agents: restrict outbound network access so a poisoned step cannot exfiltrate secrets to arbitrary hosts.

# GitHub Actions: pin to an immutable commit, restrict the token
permissions:
  contents: read
steps:
  - uses: actions/checkout@<full-40-character-commit-sha>  # v4.x.y

Dependencies: malicious packages and dependency confusion

Dependency confusion happens when a build resolves an internal package name from a public registry because the public copy has a higher version. Typosquatting and slopsquatting (registering names that AI assistants invent) target developers choosing packages. Defensive controls:

• One resolution path: route all installs through an internal registry proxy, and avoid pip's --extra-index-url, which consults both indexes and can pick the public package. In npm, bind internal scopes to the internal registry (@yourco:registry=https://npm.internal.example/) and register your scope publicly.
• Lockfiles with integrity hashes: commit them, install with npm ci or pip install --require-hashes, and review lockfile diffs.
• Release cooldown: do not auto-adopt versions published in the last few days, which gives registries and researchers time to catch malicious releases. The axios npm compromise shows how auto-merging update bots can spread a hijacked release in minutes.
• Limit install-time code: disable lifecycle scripts by default (npm ci --ignore-scripts) and allow them per package.
• Intake policy: new dependencies need an owner, a maintenance check and approval. See the Open Source Security Guide.

Signing, provenance and verification

Signing proves who published an artefact; provenance proves how and from what it was built. Sigstore makes both practical: Fulcio issues a short-lived certificate binding an OIDC identity (an email address, service account or CI workflow) to a one-time key, the signature is recorded in the Rekor append-only transparency log, and the private key is discarded. Verification checks the signature, that the certificate identity matches an expected identity, the chain to Sigstore's root, and Rekor inclusion.

Verification must name the expected signer, for example cosign verify --certificate-identity <workflow-uri> --certificate-oidc-issuer https://token.actions.githubusercontent.com <image>. Enforce it in a Kubernetes admission controller or deployment gate, starting in audit mode. Signing keys and signing workflows are machine identities. See the Machine Identity, PKI and Certificate Lifecycle Guide.

SBOM and VEX

The 2021 NTIA minimum elements defined seven fields: supplier name, component name, version, other unique identifiers, dependency relationship, author of SBOM data and timestamp. CISA's August 2025 public comment draft added Component Hash, License, Tool Name and Generation Context, renamed four fields and removed the access control element. The final 2026 Minimum Elements for a Software Bill of Materials, published with NSA, FBI and international partners and reported on 31 July 2026, keeps those additions (component hash algorithm, licence, SBOM tool name and generation context), renames supplier name to Component Producer, and applies to all software, including open source, AI software and SaaS, noting that AI and SaaS may need further elements. For models and datasets, see the AI Supply Chain and AI-BOM Guide.

• Generate at build time in SPDX or CycloneDX, sign it, and record the generation context, since source, build and post-build SBOMs differ.
• Ingest supplier SBOMs into an inventory that matches components to advisories continuously, not a file share.
• Use VEX to cut noise: OpenVEX, designed to meet CISA's VEX minimum requirements, uses four statuses: not_affected, affected, fixed and under_investigation. A not_affected statement needs a justification such as vulnerable_code_not_in_execute_path or an impact statement, and affected should carry an action statement.
• Feed vulnerability management: SBOM plus VEX plus KEV tells you which advisories need action. See the Vulnerability Management Guide.

Vendor software assurance and policy

Commercial software brings the same risks with less visibility, and tools with privileged reach are the worst case: in July 2021 attackers exploited vulnerabilities in on-premises Kaseya VSA servers to push REvil ransomware through managed service providers to their customers. NIST SP 800-161 Rev. 1 (May 2022, updated 1 November 2024) is the reference for cybersecurity supply chain risk management (C-SCRM): a multilevel approach with C-SCRM strategy, implementation plans, policies and risk assessments for products and services.

OMB described the rescinded regime as imposing "unproven and burdensome software accounting processes that prioritized compliance over genuine security investments." In practice, buyers should still ask for SSDF-aligned evidence, an SBOM, VEX, a vulnerability disclosure policy and signed updates, scaled to the software's privilege. See the Security Questionnaires Guide and the Third-Party Access Guide.

Building the programme

1. Inventory: repositories, build systems, registries, publishing tokens, signing keys and third-party software with update channels. Rank by blast radius: what can push code to production or to customers.
2. Close the identity gaps first: phishing-resistant MFA for maintainers, trusted publishing, short-lived CI tokens, removal of former contributors. These are cheap and stop the most common attacks.
3. Harden the build: pin actions by SHA, isolate release jobs, restrict egress, and generate provenance for every release.
4. Control intake: route all package installs through a proxy with a release cooldown and blocking of known-malicious packages, starting in report-only mode for two to four weeks.
5. Verify in audit mode, then enforce: deploy signature and provenance checks in admission control as warnings, fix gaps, then enforce for one pilot cluster or product before the rest. Roll back by switching the policy to warn, never by removing it.
6. SBOM and VEX: produce them for your releases, require them from critical suppliers, and connect both to vulnerability management.
7. Rehearse a compromise: run a tabletop where a popular dependency ships a credential stealer, and time how long it takes to find every affected build and rotate exposed secrets. See the Leaked Credential Response Playbook.

Small vs large organisations: a small team gets most of the value from registry MFA, trusted publishing, pinned actions, lockfiles and the repository host's dependency and secret scanning. Large organisations and software producers need an internal registry with policy, SLSA Build L3 for release pipelines, admission control, supplier tiering under SP 800-161 and an SBOM inventory.

Detection and measurement

ATT&CK's detection strategy for T1195 (DET0537) looks for software installed from atypical sources or with hash mismatches, package managers pulling from non-approved repositories, and new or replaced binaries in system paths. Add supply chain signals of your own: new outbound destinations from build agents, workflow files changed outside pull requests, tags moved to new commits, and packages published without CI provenance.

• Token exposure: number of long-lived publishing and CI tokens, trending to zero as trusted publishing replaces them.
• Pinning coverage: percentage of third-party actions and base images pinned by digest.
• Provenance coverage: percentage of releases with signed provenance, and of deployments verified against it.
• Intake control: percentage of installs resolved through the internal proxy; blocked malicious or too-new packages per month.
• Time to blast radius: hours from a public malicious-package advisory to a full list of affected builds and hosts.
• Supplier coverage: percentage of critical suppliers providing an SBOM and VEX.

Framework mapping

Common failure patterns

• Rotating some tokens, not all: the Trivy supply chain attack turned on an incomplete rotation after a stolen PAT. After any compromise, rotate every credential the affected system could read.
• Trusting mutable references: actions, images and dependencies referenced by tag or range let an attacker change what you run without touching your repository.
• Signing without verifying: provenance generated but never checked at deploy gives assurance on paper only.
• Auto-merge without a delay: update bots that merge new versions immediately carry malicious releases into production faster than registries can remove them.
• Security tools with release rights: scanners and CI integrations hold broad tokens; the Checkmarx KICS attack used credentials stolen through Trivy to poison Docker images and extensions.
• SBOMs as shelfware: collected for compliance, never matched to advisories, so the question "are we affected?" still takes days.

Practitioner checklist

• Enforce phishing-resistant MFA on every repository, registry and CI admin account, and remove former maintainers.
• Replace long-lived publishing tokens with OIDC trusted publishing; scope and expire what remains.
• Pin third-party actions and container images by digest and set minimal workflow token permissions.
• Route package installs through one internal proxy with a release cooldown and no --extra-index-url.
• Generate signed SLSA provenance for releases and verify signer identity and source at deploy time.
• Produce SBOMs to CISA's 2026 minimum elements, publish VEX, and require both from critical suppliers.
• Tier suppliers by privilege under SP 800-161 and ask for SSDF-aligned evidence even where attestation is optional.
• Track EU CRA dates: vulnerability reporting from 11 September 2026, full obligations from 11 December 2027.
• Rehearse a malicious-dependency incident and measure time to blast radius.

Standards and references

• OpenSSF SLSA: Threats and mitigations (v1.2)
• NIST: SP 800-161 Rev. 1 Cybersecurity Supply Chain Risk Management Practices for Systems and Organizations
• MITRE ATT&CK: T1195 Supply Chain Compromise
• CISA: 2025 Minimum Elements for a Software Bill of Materials (public comment draft)
• CISA: Secure Software Development Attestation Form
• European Commission: Cyber Resilience Act
• Sigstore: Overview
• OpenVEX: Specification

Related NHI Mgmt Group resources: Open Source Security Guide · SLSA and Build Provenance Guide · AI Supply Chain and AI-BOM Guide · CI/CD Pipeline Identity Security Guide · Secrets Management Guide