Chapter 45 — Independent design review
Lesson map
Lesson 45 published. Map, example, EX133.
flowchart TD
N0["Learning outcomes"]
N1["45.1 Preparing"]
N2["45.2 Reviewers"]
N3["45.3 Findings"]
N4["45.4 Responses"]
N5["45.5 Traceability"]
N6["45.6 Value"]
N7["Review meeting"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX133"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["45.1 Preparing"]
N2["45.2 Reviewers"]
N3["45.3 Findings"]
N4["45.4 Responses"]
N5["45.5 Traceability"]
N6["45.6 Value"]
N7["Review meeting"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX133"]
[Learning outcomes]
|
v
[45.1 Preparing]
|
v
[45.2 Reviewers]
|
v
[45.3 Findings]
|
v
[45.4 Responses]
|
v
[45.5 Traceability]
|
v
[45.6 Value]
|
v
[Review meeting]
|
v
[Worked example] --> [Exercise EX133]
Learning outcomes
You will (1) prepare a design for independent review; (2) receive and respond to critique; (3) distinguish major from minor issues; (4) update the design with traceable changes.
45.1 Preparing
Kwame prepares a design document: purpose, requirements, architecture, data flows, threat model (STRIDE), controls and test plan.
A complete document lets reviewers judge the design without needing Kwame present. The threat model shows which risks he considered, so reviewers can focus on what he missed. The test plan shows how each requirement will be checked. He sends the document a week before the meeting, giving reviewers time to read it carefully. A short cover note lists the parts he is least sure of.
45.2 Reviewers
A Coastline security engineer, an external engineer from another transit agency and a course tutor review it.
Each reviewer brings a different view. The Coastline engineer knows the systems and constraints; the external engineer brings experience from another organisation and no attachment to Coastline's choices; the tutor checks the engineering method and the academic standard. Together they cover technical detail, outside perspective and rigour. Reviewers receive the design document a week ahead with a short list of questions Kwame is unsure about.
45.3 Findings
Major: the verification service itself holds credentials to the app store API; if compromised, it could hide mismatches. Minor: logging retention unspecified; alert channel single point of failure.
The major finding matters because a verifier that attackers can silence is worse than none: it gives false assurance. Minor findings would not break the design but leave gaps. Without a retention period, logs might be deleted before an investigation needs them or kept longer than necessary. With a single alert channel, one outage could hide every mismatch. Sorting findings by severity tells Kwame what must be resolved before building starts and what can be fixed alongside it.
45.4 Responses
For the major issue, credentials are read-only and alerts are also sent to a separate system the service cannot modify. Minor issues are fixed with specific values and a second alert channel.
Read-only credentials mean that even a compromised verifier cannot change app store releases. Sending alerts to a separate system means a compromised verifier could fail to raise an alert but could not delete one already sent, and a missing daily heartbeat from the verifier itself raises an alarm.
45.5 Traceability
Every review comment links to the design change it caused, or a reason for no change.
The link lets reviewers check that their comments were handled and see the reasoning when a suggestion was declined. A comment with no response is treated as unresolved. The table also helps future maintainers understand why the design looks as it does, so they do not undo a change made for a good reason. Kwame keeps it in the repository alongside the design document, versioned with each revision, so the history of decisions travels with the code and survives after he leaves.
45.6 Value
Independent reviewers see assumptions the author cannot.
Authors know what they meant, so they read their documents as they intended them, not as written. Kwame had not seen that the verifier's own credentials were a target, because he thought of it as a defender. A reviewer with no part in the design asked what an attacker would do with the verifier, and the major finding followed. The cost was two hours of meeting time and a week of revisions, far less than fixing the flaw after the service was running. Kwame now builds review time into every project plan.
Review meeting
The review takes two hours. Kwame presents for fifteen minutes, then reviewers discuss each section. He listens and records comments without arguing, asking only clarifying questions. Afterwards he sorts comments into major and minor, writes responses and circulates them within a week. Reviewers confirm the major issue is resolved before the build starts.
Second round
After changes, two reviewers read the updated design and confirm their comments are addressed. The external reviewer adds one new question about how the verifier itself is updated; Kwame answers that it goes through the same pipeline, with signing and provenance checks, as any Coastline service.
Lessons
Kwame notes that writing the threat model before review saved time.
Worked example
The external engineer suggests sharing the verification approach with other transit agencies using the same app vendor. Coastline agrees to publish a summary after the capstone.
Synthetic case. Reviews are synthetic.
Errors and limits
Reviewers may disagree; the designer must weigh comments and justify choices.
Exercises
- EX133 — Major finding. What was the major finding? Rubric: 3 = verifier credentials; compromise could hide mismatches; 2 = partial; 1 = vague; 0 = none.
- EX134 — Major fix. How was the major finding addressed? Rubric: 3 = read-only credentials; alerts to separate system; 2 = partial; 1 = vague; 0 = none.
- EX135 — Traceability. How are review comments tracked? Rubric: 3 = linked to change or reason; 2 = partial; 1 = vague; 0 = none.
Synthesis
Independent review finds what authors miss; respond traceably.
Continue studying — chapter 45 of 50
← Chapter 44 (draft) · Course chapter index · Chapter 46 (draft) →