Dependencies and supply-chain security

Almost every app you build is mostly code you did not write. A small React project can pull in hundreds of packages once you count the dependencies of your dependencies. Each one is code that runs on your laptop, your build server or your users' browsers. A flaw in any of them, or a malicious package that looks harmless, becomes your problem. This is the software supply chain.

In this tutorial you will learn how supply-chain attacks happen, then practise the habits that reduce the risk: auditing, lockfiles, pinning, automated updates and a quick review before adding a new package. Prerequisites: Node.js and npm installed, or Python with pip, and an existing project folder (the Brew & Bean website or API will do). Everything here is done on your own projects.

A CVE (Common Vulnerabilities and Exposures) is a public ID, like CVE-2021-44228, for one known vulnerability. Tools compare the exact versions in your project with databases of CVEs and tell you which ones you use.

Direct dependencies are the ones you chose. Transitive dependencies are what those packages need. Vulnerabilities often hide in the transitive ones, so look at the whole tree first.

# Node: list the dependency tree (2 levels deep)
npm ls --depth=2

# Why is a package in my project?
npm explain lodash

# Python: list installed packages
pip list

# Python: tree view (install once)
pip install pipdeptree
pipdeptree

npm explain shows which of your dependencies pulled a package in. pipdeptree prints Python packages as a tree.

# Node: check against the npm advisory database
npm audit

# Only show serious ones
npm audit --audit-level=high

# Python: install and run pip-audit on your requirements file
pip install pip-audit
pip-audit -r requirements.txt

npm audit ships with npm. pip-audit checks your Python packages against known advisories.

Read each finding. Ask three questions: Is the vulnerable code actually reachable in my app? Is there a fixed version? Does the fix break my app? A vulnerability in a build-only tool is less urgent than one in code that handles user input on your server.

# Apply fixes that do not need a major version change
npm audit fix

# Then run your tests and the app before committing
npm test

npm audit fix updates to a safe version where it can. Avoid --force unless you have read what it will upgrade, because it may install breaking major versions.

A lockfile (package-lock.json, poetry.lock, uv.lock, or a pinned requirements.txt) records the exact version of every package, including transitive ones. Without it, npm install may fetch a newer version tomorrow than it did today, so a surprise release can reach your production build.

Rules: commit the lockfile to Git, and in CI and production builds install from it exactly.

# Node: install exactly what the lockfile says
# (fails if package.json and the lockfile disagree)
npm ci

# Python: freeze the exact versions you have tested
pip freeze > requirements.txt

npm ci never rewrites the lockfile and is made for CI. pip freeze writes lines like fastapi==0.115.0 for every installed package.

For Python you can go one step further with hash checking. Each package file gets a fingerprint, and pip refuses a file whose hash differs. The pip-tools package generates the hashes for you.

pip install pip-tools

# requirements.in holds only your direct dependencies, one per line (for example fastapi)
pip-compile --generate-hashes requirements.in -o requirements.txt

# Install and verify hashes
pip install --require-hashes -r requirements.txt

requirements.txt now lists every package (including transitive ones) with --hash=sha256:... lines. If a package file is swapped, the install fails.

I am about to add the npm package [package-name] to a [type of project, e.g. React website]. I only need it for [what you need]. Help me decide whether to add it. Tell me what to check on npmjs.com and GitHub (maintainers, last release, open security issues, download trend, install scripts, number of its own dependencies), and suggest whether I could do this with the standard library or a few lines of my own code instead. Do not claim facts about the package that you cannot know; tell me what to verify myself.

What to expect: A good answer gives a checklist you then follow yourself. Treat any claim about a specific package as unverified until you check the registry page.

# See metadata without installing anything
npm view express version maintainers dependencies
npm view express scripts

# Install without running install scripts (a safer first look at an unknown package)
npm install some-package --ignore-scripts

npm view only reads the registry. --ignore-scripts stops preinstall and postinstall scripts from running. Some legitimate packages need them, so use it for a first look, not blindly everywhere.

AI coding assistants add a new twist: they sometimes suggest package names that do not exist. An attacker can register such a name and wait for someone to install it. Always confirm that a package an AI suggests exists, is the popular one, and does what you asked. More on this in *AI security: prompt injection, data leaks and model risks*.

Doing this by hand once is good. Doing it automatically is better. On GitHub, Dependabot opens pull requests when a dependency has a new version or a security fix. Create this file in your repository:

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Dependabot checks weekly and opens pull requests. Keep only the ecosystems your repository really uses. Your tests in CI then show whether each update is safe to merge.

name: audit
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm audit --audit-level=high

Fails the build when a high or critical known vulnerability exists. It installs from the lockfile with npm ci so CI tests the same versions you ship.

An SBOM (Software Bill of Materials) is a list of every component in your software with versions, like the ingredients list on a food packet. When a new vulnerability is announced, companies with SBOMs can answer "are we affected?" in minutes instead of days. Common formats are SPDX and CycloneDX. Tools such as Trivy can generate one; you will try Trivy in *Security testing tools: ZAP, Semgrep and Trivy*. You do not need an SBOM for a college project, but you should know the word because customers and large employers often ask for them.