OpenCyber AcademyLesson map
Lesson 23 published. Map, example, EX067.
flowchart TD
N0["Learning outcomes"]
N1["23.1 Precision and recall"]
N2["23.2 Labelling"]
N3["Lab — check quality"]
N4["23.3 Lab result"]
N5["23.4 Improving"]
N6["23.5 Re-measuring"]
N7["Labelling carefully"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX067"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["23.1 Precision and recall"]
N2["23.2 Labelling"]
N3["Lab — check quality"]
N4["23.3 Lab result"]
N5["23.4 Improving"]
N6["23.5 Re-measuring"]
N7["Labelling carefully"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX067"]
[Learning outcomes]
|
v
[23.1 Precision and recall]
|
v
[23.2 Labelling]
|
v
[Lab — check quality]
|
v
[23.3 Lab result]
|
v
[23.4 Improving]
|
v
[23.5 Re-measuring]
|
v
[Labelling carefully]
|
v
[Worked example] --> [Exercise EX067]
Learning outcomes
You will (1) measure check quality with precision and recall; (2) label a sample; (3) compare checks; (4) improve noisy checks.
23.1 Precision and recall
Precision is the share of a check's alerts that are real; recall is the share of real problems the check finds. A noisy check wastes time; a check with low recall gives false comfort. For Brightwave, both kinds of failure have a real cost in time or risk. The outdated-component check raising many alerts that are not real teaches developers to skim them, and a credential check that misses real keys would leave secrets in repositories without anyone knowing. Measuring both figures shows which problem each check has and what kind of tuning would help.
23.2 Labelling
Diego and another developer independently label a sample of findings as real or not, then discuss disagreements. Labelling independently means neither person sees the other's choice until both are done, so agreement is measured honestly. Disagreements are discussed and the reasons written down, because they usually show that the definition of a real finding is unclear. The month of triaged findings for the two rules in the lab comes from this kind of labelling. The labelled sample is kept so later tuning can be measured on the same items.
Lab — check quality
"""Quality of two scanner rules over a month of triaged synthetic findings."""
rules = {"outdated-component": (48, 30, 2), "hardcoded-credential": (12, 3, 0)}
for r, (flags, real, missed) in rules.items():
print(f"{r:21} flags={flags:3} real={real:2} precision={real / flags:.2f} recall={real / (real + missed):.2f}")
Run with python3 lab_quality.py. Verified output:
outdated-component flags= 48 real=30 precision=0.62 recall=0.94
hardcoded-credential flags= 12 real= 3 precision=0.25 recall=1.00
23.3 Lab result
The outdated-component check has precision 0.62 and recall 0.94: it finds nearly everything but over a third of alerts are not real. The hardcoded-credential check has precision 0.25 and recall 1.00: it finds every real credential but three quarters of its alerts are test strings or examples. Recall depends on knowing what was missed, which comes from the labelled sample rather than from the check itself. For the outdated-component rule, the sample found two real problems the check missed, giving 30 of 32. These figures are estimates from one month's sample, and small samples move a lot with a few changed labels.
23.4 Improving
The credential check gets an allow list for clearly synthetic test values, reviewed by Aiko; the outdated check ignores libraries used only in development. Both changes target the false alerts without narrowing what counts as real. The allow list covers only values that are clearly synthetic, and Aiko reviews each entry so it cannot become a hiding place for a real key. Development-only libraries never reach a client's running site, which is why the outdated check can safely set them aside. Each change is recorded with its reason and the date.
23.5 Re-measuring
After changes, the same labelled sample is rerun to confirm recall did not fall. Rerunning on the same labelled items isolates the effect of the change, because nothing else about the sample differs. If recall falls, the change has hidden real problems and is reworked even if precision improved. After the credential check's tuning, a fresh sample is also labelled to check that the improvement holds on new data, giving precision 0.70 with recall still 1.00. Reporting the sample size with each figure keeps readers from trusting small changes too much.
Labelling carefully
Two labellers working independently make it possible to see how often they agree. Where they disagree, the reason is written down, because disagreements often show that the definition of a real problem is unclear. For the credential check, the team agrees that a real credential is any value that would work against a live system, while expired or example values are not. Writing this definition down raised agreement in the next sample. The labelled samples are kept, so future changes to a check can be measured on the same items.
Worked example
After tuning, the credential check's precision rises to 0.70 on a fresh sample with recall still 1.00, and developers stop ignoring its alerts.
Synthetic case. Samples and figures are synthetic.
Errors and limits
A small labelled sample gives rough estimates; report the sample size.
Exercises
- EX067 — Definitions. Define precision and recall.
Show marking criteria
Rubric: 3 = share of alerts real; share of problems found; 2 = one; 1 = vague; 0 = none. - EX068 — Lab figures. What were the lab figures?
Show marking criteria
Rubric: 3 = outdated 0.62/0.94; credential 0.25/1.00; 2 = one; 1 = vague; 0 = none. - EX069 — Re-measure. Why re-run the sample after tuning?
Show marking criteria
Rubric: 3 = check recall did not fall; 2 = partial; 1 = vague; 0 = none.
Synthesis
Measure checks and tune them without losing recall.
Continue studying — chapter 23 of 30
← Chapter 22 (draft) · Course chapter index · Chapter 24 (draft) →