Repository navigation
Companion document with examples, possibly additional guidance #34
Description
Activity
And, or, consider a short form version of the rules. And, or, break current rules into separate documents?
- vulnerability determination, CVE ID assignment, Record content (sections 4, 5)
- administrative topics (sections 1, 2, 3)
General concern: The CNA rules are long and complex and growing. CNAs and others need more simple and understandable documentation (pictures, guides, FAQs, checklists, splitting the rules into multiple documents).
Picking this up because I just commented on #40, which I see is tracked here.
On the "examples" half — I can supply a slice of it, for the vulnerability-determination part specifically, which is one of the splits you floated above.
I do open-source vulnerability research and keep a labelled record of every candidate I investigated and then rejected, currently around 550. Each is a decided case: the target, the class it appeared to be, and the specific reason it wasn't assignable. I think that shape fits the constraint you set rather than fighting it — an example says "this was decided this way," where interpretation guidance says "the Rule means this." §4.4 already asks CNAs to use experience and judgment; examples are how judgment gets calibrated, without the Rules themselves having to say more.
One concrete thing they surface. The single most common reason a plausible-looking finding turns out not to be one, in my data by a wide margin, is that the caller was already entitled to the capability — an actor operating inside its intended trust boundary. The nearest rule is 4.1.3, "non-default configuration or runtime changes made by an authorized user," which is a different determination: that's an authorized user changing something, and this is an authorized actor exercising something they already have. I don't think 4.1.3 should necessarily be rewritten — but a reader who only has 4.1.3 will keep arriving at the wrong answer on the common case, and worked examples would close that without a rules change.
On the truth-table format: the reasons cluster tightly enough to tabulate. Roughly half are the entitlement case above; the rest are a small number of repeating shapes — the flaw exists only on main and not in any shipped release; a guard is present, one layer up from where it was expected; a field is settable but no security decision reads it; a sink is real but unreachable through any exposed path; the deployment has no tenancy boundary to cross. Each is a row with real cases behind it.
Two limits I'd rather state than have found. My corpus is skewed — it's mostly web-application authorization in open-source projects, so it would under-represent memory safety, hardware and firmware, and a companion document wants breadth I can't supply alone. And these are my determinations, not a CNA's; they'd need review by someone whose judgement the Program already trusts before they were worth publishing as examples. I've had one of my own findings withdrawn after a maintainer determined the broader access path was intended, so I'd rather over-flag that than have it come up later.
If it's useful I'll put a first slice up as a table and it can be argued with in public. Happy to be told this isn't the shape you're after.
The SPWG briefly discussed the idea of a "guidance" or "examples" document as a companion to the CNA Operational Rules. Would need to take care not to provide a back or side channel to the actual Rules. Examples, possibly including flow charts or truth tables, were preferred over "interpretation guidance."