Review dependency health without treating a score as a guarantee

Project health becomes a security decision only when joined to how you use the dependency. A parser for anonymous uploads, a development formatter and a privileged deployment agent have different exposure and replacement costs. Start with required functionality, execution context, data handled, update mechanism, available alternatives and the team's ability to maintain a fork. Popularity or a high aggregate score cannot answer those product-specific questions.

The fictional team needs an archive parser for untrusted customer uploads. Candidate A has a higher total security score but a single active maintainer and an unexplained release workflow gap. Candidate B has a lower score because its badge and packaging checks are incomplete, yet its recent fixes have clear review and release records. The task is not to pick the prettier dashboard. It is to decide which evidence addresses the consequence of parsing attacker-controlled bytes and whether the remaining uncertainty can be bounded operationally.

OpenSSF Scorecard runs about 20 automated checks against a source repository and rates each from 0 to 10, or -1 when it could not reach a result. Each check carries a risk level: Dangerous-Workflow and Webhooks are Critical; Binary-Artifacts, Branch-Protection, Code-Review, Dependency-Update-Tool, Maintained, Signed-Releases, Token-Permissions and Vulnerabilities are High. A failed check can signal a real weakness, unsupported tooling or an observation limitation, and a passed check can cover a narrow behavior rather than the entire project. Inspect raw findings, the scan date and the repository identity. Do not assume that a repository's settings describe every package published under its name, or that its score is a probability of compromise.

For archive parsing, relevant evidence includes response to input-validation defects, release provenance, reviewed changes, test cases for malformed input and a way to report vulnerabilities. A quiet repository may be stable or abandoned; commit frequency alone does not distinguish those states. A recently added maintainer can improve continuity or introduce takeover risk; examine the release authorization path. Where an automated finding conflicts with a supplied release record, preserve both and investigate the specific claim rather than averaging away the disagreement.

The script below gathers intake evidence for one exact npm version from public APIs, without a token: deps.dev reports licenses, advisories, verified provenance and how it linked the version to a repository; the Scorecard API returns the latest published result for that repository, usually from OpenSSF's weekly scan; and npm lists who can publish. For sigstore 5.0.0, deps.dev showed SLSA provenance with verified: true naming the source commit, and a repository link backed by SLSA_ATTESTATION. For the widely used tar 7.5.22 it showed no provenance and only an UNVERIFIED_METADATA repository link, taken from package.json, with one publisher; Scorecard's 2026-10-05 scan of that repository scored 5.6, with Code-Review 0 and Signed-Releases and Branch-Protection inconclusive. That says nothing about the quality of the code. It means the claim that the registry tarball came from the reviewed repository rests on trust in the publisher, which an intake gate like the one in this guide must record.

#!/usr/bin/env bash
set -euo pipefail
PKG="$1" VER="$2"   # an npm package and exact version; URL-encode scoped names (%40scope%2Fname)
DEPS="https://api.deps.dev/v3/systems/npm/packages/$PKG/versions/$VER"

# 1. License, advisories, provenance and how deps.dev linked the version to a repository
curl -s "$DEPS" | jq '{publishedAt, licenses, advisoryKeys,
  provenance: [.slsaProvenances[] | {sourceRepository, commit, verified}],
  repository: [.relatedProjects[] | select(.relationType == "SOURCE_REPO")
    | {id: .projectKey.id, relationProvenance}]}'

# 2. OpenSSF Scorecard checks for that repository (latest published result; -1 means inconclusive)
REPO=$(curl -s "$DEPS" | jq -r '[.relatedProjects[] | select(.relationType == "SOURCE_REPO")][0].projectKey.id')
curl -s "https://api.scorecard.dev/projects/$REPO" \
  | jq '{date, score, checks: [.checks[] | {name, score}]}'

# 3. Who can publish this package, and whether npm holds provenance for this version
npm view "$PKG@$VER" maintainers dist.attestations.provenance --json

A dependency intake record needs the exact package/repository relationship, required capability, criticality, exposure, assessed evidence, unresolved questions, chosen version/digest, approving role and maintenance plan. Conditions should be measurable: pin an approved archive digest, keep parsing in a restricted worker, cap input/output size, and retain regression tests. A vague promise to monitor the project leaves no event that changes the decision. Record the license as part of intake; /domains/supply-chain/dependencies/open-source-license-compliance/ covers the check.

The fixture's local rule forbids production intake for this parser unless the distributed package can be linked to an authorized release and the team has an owned update path. Candidate A lacks that link despite its higher score, so it remains pending. B has the needed release evidence and a documented response route, but its single active release owner creates continuity risk. A conditional pilot can limit exposure and establish fallback support; it is not proof that B is safer in every dimension. Stronger isolation also increases latency and operational work, which the decision should acknowledge.

A health assessment expires when relevant facts change: maintainer ownership, release signing identity, registry namespace, security response, major architecture, support status or your own use of the package. Reassess high-consequence dependencies on a scheduled cadence as well as on those events. An old intake approval should not authorize a new major version that introduces native code or network access without review. Watch the publishing path too: in September 2025 the Shai-Hulud worm stole npm tokens from developer machines and CI runners and used them to publish malicious versions of other packages those tokens could publish. A new version that loses provenance its predecessors had, adds an install script or comes from a new publisher deserves review before it is installed; pnpm trustPolicy: no-downgrade fails an install when a package's trust evidence is weaker than in earlier releases. Ownership changes were the signal that mattered in /domains/supply-chain/dependencies/case-study-event-stream/ and /domains/supply-chain/dependencies/case-study-polyfill-io/: the handover of an npm package and the sale of a CDN domain.

NIST supply-chain risk guidance and SSDF provide broader risk and lifecycle context, but the concrete policy here is fictional. For an organization-wide program, the OpenSSF S2C2F puts intake checks like these into a maturity model (/domains/supply-chain/dependencies/s2c2f-adoption/), and a maintainer's dated OSPS Baseline claim (/domains/supply-chain/ci-cd/osps-baseline-for-maintainers/) is one more piece of evidence to read, not a score. Its purpose is to show how evidence becomes an engineering condition. Preserve the rejected or deferred option and why; otherwise the next team may repeat the same superficial score comparison. The exercise includes all relevant observations and decision thresholds. It deliberately leaves code quality unproven so the reader cannot turn project-health evidence into an unsupported statement that the parser is vulnerability-free.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. OpenSSF Scorecard project and checks
2. NIST SP 800-161 Rev. 1, updated: supply-chain risk management. May 2022, updated 1 November 2024.
3. NIST SP 800-218: SSDF 1.1, final (1.2 initial public draft published 2025-12-17). Version 1.1 (February 2022).
4. OpenSSF Scorecard: checks and risk levels
5. OpenSSF Scorecard API
6. deps.dev API v3
7. OpenSSF: Concise Guide for Evaluating Open Source Software
8. CISA: widespread supply chain compromise impacting the npm ecosystem (2025-09-23)
9. pnpm settings: dependency resolution (trustPolicy)

Reference information

Tags

Dependency managementBuild integrity and provenanceSupplier and open source risk

SDLC phase

DevelopmentReleaseSecurity program

Role

Platform engineers and SREs

ASVS 5.0.0 requirements

v5.0.0-15.1.2 · v5.0.0-15.1.4

Download this guide as Markdown

Continue exploring