Skip to content

Lesson 1 of 1

Reading a dependency change

Listen to an AI summary of Reading a dependency change

0:00 / 0:33

Code the team did not write

The code in a library runs as part of the application, with the same access to data and files. A vulnerability in a library is in every application that uses the library. Once the vulnerability is on the CVE list of known vulnerabilities, attackers can look for applications that use the library.

What is a package

A package is a library in the form that is downloaded and installed. A registry is a website that stores packages for everyone to download. Each update of a package has a version number, such as 2.1.0.

The example is a sports shop website, and part of the shop is written in JavaScript. npm is a program that downloads JavaScript packages from a registry and installs the packages.

The manifest and the lockfile

A manifest is the file in a project that lists the packages the project asked for. In an npm project the manifest is package.json.

A package can need other packages, and those packages can need more. A project that asks for twelve packages can install several hundred.

A lockfile is the file that records the exact version of every package that will be installed. In an npm project the lockfile is package-lock.json.

  1. The manifest

    package.json asks for 1 package

  2. npm

    finds every package that package needs

  3. The lockfile

    package-lock.json records 40 packages

One package in the manifest can become forty packages in the lockfile.

What is a supply chain attack

A supply chain attack is an attacker putting harmful code into a package that other people install.

One method is a stolen account. The attacker signs in as the person who publishes a popular package, then publishes a new version with harmful code.

Reading the lockfile

The diff of a merge request shows each removed line with a minus sign and each added line with a plus sign. A merge request that adds or updates a package changes the lockfile.

A merge request to the sports shop has the title Update colour-log to 2.1.1. colour-log is a package that adds colour to the messages the shop prints for the team. The picture shows part of the diff of package-lock.json, and the next sections explain each label. The entry for a package starts with node_modules/ and the name of the package.

package-lock.json+8-1

  1. "node_modules/colour-log": {// the package that was updated
  2. - "version": "2.1.0",// the old version, removed
  3. + "version": "2.1.1",// the new version, added
  4. + "resolved": "https://registry.npmjs.org/colour-log/-/colour-log-2.1.1.tgz",// the address the package came from
  5. + "integrity": "sha512-9f1X...",// the integrity hash (sha512 is the kind of hash)
  6. + "hasInstallScript": true,// the package has an install script
  7. },
  8. +"node_modules/node-fetch": {// a new package
  9. + "version": "2.6.1",
  10. + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz",
  11. + "integrity": "sha512-V4aY...",
Part of the diff of the sports shop's lockfile. Some lines are left out.

The version and the address

A version has three numbers. A change to the first number is meant to mark a big update, and the last number a small fix.

The line with resolved gives the URL, the web address, that npm downloaded the package from. registry.npmjs.org is the public npm registry. An address on another website, or an address that starts http:// or git+, means the package did not come from the registry.

The integrity hash

An integrity hash is a hash of a package stored in the lockfile, which shows whether the package has changed. The npm program works out the hash of each downloaded package and refuses a package whose hash does not match the lockfile.

A new version has a new hash. A sha512 hash that changes while the version stays the same is a warning. The registry does not allow a package to change under the same version number. Someone published the package somewhere else, or someone edited the lockfile by hand.

The install script

An install script is a command inside a package that runs on the computer when the package is installed. The line with hasInstallScript shows that version 2.1.1 has an install script.

An install script runs on every computer that installs the package, such as a team member's laptop and the shop's server. The script can do whatever the person who installs the package can do, such as send that person's files to another server. Inside a package, an install script has the name preinstall, install or postinstall.

The new package

The last four lines add node-fetch, a package that the new version of colour-log needs. node-fetch sends requests, messages that ask another server for something.

The title of the merge request describes a small fix and does not mention node-fetch. A package that colours messages has no need for an install script or for requests to other servers. A small fix that adds packages is a stronger warning than a big update that adds packages. A package published from a stolen account can look like this diff.

Package names

Typosquatting is publishing a harmful package under a name a letter or two away from the name of a popular package. lodash is a popular JavaScript package, and a typosquatting package could have the name lodahs. A person who mistypes the name installs the harmful package.

A team can write packages for the team's own use and keep the packages in a private registry. Dependency confusion is publishing a public package with the same name as a private package, so that the wrong package is installed. Some installers look in both registries and fetch the package with the higher version number, which can be the public one.

Examples of defences

  • A lockfile saved in the repository. Every install then uses the same versions and checks each integrity hash.
  • A private registry that is the only place npm looks for the team's own packages.
  • Dependency scanning, which checks each dependency against lists of known vulnerabilities and harmful packages, such as the CVE list.

Examples of what to look for

  • A new node_modules/... entry that the merge request does not explain.
  • A resolved address outside the registry the project uses.
  • An integrity hash that changed while the version stayed the same.
  • A line with hasInstallScript: true, or a new postinstall line.
  • A package name a letter or two away from a well known name.
  • A small fix that adds packages.
  • A manifest change with no lockfile change, so the diff does not show what will be installed.
  • A version changed to one on the CVE list, or left on one when a fix is available.

Check your understanding

  1. State the difference between the manifest and the lockfile.

    Show the answer

    The manifest lists the packages the project asked for. The lockfile records the exact version of every package that will be installed.

  2. Name two signs in the sports shop's diff that the update may be harmful.

    Show the answer

    The install script, and the new package node-fetch, which the merge request does not explain.

  3. Give one reason why a vulnerability in a library matters to every application that uses the library.

    Show the answer

    The code in the library runs as part of each application.

Practise it

Challenges with a weakness this lesson teaches.