Supply Chain Security

---
name: supply-chain-security
description: "Supply chain security capability pack. Covers dependency audit, behavioral analysis, provenance verification, lockfile integrity, and typosquat detection. Use for any dependency trust review, pre-install package vetting, SBOM audit, dependency-update PR review, or supply chain security task."
version: 0.1.0
type: reference-based
keywords: ["supply chain security", "供应链安全", "dependency audit", "依赖审计", "SBOM", "软件物料清单", "behavioral analysis", "行为分析", "provenance", "来源验证", "lockfile", "锁文件", "typosquatting", "名称仿冒", "vulnerability scan", "漏洞扫描", "CVE", "package poisoning", "包投毒", "sigstore", "SLSA", "npm audit", "pip-audit"]
---

# Supply Chain Security Capability Pack

> Pre-install trust analysis. Core question: **"Should I trust this dependency?"**
> **PRODUCES**: Structured audit reports + remediation plans, NOT code. Artifacts go under `.tad/active/research/{project}/` (SBOM, audit/behavioral/provenance/lockfile/typosquat reports, raw scanner JSON).
> **SCOPE**: Pre-install analysis ONLY. Post-install CVE monitoring belongs to the security-monitoring pack.
> **ECOSYSTEMS**: npm, pip, cargo, go (detection also covers maven/gradle, ruby, PHP). Known limitation: lockfile integrity is full for npm/yarn, partial for pip/go (no hash verification equivalent).
> **REFERENCE INCIDENT**: litellm 1.82.7/1.82.8 PyPI poisoning (2026-03-24) — CVE-only scanners missed it entirely. Every audit must ask: "would this have caught it?"

---

## Severity Policy — MANDATORY Pipeline Gating

These rules are non-negotiable for any security-pack task:

- **CRITICAL and HIGH findings BLOCK the pipeline.** Never demote a CRITICAL/HIGH to a warning.
- **MEDIUM and LOW findings warn only** — they must not block.
- **accept_risk requires documented justification** in the triage report **with owner sign-off**. No silent risk acceptance.
- **Grace period**: existing findings get a 2-sprint remediation window.
- **litellm rule — NO grace period**: for behavioral analysis findings (socket CLI alerts), there is NO grace period. Behavioral anomalies in new/updated dependencies **block merge immediately**.

---

## Step 1: Context Detection

Non-circular triggers — each is an event you can recognize BEFORE reading any reference:

| User Signal / Event | Load Reference |
|---|---|
| "audit dependencies", CVE/vulnerability scan, SBOM request, "is this project's dependency tree safe", new project onboarding | `references/dependency-audit.md` |
| A lockfile diff shows new/updated packages, a Dependabot/Renovate PR is open, "is this package/version safe to install", post-incident package vetting | `references/behavioral-analysis.md` |
| Deploying a container image, "verify publisher/signature", SLSA/sigstore/cosign mentioned, GitHub Actions workflow review, maintainer-change worry | `references/provenance-verification.md` |
| Lockfile missing/modified/gitignored, hash validation, "reproducible installs", registry source policy, CI install gating | `references/lockfile-integrity.md` |
| Adding a package by typed name, "did I spell this package right", suspicious look-alike package name, pre-install name check | `references/typosquat-detection.md` |
| Final audit review, Gate 2 design review or Gate 4 acceptance of supply-chain work, "review this audit report" | `references/review-checklist.md` |

**Multi-signal**: load all matched references. A full audit loads all five capability references.

---

## Step 2: Decision Entry Point

**Q1 — What triggered this task?**
- Full project trust audit → start with `dependency-audit.md`. Generate the SBOM FIRST — it is the foundation artifact consumed by typosquat detection and downstream monitoring. Then run all other capabilities.
- Dependency change (lockfile diff, dep-update PR) → `behavioral-analysis.md` + `typosquat-detection.md`. Priority order: new packages > version updates > transitive updates.
- Container image deploy / release signing → `provenance-verification.md`.
- CI policy setup or install reproducibility → `lockfile-integrity.md` + Severity Policy above.

**Q2 — Which ecosystems?** Detect from package manager files: `package.json`/lockfiles → npm; `requirements.txt`/`pyproject.toml`/`uv.lock`/`poetry.lock` → pip; `Cargo.toml` → cargo; `go.mod` → go; `pom.xml`/`build.gradle` → maven/gradle; `Gemfile` → ruby; `composer.json` → PHP. Multiple ecosystems may coexist (JS frontend + Python backend) — scan ALL of them; a missed ecosystem is a failed audit.

**Q3 — Delivering or reviewing an audit?** Before delivering an audit report, or when running Gate 2/Gate 4 on supply-chain work → read `references/review-checklist.md` (Supply Chain Security Engineer persona, 10-item cross-cutting checklist, gate checklists, expected output tree).

---

## Quick Rule Index

### Dependency Audit (`references/dependency-audit.md`)
- **SBOM first**: syft-generated CycloneDX (spec >= 1.5) including direct AND transitive deps — the foundation artifact for every other capability.
- **Run ALL applicable scanners** (osv-scanner multi-ecosystem first pass; npm audit / pip-audit / cargo audit per ecosystem; depscan deep mode) — cross-referencing finds blind spots. CRITICAL findings must be cross-referenced by at least 2 scanners.
- **Every CRITICAL/HIGH** needs: fix version check, breaking-change risk, EPSS score, KEV catalog check (KEV = highest priority), and a remediation path or documented accept-risk.
- Separate direct vs transitive findings; flag unmaintained deps (no release in 12+ months). JSON output for CI consumption.

### Behavioral Analysis (`references/behavioral-analysis.md`)
- **HIGH RISK — block immediately**: new network calls to unknown domains; filesystem writes outside package dir; new eval/exec/system usage; install script added where none existed; obfuscated code.
- **MEDIUM — review required**: new optional deps; maintainer change between versions; >50% code size increase.
- **LOW — informational**: minor bump with no behavioral change; dev dependency update.
- No block without evidence; every package gets an explicit allow/block/review decision.
- Every report MUST answer: "Would this scan have caught the litellm 1.82.7 behavioral change?"

### Provenance Verification (`references/provenance-verification.md`)
- Verify container images with cosign (certificate identity + OIDC issuer); npm provenance via npm audit signatures.
- **GitHub Actions MUST be pinned to full commit SHA**, never mutable tags (trivy-action March 2026: 75/76 tags hijacked).
- Document SLSA level (1: provenance exists, 2: signed, 3: hardened build) per critical dependency.
- Publisher red flags: publisher changed between versions; single maintainer (bus factor = 1); email domain change; recent ownership transfer.
- OSSF Scorecard: flag overall score < 5, Branch-Protection = 0, Code-Review = 0, or any zero check on a critical dep. Provenance grade = signature status + SLSA level + Scorecard score.

### Lockfile Integrity (`references/lockfile-integrity.md`)
- **FAIL pipeline**: missing lockfile for a manifest; npm/yarn entries without integrity hashes; any non-HTTPS source; lockfile modified without a corresponding manifest change.
- **WARN**: pip requirements.txt without hash pins; go.sum entries not in go.mod.
- lockfile-lint validates npm/yarn (sha512, HTTPS-only, allowed hosts); cargo generate-lockfile --check catches stale/hand-edited Cargo.lock.
- pip has no default hashes — recommend pip-compile --generate-hashes or uv lock.
- Lockfiles must NOT be gitignored for applications (libraries may exclude, apps should not).

### Typosquat Detection (`references/typosquat-detection.md`)
- Apply **at least 4 variant techniques** per dependency: character swap, omission, addition, homoglyph (plus hyphen/underscore and scope confusion).
- Suspicion score: registered variant + low downloads + recent creation + publisher mismatch.
- Scan the FULL SBOM — typosquats hide in transitive deps, not just direct ones.
- Maintain an allowlist of verified-safe names — otherwise repeated runs create alert fatigue.

### Review & Gates (`references/review-checklist.md`)
- One cross-cutting Supply Chain Security Engineer persona reviews all capabilities in a single audit pass.
- Gate 2 design checklist (scope, behavioral coverage, SBOM planned, severity policy, accept-risk process) and Gate 4 acceptance checklist (remediation plans, signatures, lockfile validation, machine-readable report).

---

## Anti-Patterns

### Dependency Audit
- ❌ CVE-only scanning without behavioral analysis — misses litellm-class zero-day attacks
- ❌ Scanning only direct dependencies while ignoring transitive (the axios attack came through a transitive dep)
- ❌ Auto-fixing without checking breaking changes — cargo audit fix / npm audit fix may introduce regressions

### Behavioral Analysis
- ❌ Treating all socket CLI warnings as false positives — behavioral anomalies require investigation
- ❌ Only scanning direct dependencies when transitive deps change
- ❌ Auto-merging dependency PRs without behavioral review (Dependabot/Renovate + socket CLI needed)

### Provenance Verification
- ❌ Trust-by-popularity — GitHub stars are gameable (axios had 100M+ weekly downloads and was still compromised)
- ❌ Assuming cosign coverage is universal — most PyPI packages have NOT opted into sigstore
- ❌ Checking provenance once without continuous monitoring — maintainer changes happen anytime

### Lockfile Integrity
- ❌ Having a lockfile without verifying hashes — provides reproducibility but NOT integrity
- ❌ Adding lockfiles to .gitignore for applications (libraries may exclude, apps should not)
- ❌ Assuming pip requirements.txt provides lockfile-level integrity (it doesn't without --hash flags)

### Typosquat Detection
- ❌ Only checking direct dependencies — typosquats hide in transitive deps
- ❌ Ignoring homoglyph attacks (Cyrillic е looks identical to Latin e)
- ❌ Running detection once without maintaining allowlist — creates alert fatigue

---

## Anti-Skip Table

| Shortcut Attempt | Required Action |
|---|---|
| "The CVE scan is clean, we're done" | MUST also run behavioral analysis (`behavioral-analysis.md`) — CVE-only scanning missed the litellm 1.82.7 poisoning entirely |
| "It's just a minor version bump in the lockfile" | MUST diff the lockfile and behavioral-scan every new/updated package — behavioral anomalies block merge with NO grace period |
| "This package is popular, it's safe" | MUST run provenance checks (`provenance-verification.md`) — popularity is gameable; axios was compromised at 100M+ weekly downloads |
| "The lockfile exists, installs are safe" | MUST validate hashes and HTTPS-only sources (`lockfile-integrity.md`) — a lockfile without hash verification gives reproducibility, not integrity |
| "I'll downgrade this HIGH to a warning to unblock CI" | MUST NOT — CRITICAL/HIGH block the pipeline; the only exit is documented accept-risk with owner sign-off |
| "Direct deps are checked, transitive ones are fine" | MUST cross-reference the full SBOM — typosquats and vulnerable packages hide in transitive deps |
| "The audit report looks complete" | MUST run the 10-item checklist in `review-checklist.md`, including "would this have detected litellm 1.82.7?" |