Dependency security: before you start

Use this short introduction before Exercise 01. Return to it in Exercises 02–03 if needed. Allow 15–20 minutes for reading and discussion. You need basic JavaScript and enough terminal familiarity to run supplied commands; you do not need prior security-scanner experience.

1. What is the supplied app?

It counts fictional course registrations and constructs a report URL. It does not send a web request. You will maintain this existing application, not build it from scratch.

• src/app.mjs is the application code. lodash.countBy counts registrations by course; axios.getUri constructs a URL without sending it.
• test/app.test.mjs contains checks of that behavior. node --test runs them; four should pass before and after a successful repair.
• sample-data/registrations.json supplies the fictional input. The app should report Security: 2, Web: 1 and a URL at example.invalid.

A dependency is another package of code the app uses. A package manager downloads packages and records their versions. Your instructor selects one track (npm, pnpm, Yarn or Bun), not all five.

2. Which files describe the dependencies?

Term	Plain-language meaning	Find it here
Manifest	The app's declared package requirements and settings.	package.json; see dependencies.
Lockfile	The package manager's record of the resolved versions, including packages required by other packages.	package-lock.json, pnpm-lock.yaml, yarn.lock or bun.lock, depending on your track.
Direct dependency	A package the app declares itself.	axios and lodash in package.json.
Transitive dependency	A package required by another dependency.	axios requires follow-redirects in the starter.
Dependency tree / graph	A map of those relationships.	The tree command in your manager setup guide.
Diff	A comparison showing what changed between two file versions.	Your editor's file comparison or Git diff.

Read app → axios → follow-redirects as “our app needs axios, and axios needs follow-redirects.” Being transitive does not itself mean vulnerable, safe or unused.

The manager updates the manifest and lockfile together. Do not hand-edit the lockfile or delete it to make a warning disappear. A frozen/immutable install uses the supplied lockfile without silently changing its resolved versions. Lifecycle scripts are code packages may run during installation; the sample commands disable them for safety. Scanner installation is separate and may require its own install scripts, so instructors should prepare it before class.

3. Read one scan report, not every field at once

JSON is a structured text format: names on the left of a colon label the values on the right. Braces group fields; square brackets contain lists. Open the scanner's timestamped .json file in your editor, not in a terminal as a command. Search for the field names below.

This is a shortened historical excerpt from the supplied npm starter report, not a current scan or a complete file to feed into a gate:

{
  "status": "ok",
  "complete": true,
  "packageCount": 3,
  "findingCount": 2,
  "findings": [
    {
      "package": "axios",
      "version": "0.21.1",
      "severity": "high",
      "relationship": "direct",
      "dependencyPaths": [["project", "axios"]],
      "vulnerabilities": [{"id": "GHSA-cph5-m8f7-6c5x"}]
    }
  ]
}

Field	What to record or ask
status / complete	Did the scan finish successfully? Incomplete data is not a clean result.
packageCount	How many package entries were scanned?
findingCount	How many package findings were reported? One package can have several advisories. The excerpt shows only one of the original two findings.
package / version	Which installed/resolved package version matched an advisory?
severity	Reported seriousness; not proof the example app can be exploited.
relationship / dependencyPaths	Is it direct or transitive? How does it relate to this app?
vulnerabilities[].id	An advisory identifier to investigate. [] means look inside each list item, not a literal field name to search for.

Ignore optional scoring and prioritization fields for the beginner task. Locate one package finding first, then its advisory. An advisory describes a reported vulnerability, affected versions and any known fix. A GHSA identifier names a GitHub advisory; a CVE identifier may name the same underlying vulnerability in another system. They are not additional vulnerable packages to count.

For this example, the ID forms this URL: https://github.com/advisories/GHSA-cph5-m8f7-6c5x . For your task, use the exact ID in your report. Read the affected version range and the vulnerable behavior. Compare that behavior with what our small app actually does. A version match is evidence to investigate and remediate; it does not show an exploit occurred in this app.

4. Choose and verify a repair

The report's suggestedFixCommands describes a combined proposed update. Each finding may also contain a runnableFixCommand. These are suggestions to review, not commands to execute blindly. Use your track's script-disabled change syntax, not an unrelated manager command copied from somewhere else.

Version labels commonly use major.minor.patch (for example, 1.2.3). A major upgrade, such as 1.x to 2.x, may change how callers must use the package. Even a smaller version change can affect behavior; a project on 0.x also deserves care. Compatibility means the updated package still works for the app's needs. Read release/advisory notes and test rather than assuming that a larger number solves everything.

Before editing:

1. Save copies of the current manifest, lockfile and scan report in a separate evidence folder.
2. Find the package, current version, proposed target and advisory evidence.
3. Explain why the target addresses the finding and what might change. Ask the instructor to review your proposed command. For self-study, write down your reasoning first.
4. Apply the selected manager's command from its setup guide. It updates the files; you do not need to edit JSON by hand.
5. Compare the saved files with the updated files. Note changed direct versions and related transitive versions. A larger graph after an upgrade is not automatically wrong; explain it.
6. Run the four application tests, run the app and rescan. Keep before/after results. Do not report success if scanning failed.

The supplied reference solution is one tested migration, not the only valid answer. A live report may recommend different versions or find newly reported issues. Passing four functional tests and seeing no known findings does not prove universal compatibility or security.

5. Check your understanding

Before the worksheet, explain to a partner or instructor:

1. Why can this app pass its tests and still contain a vulnerable dependency?
2. In app → axios → follow-redirects, which dependency is transitive?
3. If one package has four advisory IDs, does that necessarily mean four vulnerable packages?
4. What should you do if complete is false?

If these are unclear, pause and ask for help. Exercises 02–03 assume you can already interpret a finding, propose a reviewed version change and verify it.

Reference-report fallback

In a student kit, reference-reports/before.json, after.json and provenance.json are historical artifacts for your selected manager. In the full repository they are under the selected track's reports folder (before/scan.json, after/scan.json, provenance.json). They are not fresh results from your computer. If live scanning is unavailable, label your work supplied-report analysis, explain the artifacts and describe unexecuted checks as proposed, not completed.