Supply Chain Audit

Supply Chain Audit Skill

Auditing software supply chain security across CI/CD pipelines, container images, and language package ecosystems. Produces structured findings with severity ratings, file:line references, and actionable fix templates.

When to Use This Skill

• CI/CD security review: Unpin action refs, excessive permissions, secret leakage
• Dependency pinning: Lock files missing, hash verification absent, mutable semver refs
• Container supply chain: Mutable base image tags, non-root execution, SBOM generation
• Credential hygiene: OIDC migration from long-lived secrets, subject constraint gaps
• Compliance mapping: SLSA L1-L4 readiness assessment, SBOM generation guidance
• Pre-merge gate: Block PRs that introduce High/Critical supply chain regressions

---

Prerequisites — External Tool Check

Before running the audit, check for missing external tools and offer to install them:

from supply_chain_audit.external_tools import check_missing_tools, install_tool

missing = check_missing_tools()
if missing:
    # Show the user what's missing and what each tool does
    for tool in missing:
        print(f"Missing: {tool['name']} — {tool['description']}")
        for opt in tool['install_options']:
            print(f"  Install: {opt}")

    # Ask the user if they want to install
    # If yes, install each one:
    for tool in missing:
        success, msg = install_tool(tool['name'])
        print(f"  {tool['name']}: {msg}")

The audit runs without these tools (offline/degraded mode) but produces fewer findings:

---

Ecosystem Detection

Detect which dimensions apply before running checks:

Run all triggered dimensions. Report skipped dimensions explicitly.

---

12 Audit Dimensions

Dimensions 1-4: GitHub Actions

See reference/actions.md

Dimensions 5 & 12: Containers

See reference/containers.md

Dimension 6: Credentials

See reference/credentials.md

Dimension 7: .NET / NuGet

See reference/dotnet.md

Dimension 8: Python

See reference/python.md

Dimension 9: Rust

See reference/rust.md

Dimension 10: Node.js

See reference/node.md

Dimension 11: Go

See reference/go.md

---

5-Step Audit Workflow

Step 1: Scope Detection

# Detect active ecosystems
ls .github/workflows/*.yml 2>/dev/null && echo "GHA detected"
ls Dockerfile docker-compose.yml 2>/dev/null && echo "Containers detected"
ls requirements*.txt pyproject.toml 2>/dev/null && echo "Python detected"
ls package.json 2>/dev/null && echo "Node detected"
ls go.mod 2>/dev/null && echo "Go detected"
ls Cargo.toml 2>/dev/null && echo "Rust detected"
ls *.csproj 2>/dev/null && echo ".NET detected"

Record active dimensions. Skip and annotate inactive ones in the report.

Step 2: Static Analysis (per ecosystem)

Run dimension-specific checks from each reference file. Collect raw findings with:

• Dimension number
• File path and line number (file:line)
• Current value (the offending pattern)
• Expected value (the fix)
• Severity: Critical / High / Medium / Info

Step 3: Severity Scoring

Map findings to CVSS-aligned severity bands:

Step 4: Report Generation

Produce a structured markdown report:

## Supply Chain Audit Report

**Date**: YYYY-MM-DD
**Scope**: [list active ecosystems]
**Skipped**: [list inactive ecosystems with reason]

### Summary

| Severity | Count |
| -------- | ----- |
| Critical | N     |
| High     | N     |
| Medium   | N     |
| Info     | N     |

### Findings

#### CRITICAL-001 · Dim 1 · Unpin third-party action

- **File**: `.github/workflows/release.yml:14`
- **Current**: `uses: actions/checkout@v4`
- **Expected**: `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2`
- **Fix**: Look up SHA at https://github.com/actions/checkout/releases

### SLSA Readiness

[See reference/sbom-slsa.md for compliance table]

### Recommended Next Steps

1. Fix all Critical findings before next deployment
2. Delegate lock-file issues to `dependency-resolver` skill
3. Install SHA-pinning pre-commit hooks via `pre-commit-manager` skill

Step 5: Remediation Prioritization

Order fixes:

1. Critical first: Unpin + write-permissions + secret-access combinations 2. High: Any mutable reference in production workflows 3. Delegate: Lock file generation to dependency-resolver 4. Automate: Pre-commit enforcement via pre-commit-manager 5. Compliance: SBOM generation, SLSA provenance — see reference/sbom-slsa.md

---

Output Format Conventions

• Every finding includes file:line (e.g., .github/workflows/ci.yml:23)
• Fix templates are copy-pasteable with no placeholders requiring guessing
• SHA lookups always reference the official release page URL
• Severity is explicit per finding; never implicit
• Report ends with a "next steps" section distinguishing manual vs. automatable fixes

---

Integration Points

---

Evaluation Scenarios

See reference/eval-scenarios.md for three graded scenarios:

• Scenario A: GitHub Actions monorepo — GHA + Python + Node (7 planted findings)
• Scenario B: Containerized Go service — Containers + Go + Credentials (5 findings)
• Scenario C: .NET + Rust mixed repo — .NET + Rust + SLSA readiness (6 findings)

---

Additional Reference

• SBOM generation, CVSS scoring, SLSA L1-L4 mapping, fix-PR workflow
• Invocation interface, finding schema, inter-skill contracts, error handling
• GitHub Actions SHA lookup: gh api repos/{owner}/{repo}/git/ref/tags/{tag}
• SLSA framework: https://slsa.dev
• OpenSSF Scorecard: https://securityscorecards.dev

---

Related Skills

• dependency-resolver — lock file conflict resolution
• pre-commit-manager — automated quality enforcement hooks
• cybersecurity-analyst — runtime security and threat modeling
• silent-degradation-audit — CI reliability and regression detection
• pr-review-assistant — philosophy-aware PR review including supply chain checks

Supply Chain Audit

Audits software supply chain security across 12 dimensions: GitHub Actions SHA pinning, workflow permissions, secrets scanning, cache poisoning, container image digests, OIDC credentials, and ecosystem lock files.

Quick Start

"supply chain audit"
→ Full audit at repo root, all detected ecosystems

"check action pinning"
→ GitHub Actions dimensions only (1-4)

"audit dependencies in ./services/api"
→ Scoped to a subdirectory

"CI security audit --scope gha,containers"
→ Dimensions 1-5, 12 only

What It Audits

Output

Produces a structured markdown report with:

• Severity summary (Critical / High / Medium / Info)
• Findings with file:line references and ready-to-use fix templates
• SLSA readiness assessment
• Handoffs to dependency-resolver and pre-commit-manager

Example finding:

CRITICAL-001 · Dim 1 · Unpinned third-party action File: .github/workflows/release.yml:14 Current: uses: actions/checkout@v4 Expected: uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 Fix: https://github.com/actions/checkout/releases Why: Mutable semver tag allows silent code replacement without any file change in your repo — a direct supply-chain compromise vector.

Configuration

Accepted Risks

Create .supply-chain-accepted-risks.yml to suppress findings that are intentionally accepted:

• id: HIGH-002

file: .github/workflows/ci.yml line: 47 dimension: 1 rationale: "Pinning blocked by upstream; tracked in GH-4521" review_date: "2026-06-01"

Constraints: 64KB file cap; no wildcards; Critical findings cannot be suppressed; past review_date restores original severity.

Integration Points

Documentation

Dimensions 1-4: GitHub Actions Supply Chain

Dimension 1: Action SHA Pinning

Every uses: step in .github/workflows/*.yml must reference a full 40-character commit SHA.

Pattern to Detect (High/Critical)

# VIOLATION — mutable semver tag
uses: actions/checkout@v4

# VIOLATION — mutable branch
uses: my-org/my-action@main

# CORRECT — immutable SHA with version comment
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

Severity Rules

SHA Lookup

# Look up SHA for a specific tag
gh api repos/actions/checkout/git/ref/tags/v4.2.2 --jq '.object.sha'

# If tag points to a tag object (not commit), dereference it
gh api repos/actions/checkout/git/tags/<tag-object-sha> --jq '.object.sha'

Fix Template

# Replace:
uses: actions/checkout@v4
# With:
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

Common Actions SHA Reference (verify at time of audit — these change with releases)

---

Dimension 2: Workflow Permissions

Overly broad permissions expose the GITHUB_TOKEN to compromise.

Pattern to Detect

# VIOLATION — implicit all permissions (default behavior pre-2023)
# No permissions key at all in workflow

# VIOLATION — explicit write-all
permissions: write-all

# CORRECT — read-all at top, minimal write at job level
permissions: read-all

jobs:
  build:
    permissions:
      contents: read
      packages: write  # only what this job needs

Checks

1. Top-level permissions: key exists and is not write-all 2. Each job that writes (contents: write, packages: write, id-token: write, etc.) has a comment explaining why 3. pull_request_target trigger without explicit permissions restriction — flag Critical (privilege escalation risk)

Severity

---

Dimension 3: Secret Exposure

Pattern to Detect

# VIOLATION — secret echoed to log
- run: echo "${{ secrets.MY_SECRET }}"

# VIOLATION — secret exported to env then used in shell
- run: export TOKEN=$TOKEN && curl -H "Auth: $TOKEN" ...
  env:
    TOKEN: ${{ secrets.API_TOKEN }}
# (not a violation by itself but flag for review if token is printed anywhere)

# VIOLATION — ACTIONS_STEP_DEBUG unguarded
- run: |
    echo "Debug: ${{ secrets.AWS_KEY }}"
  if: ${{ runner.debug == '1' }}

Checks

1. Grep for echo.*secrets\. — flag Critical 2. Grep for print.*secrets\. — flag Critical 3. Check ACTIONS_RUNNER_DEBUG / ACTIONS_STEP_DEBUG handling 4. Check for secrets in actions/cache keys — flag High (cache key logged) 5. Check that ${{ github.event.pull_request.head.sha }} is not used to check out untrusted code in pull_request_target

Severity

---

Dimension 4: Cache Poisoning

Pattern to Detect

# RISK — broad restore-keys may restore cache from untrusted branch
- uses: actions/cache@<sha> # verify this is pinned
  with:
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-    # broad fallback — may restore attacker-poisoned cache

Checks

1. restore-keys: breadth — single broad fallback matches too many keys 2. Cache key includes content hash (hashFiles(...)) — required 3. actions/cache action itself is SHA-pinned (Dimension 1 catch) 4. Workflow uses cache: 'npm' shorthand in setup-node — verify the version is pinned

Severity

---

Verification Checklist (GitHub Actions)

• [ ] Every uses: step has a full 40-char SHA
• [ ] SHA comment matches the version tag
• [ ] Top-level permissions: read-all present
• [ ] No pull_request_target without explicit permissions restriction
• [ ] No echo "${{ secrets.* }}" patterns
• [ ] Cache keys include hashFiles
• [ ] No broad single-token restore-keys

Dimensions 5 & 12: Container Supply Chain

Dimension 5: Base Image Pinning

Container base images must be pinned by digest, not by tag.

Pattern to Detect

# VIOLATION — mutable tag
FROM python:3.12-slim

# VIOLATION — latest (most dangerous)
FROM ubuntu:latest

# CORRECT — digest-pinned with tag comment
FROM python:3.12-slim@sha256:a4c3b5d9e1f2a8c7b6d4e3f1a0b2c5d8e9f3a1b4c7d6e5f8a2b1c0d3e4f7a9b8  # 3.12.3-slim

Digest Lookup

# Get current digest for an image
docker manifest inspect python:3.12-slim --verbose | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(d[0]['Descriptor']['digest'])"

# Or via crane (preferred, no Docker daemon required)
crane digest python:3.12-slim

# Or via skopeo
skopeo inspect --format '{{.Digest}}' docker://python:3.12-slim

Severity

Multi-Stage Builds

For multi-stage builds, pin ALL stages including intermediate build stages:

# Build stage — pin it too (supply chain risk in build tools)
FROM golang:1.22-alpine@sha256:<digest>  # 1.22.3-alpine3.19 AS builder

# Final stage — use minimal base
FROM gcr.io/distroless/static@sha256:<digest>  # latest-nonroot

---

Dimension 12: Docker Build Chain Security

Detection Commands

# Dim 12 — detect final stage running as root (no USER instruction before CMD/ENTRYPOINT)
grep -n "^USER\|^CMD\|^ENTRYPOINT\|^FROM" Dockerfile 2>/dev/null

# Dim 12 — count USER instructions; 0 means root execution
grep -c "^USER" Dockerfile 2>/dev/null || echo "0 — no USER instruction found"

# Dim 12 — detect RUN curl|bash pattern (any stage)
grep -n "curl.*|.*bash\|wget.*|.*sh\|curl.*sh" Dockerfile 2>/dev/null

# Dim 12 — detect ADD (allows remote URL expansion, use COPY instead)
grep -n "^ADD " Dockerfile 2>/dev/null

Non-Root USER

Every production image must drop to a non-root user before the final CMD/ENTRYPOINT.

# VIOLATION — runs as root
CMD ["./app"]

# CORRECT
RUN addgroup --system appgroup && adduser --system --ingroup appgroup appuser
USER appuser
CMD ["./app"]

# CORRECT — distroless nonroot variant handles this automatically
FROM gcr.io/distroless/static-debian12:nonroot@sha256:<digest>

Minimal Final Stage

# VIOLATION — shipping build tools to production
FROM golang:1.22@sha256:<digest> AS final
COPY . .
RUN go build -o /app .
CMD ["/app"]

# CORRECT — multi-stage, scratch or distroless final
FROM golang:1.22@sha256:<digest> AS builder
RUN go build -o /app ./cmd/server

FROM gcr.io/distroless/static@sha256:<digest> AS final
COPY --from=builder /app /app
ENTRYPOINT ["/app"]

COPY --chown Pattern

When copying files as non-root, use --chown to avoid root-owned files:

COPY --chown=appuser:appgroup --from=builder /app /app

Checks

| Check | Severity | | ---------------------------------------------------------------- | -------------------------- | -------- | | Final stage runs as root (no USER instruction) | High | | Final stage is not scratch/distroless/alpine-based | Medium | | COPY without --chown for non-root user | Medium | | RUN curl ... | bash pattern in any stage | Critical | | Package install without version pinning in RUN apt-get install | Medium | | ADD used instead of COPY (allows remote URL expansion) | High |

APT/APK Version Pinning

# VIOLATION — no version pins
RUN apt-get install -y curl git

# CORRECT — with version pins
RUN apt-get install -y \
    curl=7.88.1-10+deb12u5 \
    git=1:2.39.2-1.1

# ALTERNATIVE — use digest-pinned base that already has these tools

---

SBOM for Container Images

Generate a Software Bill of Materials for audit and compliance:

# syft — generates SBOM from image
syft python:3.12-slim@sha256:<digest> -o spdx-json > sbom.spdx.json

# grype — scan SBOM for vulnerabilities
grype sbom:./sbom.spdx.json

# trivy — combined scan (vulnerabilities + misconfig)
trivy image python:3.12-slim@sha256:<digest>

Add to CI workflow (Dimension 1 applies — pin these actions too):

- name: Generate SBOM
  uses: anchore/sbom-action@<sha> # pin to full SHA
  with:
    image: ${{ env.IMAGE_REF }}
    format: spdx-json
    output-file: sbom.spdx.json

- name: Scan for vulnerabilities
  uses: anchore/scan-action@<sha> # pin to full SHA
  with:
    sbom: sbom.spdx.json
    fail-build: true
    severity-cutoff: high

---

Verification Checklist (Containers)

• [ ] All FROM instructions use digest pinning (@sha256:...)
• [ ] Digest has version comment (# 3.12.3-slim)
• [ ] Final stage is scratch, distroless, or minimal alpine
• [ ] USER instruction drops to non-root before CMD/ENTRYPOINT
• [ ] No RUN curl ... | bash or RUN wget ... | sh patterns
• [ ] Multi-stage: all intermediate stages also digest-pinned
• [ ] SBOM generation step in CI workflow

Supply Chain Audit — Interface Contracts

Formal contracts for the supply-chain-audit skill: invocation interface, finding schema, inter-skill handoffs, error handling, and versioning strategy.

---

Table of Contents

1. Invocation Interface 2. Finding Schema 3. Report Schema 4. Inter-Skill Handoff Contracts 5. Error Handling Patterns 6. Versioning Strategy

---

Invocation Interface

The skill activates via trigger phrases (see auto_activates in SKILL.md frontmatter) or explicit invocation with optional scope qualifiers.

Trigger Grammar

<trigger-phrase> [in <path>] [--scope <dimension-set>] [--min-severity <level>]

Invocation Examples

"audit dependencies"
→ Full audit at repo root, all detected ecosystems, all severities

"supply chain audit in ./services/api"
→ Scopes audit to ./services/api directory only

"check action pinning --min-severity High"
→ Dims 1-4 only; suppresses Medium and Info findings

"CI security audit --scope gha,containers"
→ Dimensions 1-5, 12 only

Scope Mapping

---

Finding Schema

Every finding conforms to this structure. Findings are the atomic output unit.

Finding Object

id: "CRITICAL-001" # Severity prefix + 3-digit sequence (unique per report)
dimension: 1 # Integer 1-12
severity: Critical # Critical | High | Medium | Info
file: ".github/workflows/release.yml" # Relative POSIX path from audit root
line: 14 # 1-indexed; 0 if file-level (no specific line)
current_value: "uses: actions/checkout@v4"
expected_value: "uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2"
fix_url: "https://github.com/actions/checkout/releases"
rationale: "Mutable semver tag allows silent code replacement without any
  file change in your repo — a direct supply-chain compromise vector."
tool_required: null # null = static analysis only; tool name if network needed
offline_detectable: true # true = regex pattern; false = requires live lookup

Field Constraints

Severity Assignment Protocol

1. CVE present: use published CVSS v3.1 base score. 2. No CVE: compute composite score via heuristic table in sbom-slsa.md. 3. Tie-break: when composite score lands exactly on a band boundary, assign the higher severity if the affected workflow has push or pull_request triggers.

---

Report Schema

The complete audit report is structured markdown, produced verbatim at Step 4.

Report Structure

## Supply Chain Audit Report

**Date**: YYYY-MM-DD
**Root**: <path audited>
**Scope**: [active ecosystems]
**Skipped**: [inactive ecosystems — reason for each]
**Tool availability**: [tools present; tools absent and which checks are degraded]

---

### Summary

| Severity  | Count |
| --------- | ----- |
| Critical  | N     |
| High      | N     |
| Medium    | N     |
| Info      | N     |
| **Total** | **N** |

---

### Findings

#### {id} · Dim {N} · {short description}

- **Severity**: {Critical|High|Medium|Info}
- **File**: `{file}:{line}`
- **Current**: `{current_value}`
- **Expected**: `{expected_value}`
- **Fix**: {fix_url or inline instruction}
- **Why**: {rationale — one sentence}

[ordered: Critical → High → Medium → Info]

---

### SLSA Readiness

[SLSA assessment table from sbom-slsa.md template]

---

### Recommended Next Steps

1. [Critical — manual fix required before merge]
2. [High — fix before next release]
3. [Delegate to dependency-resolver: {ecosystems with lock file issues}]
4. [Install pre-commit hooks via pre-commit-manager: {hook list}]
5. [Optional SBOM generation: {commands}]

---

### Accepted Risks

[Findings matched to .supply-chain-accepted-risks.yml — with review dates]

Empty Report (No Findings)

## Supply Chain Audit Report

**Date**: YYYY-MM-DD
**Root**: <path audited>
**Result**: No findings at or above {min-severity} severity.

Supply chain posture: ✅ Passing for audited scope.

### Dimensions Checked / Skipped

| Dimension | Description          | Status             | Reason                 |
| --------- | -------------------- | ------------------ | ---------------------- |
| 1         | Action SHA pinning   | ✅ Checked — clean |                        |
| 2         | Workflow permissions | ✅ Checked — clean |                        |
| 3         | Secret exposure      | ✅ Checked — clean |                        |
| 4         | Cache poisoning      | ✅ Checked — clean |                        |
| 5         | Base image pinning   | ⏭ Skipped         | No Dockerfile detected |
| 6         | OIDC credentials     | ✅ Checked — clean |                        |
| 7         | NuGet lock files     | ⏭ Skipped         | No .csproj detected    |
| 8         | Python dep integrity | ✅ Checked — clean |                        |
| 9         | Cargo supply chain   | ⏭ Skipped         | No Cargo.toml detected |
| 10        | Node.js integrity    | ✅ Checked — clean |                        |
| 11        | Go module integrity  | ✅ Checked — clean |                        |
| 12        | Docker build chain   | ⏭ Skipped         | No Dockerfile detected |

This section is mandatory in empty reports. Absence of findings must be distinguishable from a skipped audit — always list which dimensions ran and which were absent from the repository.

---

Inter-Skill Handoff Contracts

Structured messages passed when delegating. Use these templates verbatim.

→ dependency-resolver

Trigger: Findings in Dims 7–11 for missing/outdated lock files or conflicts.

Delegating to dependency-resolver.

Context from supply-chain-audit:
- Ecosystems with lock file issues: {comma-separated list}
- Findings requiring lock file action:
  {finding id} — {file}:{line} — {current_value}
- CI validation commands after fix:
  {npm ci | cargo build | go mod verify | dotnet restore --locked-mode}
- Constraint: Do not change hash-pinned versions confirmed correct by
  supply-chain-audit Dim {8|9|10|11}. Listed constraints: {values if any}

→ pre-commit-manager

Trigger: Audit complete; regression prevention recommended.

Delegating to pre-commit-manager.

Context from supply-chain-audit:
- Hooks to install (based on active ecosystems):
  - zizmor or actionlint     → SHA pinning and permissions (Dims 1-3)
  - detect-secrets           → Credential scanning (Dims 3, 6)
  - npm ci enforcement hook  → Lock file requirement (Dim 10)
  - go mod verify hook       → go.sum integrity (Dim 11)
  - hadolint                 → Container best practices (Dims 5, 12)
  - cargo-audit hook         → Rust advisory check (Dim 9)
- Findings this would have prevented: {finding ids}

→ cybersecurity-analyst

Trigger: Findings indicating runtime concerns outside supply chain scope.

Escalating to cybersecurity-analyst.

Context from supply-chain-audit:
- Supply chain audit complete. These findings suggest broader runtime concerns:
  {finding id} — {file}:{line} — {rationale}
- Out of scope for supply-chain-audit because:
  {runtime exposure | network configuration | incident response | threat modeling}
- Supply chain posture: Critical: N, High: N, Medium: N, Info: N

→ silent-degradation-audit

Trigger: Security control steps use continue-on-error: true or suppress exit codes.

Delegating to silent-degradation-audit.

Context from supply-chain-audit:
- Security controls may be silently failing:
  {finding id} — {file}:{line} — {current_value}
- Concern: {e.g., grype scan step uses continue-on-error: true —
  a failed scan does not block the workflow}
- Request: Audit CI reliability for affected workflows to confirm
  security gates are enforcing, not just running.

---

Error Handling Patterns

Named Error Conditions

Five error conditions abort or constrain the audit with an explicit error code:

Tool Not Available (Degraded Mode)

When gh, crane, skopeo, syft, or grype is absent (not a timeout — use TOOL_TIMEOUT for timeouts):

⚠ Tool not available: {tool name}
Impact: {specific check} in Dimension {N} requires {tool} for live lookup.
Fallback: Pattern-based findings only. Findings with offline_detectable: false
are omitted. Re-run with {tool} installed for complete coverage.

Never fail silently. Always state which checks were degraded.

File Not Readable

⚠ File not readable: {file path}
Dimension {N} check skipped for this file.
Action: Manually verify {specific_pattern} in {file}.

Ecosystem Signal Present but Empty

ℹ {file} detected but contains no dependency declarations.
Dimension {N} check: No findings (nothing to audit).

Conflicting Severity Signals

When two checks assign different severities to the same file:line:

⚠ Conflicting severity signals at {file}:{line}
- Signal A: {severity} — {reason}
- Signal B: {severity} — {reason}
Resolution: Assigned {higher severity} per tie-break rule. Verify manually.

Accepted Risk File Present

When .supply-chain-accepted-risks.yml exists:

1. Validate file size ≤ 64KB; abort with ACCEPTED_RISKS_OVERFLOW if exceeded. 2. Reject any entry with wildcard characters in id field. 3. For each entry: check review_date — if past today, restore original severity. 4. Match findings by dimension + file + line. Critical findings are never suppressed regardless of matching accepted-risk entry. 5. Matched non-Critical findings: include in report with [ACCEPTED RISK — review: YYYY-MM-DD] and display severity as Info. 6. Never omit accepted-risk findings from the report — they must remain visible for review-date tracking.

---

Security Invariants

Seven invariants are enforced unconditionally regardless of scope or configuration:

---

Versioning Strategy

Current Version: 1.0.0

Semantic versioning scoped to the SKILL.md contract:

Stability Guarantees (≥ v1.0.0)

Finding schema: id, dimension, severity, file, line, current_value, expected_value are stable. New optional fields may be added in minor versions. Field removals require a major bump.

Handoff message templates: Stable for all four delegated skills at v1.x.x. New to: skills may be added in minor versions without breaking existing consumers.

No version negotiation: Static-analysis skill — version is in SKILL.md frontmatter.

When to Bump Version

Do bump when:

• Dimension added or removed (minor)
• Finding schema fields change (major if removing/renaming; minor if adding optional)
• New reference file expands auditable scope (minor)
• Detection pattern fix that changes existing finding counts (patch)

Do not bump for:

• Prose improvements to rationale text
• New tool entries in the SBOM tooling table
• New eval scenarios in eval-scenarios.md
• SHA placeholder annotation fixes

Dimension 6: Credential Hygiene and OIDC Migration

Overview

Long-lived credentials (static tokens, API keys, service account keys) in CI/CD are a persistent supply chain risk. OIDC (OpenID Connect) federated identity eliminates the need for long-lived secrets entirely for cloud provider access.

---

Detection: Long-Lived Secrets to Flag

Detection Commands

# Dim 6 — scan workflow files for long-lived credential secret names
grep -rn "AWS_ACCESS_KEY_ID\|AWS_SECRET_ACCESS_KEY\|AZURE_CREDENTIALS\|GOOGLE_CREDENTIALS\|GCP_SA_KEY\|AZURE_CLIENT_SECRET" .github/workflows/ 2>/dev/null

# Dim 6 — detect static credentials passed to cloud provider actions
grep -rn "aws-access-key-id\|aws-secret-access-key\|creds:" .github/workflows/ 2>/dev/null

# Dim 6 — check for OIDC-capable actions that are using secret-based auth instead
grep -rn "configure-aws-credentials\|azure/login\|google-github-actions/auth" .github/workflows/ 2>/dev/null

Secrets That Should Migrate to OIDC

# REVIEW — candidates for OIDC migration
secrets:
  AWS_ACCESS_KEY_ID         # → use aws-actions/configure-aws-credentials with OIDC
  AWS_SECRET_ACCESS_KEY     # → same
  AZURE_CREDENTIALS         # → use azure/login with OIDC
  GOOGLE_CREDENTIALS        # → use google-github-actions/auth with OIDC
  GCP_SA_KEY                # → same
  AZURE_CLIENT_SECRET       # → use federated identity credential

Secrets That Cannot Migrate (Accept and Document)

# ACCEPTABLE — no OIDC alternative exists
secrets:
  DOCKERHUB_TOKEN           # DockerHub has no OIDC support for GitHub Actions
  NPM_TOKEN                 # npm registry has no OIDC push support
  PYPI_TOKEN                # PyPI has OIDC via trusted publishers (migrate if possible)
  SLACK_WEBHOOK             # notification-only, rotate regularly

PyPI Trusted Publishers (OIDC Available)

PyPI supports OIDC via "trusted publishers" — flag PYPI_TOKEN as a migration candidate:

# VIOLATION — long-lived API token
- name: Publish to PyPI
  uses: pypa/gh-action-pypi-publish@<sha>
  with:
    password: ${{ secrets.PYPI_TOKEN }}

# CORRECT — OIDC trusted publisher (no secret needed)
jobs:
  publish:
    permissions:
      id-token: write  # required for OIDC
    steps:
      - uses: pypa/gh-action-pypi-publish@<sha>
        # no password needed — OIDC authenticates automatically

---

OIDC Migration Patterns

AWS

# CORRECT — OIDC for AWS
jobs:
  deploy:
    permissions:
      id-token: write # required for OIDC token request
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@<sha> # pin SHA
        with:
          role-to-assume: arn:aws:iam::123456789:role/github-actions-deploy
          role-session-name: github-actions-${{ github.run_id }}
          aws-region: us-east-1

Azure

# CORRECT — OIDC for Azure
jobs:
  deploy:
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: azure/login@<sha> # pin SHA
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
          # No client-secret — uses OIDC federated identity

GCP

# CORRECT — OIDC for GCP
jobs:
  deploy:
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: google-github-actions/auth@<sha> # pin SHA
        with:
          workload_identity_provider: projects/123/locations/global/workloadIdentityPools/github/providers/github
          service_account: deploy@project.iam.gserviceaccount.com
          # No service account key JSON — uses OIDC

---

Subject Constraint Verification

OIDC tokens without subject constraints allow any repository to assume the role.

AWS Trust Policy (Correct)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
        }
      }
    }
  ]
}

Subject Constraint Audit Checks

1. AWS: IAM role trust policy has sub condition — not just aud 2. Azure: Federated credential has subject set to specific repo+branch 3. GCP: Workload Identity Pool has attribute condition on repository

Flag as High if OIDC is used but subject constraints are missing (any repo can assume the role).

---

Secret Rotation Assessment

For secrets that cannot migrate to OIDC:

# Flag for rotation audit if age > 90 days:
# - Check GitHub secret creation date via API
gh api repos/{owner}/{repo}/actions/secrets/{secret_name} --jq '.updated_at'

Severity

---

Verification Checklist (Credentials)

• [ ] AWS/Azure/GCP access uses OIDC, not static credentials
• [ ] OIDC subject constraints lock down to specific repo + branch
• [ ] id-token: write permission is at job level, not workflow level
• [ ] PyPI publishing uses trusted publishers if possible
• [ ] Remaining long-lived secrets are documented with rotation policy
• [ ] No credentials committed in workflow files or .env files

Dimension 7: .NET / NuGet Supply Chain

Overview

.NET projects face supply chain risks from unlocked package restores, unauthorized NuGet sources, and missing vulnerability audit gates.

---

Check 1: NuGet Lock File (RestoreLockedMode)

Detection

# Check if lock files exist
find . -name "packages.lock.json" | wc -l

# Check if RestoreLockedMode is enabled
grep -r "RestoreLockedMode" **/*.csproj **/*.props 2>/dev/null

Pattern

<!-- VIOLATION — no lock mode, package versions can drift -->
<Project Sdk="Microsoft.NET.Sdk">
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

<!-- CORRECT — with lock mode in Directory.Build.props -->
<Project>
  <PropertyGroup>
    <RestoreLockedMode Condition="'$(CI)' == 'true'">true</RestoreLockedMode>
    <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  </PropertyGroup>
</Project>

Generate lock files locally:

dotnet restore --use-lock-file
# Commit the resulting packages.lock.json
git add **/packages.lock.json

Severity

---

Check 2: NuGet Source Authorization

Detection

# Check NuGet.Config for package sources
find . -name "NuGet.Config" | xargs grep -l "<packageSources>" 2>/dev/null

Pattern

<!-- VIOLATION — public source without clear-text disable -->
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="internal" value="https://pkgs.dev.azure.com/myorg/_packaging/feed/nuget/v3/index.json" />
  </packageSources>
</configuration>

<!-- CONCERN — dependency confusion risk if internal package names overlap with nuget.org -->
<!-- CORRECT — explicit source mapping (NuGet 6.0+) prevents dependency confusion -->
<configuration>
  <packageSources>
    <clear />  <!-- disable all default sources -->
    <add key="internal" value="https://pkgs.dev.azure.com/myorg/_packaging/feed/nuget/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="internal">
      <package pattern="MyOrg.*" />  <!-- only internal packages from internal source -->
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />  <!-- everything else from nuget.org -->
    </packageSource>
  </packageSourceMapping>
</configuration>

Dependency Confusion Risk

If both internal and public sources are listed without packageSourceMapping, NuGet may resolve an internal package name from the public source if an attacker publishes a higher-versioned package with that name.

Severity

---

Check 3: NuGetAudit Vulnerability Gate

NuGet 6.8+ (included in .NET 8 SDK) has built-in vulnerability auditing.

Detection

# Check SDK version
dotnet --version

# Run audit manually
dotnet list package --vulnerable --include-transitive

CI Integration

- name: Audit NuGet packages
  run: dotnet list package --vulnerable --include-transitive 2>&1 | tee nuget-audit.txt

- name: Fail on high/critical vulnerabilities
  run: |
    if grep -q "High\|Critical" nuget-audit.txt; then
      echo "::error::High or Critical NuGet vulnerabilities found"
      exit 1
    fi

Directory.Build.props Audit Configuration

<!-- Fail build on high/critical vulnerabilities (NuGet 6.8+) -->
<Project>
  <PropertyGroup>
    <NuGetAudit>true</NuGetAudit>
    <NuGetAuditMode>all</NuGetAuditMode>          <!-- include transitive deps -->
    <NuGetAuditLevel>high</NuGetAuditLevel>        <!-- fail on High and Critical -->
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>
</Project>

Severity

---

Check 4: Central Package Management

For multi-project solutions, Directory.Packages.props centralizes version control:

<!-- Directory.Packages.props — single source of truth for versions -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageVersion Include="Microsoft.Extensions.Logging" Version="8.0.0" />
  </ItemGroup>
</Project>

Individual projects then omit versions:

<PackageReference Include="Newtonsoft.Json" />  <!-- version from Directory.Packages.props -->

Flag as Medium if solution has 3+ projects without central package management.

---

Verification Checklist (.NET / NuGet)

• [ ] packages.lock.json exists and is committed for each project
• [ ] RestoreLockedMode=true in CI environment
• [ ] NuGet.Config has <packageSourceMapping> if internal sources are present
• [ ] NuGetAudit=true with NuGetAuditLevel=high in Directory.Build.props
• [ ] CI pipeline has a step that fails on High/Critical NuGet advisories
• [ ] No <clear /> missing when mixing public and private sources

Evaluation Scenarios

Three graded scenarios for validating the supply-chain-audit skill. Each scenario specifies fixture files, planted findings, expected outputs, and pass/fail criteria.

---

Scenario A: GitHub Actions Monorepo (GHA + Python + Node)

Active Ecosystems: GitHub Actions (Dims 1-4), Python (Dim 8), Node.js (Dim 10) Total Planted Findings: 7 Expected Severity Distribution: 2 Critical, 3 High, 2 Medium

Fixture Files

.github/workflows/ci.yml

# Planted findings: F1 (Dim1 Critical), F2 (Dim2 High), F3 (Dim3 Critical)
name: CI
on: [push, pull_request_target] # F2: pull_request_target without permissions

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # F1: unpinned action (High→Critical with pull_request_target)
      - uses: actions/setup-python@v5 # also unpinned
      - run: pip install -r requirements.txt
      - run: echo "Token=${{ secrets.API_TOKEN }}" # F3: secret echoed to log
      - run: pytest

requirements.txt

# Planted finding: F4 (Dim8 High — no hash pinning)
requests==2.31.0
flask==3.0.3
gunicorn==22.0.0

package.json

{
  "name": "frontend",
  "scripts": {
    "build": "npx webpack --config webpack.config.js",
    "test": "jest"
  },
  "devDependencies": {
    "webpack": "^5.91.0"
  }
}

Planted findings: F5 (Dim10 High — no lock file), F6 (Dim10 High — unversioned npx), F7 (Dim8 Medium — pip install without --require-hashes in workflow)

Expected Findings

Note: Ref column uses fixture labels (F1-F7). Actual skill output IDs follow {SEVERITY}-{NNN} format defined in contracts.md (e.g., CRIT-001). File-level findings (no applicable line) use :0.

Pass/Fail Criteria

• PASS: Skill identifies all 7 findings with correct severity
• PARTIAL PASS: Skill identifies 5-6 findings; missing findings are Info-level misses
• FAIL: Skill misses F1, F2, or F3 (Critical findings)
• FAIL: Skill misses F4 (High finding in requirements.txt)

---

Scenario B: Containerized Go Service (Containers + Go + Credentials)

Active Ecosystems: Containers (Dims 5, 12), Go (Dim 11), Credentials (Dim 6) Total Planted Findings: 5 Expected Severity Distribution: 1 Critical, 3 High, 1 Medium

Fixture Files

Dockerfile

# Planted finding: F1 (Dim5 High — mutable tag)
FROM golang:1.22-alpine AS builder
RUN apk add --no-cache git
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o /app/server ./cmd/server

# Planted finding: F2 (Dim12 High — final stage not distroless + root user)
FROM alpine:latest  # also unpinned — F3 (Dim5 Critical — :latest)
COPY --from=builder /app/server /server
CMD ["/server"]  # runs as root — no USER instruction

.github/workflows/deploy.yml

# Planted finding: F4 (Dim6 High — long-lived AWS credentials)
name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2 (pinned — not a planted finding)
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

go.mod

module github.com/myorg/service

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/some/package v1.0.0
)

// Planted finding: F5 (Dim11 Medium — mutable replace)
replace github.com/some/package => github.com/myorg/fork main

Expected Findings

Note: Ref column uses fixture labels (F1-F5). Actual skill output IDs follow {SEVERITY}-{NNN} format defined in contracts.md.

Pass/Fail Criteria

• PASS: Skill identifies all 5 findings with correct severity
• PARTIAL PASS: Skill identifies F1, F3, F4 (misses F2 or F5)
• FAIL: Skill misses F3 (Critical — :latest tag)
• FAIL: Skill misses F4 (High — static cloud credentials)

---

Scenario C: .NET + Rust Mixed Repo (Dim7 + Dim9 + SLSA Readiness)

Active Ecosystems: .NET/NuGet (Dim 7), Rust (Dim 9), SLSA assessment Total Planted Findings: 6 Expected Severity Distribution: 0 Critical, 4 High, 2 Medium

Fixture Files

MyService/MyService.csproj

<!-- Planted finding: F1 (Dim7 High — no lock file) -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
    <PackageReference Include="Microsoft.Extensions.Http" Version="8.0.0" />
  </ItemGroup>
</Project>

(No packages.lock.json present, no Directory.Build.props)

NuGet.Config

<!-- Planted finding: F2 (Dim7 High — dependency confusion risk) -->
<configuration>
  <packageSources>
    <add key="internal" value="https://pkgs.dev.azure.com/myorg/_packaging/feed/nuget/v3/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <!-- Missing <clear /> and no packageSourceMapping -->
  </packageSources>
</configuration>

Cargo.toml (workspace member tools/)

# Planted finding: F3 (Dim9 Medium — Cargo.lock in .gitignore for binary)
[package]
name = "deploy-tool"
version = "0.1.0"
edition = "2021"

[[bin]]
name = "deploy-tool"
path = "src/main.rs"

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
serde_json = "1.0"

(.gitignore contains Cargo.lock)

.github/workflows/build.yml

# Planted findings: F4 (Dim1 High — unpinned), F5 (Dim2 Medium — no permissions)
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4 # F4: unpinned
      - uses: actions/setup-dotnet@v4 # also unpinned
      - run: dotnet build
      - uses: dtolnay/rust-toolchain@stable # F6: unpinned
        with:
          toolchain: stable
      - run: cargo build --release

(No permissions: key — F5)

Expected Findings

Note: Ref column uses fixture labels (F1-F6). Actual skill output IDs follow {SEVERITY}-{NNN} format defined in contracts.md. File-level findings (absent file/property) use :0.

SLSA Readiness Expected Assessment

| Requirement             | Status                                           |
| ----------------------- | ------------------------------------------------ |
| Build is scripted       | ✅                                               |
| Build runs on hosted CI | ✅                                               |
| Provenance generated    | ❌ No SLSA generator workflow found              |
| Action refs SHA-pinned  | ❌ 3 unpinned refs found (F4, F6 + setup-dotnet) |

Current SLSA Level: L1 (scripted build, no provenance)
Blockers to L2: Add SLSA generator; sign provenance with OIDC

Pass/Fail Criteria

• PASS: Skill identifies all 6 findings; SLSA assessment reports L1 with blockers
• PARTIAL PASS: Skill identifies 4-5 findings; SLSA assessment present
• FAIL: Skill misses F2 (dependency confusion risk in NuGet.Config)
• FAIL: No SLSA readiness assessment produced

Dimension 11: Go Module Integrity

---

Check 1: go.sum Presence and Commitment

Detection

# Check go.sum exists
ls go.sum 2>/dev/null || echo "MISSING"

# Check if go.sum is in .gitignore (violation)
grep "go.sum" .gitignore 2>/dev/null && echo "VIOLATION: go.sum in .gitignore"

Why go.sum Matters

go.sum contains cryptographic hashes for every module version used in the build. The Go toolchain refuses to use a module if its hash doesn't match. Committing go.sum makes the lockfile tamper-evident and enables reproducible builds.

Severity

---

Check 2: GONOSUMCHECK and GONOSUMDB

Detection

grep -rn "GONOSUMCHECK\|GONOSUMDB\|GOFLAGS\|GONOSUMCHECK" \
    .github/workflows/ Makefile Dockerfile .env* 2>/dev/null

Pattern

# VIOLATION — disables sum verification entirely
env:
  GONOSUMCHECK: "*"
  GONOSUMDB: "*"

# VIOLATION — disables sum check for specific module (may be legitimate but flag for review)
env:
  GONOSUMCHECK: "github.com/internal/mymodule"

# ACCEPTABLE — private modules that can't reach sum.golang.org
env:
  GONOSUMCHECK: "github.com/myorg/*"  # only if myorg is your own org
  GOPRIVATE: "github.com/myorg/*"

Severity

---

Check 3: replace Directives

replace directives in go.mod override module sources — like Rust's [patch]. They are appropriate for workspace development but risky when pointing outside the repository.

Detection

grep -A2 "^replace" go.mod 2>/dev/null

Pattern

// VIOLATION — path outside repository
replace github.com/some/package => ../../external/package

// ACCEPTABLE — workspace member
replace github.com/myorg/internal => ./internal

// ACCEPTABLE — specific commit (not branch)
replace github.com/some/package => github.com/myorg/fork v0.0.0-20240101000000-abc123456789

// VIOLATION — mutable branch
replace github.com/some/package => github.com/myorg/fork main

Severity

---

Check 4: go mod verify

# Verify module downloads against go.sum
go mod verify

# Check for vulnerabilities (requires Go 1.18+)
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...

CI Integration

- name: Verify modules
  run: go mod verify

- name: Check vulnerabilities
  run: |
    go install golang.org/x/vuln/cmd/govulncheck@latest
    govulncheck ./...

---

Check 5: Toolchain Pinning (Go 1.21+)

Go 1.21 introduced toolchain directive in go.mod:

// go.mod
go 1.22.3
toolchain go1.22.3  // pins exact Go toolchain version

Detection

grep "^toolchain" go.mod 2>/dev/null || echo "No toolchain directive"

Severity

---

Verification Checklist (Go)

• [ ] go.sum committed and not in .gitignore
• [ ] go mod verify passes in CI
• [ ] No GONOSUMCHECK=* or GONOSUMDB=* in CI
• [ ] GONOSUMCHECK scoped only to your own organization's modules
• [ ] No replace directives pointing outside the repository
• [ ] govulncheck ./... runs in CI
• [ ] toolchain directive pinned in go.mod (Go 1.21+)

Dimension 10: Node.js Supply Chain

---

Check 1: npm ci vs npm install

Detection

grep -rn "npm install\|yarn install\|pnpm install" .github/workflows/ Makefile Dockerfile 2>/dev/null

Pattern

# VIOLATION — npm install updates lock file, allows version drift
- run: npm install

# CORRECT — npm ci uses lock file exactly, fails if package-lock.json is missing
- run: npm ci

# CORRECT — yarn equivalent
- run: yarn install --frozen-lockfile

# CORRECT — pnpm equivalent
- run: pnpm install --frozen-lockfile

Why It Matters

npm install will update package-lock.json if a package version has changed. In CI, this silently installs a different version than what was tested locally. npm ci fails if package-lock.json is out of sync — making the issue visible.

Lock File Committed

# Check lock file exists and is not in .gitignore
ls package-lock.json yarn.lock pnpm-lock.yaml 2>/dev/null
grep -E "package-lock.json|yarn.lock|pnpm-lock.yaml" .gitignore 2>/dev/null

Severity

---

Check 2: npx Risk

npx downloads and executes packages on demand. Without a version pin or SHA, it installs the latest published version — a supply chain risk.

Detection

grep -rn "npx " .github/workflows/ Makefile scripts/ 2>/dev/null

Pattern

# VIOLATION — downloads latest version at runtime
- run: npx create-react-app my-app

# VIOLATION — no version pinning
- run: npx prettier --check .

# BETTER — pin version
- run: npx prettier@3.2.5 --check .

# BEST — install as dev dependency, use local binary
- run: npm ci && ./node_modules/.bin/prettier --check .

# BEST — package.json script
- run: npm run lint # delegates to local binary via scripts

Severity

---

Check 3: postinstall Scripts

postinstall scripts in package.json execute automatically on npm install. Malicious packages abuse this to execute arbitrary code.

Detection

# Check own package.json for postinstall scripts
python3 -c "
import json
with open('package.json') as f:
    pkg = json.load(f)
scripts = pkg.get('scripts', {})
for name in ['postinstall', 'install', 'preinstall', 'prepare']:
    if name in scripts:
        print(f'{name}: {scripts[name]}')
"

# Check dependencies for postinstall scripts (requires node_modules to be installed)
# Static analysis — check lock file for known risky patterns
grep -l "postinstall" node_modules/*/package.json 2>/dev/null | head -20

Severity

---

Check 4: package-lock.json Integrity

Detect Suspicious Lock File Patterns

# Check for non-registry sources in package-lock.json
python3 -c "
import json
with open('package-lock.json') as f:
    lock = json.load(f)
packages = lock.get('packages', lock.get('dependencies', {}))
for name, info in packages.items():
    resolved = info.get('resolved', '')
    # Flag non-npm registry URLs
    if resolved and 'registry.npmjs.org' not in resolved and 'npmjs.com' not in resolved:
        if 'github.com' in resolved or 'gitlab.com' in resolved:
            print(f'GIT SOURCE: {name} -> {resolved}')
        elif resolved.startswith('http'):
            print(f'UNKNOWN SOURCE: {name} -> {resolved}')
" 2>/dev/null

Severity

---

Check 5: npm audit

# Run audit
npm audit --json | python3 -c "
import sys, json
report = json.load(sys.stdin)
vulns = report.get('vulnerabilities', {})
for name, info in vulns.items():
    severity = info.get('severity', 'unknown')
    if severity in ('high', 'critical'):
        print(f'{severity.upper()}: {name}')
        for via in info.get('via', []):
            if isinstance(via, dict):
                print(f'  CVE: {via.get(\"url\", \"N/A\")}')
"

# Fail CI on high/critical
npm audit --audit-level=high

CI Integration

- name: Security audit
  run: npm audit --audit-level=high

---

Verification Checklist (Node.js)

• [ ] CI uses npm ci (not npm install)
• [ ] package-lock.json / yarn.lock / pnpm-lock.yaml committed and not in .gitignore
• [ ] No unversioned npx <package> in CI scripts
• [ ] npm audit --audit-level=high fails CI on High/Critical CVEs
• [ ] Direct dependencies with postinstall scripts reviewed
• [ ] Lock file has no packages resolved from non-registry URLs

Dimension 8: Python Dependency Integrity

Overview

Python supply chain attacks target requirements.txt files without hash pinning, the --extra-index-url flag's resolution order, and typosquatted package names that mimic popular packages.

---

Check 1: Hash Pinning in requirements.txt

Detection

# Check if requirements files have hash pinning
grep -c "sha256:" requirements*.txt requirements/**/*.txt 2>/dev/null

Pattern

# VIOLATION — version-only pin, no hash verification
requests==2.31.0
numpy==1.26.4

# CORRECT — with hash pinning
requests==2.31.0 \
    --hash=sha256:58cd2187423d... \
    --hash=sha256:942c5a758f98...
numpy==1.26.4 \
    --hash=sha256:2a02aba9ed12...

Generate Hash-Pinned Requirements

# pip-compile (pip-tools) — generates hash-pinned requirements from .in file
pip install pip-tools
pip-compile --generate-hashes requirements.in -o requirements.txt

# pip-compile for extras
pip-compile --generate-hashes --extra dev pyproject.toml -o requirements-dev.txt

# pip install with hashes (enforces hashes present)
pip install --require-hashes -r requirements.txt

Severity

---

Check 2: --extra-index-url Risk

Detection

grep -rn "extra-index-url\|extra_index_url\|--index-url" \
    requirements*.txt setup.cfg pyproject.toml pip.conf .pip/ 2>/dev/null

The Risk

When --extra-index-url is combined with --index-url, pip resolves by choosing the highest version across all sources — not the first source. An attacker can publish a package with a higher version to PyPI if your internal package name is not reserved there.

# VIOLATION — dependency confusion risk
--extra-index-url https://my-internal-registry.example.com/simple/
requests==2.31.0      # fetched from PyPI (correct)
mycompany-auth==1.2.0  # intended from internal, but attacker could publish 1.2.1 on PyPI

Mitigation

# CORRECT — use --index-url to make internal source primary, add PyPI as extra
--index-url https://my-internal-registry.example.com/simple/
--extra-index-url https://pypi.org/simple/

# Better — use hash pinning to prevent substitution
mycompany-auth==1.2.0 \
    --hash=sha256:abc123...   # hash prevents attacker version from being accepted

Severity

---

Check 3: Typosquatting Detection

Heuristic Signals (Static Analysis)

Without live PyPI data, use these signals to flag likely typosquats for manual review:

# Packages with edit distance 1-2 from popular packages
# Common typosquatting patterns:
SUSPICIOUS_PATTERNS = [
    r"re-quests",      # requests
    r"reqeusts",       # requests
    r"pillow-pil",     # Pillow
    r"np-numpy",       # numpy
    r"panda-s",        # pandas
    r"scikit-learn2",  # scikit-learn
    r"boto-3",         # boto3
    r"crypto-graphy",  # cryptography
]

Known Malicious Pattern Families

Flag packages matching these patterns for review:

• Name differs from popular package by 1-2 character substitution (e.g., o → 0)
• Name adds/removes a hyphen or underscore vs. well-known package
• Name is <package>-utils, <package>-tools, <package>-helper variants of core packages
• Package was published within 7 days of a popular package's major release

Note: Typosquatting detection is heuristic-based without live PyPI download data. Flag suspicious packages; do not assert they are malicious.

Severity

---

Check 4: pyproject.toml and setup.cfg

Detection

# Check for version specifiers without upper bounds in pyproject.toml
grep -E ">=|~=" pyproject.toml setup.cfg 2>/dev/null

Pattern

# VIOLATION — no upper bound allows installing attacker-published future version
[project]
dependencies = [
    "requests>=2.0",    # will install any future version including attacker-published 99.0
]

# BETTER — pinned range
dependencies = [
    "requests>=2.31,<3.0",
]

# BEST (for deployed applications) — use requirements.txt with hash pinning
# pyproject.toml is for libraries; requirements.txt for deployed apps

Severity

---

Verification Checklist (Python)

• [ ] requirements.txt uses --hash=sha256: for all packages
• [ ] CI uses pip install --require-hashes -r requirements.txt
• [ ] --extra-index-url (if present) is combined with hash pinning
• [ ] Internal package names are reserved on PyPI
• [ ] No obvious typosquats in dependency list
• [ ] pip-tools or equivalent generates lock files from .in source files
• [ ] pip-compile --generate-hashes in contributor documentation

Dimension 9: Rust / Cargo Supply Chain

---

Check 1: Cargo.lock Committed

Detection

# Check if Cargo.lock is in .gitignore (violation for applications)
grep "Cargo.lock" .gitignore 2>/dev/null
# Check if Cargo.lock exists
ls Cargo.lock 2>/dev/null || echo "MISSING"

Rule

Severity

---

Check 2: build.rs Risk Assessment

build.rs files execute arbitrary Rust code at compile time. They are a supply chain risk vector when present in transitive dependencies.

Detection

# Find build.rs files in the project
find . -name "build.rs" -not -path "*/target/*"

# Find which dependencies use build scripts
cargo metadata --format-version 1 | python3 -c "
import sys, json
meta = json.load(sys.stdin)
for pkg in meta['packages']:
    if pkg.get('build_script') and pkg['name'] not in ['$(basename $(pwd))']:
        print(f'{pkg[\"name\"]} {pkg[\"version\"]}: build_script={pkg[\"build_script\"]}')
"

Assessment

Flag direct dependencies with build.rs for manual review:

# Information finding — not automatically a violation
FOUND: openssl-sys 0.9.x uses build.rs (legitimate — detects system OpenSSL)
FOUND: prost-build 0.12.x uses build.rs (legitimate — protobuf code generation)
REVIEW: unknown-crate 0.1.0 uses build.rs (investigate purpose)

Severity

---

Check 3: [patch] and [replace] Directive Scope

[patch] and [replace] sections in Cargo.toml override crate sources. They are legitimate for local development but dangerous if committed with path patches pointing outside the repository.

Detection

grep -A5 "\[patch\]" Cargo.toml 2>/dev/null
grep -A5 "\[replace\]" Cargo.toml 2>/dev/null

Pattern

# VIOLATION — path patch pointing outside the repo
[patch.crates-io]
serde = { path = "../../external/serde-fork" }  # arbitrary code execution risk

# ACCEPTABLE — pointing to workspace member
[patch.crates-io]
my-internal-crate = { path = "./crates/my-internal-crate" }

# ACCEPTABLE — specific git commit (not branch)
[patch.crates-io]
some-crate = { git = "https://github.com/some/crate", rev = "abc1234" }

# VIOLATION — mutable branch patch
[patch.crates-io]
some-crate = { git = "https://github.com/some/crate", branch = "main" }

Severity

---

Check 4: cargo audit

# Install if not present
cargo install cargo-audit

# Run audit
cargo audit

# Output machine-readable JSON for CI parsing
cargo audit --json | python3 -c "
import sys, json
report = json.load(sys.stdin)
vulns = report.get('vulnerabilities', {}).get('list', [])
for v in vulns:
    print(f'{v[\"advisory\"][\"id\"]}: {v[\"package\"][\"name\"]} {v[\"package\"][\"version\"]} - {v[\"advisory\"][\"title\"]}')
    print(f'  CVSS: {v[\"advisory\"].get(\"cvss\", \"N/A\")}')
"

CI Integration

- name: Install cargo-audit
  run: cargo install cargo-audit --locked

- name: Run security audit
  run: cargo audit --deny warnings

Severity

---

Verification Checklist (Rust)

• [ ] Cargo.lock is committed (for binary/application projects)
• [ ] cargo audit runs in CI and fails on vulnerabilities
• [ ] No [patch] with external paths outside the repository
• [ ] No [patch] with mutable git branch references
• [ ] Direct dependencies with build.rs reviewed and justified
• [ ] No [replace] directives (use [patch] instead)

SBOM, CVSS Scoring, SLSA Compliance, and Fix-PR Workflow

Table of Contents

1. SBOM Generation 2. CVSS Severity Mapping 3. SLSA L1-L4 Compliance 4. Fix-PR Generation Workflow 5. Integration with amplihack Skills

---

SBOM Generation

A Software Bill of Materials documents all components in a software artifact. SBOM generation is required for SLSA L1+ and increasingly mandated by US Executive Order 14028 (2021) and EU CRA (2024).

Tooling by Artifact Type

SBOM Attestation in CI

Attach SBOM to GitHub release artifacts using cosign:

- name: Generate SBOM
  uses: anchore/sbom-action@<sha> # pin to full SHA — see actions.md Dim 1
  with:
    format: spdx-json
    output-file: sbom.spdx.json

- name: Sign SBOM with cosign
  env:
    COSIGN_EXPERIMENTAL: 1
  run: |
    cosign attest --predicate sbom.spdx.json \
      --type spdxjson \
      ${{ env.IMAGE_REF }}

SBOM File Handling (Warn-Before-Write)

Before writing an SBOM file to the repository, warn the user:

⚠ SBOM Write Advisory:
Writing sbom.spdx.json to the repository will make your full dependency tree
publicly visible. Consider whether this is intended before committing.

Recommended actions:
  1. Add to .gitignore if not intended for version control:
       echo "sbom.spdx.json" >> .gitignore
       echo "*.cyclonedx.json" >> .gitignore
  2. If storing in the repo is intentional (e.g., for release assets):
       - Add to .github/release-assets/ not to the project root
       - Attach to GitHub Releases rather than committing to main branch
  3. For CI-only SBOM (recommended):
       - Upload as workflow artifact: actions/upload-artifact
       - Attach to release via gh release upload
       - Never commit to version control

Vulnerability Scanning from SBOM

# grype — scan SBOM for CVEs
grype sbom:./sbom.spdx.json --fail-on high

# osv-scanner — scan against OSV vulnerability database
osv-scanner --sbom=sbom.spdx.json

---

CVSS Severity Mapping

This skill uses CVSS v3.1 base score bands for all severity ratings:

Supply Chain Risk Scoring (Non-CVE Findings)

When a finding is not associated with a CVE (e.g., mutable action ref, missing lock file), use the following heuristic to assign severity:

Example: Unpin third-party action (base 6.0) + write permissions (+2.0) + secret access (+2.0) = 10.0 → Critical

---

SLSA L1-L4 Compliance

SLSA (Supply-chain Levels for Software Artifacts) is a framework for measuring supply chain security maturity. https://slsa.dev

Compliance Table

Achieving SLSA L3 with GitHub Actions

SLSA L3 is achievable with GitHub Actions + the SLSA generic generator:

# .github/workflows/release.yml
jobs:
  build:
    outputs:
      hashes: ${{ steps.hash.outputs.hashes }}
    steps:
      - name: Build artifact
        run: |
          make build
          sha256sum my-artifact > hashes.txt

      - id: hash
        run: echo "hashes=$(cat hashes.txt | base64 -w0)" >> $GITHUB_OUTPUT

  provenance:
    needs: [build]
    permissions:
      actions: read
      id-token: write
      contents: write
    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@1234567890abcdef1234567890abcdef12345678 # v2.0.0 — replace with SHA from https://github.com/slsa-framework/slsa-github-generator/releases
    # IMPORTANT: Pin to full SHA — look up current SHA at:
    # https://github.com/slsa-framework/slsa-github-generator/releases
    with:
      base64-subjects: "${{ needs.build.outputs.hashes }}"
      upload-assets: true

Note on SHA pinning for the SLSA generator itself: The SLSA generator workflow (slsa-framework/slsa-github-generator) must itself be pinned to a full commit SHA (not a semver tag), per Dimension 1 of this skill. Using a semver tag here would be a High finding — an ironic violation in a provenance workflow.

Verification of SLSA Provenance

# Install slsa-verifier
go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest

# Verify provenance for a release artifact
slsa-verifier verify-artifact \
  --provenance-path my-artifact.intoto.jsonl \
  --source-uri github.com/myorg/myrepo \
  --source-tag v1.2.3 \
  my-artifact

SLSA Readiness Assessment Template

Include this in audit reports:

### SLSA Readiness

| Requirement                              | Status  | Gap                         |
| ---------------------------------------- | ------- | --------------------------- |
| Build is scripted (not manual)           | ✅ / ❌ |                             |
| Build runs on hosted CI (GitHub Actions) | ✅ / ❌ |                             |
| Provenance is generated per build        | ✅ / ❌ | Add SLSA generator workflow |
| Provenance is signed (OIDC-based)        | ✅ / ❌ | Requires id-token: write    |
| All action refs pinned to SHA            | ✅ / ❌ | See Dim 1 findings          |
| SLSA generator itself is SHA-pinned      | ✅ / ❌ |                             |

**Current SLSA Level**: L0 / L1 / L2 / L3
**Blockers to next level**: [list]

---

Fix-PR Generation Workflow

When audit produces actionable findings, generate a fix PR using this checklist:

Priority Ordering for Fix PR

1. Critical findings — block all other PRs until resolved 2. High findings in production deploy workflows — fix before next release 3. High findings in all other workflows — fix within sprint 4. Medium findings — batch into single "supply chain hygiene" PR 5. Info findings — batch or close as accepted risk

Fix PR Safety Checklist

Before opening a fix PR:

• [ ] Verify each new SHA corresponds to the expected version tag
• [ ] For actions: gh api repos/{owner}/{action}/git/ref/tags/{tag} confirms SHA
• [ ] For containers: crane digest {image}:{tag} confirms digest
• [ ] Add version comment after each pinned SHA
• [ ] Run CI on fix branch before requesting review
• [ ] For lock file additions: regenerate with npm ci, cargo update, etc.
• [ ] Document any accepted-risk findings in .supply-chain-accepted-risks.yml

Accepted Risk Documentation Template

.supply-chain-accepted-risks.yml uses YAML format matching the schema in contracts.md:

# .supply-chain-accepted-risks.yml
- id: HIGH-001
  file: .github/workflows/ci.yml
  line: 0
  dimension: 6
  rationale: "DockerHub does not support OIDC for GitHub Actions; token scoped to single repository, rotated quarterly."
  review_date: "2026-06-01"

- id: INFO-002
  file: .github/workflows/internal.yml
  line: 8
  dimension: 1
  rationale: "Internal action maintained by Platform team; monitored via internal security review process."
  review_date: "2026-09-01"

Constraints (enforced by contracts.md error handling):

• File size ≤ 64KB (ACCEPTED_RISKS_OVERFLOW if exceeded)
• No wildcards in id field
• review_date must be a future date — past dates restore original severity
• Critical findings cannot be suppressed regardless of matching entry

---

Integration with amplihack Skills

Delegate to dependency-resolver

After finding lock file issues (Dims 7, 8, 9, 10, 11), delegate:

"I found missing/outdated lock files in this audit. Delegating to dependency-resolver
for conflict resolution and lock file regeneration."

Handoff context to pass:

• Which ecosystems have lock file issues
• Whether conflicts exist between transitive deps
• CI command to validate after fix (npm ci, cargo build, go mod verify)

Delegate to pre-commit-manager

After audit completes, offer to install enforcement hooks:

"Supply chain audit complete. To prevent regressions, I recommend installing
pre-commit hooks via pre-commit-manager for:
- SHA pinning validation (actions-security via zizmor or actionlint)
- npm ci enforcement (lock file check hook)
- go mod verify hook
- detect-secrets for credential scanning"