references/decision_points contains a mixture of 'references' and 'how-to-guides' per diataxis.fr

[sei-renae]

Context

Per (diataxis.fr/reference](https://diataxis.fr/reference/)

Reference material contains propositional or theoretical knowledge that a user looks to in their work.

The only purpose of a reference guide is to describe, as succinctly as possible, and in an orderly way. Whereas the content of tutorials and how-to guides are led by needs of the user, reference material is led by the product it describes.

Whereas

A how-to guide helps the user get something done, correctly and safely; it guides the user’s action. diataxis.fr/how-to-guide

Issue

In the References>Decision Points section, the 'Gathering Information...' sections have inconsistent header levels and usage of Admonitions boxes. Furthermore, these would be better suited as 'how-to-guides' (HTGs). The following pages contain 'Gathering Information...' sections with varying degrees of what could be a complete HTG:

• Automatable (incomplete HTG)
• Exploitation (complete HTG)
• Mission Impact (suggests a future HTG)
• Safety Impact (incomplete, suggesting future, and stating out of scope HTG)
• System Exposure (complete HTG)
• Technical Impact (shouldn't be a Gathering Info)
• Value Density (incomplete HTG)

Screenshots to show inconsistency

Proposal

Rewrite the above References>Decision Points pages per diataxis.fr/reference and create how-to-guides as a separate section. The how-to-guides can include hyperlinks to the corresponding reference pages.

[ahouseholder]

I like this idea. We don't necessarily have advice on gathering information for every decision point, but for the ones we do, we should put that information into focused How To articles. Since How To articles are geared toward specific users trying to solve a practical problem, it'd make sense to have them written from a practitioner's perspective, which is what the "gathering..." blobs were intended for in the first place.

The reference page probably then just becomes something like:

• (probably needed, but we don't have them consistently yet) a description of what semantic dimension the decision point is intended to describe
• the latest version of the decision point at or near the top of the page/above the fold (automated python include)
• (if appropriate) connecting text to any related decision points (human-written)
• (if appropriate) pointers back to the aforementioned How To guide for that particular decision point (human-written)
• (if appropriate) a list of the previous versions of the decision point (automated python include)

[ahouseholder]

Any solution to this issue should subsume and resolve #537, because #537 is just about reformatting, whereas this one is about moving content around (which will also address consistent formatting in the end)

• #537

Also note that there is relevant commentary in #362 although the consensus there is that these are distinct issues.

• #362

[sei-renae]

@ahouseholder how's this, for the references/decision_point/exploitation page?

# Exploitation

!!! tip inline end

    Learn more about this decision point in the [How-To section](../../howto/gathering_info/exploitation.md).

The intent of this measure is the present state of exploitation of the vulnerability. The intent is not to predict future exploitation but only to acknowledge the current state of affairs. Predictive systems, such as EPSS, could be used to augment this decision or to notify stakeholders of likely changes [@jacobs2021epss].

\```python exec="true" idprefix=""
from ssvc.decision_points.exploitation import LATEST
from ssvc.doc_helpers import example_block

print(example_block(LATEST))
\```

## CWE-IDs for *PoC*

The table below lists CWE-IDs that could be used to mark a vulnerability as *PoC* if the vulnerability is described by the CWE-ID.

!!! example "CWE-295"

    For example, [CWE-295 Improper Certificate Validation
    ](https://cwe.mitre.org/data/definitions/295.html), and its child CWEs,
    describe improper validation of TLS certificates. These CWE-IDs could
    always be marked as *PoC* since that meets condition (3) in the definition.

{% include-markdown "../../_includes/cwe-with-poc-examples.md" heading-offset=1 %}

## Prior Versions

\```python exec="true" idprefix=""
from ssvc.decision_points.exploitation import VERSIONS
from ssvc.doc_helpers import prior_version, example_block

versions = VERSIONS[:-1]
for version in versions:
    print(example_block(version))
    print("\n---\n")
\```

[ahouseholder]

@sei-renae could you ask this question in the form of a PR? That way we can see the diff?

[sei-renae]

@ahouseholder https://github.com/CERTCC/SSVC/pull/792

The pages are not ready; just the PR you requested before I keep going.