Chapter 29 — Capstone build
Lesson map
Lesson 29 published. Map, example, EX085.
flowchart TD
N0["Learning outcomes"]
N1["29.1 Choosing the capstone"]
N2["29.2 Design"]
N3["29.3 Using SBOMs"]
N4["29.4 Testing"]
N5["29.5 Documentation"]
N6["SBOM format"]
N7["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX085"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["29.1 Choosing the capstone"]
N2["29.2 Design"]
N3["29.3 Using SBOMs"]
N4["29.4 Testing"]
N5["29.5 Documentation"]
N6["SBOM format"]
N7["Synthesis"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX085"]
[Learning outcomes]
|
v
[29.1 Choosing the capstone]
|
v
[29.2 Design]
|
v
[29.3 Using SBOMs]
|
v
[29.4 Testing]
|
v
[29.5 Documentation]
|
v
[SBOM format]
|
v
[Synthesis]
|
v
[Worked example] --> [Exercise EX085]
Learning outcomes
You will (1) design and build a capstone improvement; (2) apply the course methods; (3) test with synthetic data; (4) document it.
29.1 Choosing the capstone
Diego's capstone is a software bill of materials (SBOM) for each client release, listing every component and version. NTIA (2021) describes the minimum elements: supplier, component name, version, unique identifier, dependency relationship, author of the data and timestamp. An SBOM extends the inventory from what runs now to what each release contained. Diego chooses it because clients have begun asking for component lists and because it closes a gap the inventory leaves. The NTIA minimum elements give a clear checklist for what each SBOM must contain, so the capstone can be tested against it.
29.2 Design
The build creates the SBOM from the lock file, attaches it to the release record next to the image digest, and stores it with the deployment record. Clients can request their SBOM. Generating the SBOM from the lockfile keeps it consistent with what the build actually installed. Storing it next to the image digest links each component list to an exact release. A client asking for their SBOM receives the one matching the release running on their site. The SBOM is regenerated only when a release is built, not on every test run.
29.3 Using SBOMs
With SBOMs per release, the inventory can answer not only "who uses this library now" but "which past release contained it", which helps when clients ask about past exposure. Without SBOMs, answering a question about past exposure means rebuilding old lockfiles from repository history, which is slow and easy to get wrong. With them, Brightwave can search stored component lists for any release. This matters when a client asks whether an older release they ran last year contained a library named in a new advisory.
29.4 Testing
Tests check that every library in the lock file appears in the SBOM and that the SBOM matches the deployed digest. Both tests run in the build, so a missing component or a mismatch fails the release before it is deployed. Diego also checks by hand that one small project's SBOM matches its lockfile. The hand check catches a formatting issue in version strings that the automated tests had not been written to detect. After that fix, the tests are trusted for the remaining projects, and a deliberately broken synthetic lockfile is used to show that a missing component really fails the build.
29.5 Documentation
A runbook explains how SBOMs are created, where they are stored and how to answer a client request. The runbook names the owner and explains how to find a past release's SBOM by date or digest. It also covers what to send a client and how to record that a request was answered. The runbook was followed once by another developer before the capstone was submitted, using a synthetic client request. It also lists the common failures seen while testing the SBOM build, with their fixes.
29.6 Scope limits
The capstone does not attempt signing SBOMs; that is noted as future work linked to the SLSA L3 goal. Keeping the scope small lets the capstone finish properly and be tested on real Brightwave projects. Signing would need the provenance and key handling planned for the SLSA L3 goal, which is not yet in place. Naming the limit openly lets the assessors judge the capstone for what it does rather than for what it might later become. The unsigned state is stated plainly in the runbook and in each client response.
SBOM format
Diego chooses a widely supported standard SBOM format so clients' own tools can read it, and keeps one SBOM per release rather than per build attempt. Each SBOM records the generating tool and version, so later differences can be explained. He compares a generated SBOM with the lock file by hand for one small project before trusting the automated tests, which confirms the test logic and catches a formatting issue in version strings.
Worked example
Diego tests the SBOM build on three client projects. One reveals a library bundled directly into code instead of through the lock file, invisible to the inventory until now. It is moved into the lock file so it is tracked like everything else.
Synthetic case. The capstone is synthetic.
Errors and limits
An SBOM lists components; it does not say whether they are safe.
Exercises
- EX085 — NTIA elements. Name four NTIA minimum elements. Rubric: 3 = supplier, name, version, identifier, relationship, author, timestamp; 2 = two; 1 = one; 0 = none.
- EX086 — New question. What new question can SBOMs answer? Rubric: 3 = which past release had a library; 2 = partial; 1 = vague; 0 = none.
- EX087 — Hidden library. What did testing reveal? Rubric: 3 = library bundled outside lock file; 2 = partial; 1 = vague; 0 = none.
Synthesis
SBOMs extend the inventory to every release.
Continue studying — chapter 29 of 30
← Chapter 28 (draft) · Course chapter index · Chapter 30 (draft) →