Companion document with examples, possibly additional guidance

[zmanion]

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."

[zmanion]

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)

[zmanion]

See #40. Labeling this issue for 4.3.0 to at least cover #40.

[zmanion]

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).

[Santoshkumarpuppala]

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.