Chapter 4 — Application and software supply chain security: core methods
Lesson map
Lesson 04 published. Map, example, EX016.
flowchart TD
N0["Learning outcomes"]
N1["4.1 Dependency sources"]
N2["Lab — dependency sources"]
N3["4.2 Lab result"]
N4["4.3 Similar names"]
N5["4.4 Source controls"]
N6["4.5 Reviewing new dependencies"]
N7["Proxy registry"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX016"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["4.1 Dependency sources"]
N2["Lab — dependency sources"]
N3["4.2 Lab result"]
N4["4.3 Similar names"]
N5["4.4 Source controls"]
N6["4.5 Reviewing new dependencies"]
N7["Proxy registry"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX016"]
[Learning outcomes]
|
v
[4.1 Dependency sources]
|
v
[Lab — dependency sources]
|
v
[4.2 Lab result]
|
v
[4.3 Similar names]
|
v
[4.4 Source controls]
|
v
[4.5 Reviewing new dependencies]
|
v
[Proxy registry]
|
v
[Worked example] --> [Exercise EX016]
Learning outcomes
You will (1) check where each dependency is resolved from; (2) identify names close to popular packages; (3) apply source controls in the build; (4) review new dependencies.
4.1 Dependency sources
Every dependency should come from an intended source: internal packages from the internal registry, public packages from the public registry through a controlled proxy. A rule that internal name prefixes may only resolve internally prevents the hl-auth problem. A controlled proxy lets Harbourline record which public packages are used and block ones it does not want. The internal-prefix rule works because internal packages share a recognisable name prefix, so the build service can refuse to fetch them from anywhere else. With the rule in place, hl-auth could not have been taken from the public registry.
Lab — dependency sources
"""Check synthetic dependency sources and flag names close to well-known packages (stdlib only)."""
import difflib
internal_prefix = "hl-"
popular = ["requests-lite", "dateparse", "yamlkit", "httpwire"]
deps = [ # name, resolved source
("hl-geo", "internal"), ("hl-auth", "public"), ("dateparse", "public"),
("yamkit", "public"), ("httpwire", "public"), ("hl-ledger", "internal"),
]
for name, src in deps:
notes = []
if name.startswith(internal_prefix) and src != "internal":
notes.append("internal name resolved from PUBLIC registry")
close = [p for p in difflib.get_close_matches(name, popular, n=1, cutoff=0.8) if p != name]
if close:
notes.append(f"name close to '{close[0]}' - confirm intended")
print(f"{name:10} {src:8} {'; '.join(notes) or 'ok'}")
Run with python3 lab_sources.py. Verified output:
hl-geo internal ok
hl-auth public internal name resolved from PUBLIC registry
dateparse public ok
yamkit public name close to 'yamlkit' - confirm intended
httpwire public ok
hl-ledger internal ok
4.2 Lab result
hl-geo and hl-ledger resolve internally (ok). hl-auth is flagged: internal name resolved from PUBLIC registry. yamkit is flagged as close to the popular yamlkit, to confirm it was intended. dateparse and httpwire are ok. The close-name check uses Python's difflib and is only a prompt for a person to check. The lab confirms what the build review found and adds one more question about yamkit. A flag from difflib does not mean a package is harmful; it only asks a person to confirm the name was intended. Priya checks both flagged items with the TrackPort team before recording a decision. Yamkit later turned out to be a typing mistake for yamlkit, which the team replaced.
4.3 Similar names
Packages with names similar to popular ones can be installed by mistake. Ohm et al. (2020) describe how such names have been used to spread harmful packages. Reviewers confirm the intended name before approving a new dependency. At Harbourline, the yamkit flag showed how easily a similar name can slip in: a developer typed one letter wrong and nobody noticed during review. The package was unmaintained but harmless. After it was replaced, Priya added "confirm exact name" to the dependency review note, so reviewers check the name against the intended package's official page.
4.4 Source controls
The build service is configured so that internal prefixes resolve only from the internal registry, lock files pin versions with hashes, and builds fail on a hash mismatch. Each control closes a different gap. The prefix rule stops internal names resolving publicly. Pinned versions with hashes mean a build uses the exact package that was reviewed. Failing on a hash mismatch stops a build if a package has changed since it was pinned. The platform team applies these settings in the build service for all teams, and Priya checks them with safe tests using synthetic packages.
4.5 Reviewing new dependencies
A new dependency requires a short note: purpose, maintainer activity, licence and source. The note gives reviewers what they need to decide quickly. Purpose shows whether the package is needed or duplicates something already used. Maintainer activity shows whether it is likely to receive fixes. Licence shows whether Harbourline may use it. Source shows where it comes from. After yamkit, the note also asks the author to confirm the exact name. Reviewers check the note before approving the pull request that adds the dependency.
Proxy registry
Public packages are fetched through the platform team's proxy, which records every package downloaded. The record lets Harbourline answer which builds used a package if an advisory or harmful version is announced later.
Worked example
The yamkit flag turns out to be a real mistake: a developer meant yamlkit. yamkit is a small, unmaintained package with no harmful content found, but it is replaced, and the dependency review note now includes "confirm exact name".
Synthetic case. Package names and results are synthetic.
Errors and limits
Similar-name checks produce false alarms; they guide review, not decisions.
Exercises
- EX016 — Lab flags. Which dependencies did the lab flag? Rubric: 3 = hl-auth public; yamkit close to yamlkit; 2 = one; 1 = vague; 0 = none.
- EX017 — Prefix rule. What rule prevents the hl-auth problem? Rubric: 3 = internal prefixes only from internal registry; 2 = partial; 1 = vague; 0 = none.
- EX018 — Build failure. When does the build fail? Rubric: 3 = hash mismatch; 2 = partial; 1 = vague; 0 = none.
- EX019 — yamkit outcome. What was yamkit? Rubric: 3 = mistaken name for yamlkit; replaced; 2 = partial; 1 = vague; 0 = none.
- EX020 — Review note. What does a new dependency note contain? Rubric: 3 = purpose, maintainers, licence, source, exact name; 2 = three; 1 = one; 0 = none.
Synthesis
Control sources, pin hashes and review names.
Continue studying — chapter 04 of 12
← Chapter 03 (draft) · Course chapter index · Chapter 05 (draft) →