paulpas Dependency Supply Chain Security
Implements comprehensive supply chain security controls across the software dependency lifecycle — from generating SBOMs and signing artifacts to verifying signatures in CI, pinning versions, scanning transitive vulnerabilities, and building reproducible outputs. This skill covers every layer of defense against modern supply chain attacks like log4shell and the xz backdoor.
TL;DR Checklist
- Generate SBOM (SPDX or CycloneDX) on every build
- Pin all dependencies to exact versions with lockfiles
- Verify package signatures (Sigstore/cosign) before install
- Scan for vulnerabilities including transitive dependencies in CI
- Configure fail-on-critical policy for dependency scanning gates
- Implement SLSA Level 2+ provenance attestation
- Use patch files or override mechanisms for vulnerable transitive deps
- Build artifacts reproducibly for deterministic outputs
When to Use
Use this skill when:
- Setting up supply chain security for a new project or service
- Responding to a supply chain attack affecting your ecosystem (e.g., xz, log4shell)
- Meeting compliance requirements (SOC2, ISO 27001, NIST SSDF, Executive Order 14028)
- You need to generate and sign SBOMs for regulatory or customer mandates
- A CI/CD pipeline is missing dependency scanning, pinning, or provenance attestation
- An audit reveals unpinned dependencies or missing transitive vulnerability checks
- Your organization requires SLSA attestation Level 2 or higher
When NOT to Use
Avoid applying the full suite when:
- Prototyping a throwaway PoC with no deployment target (pinning is still good, but SBOM/signing overhead is not justified)
- Working in an air-gapped environment where internet-based verification tools are unreachable — use internal package proxies instead
- Managing build tool dependencies only (e.g., webpack, pytest) where supply chain risk is negligible — though pinning still applies
- The project uses a fully managed SaaS platform that handles signing and SBOM generation internally (verify their claims first)
Core Workflow
Inventory Dependencies — Generate a current dependency tree with exact versions using
npm ls,pip freeze, orgo list -m all. Identify direct vs transitive dependencies, registry sources, and update frequency. Checkpoint: Every dependency must have an exact version string — no ranges like^or~in the final lockfile.Pin to Exact Versions — Convert all version constraints to exact pins in your package manifests. Generate lockfiles for every ecosystem. Never commit a project without a lockfile checked into version control. Checkpoint: Run a clean install from lockfile only (
npm ci,pip sync/poetry install,go mod download) and verify the tree matches exactly.Generate SBOM — Produce a Software Bill of Materials in SPDX or CycloneDX JSON format on every build. Upload to artifact storage or a vulnerability scanner backend so the SBOM is available for scanning against CVE databases. Checkpoint: SBOM must include every transitive dependency, not just direct ones.
Scan Dependencies — Run comprehensive vulnerability scanning including transitive dependencies in CI. Use at least one SCA tool (Snyk, Dependabot, Trivy, or osv-scanner) with a fail-on-critical policy. Configure severity thresholds appropriate for your risk profile. Checkpoint: No CRITICAL or HIGH vulnerabilities may pass the gate — MEDIUM and LOW should trigger alerts but not block CI.
Verify Signatures — Before installing packages from registries in production environments, verify package signatures using Sigstore/cosign when available. For ecosystems that support it (Go module proxies, npm provenance), validate the signature chain before build proceeds. Checkpoint: Signature verification must be enforced at build time — not just development time.
Attest Provenance (SLSA) — Generate SLSA compliance attestation for your build artifacts. Start with Level 2 (provenance generated in CI), target Level 3 (verifier is the build service itself, one-time build). Document which level each artifact meets and why. Checkpoint: Build provenance must be machine-readable (in-toto attestation) and verifiable independently.
Enforce Reproducible Builds — Configure builds to produce deterministic outputs. Pin tool versions, strip non-deterministic metadata, and verify by rebuilding the same source from scratch. Checkpoint: Rebuilt artifact hash must match the original within your defined reproducibility tolerance.
Implementation Patterns / Reference Guide
Pattern 1: SBOM Generation (SPDX and CycloneDX)
SBOMs provide a machine-readable inventory of all software components. SPDX is widely adopted in regulated industries; CycloneDX is preferred for OWASP tooling and SCA integrations.
SPDX 2.3 JSON Format — Real Example
{
"spdxVersion": "SPDX-2.3",
"dataLicense": "CC0-1.0",
"SPDXID": "SPDXRef-DOCUMENT",
"name": "my-service",
"documentNamespace": "https://spdx.org/spdxdocs/my-service-20250115",
"creationInfo": {
"created": "2025-01-15T10:30:00Z",
"creators": ["Tool: syft v0.98.0"],
"licenseListVersion": "3.20"
},
"packages": [
{
"SPDXID": "SPDXRef-Package-pip-flask-3.0.0",
"name": "flask",
"versionInfo": "3.0.0",
"downloadLocation": "NOASSERTION",
"licenseConcluded": "BSD-3-Clause",
"copyrightText": "NOASSERTION",
"externalRefs": [
{
"referenceType": "cpe23Type",
"referenceLocator": "cpe:2.3:a:pallets_project:flask:3.0.0:*:*:*:*:*:*:*"
},
{
"referenceType": "purl",
"referenceLocator": "pkg:pypi/flask@3.0.0"
}
]
}
],
"relationships": [
{
"spdxElementId": "SPDXRef-DOCUMENT",
"relatedSpdxElement": "SPDXRef-Package-pip-flask-3.0.0",
"relationshipType": "DESCRIBES"
}
]
}
CycloneDX 1.5 JSON Format — Real Example
{
"bomFormat": "CycloneDX",
"specVersion": "1.5",
"version": 1,
"metadata": {
"timestamp": "2025-01-15T10:30:00Z",
"tools": [
{
"vendor": "anchore",
"name": "syft",
"version": "0.98.0"
}
],
"component": {
"name": "my-service",
"version": "1.2.3",
"type": "application",
"purl": "pkg:docker/myorg/my-service@1.2.3"
}
},
"components": [
{
"bom-ref": "pkg:pypi/flask@3.0.0",
"name": "flask",
"version": "3.0.0",
"type": "library",
"purl": "pkg:pypi/flask@3.0.0",
"licenses": [
{
"license": {
"id": "BSD-3-Clause",
"url": "https://spdx.org/licenses/BSD-3-Clause.html"
}
}
],
"externalReferences": [
{
"type": "vcs",
"url": "https://github.com/pallets/flask"
}
]
},
{
"bom-ref": "pkg:npm/express@4.18.2",
"name": "express",
"version": "4.18.2",
"type": "library",
"purl": "pkg:npm/express@4.18.2",
"licenses": [
{ "license": { "id": "MIT" } }
]
}
]
}
CI Pipeline: Generate SBOM with syft (Python + Node.js)
#!/bin/bash
# .github/workflows/scripts/generate-sbom.sh
# Generates both SPDX and CycloneDX SBOMs for all project dependencies
set -euo pipefail
ARTIFACT_DIR="${1:-.sbom-output}"
TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
PROJECT_NAME="${GITHUB_REPOSITORY##*/}"
mkdir -p "$ARTIFACT_DIR"
echo "::group::Generate SPDX SBOM for Python dependencies"
syft python:./venv \
--output spdx-json="$ARTIFACT_DIR/spdx-python.json" \
--file-metadata.exclude "/proc/*" \
--file-ownership exclude-sticky \
2>&1 | tee "$ARTIFACT_DIR/syft-python.log"
echo "::endgroup::"
echo "::group::Generate CycloneDX SBOM for Node.js dependencies"
syft nodejs:./ \
--output cyclonedx-json="$ARTIFACT_DIR/cyclonedx-nodejs.json" \
--file-metadata.exclude "/proc/*" \
2>&1 | tee "$ARTIFACT_DIR/syft-nodejs.log"
echo "::endgroup::"
# Also generate via native tools for ecosystems where syft coverage is thin
if [ -f "go.sum" ]; then
echo "::group::Generate CycloneDX SBOM for Go modules"
cyclonedx-npm --output-file "$ARTIFACT_DIR/cyclonedx-go.json" --output-type json || true
echo "::endgroup::"
fi
# Generate a combined summary
echo "{\"timestamp\":\"$TIMESTAMP\",\"project\":\"$PROJECT_NAME\",\"sboms\":{\"spdx\":\"\`ls $ARTIFACT_DIR/spdx-*.json\`\",\"cyclonedx\":\"\`ls $ARTIFACT_DIR/cyclonedx-*.json\`\"}}" \
> "$ARTIFACT_DIR/sbom-manifest.json"
echo "::notice::SBOMs generated in $ARTIFACT_DIR/"
ls -la "$ARTIFACT_DIR"/
Python Helper: Parse and Validate SBOM Content
"""
SBOM Validation and Transformation Utilities
Provides functions for validating SPDX and CycloneDX SBOM files,
checking completeness (all dependencies present), and transforming
between formats for different tooling requirements.
"""
from __future__ import annotations
import json
import hashlib
from pathlib import Path
from typing import Any
SPDX_REQUIRED_FIELDS: set[str] = {
"spdxVersion", "dataLicense", "SPDXID", "name",
"creationInfo", "packages"
}
CYCLONEDX_REQUIRED_FIELDS: set[str] = {
"bomFormat", "specVersion", "version", "metadata"
}
def validate_spdx_sbom(sbom_path: str) -> dict[str, Any]:
"""Validate an SPDX JSON SBOM file and return validation results.
Args:
sbom_path: Path to the SPDX JSON SBOM file.
Returns:
Dictionary with validation status, package count, and any errors found.
"""
result: dict[str, Any] = {
"valid": True,
"format": "spdx",
"package_count": 0,
"errors": list[str]()
}
try:
path = Path(sbom_path)
if not path.exists():
result["valid"] = False
result["errors"].append(f"File not found: {sbom_path}")
return result
content = json.loads(path.read_text(encoding="utf-8"))
# Check required top-level fields
missing_fields = SPDX_REQUIRED_FIELDS - set(content.keys())
if missing_fields:
result["valid"] = False
result["errors"].append(f"Missing required fields: {', '.join(sorted(missing_fields))}")
# Verify creation metadata
creation_info = content.get("creationInfo", {})
if "created" not in creation_info:
result["errors"].append("No 'created' timestamp in creationInfo")
# Count and validate packages
packages = content.get("packages", [])
result["package_count"] = len(packages)
for pkg in packages:
if "name" not in pkg or "SPDXID" not in pkg:
result["errors"].append(f"Package missing required fields: {pkg}")
except json.JSONDecodeError as exc:
result["valid"] = False
result["errors"].append(f"Invalid JSON: {exc}")
except Exception as exc:
result["valid"] = False
result["errors"].append(f"Unexpected error: {exc}")
return result
def validate_cyclonedx_sbom(sbom_path: str) -> dict[str, Any]:
"""Validate a CycloneDX JSON SBOM file and return validation results.
Args:
sbom_path: Path to the CycloneDX JSON SBOM file.
Returns:
Dictionary with validation status, component count, and any errors found.
"""
result: dict[str, Any] = {
"valid": True,
"format": "cyclonedx",
"component_count": 0,
"errors": list[str]()
}
try:
path = Path(sbom_path)
if not path.exists():
result["valid"] = False
result["errors"].append(f"File not found: {sbom_path}")
return result
content = json.loads(path.read_text(encoding="utf-8"))
# Check required top-level fields
missing_fields = CYCLONEDX_REQUIRED_FIELDS - set(content.keys())
if missing_fields:
result["valid"] = False
result["errors"].append(f"Missing required fields: {', '.join(sorted(missing_fields))}")
# Verify spec version compatibility
spec_version = content.get("specVersion", "")
supported_versions = {"1.4", "1.5"}
if spec_version not in supported_versions:
result["errors"].append(f"Unsupported CycloneDX spec version: {spec_version}")
# Count components
components = content.get("components", [])
result["component_count"] = len(components)
except (json.JSONDecodeError, KeyError) as exc:
result["valid"] = False
result["errors"].append(f"Validation error: {exc}")
return result
def generate_sbom_hash(sbom_path: str) -> str:
"""Generate a SHA-256 hash of an SBOM file for integrity verification.
Args:
sbom_path: Path to the SBOM JSON file.
Returns:
Hex-encoded SHA-256 digest of the SBOM content.
"""
path = Path(sbom_path)
content_bytes = path.read_bytes()
return hashlib.sha256(content_bytes).hexdigest()
def summarize_sbom(results: list[dict[str, Any]]) -> str:
"""Generate a human-readable summary of multiple SBOM validation results.
Args:
results: List of validation result dictionaries from validate_spdx_sbom
or validate_cyclonedx_sbom.
Returns:
Formatted summary string suitable for CI log output.
"""
total_packages = sum(r.get("package_count", r.get("component_count", 0)) for r in results)
errors = [err for r in results for err in r.get("errors", [])]
lines: list[str] = []
lines.append(f"SBOM Summary: {total_packages} total components across {len(results)} SBOMs")
for r in results:
fmt = r.get("format", "unknown")
count = r.get("package_count", r.get("component_count", 0))
status = "VALID" if r.get("valid") else "INVALID"
lines.append(f" [{fmt}] {count} components — {status}")
if errors:
lines.append(f"\nErrors ({len(errors)}):")
for err in errors:
lines.append(f" - {err}")
return "\n".join(lines)
Pattern 2: Dependency Pinning Strategies
Pinning eliminates version ambiguity. Different ecosystems use different mechanisms — understand each and enforce it consistently.
BAD: Unpinned Versions (Vulnerable to Supply Chain Attacks)
// package.json — ❌ BAD: caret ranges allow any minor/patch update
{
"dependencies": {
"express": "^4.18.0",
"lodash": "^4.17.0",
"axios": ">=1.0.0",
"some-package": "*" // ❌ ANY version — most dangerous pattern
}
}
GOOD: Exact Version Pinning with Lockfile (Secure)
// package.json — ✅ GOOD: exact pin for critical packages, lockfile enforces consistency
{
"dependencies": {
"express": "4.18.2", // Exact pin
"lodash": "4.17.21", // Exact pin
"axios": "1.6.0" // Exact pin
}
}
// package-lock.json — ✅ LOCKFILE enforces transitive deps match exactly
{
"name": "my-service",
"version": "1.0.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"node_modules/express": {
"version": "4.18.2", // Exact version — no range
"resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
"integrity": "sha384-m+...base64-encoded-hash" // Cryptographic integrity check
},
"node_modules/express/node_modules/debug": {
"version": "4.3.4", // Transitive dep also exact
"resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz",
"integrity": "sha384-..."
}
}
}
Python: poetry.lock (Exact Pinning with Hash Verification)
# pyproject.toml — ✅ GOOD: explicit pin in dependencies
[tool.poetry]
name = "my-service"
version = "1.0.0"
[tool.poetry.dependencies]
python = "^3.11"
flask = "3.0.0" # Exact version (not ^3.0.0)
requests = "2.31.0" # Exact version
sqlalchemy = "2.0.23" # Exact version
[tool.poetry.group.dev.dependencies]
pytest = "7.4.3"
# poetry.lock — ✅ GENERATED lockfile with cryptographic hashes
[[package]]
name = "flask"
version = "3.0.0"
description = "A simple framework for building complex web applications."
optional = false
python-versions = ">=3.8"
[package.dependencies]
Werkzeug = ">=3.0.0"
Jinja2 = ">=3.1.2"
itsdangerous = ">=2.1.2"
[package.source]
type = "pipfile"
url = "https://pypi.org/simple"
reference = "pypi"
[[package.metadata.hashes]]
platform = null
marker = null
hash = "sha256:abcd1234..." # SHA-256 hash of the published wheel/sdist
Go: go.mod with Require Directives and go.sum
// go.mod — ✅ GOOD: exact version pins + require directives
module github.com/myorg/my-service
go 1.21
require (
github.com/gin-gonic/gin v1.9.1 // Exact pinned version
github.com/lib/pq v1.10.9 // Exact pinned version
go.uber.org/zap v1.26.0 // Exact pinned version
)
// ✅ Use replace directive for vulnerable transitive dependencies
replace github.com/golang/protobuf => github.com/golang/protobuf v1.5.3
// go.sum — ✅ GENERATED checksum database (never edit manually)
github.com/gin-gonic/gin v1.9.1 h1:jDzONb...
github.com/gin-gonic/gin v1.9.1/go.mod h1:uhGL...
github.com/lib/pq v1.10.9 h1:yQoCnH...
github.com/lib/pq v1.10.9/go.mod h1:4J...
Verifying Pinned Versions Match Published Packages
# npm: verify lockfile integrity against registry
npm ci --ignore-scripts # Install from lockfile only, skip postinstall scripts
npm audit --production # Verify no unexpected vulnerabilities appeared
# Python: pip-sync enforces exact environment state
pip install pip-tools
pip-compile requirements.in -o requirements.txt # Generate pin file
pip-sync requirements.txt # Enforce exact versions
# Go: verify go.sum entries match published checksums
GOPROXY=https://proxy.golang.org go mod download
go sum check # Verify no tampering
# Universal: compare package integrity hashes
sha256sum package.tar.gz && echo "Expected: sha256:<hash-from-lockfile>"
Pattern 3: Signature Verification with Sigstore / cosign
Sigstore provides a zero-trust signing infrastructure. Packages and build artifacts can be signed using Fulcio (identity-based certificates) and Rekor (transparency log). Verify signatures at install/build time to prevent tampered packages from being executed.
cosign Verify Commands for Different Ecosystems
# --- Go Module Proxy Verification ---
# Go 1.21+ verifies module proxy signatures automatically
# When a module is signed, the Go toolchain checks against Rekor
go install github.com/some/package@v1.2.3
# If signature is invalid: "verifying build [hash]: cosign verify failed"
# --- Docker Image Signing and Verification (cosign) ---
# Sign a container image
cosign sign --key cosign.key myregistry.io/my-service:v1.2.3
# Verify at pull time in CI
COSIGN_EXPERIMENTAL=true \
cosign verify \
--certificate-identity=ci@myorg.github.com \
--certificate-oidc-issuer=https://token.actions.githubusercontent.com \
--key https://myorg.github.dev/cosign-public-key.pub \
myregistry.io/my-service:v1.2.3 | jq .
# --- NPM Package Provenance Verification ---
# npm supports provenance attestation from GitHub Actions
npm install express@4.18.2
# npm verifies the provenance statement against Sigstore Rekor
# If missing or invalid: "provenance verification failed"
# Verify a specific package's signature
npx @sigstore/cli verify --repository https://registry.npmjs.org/express --version 4.18.2
# --- Python Package Signing Verification ---
# PyPI supports PEP 725 provenance statements (experimental)
pip install requests==2.31.0
# Verify with pip's built-in integrity check (always hashes-based)
pip download requests==2.31.0 --no-deps -d /tmp/pip-check
sha256sum /tmp/pip-check/requests-2.31.0-py3-none-any.whl
# cosign for containerized Python apps
cosign verify \
--certificate-identity=ci@build.myorg.com \
--key cosign.pub \
myregistry.io/python-app:3.11-slim
Python Helper: Signature Verification in Build Scripts
"""
Package Integrity and Signature Verification Module
Provides functions for verifying package integrity using cryptographic hashes,
checking Sigstore/cosign signatures where available, and validating build
provenance against published attestation records.
"""
from __future__ import annotations
import hashlib
import json
import subprocess
from dataclasses import dataclass, field
from enum import Enum
from pathlib import Path
from typing import Any
class VerificationStatus(Enum):
"""Possible outcomes of a package verification check."""
VERIFIED = "verified"
FAILED_HASH = "hash_mismatch"
SIGNATURE_INVALID = "signature_invalid"
NO_SIGNATURE = "no_signature_available"
TOOL_NOT_FOUND = "tool_not_found"
UNKNOWN_ERROR = "unknown_error"
@dataclass
class VerificationResult:
"""Result of verifying a package artifact's integrity and provenance."""
artifact_name: str
expected_version: str
status: VerificationStatus
hash_algorithm: str = "sha256"
expected_hash: str = ""
actual_hash: str = ""
signature_verified: bool = False
certificate_identity: str = ""
transparency_log_entry: dict[str, Any] | None = None
errors: list[str] = field(default_factory=list)
@property
def is_valid(self) -> bool:
"""Return True if the artifact passed all verification checks."""
return self.status == VerificationStatus.VERIFIED and self.signature_verified
def compute_file_hash(file_path: str, algorithm: str = "sha256") -> str:
"""Compute a cryptographic hash of a file for integrity verification.
Args:
file_path: Path to the file to hash.
algorithm: Hash algorithm — sha256 (default), sha384, or sha512.
Returns:
Lowercase hex-encoded digest string.
Raises:
FileNotFoundError: If file does not exist.
ValueError: If unsupported algorithm specified.
"""
supported = {"sha256", "sha384", "sha512"}
if algorithm not in supported:
raise ValueError(f"Unsupported hash algorithm '{algorithm}'. Use one of: {', '.join(sorted(supported))}")
path = Path(file_path)
if not path.is_file():
raise FileNotFoundError(f"Cannot hash non-existent file: {file_path}")
h = hashlib.new(algorithm)
with path.open("rb") as f:
for chunk in iter(lambda: f.read(8192), b""):
h.update(chunk)
return h.hexdigest()
def verify_package_hash(file_path: str, expected_hash: str, algorithm: str = "sha256") -> VerificationResult:
"""Verify a downloaded package file against its published hash.
Args:
file_path: Path to the downloaded package (tarball, wheel, tgz, etc.).
expected_hash: The published hash string to verify against.
algorithm: Hash algorithm used for the comparison.
Returns:
VerificationResult indicating whether the hash matches.
"""
actual = compute_file_hash(file_path, algorithm)
name = Path(file_path).name
if actual == expected_hash.lower():
return VerificationResult(
artifact_name=name,
expected_version="unknown",
status=VerificationStatus.VERIFIED,
hash_algorithm=algorithm,
expected_hash=expected_hash.lower(),
actual_hash=actual,
signature_verified=True
)
return VerificationResult(
artifact_name=name,
expected_version="unknown",
status=VerificationStatus.FAILED_HASH,
hash_algorithm=algorithm,
expected_hash=expected_hash.lower(),
actual_hash=actual,
errors=[f"Hash mismatch: expected {expected_hash}, got {actual}"]
)
def verify_cosign_signature(
image_ref: str,
certificate_identity: str,
oidc_issuer: str,
public_key_path: str | None = None,
) -> VerificationResult:
"""Verify a container image signature using cosign.
Args:
image_ref: Full image reference (registry/image:tag).
certificate_identity: Expected certificate identity claim.
oidc_issuer: OIDC issuer URL for certificate validation.
public_key_path: Optional path to cosign public key for --key verification.
Returns:
VerificationResult with signature verification status.
"""
cmd: list[str] = [
"cosign", "verify",
"--certificate-identity", certificate_identity,
"--certificate-oidc-issuer", oidc_issuer,
image_ref
]
if public_key_path:
cmd.extend(["--key", public_key_path])
try:
result = subprocess.run(
cmd,
capture_output=True,
text=True,
timeout=30
)
if result.returncode == 0:
# Parse verification output for details
payload_lines = [l for l in result.stdout.strip().split("\n") if l]
return VerificationResult(
artifact_name=image_ref,
expected_version="unknown",
status=VerificationStatus.VERIFIED,
signature_verified=True,
certificate_identity=certificate_identity,
transparency_log_entry={"verified": True, "output_lines": payload_lines[:5]}
)
return VerificationResult(
artifact_name=image_ref,
expected_version="unknown",
status=VerificationStatus.SIGNATURE_INVALID,
errors=[result.stderr.strip()]
)
except FileNotFoundError:
return VerificationResult(
artifact_name=image_ref,
expected_version="unknown",
status=VerificationStatus.TOOL_NOT_FOUND,
errors=["cosign binary not found in PATH"]
)
except subprocess.TimeoutExpired:
return VerificationResult(
artifact_name=image_ref,
expected_version="unknown",
status=VerificationStatus.UNKNOWN_ERROR,
errors=["Signature verification timed out after 30s"]
)
def run_comprehensive_verification(package_dir: str) -> list[VerificationResult]:
"""Run all available integrity and signature checks on packages in a directory.
Args:
package_dir: Directory containing downloaded packages to verify.
Returns:
List of VerificationResult objects for each package checked.
"""
results: list[VerificationResult] = []
pkg_path = Path(package_dir)
if not pkg_path.is_dir():
results.append(VerificationResult(
artifact_name=package_dir,
expected_version="unknown",
status=VerificationStatus.UNKNOWN_ERROR,
errors=["Not a valid directory"]
))
return results
# Hash-check all tarballs and wheels
for pattern in ["*.tar.gz", "*.tgz", "*.whl", "*.zip"]:
for pkg_file in pkg_path.glob(pattern):
print(f"Verifying hash: {pkg_file.name}")
result = verify_package_hash(str(pkg_file), "") # Hash would come from lockfile/SBOM
results.append(result)
return results
Pattern 4: CI Scanning Pipeline Patterns
Dependency scanning must run on every commit and PR. A single missing scan is a gap an attacker can exploit. Show both BAD (insufficient) and GOOD (comprehensive) configurations.
BAD: Incomplete / Missing Scanning Configuration
# .github/workflows/dependency-scan-bad.yml — ❌ BAD: Skips critical checks
name: Dependency Scan (Incomplete)
on: [push] # ❌ BAD: Missing pull_request trigger — PRs are never scanned
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- run: npm install # ❌ BAD: npm ci preferred for reproducibility
# ❌ BAD: No fail-on-critical — scan runs but never blocks CI
- run: npm audit --json > audit-results.json
# Missing: any failure threshold, missing: no transitive dep scanning
# ❌ BAD: No SCA tool with CVE database coverage
# Missing: Dependabot, Snyk, or Trivy for comprehensive CVE matching
# ❌ BAD: No SBOM generation — zero inventory of components
GOOD: Comprehensive Scanning Pipeline
# .github/workflows/dependency-scan-good.yml — ✅ GOOD: Full supply chain scanning
name: Dependency Supply Chain Security
on:
pull_request:
branches: [main, master]
push:
branches: [main, master]
schedule:
- cron: '0 6 * * 1' # Daily Monday at 6 AM UTC — continuous monitoring
env:
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
jobs:
sbom-generation:
name: Generate SBOMs
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies (from lockfile)
run: npm ci
- uses: anchore/sbom-action@v0
with:
path: .
format: cyclonedx-json
output-file: sbom-cyclonedx.json
artifact-name: sbom-cyclonedx
- name: Generate SPDX SBOM for Python deps
run: |
pip install syft
syft python:. --output spdx-json=spdx-python.json
echo "## SPDX SBOM" >> $GITHUB_STEP_SUMMARY
echo '```json' >> $GITHUB_STEP_SUMMARY
head -50 spdx-python.json >> $GITHUB_STEP_SUMMARY
echo '```' >> $GITHUB_STEP_SUMMARY
- uses: actions/upload-artifact@v4
with:
name: sbom-artifacts
path: |
sbom-cyclonedx.json
spdx-python.json
retention-days: 90
dependency-scanning:
name: Scan Dependencies for Vulnerabilities
runs-on: ubuntu-latest
needs: [sbom-generation]
strategy:
matrix:
ecosystem: [npm, pip, gomod]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
# --- Snyk: Comprehensive CVE database + transitive deps ---
- name: Run Snyk Security Scan
uses: snyk/actions/node@master
env:
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
with:
command: test --severity-threshold=high --fail-on=all --json=snyk-results.json
# --- Trivy: Filesystem + container scanning with CVE DB ---
- name: Run Trivy Vulnerability Scan
uses: aquasecurity/trivy-action@master
with:
scan-type: 'fs'
scan-ref: '.'
format: 'sarif'
output: 'trivy-results.sarif'
severity: 'CRITICAL,HIGH'
exit-code: '1' # ❌ Will fail the job on CRITICAL/HIGH findings
# --- osv-scanner: Google's open-source vulnerability scanner ---
- name: Run OSV-Scanner
uses: google/osv-scanner-action@v1
with:
scan-args: |
--lockfile=npm-package-lock.json
--recursive
# Upload results for all scanners
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: trivy-results.sarif
signature-verification:
name: Verify Package Signatures
runs-on: ubuntu-latest
needs: [dependency-scanning]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies from lockfile
run: npm ci --ignore-scripts # Skip potentially malicious postinstall
- name: Verify npm package provenance
run: |
npx @sigstore/cli verify \
--repository https://registry.npmjs.org/ \
--package "$(jq -r '.name' package.json)"
continue-on-error: true # Provenance may not be available for all packages
- uses: sigstore/gh-action-sigstore-python@v2
with:
signing-workflow: dependency-verification
slsa-provenance:
name: Generate SLSA Provenance Attestation
runs-on: ubuntu-latest
needs: [signature-verification]
permissions:
actions: read
id-token: write
contents: write
steps:
- uses: actions/checkout@v4
- uses: sigstore/gh-action-sigstore-python@v2
with:
inputs: build-output.tar.gz
- name: Attest to SLSA Level 2
run: |
# Generate in-toto attestation for build provenance
cosign attest \
--predicate attestation-predicate.json \
--type slsaprovenance \
--key env://COSIGN_KEY \
build-output.tar.gz
- uses: actions/upload-artifact@v4
with:
name: slsa-provenance
path: |
attestation.json
sbom-cyclonedx.json
Pattern 5: Transitive Vulnerability Management
Transitive (indirect) dependencies account for the majority of vulnerabilities in modern projects. You cannot ignore them — you must actively manage them.
Finding and Fixing Transitive Dependencies
# --- Node.js: Find vulnerable transitive dependencies ---
# Show full dependency tree including transitive deps
npm ls lodash
# my-service@1.0.0
# └── express@4.18.2
# └── qs@6.11.0 ← transitive, potentially vulnerable
# Audit ALL vulnerabilities including nested
npm audit --all
# Output:
# found 3 vulnerabilities (2 moderate, 1 high) in 542 packages
# 1 high: prototype pollution in qs < 6.12.0 (transitive via express)
# fix available: npm audit fix --force
# Override a specific transitive dependency version
npm force-rebuild qs@6.12.0 # npm v9+
# Or use overrides in package.json (see Pattern below)
# --- Python: Find and audit transitive vulnerabilities ---
# Generate full requirement tree with transitive deps
pip-tree install pipdeptree
pipdeptree -p flask --reverse
# flask==3.0.0
# ├── Werkzeug==3.0.1
# │ └── [self]
# ├── Jinja2==3.1.2
# │ └── MarkupSafe==2.1.3 ← transitive sub-dependency
# └── blinker==1.7.0
# Audit with pip-audit (scans transitive deps)
pip-audit --desc # Include transitive dependencies in scan
# Name Version ID Severity
# ---------- ------- -------------- --------
# werkzeug 3.0.1 GHSA-cph5-m8j7-rh96 High
# Fixed by: werkzeug>=3.0.2
# --- Go: Find vulnerable indirect dependencies ---
govulncheck ./...
# Finding: GO-2024-3210 (HIGH) in golang.org/x/text v0.3.8
# introduced by:
# my-service → github.com/gin-gonic/gin@v1.9.1 → golang.org/x/text@v0.3.8
# Fixed by: golang.org/x/text@v0.14.0
Override Mechanisms for Vulnerable Transitive Dependencies
// package.json — ✅ OVERRIDE: Force a specific transitive dependency version
{
"name": "my-service",
"version": "1.0.0",
"dependencies": {
"express": "4.18.2"
},
// ✅ npm v12+ overrides — forces ALL instances of qs to v6.12.0
"overrides": {
"qs": "6.12.0",
"cookie": "0.6.0"
}
}
# pyproject.toml — ✅ POETRY: Override transitive dependency version
[tool.poetry]
name = "my-service"
[tool.poetry.dependencies]
python = "^3.11"
flask = "3.0.0"
[tool.poetry.group.dev.dependencies]
pip-audit = "2.7.3"
# ✅ Poetry 1.4+ overrides section
[tool.poetry.dependencies.werkzeug]
version = ">=3.0.2"
optional = false
// go.mod — ✅ REPLACE: Redirect vulnerable transitive dependency
module github.com/myorg/my-service
go 1.21
require (
github.com/gin-gonic/gin v1.9.1
)
// ✅ Force all modules to use a safe version of the vulnerable package
replace golang.org/x/text => golang.org/x/text v0.14.0
// ✅ Or remove/reverse-dependency pin
// If no direct user needs the old version:
exclude golang.org/x/text v0.3.8
Patch Files for Dependencies That Cannot Be Upgraded
# patches/express+4.18.2.patch — Apply when express@4.18.2 has an unfixable CVE
# Use `yarn patch express@4.18.2` or `npm-patch` to generate this file
--- a/lib/request.js (revision abc123)
+++ b/lib/request.js (working copy)
@@ -45,7 +45,9 @@
- return req.header(name);
+ const raw = req.header(name);
+ // Mitigate CVE: sanitize header values to prevent injection
+ return raw ? String(raw).replace(/[<>"'&]/g, '') : '';
Pattern 6: Reproducible Builds
Reproducible (deterministic) builds produce identical artifacts when building the same source code. This eliminates a class of supply chain attacks where an attacker modifies build infrastructure to insert backdoors that only appear in published binaries but not in source code analysis.
Key Principles
| Principle | Implementation |
|---|---|
| Deterministic timestamps | Use fixed SOURCE_DATE_EPOCH instead of build-time clock |
| Sorted file order | Archive members must be sorted alphabetically by path |
| Fixed permissions | Umask set to 0o22; no owner/group metadata in archives |
| Pinned toolchains | All build tools (compilers, bundlers) at exact versions |
| No network access | Build must not download anything at compile time |
Implementation Examples
#!/bin/bash
# Reproducible Node.js build with deterministic output
set -euo pipefail
# Fixed timestamp for reproducible builds (Jan 1, 2025 00:00:00 UTC)
export SOURCE_DATE_EPOCH=1735689600
# Deterministic npm install (no postinstall scripts that add randomness)
npm ci --ignore-scripts --prefer-offline # Fail if lockfile is out of sync
# Build with fixed locale and timezone
export LC_ALL=C TZ=UTC
node build/index.js > dist/bundle.js
# Create reproducible tarball
tar --sort=name \
--mtime="@${SOURCE_DATE_EPOCH}" \
--owner=0 --group=0 --numeric-owner \
-czf "release/my-service-v$(git describe --tags).tar.gz" \
dist/ package.json package-lock.json
# Record artifact hash for verification
sha256sum "release/my-service-v$(git describe --tags).tar.gz" > release/SHA256SUMS
# Dockerfile — Reproducible multi-stage build pattern
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --ignore-scripts # Deterministic install from lockfile
COPY . .
ENV SOURCE_DATE_EPOCH=1735689600
ARG BUILD_VERSION="local-dev"
RUN npm run build -- --version="$BUILD_VERSION"
# Second stage: clean image with only built output
FROM alpine:3.19 AS runtime
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./package.json
# No node_modules in final image if build is self-contained
RUN addgroup -S app && adduser -S app -G app
USER app
CMD ["node", "dist/index.js"]
Verifying Reproducibility
#!/bin/bash
# Verify that rebuilding from source produces the same artifact
ARTIFACT="release/my-service-v1.0.0.tar.gz"
ORIGINAL_HASH=$(sha256sum "$ARTIFACT" | awk '{print $1}')
# Clean and rebuild
git clean -fdx
make build # Or: npm ci && npm run build
REBUILD_HASH=$(find dist/ -type f | sort | xargs sha256sum | sha256sum | awk '{print $1}')
if [ "$ORIGINAL_HASH" = "$REBUILD_HASH" ]; then
echo "✅ Build is reproducible — hashes match: $ORIGINAL_HASH"
else
echo "❌ Build is NOT reproducible"
echo " Original: $ORIGINAL_HASH"
echo " Rebuild: $REBUILD_HASH"
exit 1
fi
Lessons from Real-World Supply Chain Attacks
Log4Shell (CVE-2021-44228) — December 2021
What happened: A critical RCE vulnerability in Apache Log4j (a widely-used Java logging library) allowed remote code execution via crafted log messages containing ${jndi:ldap://...} expressions. Affected millions of systems globally.
What safeguards would have prevented/mitigated it:
- SBOM generation: If every organization had generated an SBOM, identifying Log4j in their dependency tree would have been instant rather than requiring a frantic search
- Transitive vulnerability scanning: Automated scanning with fail-on-critical policy would have caught this immediately — Log4j was
…(truncated)