Chapter 9 — Communication, ethics and reporting | Professional Application and software supply chain security

Open, free learning for anyone who wants to protect people and technology. No account is required to read this text or its worked answers.

Chapter 9 — Communication, ethics and reporting

Lesson map

Lesson 09 published. Map, example, EX041.

flowchart TD
  N0["Learning outcomes"]
  N1["9.1 Readers"]
  N2["9.2 Structure"]
  N3["9.3 Uncertainty"]
  N4["9.4 Ethics"]
  N5["9.5 External reporting"]
  N6["9.6 Tone"]
  N7["Reporting to managers"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
  N7 --> EX["Worked example"]
  EX --> Q["Exercise EX041"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["9.1 Readers"]
  N2["9.2 Structure"]
  N3["9.3 Uncertainty"]
  N4["9.4 Ethics"]
  N5["9.5 External reporting"]
  N6["9.6 Tone"]
  N7["Reporting to managers"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX041"]

[Learning outcomes]
    |
    v
[9.1 Readers]
    |
    v
[9.2 Structure]
    |
    v
[9.3 Uncertainty]
    |
    v
[9.4 Ethics]
    |
    v
[9.5 External reporting]
    |
    v
[9.6 Tone]
    |
    v
[Reporting to managers]
    |
    v
[Worked example] --> [Exercise EX041]

Learning outcomes

You will (1) write clear findings and reports for different readers; (2) communicate uncertainty; (3) act ethically with information; (4) report externally through proper channels.

9.1 Readers

Developers need precise locations and fixes; managers need risk, cost and decisions; customers need plain explanations of impact. One finding may need three versions. For hl-auth, developers needed the registry setting and the build log; the platform team needed the configuration change; Marcus and the product manager needed the risk, the decision and the cost. Priya writes each version from the same evidence, so they do not contradict each other. Customers would only need an explanation if their data had been affected, which it was not.

9.2 Structure

A finding report: summary, what was found, evidence, impact in TrackPort's context, recommendation, owner and target date. The same structure is used for every finding, so readers know where to look. The summary gives the main point in one or two sentences. Evidence and impact explain why the finding matters for TrackPort specifically. The recommendation, owner and date tell the team what happens next. The TrackPort team found this format easy to act on and asked for it in future scans.

9.3 Uncertainty

Say what is known and unknown: "No harmful content was found in the public hl-auth package; we cannot rule out that it was downloaded by others." Stating what is unknown prevents readers from assuming a problem is fully resolved. For hl-auth, the comparison showed no harmful content, but Harbourline cannot know who else downloaded the public package. Priya writes such sentences carefully, separating evidence from inference, and asks Marcus to check them. Readers can then judge the remaining hl-auth risk for themselves instead of assuming the finding is fully closed.

9.4 Ethics

Findings about other organisations' packages are reported through official channels, never publicised to embarrass. Information about weaknesses is shared only with those who need it. The public hl-auth package was published by mistake, apparently by a former contractor, and reporting it through the registry operator's official process fixed the problem without blame. Publicising it would have exposed Harbourline's mistake and helped nobody. Priya and Marcus share details of unfixed weaknesses only with the teams that need them to act. Any exception, such as sharing details with a vendor's support team, needs Marcus's approval and is recorded with its reason.

9.5 External reporting

Vulnerabilities in open-source dependencies found by Harbourline are reported privately to maintainers following their security policy, with time to fix. Private reporting gives maintainers time to release a fix before details are public. When Priya found a minor flaw in a library TrackPort uses, she reported it following the project's security policy, with a description and a suggested fix. The maintainer released a fix in three weeks, and TrackPort updated within the high target. Marcus approved the report before it was sent, because a disclosure in Harbourline's name affects its relationship with the project's maintainers.

9.6 Tone

Reports describe systems and processes, not individual blame. Blaming individuals discourages people from reporting problems and rarely fixes the cause. The analytics case was a process gap, not a careless reviewer, and the public hl-auth package came from a mistake years ago. Priya writes findings about missing rules, settings and checks, which teams can fix. Marcus reviews reports for tone before they are shared. Where a person's action is relevant, the report describes the action and the missing safeguard, not the person's name.

Reporting to managers

For the product manager, Priya writes one page: the risk in plain terms, what was done, what remains, the cost in developer days, and the decision needed. She avoids jargon such as CVE identifiers unless asked. Decisions come faster when options and their costs are laid out side by side. Over the course, the product manager starts asking for the same format from other teams, and Marcus adopts it for quarterly risk reviews. Priya keeps a small library of example reports, with all names synthetic, for new team members.

Worked example

Priya finds a minor flaw in an open-source library TrackPort uses. Following the project's security policy, she reports it privately with a description and a suggested fix. The maintainer releases a fix in three weeks and credits Harbourline, and TrackPort updates within the high target.

Synthetic case. Events are synthetic.

Errors and limits

Overconfident reports damage trust when facts change; state uncertainty early.

Exercises

EX041 — Report structure. List the finding report sections. Rubric: 3 = summary, finding, evidence, impact, recommendation, owner, date; 2 = four; 1 = two; 0 = none.
EX042 — Readers. What do managers need? Rubric: 3 = risk, cost, decisions; 2 = partial; 1 = vague; 0 = none.
EX043 — Uncertainty. How is uncertainty expressed? Rubric: 3 = state known and unknown; 2 = partial; 1 = vague; 0 = none.
EX044 — External report. How was the library flaw reported? Rubric: 3 = privately per security policy; 2 = partial; 1 = vague; 0 = none.
EX045 — Tone. What should reports avoid? Rubric: 3 = individual blame; 2 = partial; 1 = vague; 0 = none.

Synthesis

Write for the reader, state uncertainty and report responsibly.

Continue studying — chapter 09 of 12

← Chapter 08 (draft) · Course chapter index · Chapter 10 (draft) →