From 719b061e855d277d9b13a13e447f8fb819069c89 Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Thu, 30 Nov 2023 10:32:44 -0500 Subject: [PATCH] Markdownlint cli2 (#32) * improve markdown lint config for emphasis and strong * Run markdownlint on content markdownlint-cli2 --config .markdownlint-cli2.yaml --fix "**/*.md" "#node_modules" --- .markdownlint-cli2.yaml | 4 + README.md | 16 +-- docs/howto/case_object.md | 2 +- docs/howto/em_icalendar.md | 24 ++-- docs/howto/process_implementation.md | 32 ++--- docs/reference/formal_protocol/conclusion.md | 2 +- docs/reference/formal_protocol/index.md | 6 +- docs/reference/formal_protocol/states.md | 16 +-- docs/reference/iso_30111_2019.md | 2 +- docs/reference/iso_5895_2022.md | 2 +- docs/reference/ssvc_crosswalk.md | 104 +++++++-------- docs/topics/background/notation.md | 2 +- docs/topics/behavior_logic/msg_cs_bt.md | 34 ++--- docs/topics/behavior_logic/msg_em_bt.md | 36 +++--- docs/topics/behavior_logic/msg_other_bt.md | 8 +- docs/topics/behavior_logic/msg_rm_bt.md | 16 +-- docs/topics/formal_protocol/worked_example.md | 42 +++--- docs/topics/future_work/cvd_directory.md | 6 +- docs/topics/future_work/ontology.md | 2 +- docs/topics/process_models/cs/index.md | 54 ++++---- .../process_models/em/working_with_others.md | 16 +-- .../model_interactions/index.md | 8 +- .../model_interactions/rm_em_cs.md | 14 +- docs/topics/process_models/rm/index.md | 122 +++++++++--------- .../process_models/rm/rm_interactions.md | 14 +- docs/topics/user_stories/index.md | 12 +- 26 files changed, 300 insertions(+), 296 deletions(-) diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index a13b06dc..0f792f09 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -3,4 +3,8 @@ config: "MD033": false "MD041": false "MD046": false + "MD049": + style: "asterisk" + "MD050": + style: "asterisk" "MD051": false diff --git a/README.md b/README.md index c2446afd..f299cc92 100644 --- a/README.md +++ b/README.md @@ -36,13 +36,13 @@ More recently, the CERT/CC has been working towards formalizing this knowledge i This work began with [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure (MPCVD)](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513), which also appeared in an abridged form as [Are We Skillful or Just Lucky? Interpreting the Possible Histories of Vulnerability Disclosures](https://dl.acm.org/doi/10.1145/3477431) -in the ACM Journal _Digital Threats: Research and Practice_. +in the ACM Journal *Digital Threats: Research and Practice*. In 2022, we published a collection of [Coordinated Vulnerability Disclosure User Stories](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=886543) derived from both our process modeling work and from the experience of building VINCE. That same year, we published [Designing Vultron: A Protocol for Multi-Party Coordinated Vulnerability Disclosure (MPCVD)](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=887198), which serves as the basis for the work contained in this repository. -## So what _is_ Vultron? +## So what *is* Vultron? Vultron is: @@ -62,16 +62,16 @@ Currently, the work is focused on mapping the formal protocol onto the syntax an protocol. Examples of our first steps in that direction can be found in [doc/examples](doc/examples) -## What is Vultron _not_? +## What is Vultron *not*? Vultron is **not** a drop-in replacement for any particular -- _tracking system_—e.g., [Bugzilla](https://www.bugzilla.org/), [Jira](https://www.atlassian.com/software/jira) -- _CVD or threat coordination tool_—e.g., [VINCE](https://github.com/CERTCC/VINCE), [MISP](https://www.misp-project.org/) -- _Vulnerability disclosure program_—e.g., [DC3 VDP](https://www.dc3.mil/Missions/Vulnerability-Disclosure/Vulnerability-Disclosure-Program-VDP/) -- _Vulnerability disclosure platform or service_—e.g., [HackerOne](https://hackerone.com/), [Bugcrowd](https://www.bugcrowd.com/), [Synack](https://www.synack.com/) +- *tracking system*—e.g., [Bugzilla](https://www.bugzilla.org/), [Jira](https://www.atlassian.com/software/jira) +- *CVD or threat coordination tool*—e.g., [VINCE](https://github.com/CERTCC/VINCE), [MISP](https://www.misp-project.org/) +- *Vulnerability disclosure program*—e.g., [DC3 VDP](https://www.dc3.mil/Missions/Vulnerability-Disclosure/Vulnerability-Disclosure-Program-VDP/) +- *Vulnerability disclosure platform or service*—e.g., [HackerOne](https://hackerone.com/), [Bugcrowd](https://www.bugcrowd.com/), [Synack](https://www.synack.com/) -Instead, it is our hope that Vultron could serve as a _lingua franca_ for the exchange of vulnerability case coordination information +Instead, it is our hope that Vultron could serve as a *lingua franca* for the exchange of vulnerability case coordination information between those systems and services. Vultron is not a vulnerability priortization tool, although it is intended to be compatible with common diff --git a/docs/howto/case_object.md b/docs/howto/case_object.md index 3cf79e50..83b38334 100644 --- a/docs/howto/case_object.md +++ b/docs/howto/case_object.md @@ -152,7 +152,7 @@ Here, we highlight the minimum requirements that the protocol demands: - Each `Message` has an identified sender (who is a `Participant` in the case) and one or more message types as enumerated in [Message Types](../reference/formal_protocol/messages.md). - Message types are represented as flags since a single actual message might represent multiple message types. -- For example, a report submission that includes an embargo proposal might have both the _RS_ and _EP_ message type flags set. +- For example, a report submission that includes an embargo proposal might have both the *RS* and *EP* message type flags set. Conceptually, one might think of the `Case` as a shared object among engaged `Participants` and that `Messages` are sent to the `Case` for all `Participants` to see. diff --git a/docs/howto/em_icalendar.md b/docs/howto/em_icalendar.md index 796b817d..01eb6a79 100644 --- a/docs/howto/em_icalendar.md +++ b/docs/howto/em_icalendar.md @@ -23,15 +23,15 @@ A mapping of EM concepts to `iCalendar` field mappings is provided in the table | Embargo ID | `SUMMARY: embargo expiration` | - | | Embargo End Time and Date | `DSTART = DTEND` (0 duration event) | - | | Proposer | `ORGANIZER` | - | -| Participant (proposed) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=NEEDS-ACTION` | _EP_, _EV_ | -| Participant (acknowledge without acceptance) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=TENTATIVE` | _EK_ | -| Participant (accept) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=ACCEPTED` | _EA_, _EC_ | -| Participant (reject) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=DECLINED` | _ER_, _EJ_ | +| Participant (proposed) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=NEEDS-ACTION` | *EP*, *EV* | +| Participant (acknowledge without acceptance) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=TENTATIVE` | *EK* | +| Participant (accept) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=ACCEPTED` | *EA*, *EC* | +| Participant (reject) | `ATTENDEE;`
`ROLE=OPT-PARTICIPANT;`
`PARTSTAT=DECLINED` | *ER*, *EJ* | | Details (link to case trackers, etc.) | `DESCRIPTION` | - | -| Embargo Status $q^{em} \in P$ | `STATUS:TENTATIVE` | _EP_ | -| Embargo Status $q^{em} \in A$ | `STATUS:CONFIRMED` | _EA_, _EC_ | -| Embargo Status $q^{em} \in X$ due to early termination | `STATUS:CANCELLED` | _ET_ | -| Embargo Status $q^{em} \in N$ due to lack of acceptance quorum | `STATUS:CANCELLED` | _ER_ | +| Embargo Status $q^{em} \in P$ | `STATUS:TENTATIVE` | *EP* | +| Embargo Status $q^{em} \in A$ | `STATUS:CONFIRMED` | *EA*, *EC* | +| Embargo Status $q^{em} \in X$ due to early termination | `STATUS:CANCELLED` | *ET* | +| Embargo Status $q^{em} \in N$ due to lack of acceptance quorum | `STATUS:CANCELLED` | *ER* | | Other | `CATEGORIES:EMBARGO`
`RSVP: TRUE` | - | !!! note "" @@ -142,10 +142,10 @@ existing embargo can be achieved as follows. Terminating an existing embargo ($q^{em} \in \{A,R\} \xrightarrow{t} X$) can be triggered in one of two ways: -- A _normal_ exit occurs when the planned embargo end time has +- A *normal* exit occurs when the planned embargo end time has expired. -- An _abnormal_ exit occurs when some external event causes the +- An *abnormal* exit occurs when some external event causes the embargo to fail, such as when the vulnerability or its exploit has been made public, attacks have been observed, etc., as outlined in [Early Termination](../topics/process_models/em/early_termination.md). @@ -154,11 +154,11 @@ Translating this into `iCalendar` semantics, we have the following, which assumes an existing embargo is represented by a `VEVENT` with `STATUS:CONFIRMED`. -1. _Normal termination_: The `VEVENT` retains its `STATUS:CONFIRMED` +1. *Normal termination*: The `VEVENT` retains its `STATUS:CONFIRMED` and passes quietly from the future through the present into the past. -2. _Abnormal termination_: The `ORGANIZER` sets the `VEVENT` to +2. *Abnormal termination*: The `ORGANIZER` sets the `VEVENT` to `STATUS:CANCELLED` and sends it out to the `ATTENDEE` list. The above is consistent with our premise in diff --git a/docs/howto/process_implementation.md b/docs/howto/process_implementation.md index 7d8f8c26..2fe4affc 100644 --- a/docs/howto/process_implementation.md +++ b/docs/howto/process_implementation.md @@ -14,13 +14,13 @@ incident or service request workflow. As such, the RM process could be implemented as a JIRA ticket workflow, as part of a Kanban process, etc. The main modifications needed to adapt an existing workflow are to intercept the key milestones and emit the appropriate RM messages: -- when the reports are received (_RK_) +- when the reports are received (*RK*) -- when the report validation process completes (_RI_, _RV_) +- when the report validation process completes (*RI*, *RV*) -- when the report prioritization process completes (_RA_, _RD_) +- when the report prioritization process completes (*RA*, *RD*) -- when the report is closed (_RC_) +- when the report is closed (*RC*) ### Vulnerability Draft Pre-Publication Review @@ -30,9 +30,9 @@ The main modifications needed to adapt an existing workflow are to intercept the MPCVD case Participants often share pre-publication drafts of their advisories during the embargo period. Our protocol proposal is mute on this subject because it is not strictly necessary for the MPCVD process to complete successfully. -However, as we observe in the [ISO Crosswalk](../reference/iso_crosswalk.md), the _GI_ and _GK_ message types appear to provide sufficient mechanics for this +However, as we observe in the [ISO Crosswalk](../reference/iso_crosswalk.md), the *GI* and *GK* message types appear to provide sufficient mechanics for this process to be fleshed out as necessary. -This draft-sharing process could be built into the [_prepare publication_](../topics/behavior_logic/publication_bt.md#prepare-publication-behavior) process, where appropriate. +This draft-sharing process could be built into the [*prepare publication*](../topics/behavior_logic/publication_bt.md#prepare-publication-behavior) process, where appropriate. ## EM Implementation Notes @@ -56,29 +56,29 @@ However, at times, case Participants may find it necessary to coordinate even mo Because part of the CS model is Participant specific and the other is global to the case, we address each part below. -### The _vfd_ Process +### The *vfd* Process -Similar to the RM process, which is specific to each Participant, the _vfd_ process is +Similar to the RM process, which is specific to each Participant, the *vfd* process is individualized to each Vendor (or Deployer, for the simpler $d \xrightarrow{\mathbf{D}} D$ state transition). Modifications to the Vendor's development process to implement the Vultron Protocol are expected to be minimal and are limited to the following: -- acknowledging the Vendor's role on report receipt with a _CV_ message +- acknowledging the Vendor's role on report receipt with a *CV* message -- emitting a _CF_ message when a fix becomes ready (and possibly terminating any active embargo to open the door to publication) +- emitting a *CF* message when a fix becomes ready (and possibly terminating any active embargo to open the door to publication) -- (if relevant) issuing a _CD_ message when the fix has been deployed +- (if relevant) issuing a *CD* message when the fix has been deployed Non-Vendor Deployers are rarely involved in MPCVD cases, but when they are, their main integration point is to emit a -_CD_ message when deployment is complete. +*CD* message when deployment is complete. -### The _pxa_ Process +### The *pxa* Process -On the other hand, the _pxa_ process hinges on monitoring public and private sources for evidence of information leaks, +On the other hand, the *pxa* process hinges on monitoring public and private sources for evidence of information leaks, research publications, and adversarial activity. -In other words, the _pxa_ process is well positioned to be wired into Participants' threat intelligence and threat +In other words, the *pxa* process is well positioned to be wired into Participants' threat intelligence and threat analysis capabilities. -The goal would be to emit _CP_, _CX_, and _CA_ messages as appropriate when such evidence is detected. +The goal would be to emit *CP*, *CX*, and *CA* messages as appropriate when such evidence is detected. Some portions of this process can be automated: - Human analysts and/or automated search agents can look for evidence of early publication of vulnerability information. diff --git a/docs/reference/formal_protocol/conclusion.md b/docs/reference/formal_protocol/conclusion.md index a4a7b4e0..a13c4d47 100644 --- a/docs/reference/formal_protocol/conclusion.md +++ b/docs/reference/formal_protocol/conclusion.md @@ -97,7 +97,7 @@ driven by outside events (e.g., public awareness, exploits in the wild, attacks #### Participant-Specific -The _Vendor fix path_ is shown below, and is specific to individual Vendor Participants. +The *Vendor fix path* is shown below, and is specific to individual Vendor Participants. It reflects each Participant's state changes in the fix development and deployment process. ```mermaid diff --git a/docs/reference/formal_protocol/index.md b/docs/reference/formal_protocol/index.md index a332120e..133d0963 100644 --- a/docs/reference/formal_protocol/index.md +++ b/docs/reference/formal_protocol/index.md @@ -16,7 +16,7 @@ A communication protocol allows independent processes, represented as finite sta transitions through the passing of messages. [Brand and Zafiropulo](https://doi.org/10.1145/322374.322380) defined a protocol as follows. -!!! note "_Protocol_ Formally Defined" +!!! note "*Protocol* Formally Defined" A **protocol** with $N$ processes is a quadruple: @@ -49,7 +49,7 @@ a protocol as follows. receives message $x$ in state $s$. It is a transmission if $x$ is from $M_{ij}$ and a reception if $x$ is from $M_{ji}$. -!!! note "_Global State_ Formally Defined" +!!! note "*Global State* Formally Defined" The **global state** of a protocol given by the above is a pair $\langle S, C \rangle$, where @@ -77,7 +77,7 @@ in their roles (Finder, Vendor, Coordinator, Deployer, and Other). Each Participant has their own process, but Participants might take on multiple roles in a given case. -!!! note "_Number of Processes_" +!!! note "*Number of Processes*" The total number of processes $N$ is simply the count of unique Participants. diff --git a/docs/reference/formal_protocol/states.md b/docs/reference/formal_protocol/states.md index afa17957..b37d5e86 100644 --- a/docs/reference/formal_protocol/states.md +++ b/docs/reference/formal_protocol/states.md @@ -5,7 +5,7 @@ Each Participant in an MPCVD case has a corresponding RM state, an EM state, and an overall CS state. Therefore, we can represent a Participant's state as a triple comprising the state of each of these models. -!!! note "_Participant State_" +!!! note "*Participant State*" A Participant's state is a triple comprising the state of each of the RM, EM, and CS models. @@ -29,7 +29,7 @@ any given Participant. A generic state model for a CVD Participant can be composed from the Cartesian product of $\mathcal{Q}^{rm}$, $\mathcal{Q}^{em}$, and $\mathcal{Q}^{cs}$ as shown below. -!!! note "_Participant State Space_" +!!! note "*Participant State Space*" A Participant's state is a triple comprising the state of each of the RM, EM, and CS models. The set of all possible Participant states is the Cartesian product of the RM, EM, and CS state sets. @@ -131,7 +131,7 @@ Participant doesn't even know about yet. Therefore, the $Start$ state also implies that the EM and CVD Case states do not matter. We use $*$ to represent the "don't care" value. -???+ note "Unreachable EM and CS States when RM is in _Closed_ or _Start_" +???+ note "Unreachable EM and CS States when RM is in *Closed* or *Start*" $$q^{rm} \in \{S,C\} \implies (q^{em} \in *) \cup (q^{cs} \in *)$$ @@ -140,13 +140,13 @@ words, $q^{cs} \in \cdot\cdot\cdot pX \cdot$ is an ephemeral state that resolves quickly to $q^{cs} \in \cdot\cdot\cdot PX \cdot$. (As a reminder, dots ($\cdot$) in CVD case state notation indicate single-character wildcards.) -???+ note "Unreachable CS States when CS is in _Public_ or _Exploit_" +???+ note "Unreachable CS States when CS is in *Public* or *Exploit*" $$q^{cs} \in \cdot\cdot\cdot pX \cdot \implies q^{cs} \in \cdot\cdot\cdot PX \cdot$$ Furthermore, when a vulnerability becomes public, the EM state no longer matters. -???+ note "Unreachable EM States when CS is in _Public_" +???+ note "Unreachable EM States when CS is in *Public*" $$q^{cs} \in \cdot\cdot\cdot PX \cdot \implies q^{em} \in *$$ @@ -263,10 +263,10 @@ state that was just added. As a Vendor has a report in $Received$, it is, by definition, at least in the $Vfd$ case state. Vendors create fixes only when they are in the $Accepted$ RM state. -Because the $Received$, $Invalid$, and $Valid$ states come strictly _before_ the $Accepted$ state in the RM DFA, +Because the $Received$, $Invalid$, and $Valid$ states come strictly *before* the $Accepted$ state in the RM DFA, there is no way for the Vendor to be in either $VFd$ or $VFD$ while in any of those states. -???+ note "Vendor CS States When RM is in _Received_, _Invalid_, or _Valid_" +???+ note "Vendor CS States When RM is in *Received*, *Invalid*, or *Valid*" $$q^{rm}_{Vendor} \in \{R,I,V\} \implies q^{cs}_{Vendor} \in Vfd\cdot\cdot\cdot$$ @@ -623,7 +623,7 @@ states, as we show next. Finally, CVD cases often involve Participants who are neither Vendors nor Deployers. Specifically, Finder/Reporters fall into this category, as do Coordinators. -Other roles, as outlined in the [_CERT Guide to Coordinated Vulnerability Disclosure_](https://vuls.cert.org/confluence/display/CVD), +Other roles, as outlined in the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD), could be included here as well. Because they do not participate directly in the Vendor fix path, these Non-Vendor, Non-Deployer CVD Participants fall into the $\varnothing$ case substate we added above. diff --git a/docs/reference/iso_30111_2019.md b/docs/reference/iso_30111_2019.md index aa5d4123..30cbc02e 100644 --- a/docs/reference/iso_30111_2019.md +++ b/docs/reference/iso_30111_2019.md @@ -25,7 +25,7 @@ The table below provides a mapping of ISO/IEC 30111:2019 onto the relevant conce | | c) Root Cause Analysis | [Do Work Behavior](../topics/behavior_logic/do_work_bt.md)
$q^{rm} \in A$ | | | d) Further investigation | [Do Work Behavior](../topics/behavior_logic/do_work_bt.md)
$q^{rm} \in A$ | | | e) Prioritization | the [Valid](../topics/process_models/rm/index.md#the-valid-v-state) state
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
$q^{rm} \in V \xrightarrow{d} D$ on defer
$q^{rm} \in V \xrightarrow{a} A$ on accept | -| | f) Inform reporter | [Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
Emit _RV_, _RI_, _RA_, _RD_ messages as appropriate | +| | f) Inform reporter | [Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
Emit *RV*, *RI*, *RA*, *RD* messages as appropriate | | 7.1.5 Remediation Development | all| the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Fix Ready](../topics/process_models/model_interactions/rm_em_cs.md#fix-ready)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
$q^{rm} \in A$
$q^{cs} \in Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} VFd\cdot\cdot\cdot$ | | 7.1.6 Release | - | the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{cs} \in VFdp\cdot\cdot \xrightarrow{\mathbf{P}} VFdP \cdot\cdot$ | | 7.1.7 Post-release | all | [Report Closure Behavior](../topics/behavior_logic/rm_closure_bt.md)
[Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
$q^{cs} \in VF\cdot P \cdot\cdot$
$q^{rm} \in \{A,D\}$ | diff --git a/docs/reference/iso_5895_2022.md b/docs/reference/iso_5895_2022.md index cda02d56..52d0315e 100644 --- a/docs/reference/iso_5895_2022.md +++ b/docs/reference/iso_5895_2022.md @@ -23,7 +23,7 @@ The table below contains our mapping of relevant sections of that technical repo | | 7.6 Processes and Controls | See NDA Note in [Embargo Management Model](../topics/process_models/em/index.md) | | 8 MPCVD lifecycle for each product | all | [Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{rm} \in A$ | | 9 MPCVD lifecycle for each vulnerability | 9.1 Receipt | the [Start](../topics/process_models/rm/index.md#the-start-s-state) state
the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Vendor Awareness](../topics/process_models/cs/index.md#the-vendor-awareness-substate-v-v) substate
[Process RM Messages Behavior](../topics/behavior_logic/msg_rm_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in S \xrightarrow{r} R$
$q^{cs} \in vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$ | -| | 9.2 Verification | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Valid](../topics/process_models/rm/index.md#the-valid-v-state) state
the [Valid](../topics/process_models/rm/index.md#the-invalid-i-state) state
[Embargo Principles](../topics/process_models/em/principles.md)
[Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in R \xrightarrow{v} V$ (valid)
$q^{rm} \in R \xrightarrow{i} I$ (invalid)
Emit _RV_. _RI_, _RA_, _RD_ as appropriate | +| | 9.2 Verification | the [Received](../topics/process_models/rm/index.md#the-received-r-state) state
the [Valid](../topics/process_models/rm/index.md#the-valid-v-state) state
the [Valid](../topics/process_models/rm/index.md#the-invalid-i-state) state
[Embargo Principles](../topics/process_models/em/principles.md)
[Report Validation Behavior](../topics/behavior_logic/rm_validation_bt.md)
[Report Prioritization Behavior](../topics/behavior_logic/rm_prioritization_bt.md)
[Reporting Behavior](../topics/behavior_logic/reporting_bt.md)
$q^{rm} \in R \xrightarrow{v} V$ (valid)
$q^{rm} \in R \xrightarrow{i} I$ (invalid)
Emit *RV*. *RI*, *RA*, *RD* as appropriate | | | 9.3 Remediation development | the [Accepted](../topics/process_models/rm/index.md#the-accepted-a-state) state
the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Fix Ready](../topics/process_models/model_interactions/rm_em_cs.md#sec:cs_f_em/index.md)
[Fix Development Behavior](../topics/behavior_logic/fix_dev_bt.md)
$q^{rm} \in A$
$q^{cs} \in Vfd\cdot\cdot\cdot \xrightarrow{\mathbf{F}}VFd\cdot\cdot\cdot$ | | | 9.4 Release | the [Fix Readiness](../topics/process_models/cs/index.md#the-fix-readiness-substate-f-f) substate
[Publication Behavior](../topics/behavior_logic/publication_bt.md)
$q^{cs} \in VFdp\cdot\cdot \xrightarrow{\mathbf{P}} VFDP\cdot\cdot$ | | | 9.5 Post-release | [Report Closure Behavior](../topics/behavior_logic/rm_closure_bt.md)
[Deployment Behavior](../topics/behavior_logic/deployment_bt.md)
$q^{rm} \in \{A,D\}$
$q^{cs} \in VF\cdot P \cdot\cdot$ | diff --git a/docs/reference/ssvc_crosswalk.md b/docs/reference/ssvc_crosswalk.md index 1f19525a..d78912fc 100644 --- a/docs/reference/ssvc_crosswalk.md +++ b/docs/reference/ssvc_crosswalk.md @@ -3,19 +3,19 @@ {% include-markdown "../includes/not_normative.md" %} In the context of the Vultron Protocol, once a report has been validated -(i.e., it is in the RM [_Valid_](../topics/process_models/rm/index.md#the-valid-v-state) state, $q^{rm} \in V$), it must be prioritized to +(i.e., it is in the RM [*Valid*](../topics/process_models/rm/index.md#the-valid-v-state) state, $q^{rm} \in V$), it must be prioritized to determine what further effort, if any, is necessary. While any prioritization scheme might be used, here we demonstrate an application of the [SSVC](https://github.com/CERTCC/SSVC) model. ## SSVC Supplier and Deployer Trees -The default outcomes for both the SSVC [_Supplier_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_supplier.pdf) -and [_Deployer_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_deployer_SeEUMss.pdf) Trees are -_Defer_, _Scheduled_, _Out of Cycle_, and _Immediate_. -The mapping from SSVC outcomes to RM states is straightforward, as shown below for the _Supplier Tree_ and -the _Deployer Tree_. +The default outcomes for both the SSVC [*Supplier*](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_supplier.pdf) +and [*Deployer*](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_deployer_SeEUMss.pdf) Trees are +*Defer*, *Scheduled*, *Out of Cycle*, and *Immediate*. +The mapping from SSVC outcomes to RM states is straightforward, as shown below for the *Supplier Tree* and +the *Deployer Tree*. -!!! note "SSVC _Supplier Tree_ Mapping to RM States" +!!! note "SSVC *Supplier Tree* Mapping to RM States" $$\label{eq:ssvc_supplier_tree_output} q^{rm} \in @@ -30,7 +30,7 @@ the _Deployer Tree_. \end{Bmatrix} \\ \end{cases}$$ -!!! note "SSVC _Deployer Tree_ Mapping to RM States" +!!! note "SSVC *Deployer Tree* Mapping to RM States" $$\label{eq:ssvc_deployer_tree_output} q^{rm} \in @@ -46,11 +46,11 @@ the _Deployer Tree_. \end{cases}$$ The -SSVC _Defer_ -output maps directly onto the RM [_Deferred_](../topics/process_models/rm/index.md#the-deferred-d-state) state. +SSVC *Defer* +output maps directly onto the RM [*Deferred*](../topics/process_models/rm/index.md#the-deferred-d-state) state. Otherwise, the three outputs that imply further action is necessary—Scheduled_, -_Out-of-Cycle_, and _Immediate_—all proceed to the RM [_Accepted_](../topics/process_models/rm/index.md#the-accepted-a-state) state. -The different categories imply different processes within the _Accepted_ state. +*Out-of-Cycle*, and *Immediate*—all proceed to the RM [*Accepted*](../topics/process_models/rm/index.md#the-accepted-a-state) state. +The different categories imply different processes within the *Accepted* state. But because the RM model does not dictate internal organizational processes, further description of what those processes might look like is out of scope for this crosswalk. @@ -66,12 +66,12 @@ the main part of this documentation: ## SSVC Coordinator Trees -SSVC version 2 offers two decision trees for Coordinators: A [_Coordinator Triage Tree_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-triage.pdf) -and a [_Coordinator Publish Tree_](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-publish.pdf). -The outputs for the _Coordinator Triage_ Decision Tree are _Decline_, _Track_, and _Coordinate_. -Similar to the _Supplier Tree_ mapping above, the mapping here is simple, as shown below. +SSVC version 2 offers two decision trees for Coordinators: A [*Coordinator Triage Tree*](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-triage.pdf) +and a [*Coordinator Publish Tree*](https://github.com/CERTCC/SSVC/blob/v2.1/doc/graphics/ssvc_2_coord-publish.pdf). +The outputs for the *Coordinator Triage* Decision Tree are *Decline*, *Track*, and *Coordinate*. +Similar to the *Supplier Tree* mapping above, the mapping here is simple, as shown below. -!!! note "SSVC _Coordinator Triage Tree_ Mapped to RM States" +!!! note "SSVC *Coordinator Triage Tree* Mapped to RM States" $$\label{eq:ssvc_coordinator_triage_tree_output} q^{rm} \in @@ -85,12 +85,12 @@ Similar to the _Supplier Tree_ mapping above, the mapping here is simple, as sho \end{Bmatrix} \\ \end{cases}$$ -Again, whereas the _Decline_ output maps directly to the RM [_Deferred_](../topics/process_models/rm/index.md#the-deferred-d-state) state, the remaining two -states (_Track_ and _Coordinate_) imply the necessity for distinct processes within the Coordinator's RM [_Accepted_](../topics/process_models/rm/index.md#the-accepted-a-state) state. +Again, whereas the *Decline* output maps directly to the RM [*Deferred*](../topics/process_models/rm/index.md#the-deferred-d-state) state, the remaining two +states (*Track* and *Coordinate*) imply the necessity for distinct processes within the Coordinator's RM [*Accepted*](../topics/process_models/rm/index.md#the-accepted-a-state) state. -On the other hand, the SSVC _Coordinator Publish Tree_ falls entirely within the Coordinator's _Accepted_ state, so its +On the other hand, the SSVC *Coordinator Publish Tree* falls entirely within the Coordinator's *Accepted* state, so its output does not directly induce any Coordinator RM state transitions. -However, a number of its decision points _do_ touch on the protocol models, which we cover next. +However, a number of its decision points *do* touch on the protocol models, which we cover next. ## SSVC Decision Points and the Vultron Protocol @@ -100,15 +100,15 @@ Vultron Protocol. ### Exploitation -The SSVC _Exploitation_ decision point permits three possible values: +The SSVC *Exploitation* decision point permits three possible values: -- _None_ -- _PoC_ -- _Active_ +- *None* +- *PoC* +- *Active* These values map directly onto state subsets in the [Case State (CS) model](../topics/process_models/cs/index.md), as shown below. -!!! note "SSVC _Exploitation_ Decision Point Mapped to CS States" +!!! note "SSVC *Exploitation* Decision Point Mapped to CS States" $$ SSVC(exploitation) = \begin{cases} @@ -117,22 +117,22 @@ These values map directly onto state subsets in the [Case State (CS) model](../t Active & \iff q^{cs} \in \cdot\cdot\cdot\cdot\cdot A \\ \end{cases}$$ -A value of _None_ implies that no exploits have been made public, and no attacks have been observed +A value of *None* implies that no exploits have been made public, and no attacks have been observed (i.e., $q^{cs} \in \cdot\cdot\cdot\cdot xa$). -The _PoC_ value means that an exploit is public, but no attacks have been observed +The *PoC* value means that an exploit is public, but no attacks have been observed (i.e., $q^{cs} \in \cdot\cdot\cdot\cdot Xa$). -Finally, the _Active_ value indicates attacks are occurring +Finally, the *Active* value indicates attacks are occurring (i.e., $q^{cs} \in \cdot\cdot\cdot\cdot\cdot A$). These case states and SSVC values are equivalent in both directions, hence our use of the "if-and-only-if" ($\iff$) symbol. ### Report Public -The SSVC _Report Public_ decision point also maps directly onto the [CS model](../topics/process_models/cs/index.md). -A value of _Yes_ means that the report is public, equivalent to $q^{cs} \in \cdot\cdot\cdot P \cdot\cdot$. -On the other hand, a _No_ value is the same as $q^{cs} \in \cdot\cdot\cdot p \cdot\cdot$. +The SSVC *Report Public* decision point also maps directly onto the [CS model](../topics/process_models/cs/index.md). +A value of *Yes* means that the report is public, equivalent to $q^{cs} \in \cdot\cdot\cdot P \cdot\cdot$. +On the other hand, a *No* value is the same as $q^{cs} \in \cdot\cdot\cdot p \cdot\cdot$. As above, "$\iff$" indicates the bidirectional equivalence. -!!! note "SSVC _Report Public_ Decision Point Mapped to CS States" +!!! note "SSVC *Report Public* Decision Point Mapped to CS States" $$SSVC(report~public) = \begin{cases} @@ -142,11 +142,11 @@ As above, "$\iff$" indicates the bidirectional equivalence. ### Supplier Contacted -If the Supplier (Vendor) has been notified (i.e., there is reason to believe they are at least in the RM [_Received_](../topics/process_models/rm/index.md#the-received-r-state) -state, equivalent to the $V\cdot\cdot\cdot\cdot\cdot$ CS state subset) the _Supplier Contacted_ value should be _Yes_, -otherwise it should be _No_. +If the Supplier (Vendor) has been notified (i.e., there is reason to believe they are at least in the RM [*Received*](../topics/process_models/rm/index.md#the-received-r-state) +state, equivalent to the $V\cdot\cdot\cdot\cdot\cdot$ CS state subset) the *Supplier Contacted* value should be *Yes*, +otherwise it should be *No*. -!!! note "SSVC _Supplier Contacted_ Decision Point Mapped to RM States" +!!! note "SSVC *Supplier Contacted* Decision Point Mapped to RM States" $$SSVC(supp.~contacted) = \begin{cases} @@ -158,16 +158,16 @@ otherwise it should be _No_. ### Report Credibility Unlike most of the other SSVC decision points covered here that form a part of a Participant's report prioritization -process _after_ report validation, the _Report Credibility_ decision point forms an important step in the Coordinator's +process *after* report validation, the *Report Credibility* decision point forms an important step in the Coordinator's validation process. In fact, it is often the only validation step possible when the Coordinator lacks the ability to reproduce a vulnerability whether due to constraints of resources, time, or skill. -Thus, a value of _Credible_ can be expected to lead to an RM transition to [_Valid_](../topics/process_models/rm/index.md#the-valid-v-state) ($q^{rm} \in R \xrightarrow{v} V$), +Thus, a value of *Credible* can be expected to lead to an RM transition to [*Valid*](../topics/process_models/rm/index.md#the-valid-v-state) ($q^{rm} \in R \xrightarrow{v} V$), assuming any additional validation checks also pass. -On the contrary, _Not-Credible_ always implies the RM transition to [_Invalid_](../topics/process_models/rm/index.md#the-invalid-i-state) ($q^{rm} \in R \xrightarrow{i} I$) +On the contrary, *Not-Credible* always implies the RM transition to [*Invalid*](../topics/process_models/rm/index.md#the-invalid-i-state) ($q^{rm} \in R \xrightarrow{i} I$) because "Valid-but-not-Credible" is a contradiction. -!!! note "SSVC _Report Credibility_ Decision Point Mapped to RM States" +!!! note "SSVC *Report Credibility* Decision Point Mapped to RM States" $$SSVC(report~cred.) = \begin{cases} @@ -177,20 +177,20 @@ because "Valid-but-not-Credible" is a contradiction. ### Supplier Engagement -The possible values for the _Supplier_ (Vendor) _Engagement_ decision point are _Active_ or _Unresponsive_. +The possible values for the *Supplier* (Vendor) *Engagement* decision point are *Active* or *Unresponsive*. From the Coordinator's perspective, if enough Suppliers in a CVD case have communicated their engagement in a case -(i.e., enough Vendors are in the RM _Accepted_ state already or are expected to make it there soon from either the -_Received_ or _Valid_ states), then the SSVC value would be _Active_. +(i.e., enough Vendors are in the RM *Accepted* state already or are expected to make it there soon from either the +*Received* or *Valid* states), then the SSVC value would be *Active*. -Vendors in _Invalid_ or _Closed_ can be taken as disengaged, and it might be appropriate to select _Unresponsive_ for -the SSVC _Engagement_ decision point. +Vendors in *Invalid* or *Closed* can be taken as disengaged, and it might be appropriate to select *Unresponsive* for +the SSVC *Engagement* decision point. -Vendors in either _Received_ or _Deferred_ might be either _Active_ or _Unresponsive_, depending on the specific report +Vendors in either *Received* or *Deferred* might be either *Active* or *Unresponsive*, depending on the specific report history. This mapping is formalized below and in the figure that follows. -!!! note "SSVC _Supplier Engagement_ Decision Point Mapped to RM States" +!!! note "SSVC *Supplier Engagement* Decision Point Mapped to RM States" $$ SSVC(supp.~eng.) = \begin{cases} @@ -235,10 +235,10 @@ graph LR ### Supplier Involvement -The _Supplier Involvement_ decision point can take on the values _Fix-Ready_, _Cooperative_, or _Uncooperative/Unresponsive_. -We begin by noting the equivalence of the _Fix-Ready_ value with the similarly named substate of the CS model. +The *Supplier Involvement* decision point can take on the values *Fix-Ready*, *Cooperative*, or *Uncooperative/Unresponsive*. +We begin by noting the equivalence of the *Fix-Ready* value with the similarly named substate of the CS model. -!!! note "SSVC _Supplier Involvement_ Decision Point Mapped to CS States" +!!! note "SSVC *Supplier Involvement* Decision Point Mapped to CS States" $$\begin{aligned} \label{eq:ssvc_supplier_involvement_fr} @@ -294,7 +294,7 @@ graph LR S --> un ``` -!!! tip "_Engagement_ vs. _Involvement_: What's the Difference?" +!!! tip "*Engagement* vs. *Involvement*: What's the Difference?" Note the discrepancy between the mappings given for SSVC _Supplier Engagement_ versus those for _Supplier Involvement_. This distinction is most prominent in the connections from the _Received_ and _Deferred_ RM states in the two figures above. diff --git a/docs/topics/background/notation.md b/docs/topics/background/notation.md index 62455642..77247367 100644 --- a/docs/topics/background/notation.md +++ b/docs/topics/background/notation.md @@ -7,7 +7,7 @@ This page provides a reference for the conventions and notation used throughout ## Documentation Conventions -We are using the [_Admonitions_](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (call-outs) provided by +We are using the [*Admonitions*](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (call-outs) provided by [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) to highlight specific types of information in this documentation. diff --git a/docs/topics/behavior_logic/msg_cs_bt.md b/docs/topics/behavior_logic/msg_cs_bt.md index 2a217161..dc5dbe02 100644 --- a/docs/topics/behavior_logic/msg_cs_bt.md +++ b/docs/topics/behavior_logic/msg_cs_bt.md @@ -36,20 +36,20 @@ flowchart LR We are still working through the children of [Receive Messages](msg_intro_bt.md) behavior tree. And as we've come to expect, a precondition check leads to a fallback node in which CS acknowledgement -messages (_CK_) receive no further attention and return _Success_. +messages (*CK*) receive no further attention and return *Success*. The main CS message-handling sequence comes next, with all matching incoming messages resulting in emission of an -acknowledgment message (_CK_). +acknowledgment message (*CK*). These messages are presented as sub-trees below: - (A) [Participant-agnostic CS Status Messages](#participant-agnostic-cs-status-messages) - (B) [Participant-Specific CS Status Messages](#participant-specific-cs-status-messages) -Returning from handling regular CS messages, the tree next (C) handles error messages (_CE_) with the familiar motif -of an error (_CE_) triggering a general inquiry (_GI_) to seek resolution. +Returning from handling regular CS messages, the tree next (C) handles error messages (*CE*) with the familiar motif +of an error (*CE*) triggering a general inquiry (*GI*) to seek resolution. Finally, the tree has handled all expected messages, so anything else would result in an error -condition and emission of a _CE_ message accordingly. +condition and emission of a *CE* message accordingly. ## Participant-agnostic CS Status Messages @@ -109,30 +109,30 @@ flowchart LR global_seq -->|A2| terminate ``` -(A1a) Information that the vulnerability has been made public (_CP_) is met -with a transition to the _Public Aware_ state in the CS model when +(A1a) Information that the vulnerability has been made public (*CP*) is met +with a transition to the *Public Aware* state in the CS model when necessary. (A1b) Similarly, information that an exploit has been made public -forces both the __X__ and __P__ transitions, as necessary. -Because the __P__ transition, should it occur in response to a -_CX_ message, represents possibly new information to the case, it -triggers the emission of a _CP_ message to convey this information to +forces both the **X** and **P** transitions, as necessary. +Because the **P** transition, should it occur in response to a +*CX* message, represents possibly new information to the case, it +triggers the emission of a *CP* message to convey this information to the other Participants. (A1c) Likewise, a message indicating attacks underway -triggers the __A__ transition. +triggers the **A** transition. -Again, we note that any of the __P__, __X__, or -__A__ transitions in the CS model imply that no new embargo should be +Again, we note that any of the **P**, **X**, or +**A** transitions in the CS model imply that no new embargo should be entered, and any existing embargo should be terminated. Hence, the sequence described in the previous paragraph leads to the [embargo termination tree](em_terminate_bt.md). ## Participant-Specific CS Status Messages -Next, we see that messages indicating _Vendor Awareness_ (_CV_), _Fix -Readiness_ (_CF_), and _Fix Deployed_ (_CD_) are treated as mere status +Next, we see that messages indicating *Vendor Awareness* (*CV*), *Fix +Readiness* (*CF*), and *Fix Deployed* (*CD*) are treated as mere status updates for the Participant because they are participant-specific. They are recognized and acknowledged but trigger no further action directly. @@ -159,4 +159,4 @@ Therefore, messages representing another Participant's status change for this po CS do not directly affect the receiving Participant's status. This is not to say that the Participant might not choose to take some action based on their knowledge of a Vendor's (or Deployer's) status. -Rather, such follow-up would be expected to occur as part of the Participant's [_do work_ process](do_work_bt.md). +Rather, such follow-up would be expected to occur as part of the Participant's [*do work* process](do_work_bt.md). diff --git a/docs/topics/behavior_logic/msg_em_bt.md b/docs/topics/behavior_logic/msg_em_bt.md index 7f84adb6..4c5dcf2b 100644 --- a/docs/topics/behavior_logic/msg_em_bt.md +++ b/docs/topics/behavior_logic/msg_em_bt.md @@ -72,21 +72,21 @@ flowchart LR It is a child of the fallback node started in [Receiving Messages Behavior](msg_intro_bt.md). A precondition check for EM message types is followed by a fallback node. -EM acknowledgment messages (_EK_) receive no further attention and return _Success_. +EM acknowledgment messages (*EK*) receive no further attention and return *Success*. ## Messages That Lead to a Simple Acknowledgment -Next is a branch handling all the messages that will result in a simple acknowledgment (_EK_). +Next is a branch handling all the messages that will result in a simple acknowledgment (*EK*). -(A) First, we handle embargo error messages (_EE_), which additionally trigger a general inquiry (_GI_) message to attempt +(A) First, we handle embargo error messages (*EE*), which additionally trigger a general inquiry (*GI*) message to attempt to resolve the problem. -(B) Second are embargo termination messages (_ET_). -If the Participant is already in the EM _eXited_ state (_X_), no further action is taken (aside from the _EK_). -Otherwise, if the Participant is in either _Active_ or _Revise_ EM states, the _ET_ message triggers a state +(B) Second are embargo termination messages (*ET*). +If the Participant is already in the EM *eXited* state (*X*), no further action is taken (aside from the *EK*). +Otherwise, if the Participant is in either *Active* or *Revise* EM states, the *ET* message triggers a state transition $q^{em} \xrightarrow{t} X$. -(C) Embargo rejections are handled next in a simple sequence that returns the state from _Proposed_ to _None_. +(C) Embargo rejections are handled next in a simple sequence that returns the state from *Proposed* to *None*. ### Handling Viable Embargo Messages @@ -170,24 +170,24 @@ flowchart LR ec_seq --> ec_em_to_A ``` -(D2a) An embargo proposal (_EP_) -results in either a move from _None_ to _Proposed_ or stays in +(D2a) An embargo proposal (*EP*) +results in either a move from *None* to *Proposed* or stays in *Proposed*, if that was already the case. -(D2b) An embargo acceptance (_EA_) -transitions from _Proposed_ to _Active_. +(D2b) An embargo acceptance (*EA*) +transitions from *Proposed* to *Active*. -(D2c) Similar to the _EP_ behavior, -an embargo revision proposal (_EV_) either moves from _Active_ to -*Revise* or stays in _Revise_, as appropriate. +(D2c) Similar to the *EP* behavior, +an embargo revision proposal (*EV*) either moves from *Active* to +*Revise* or stays in *Revise*, as appropriate. (D2d) Finally, we deal with -revision rejection (_EJ_) or acceptance (_EC_) when in the *Revise* +revision rejection (*EJ*) or acceptance (*EC*) when in the *Revise* state. -Climbing back up the tree, we see that _Success_ in any of the +Climbing back up the tree, we see that *Success* in any of the branches in this or the previous paragraph results in an acknowledgment -message _EK_. +message *EK*. ## Messages That Require More than a Simple Acknowledgment @@ -199,4 +199,4 @@ This branch takes us to the [Terminate Embargo tree](em_terminate_bt.md), which other messages being emitted. Finally, back at the end of the tree at the top of the page, when no other branch has succeeded, -we emit an embargo error (_EE_) message to relay the failure. +we emit an embargo error (*EE*) message to relay the failure. diff --git a/docs/topics/behavior_logic/msg_other_bt.md b/docs/topics/behavior_logic/msg_other_bt.md index b873cfe0..aa042bb6 100644 --- a/docs/topics/behavior_logic/msg_other_bt.md +++ b/docs/topics/behavior_logic/msg_other_bt.md @@ -31,7 +31,7 @@ flowchart LR ``` This tree represents the final chunk of the fallback node in the [Receive Messages Behavior](msg_intro_bt.md). -And here, for the final time, we see a message type check and that general acknowledgment messages (_GK_) -receive no further attention and return _Success_. -General inquiries (_GI_) get at least an acknowledgment, with any follow-up to be handled by [_do work_](do_work_bt.md). -As usual, errors (_GE_) also trigger follow-up inquiries (_GI_) in the interest of resolution. +And here, for the final time, we see a message type check and that general acknowledgment messages (*GK*) +receive no further attention and return *Success*. +General inquiries (*GI*) get at least an acknowledgment, with any follow-up to be handled by [*do work*](do_work_bt.md). +As usual, errors (*GE*) also trigger follow-up inquiries (*GI*) in the interest of resolution. diff --git a/docs/topics/behavior_logic/msg_rm_bt.md b/docs/topics/behavior_logic/msg_rm_bt.md index 4d4f3297..69dcffe2 100644 --- a/docs/topics/behavior_logic/msg_rm_bt.md +++ b/docs/topics/behavior_logic/msg_rm_bt.md @@ -56,12 +56,12 @@ flowchart LR This tree is a child of the fallback node started in [Receiving Messages Behavior](msg_intro_bt.md). Beginning with a precondition check for any RM message type, the tree proceeds to a fallback node. -RM acknowledgment messages (_RK_) receive no further attention and return _Success_. +RM acknowledgment messages (*RK*) receive no further attention and return *Success*. Next comes the main RM message processing sequence. A fallback node covers three major cases: -- (A) First comes a sequence that handles new reports (_RS_ when +- (A) First comes a sequence that handles new reports (*RS* when $q^{rm} \in S$). This branch changes the recipient's RM state regardless of the Participant's role. If the Participant happens to @@ -69,11 +69,11 @@ A fallback node covers three major cases: vulnerability described by the report, the Vendor would also note the CS transition from $q^{cs} \in vfd \xrightarrow{\mathbf{V}} Vfd$ and - emit a corresponding _CV_ message. + emit a corresponding *CV* message. -- (B) Next, we see that an RM Error (_RE_) results in the emission - of a general inquiry (_GI_) for Participants to sort out what the - problem is, along with an _RK_ to acknowledge receipt of the error. +- (B) Next, we see that an RM Error (*RE*) results in the emission + of a general inquiry (*GI*) for Participants to sort out what the + problem is, along with an *RK* to acknowledge receipt of the error. - (C) Finally, recall that the RM process is unique to each CVD @@ -83,6 +83,6 @@ A fallback node covers three major cases: associated case ($q^{rm} \not\in S$), the recipient might update their record of the sender's state, but no further action is needed. -For all three cases, an _RK_ message acknowledges receipt of the -message. Any unhandled message results in an _RE_ response, indicating +For all three cases, an *RK* message acknowledges receipt of the +message. Any unhandled message results in an *RE* response, indicating an error. diff --git a/docs/topics/formal_protocol/worked_example.md b/docs/topics/formal_protocol/worked_example.md index fe20f79b..90950bed 100644 --- a/docs/topics/formal_protocol/worked_example.md +++ b/docs/topics/formal_protocol/worked_example.md @@ -23,13 +23,13 @@ sequenceDiagram Finders become Reporters when they report a vulnerability to someone else. The next figure shows a Finder sending a -report (_RS_) in conjunction with an embargo proposal (_EP_) to a +report (*RS*) in conjunction with an embargo proposal (*EP*) to a Vendor. The Vendor receives the report and updates their state accordingly. Then the Vendor replies to acknowledge receipt of the report and the embargo proposal, and confirms that they (i.e., the -Vendor) are aware of the report (_RK_, _EK_, and _CV_, respectively). -Note that the _EK_ response is intended to convey receipt of the embargo -proposal (_EP_) but does not constitute acceptance of the proposal. We +Vendor) are aware of the report (*RK*, *EK*, and *CV*, respectively). +Note that the *EK* response is intended to convey receipt of the embargo +proposal (*EP*) but does not constitute acceptance of the proposal. We will discuss that in the next subsection. ```mermaid @@ -51,7 +51,7 @@ In this section, we show a variety of responses a Vendor might have to an embarg ### Vendor Accepts Embargo First is a basic accept sequence in which the Vendor accepts the proposed embargo and tells the -Reporter this through an _EA_ message. The Reporter acknowledges this with an _EK_ in response. +Reporter this through an *EA* message. The Reporter acknowledges this with an *EK* in response. ```mermaid sequenceDiagram @@ -73,7 +73,7 @@ sequenceDiagram ### Vendor Rejects Embargo Next we show a rejected proposal. As above, this is a simple sequence where the Vendor indicates their rejection of the -proposal with an _ER_ message, and the Reporter acknowledges this with an _EK_ message. +proposal with an *ER* message, and the Reporter acknowledges this with an *EK* message. ```mermaid sequenceDiagram @@ -91,10 +91,10 @@ sequenceDiagram ### Vendor Counterproposal Here we demonstrate a Vendor embargo counterproposal. The Vendor responds to the Reporter's prior -_EP_ message with an _EP_ message of their own. The Reporter initially -acknowledges the counterproposal with an _RK_ message and then evaluates -it and accepts with an _EA_ message. Finally, the Vendor acknowledges -the acceptance with an _EK_ message. Note, however, that there is no +*EP* message with an *EP* message of their own. The Reporter initially +acknowledges the counterproposal with an *RK* message and then evaluates +it and accepts with an *EA* message. Finally, the Vendor acknowledges +the acceptance with an *EK* message. Note, however, that there is no active embargo until the Reporter accepts it. This method of counterproposal might delay the establishment of an embargo. @@ -163,7 +163,7 @@ Here we show two responses from a Vendor in the course of prioritizing a report. ### Vendor Accepts Report -This figure shows a Vendor accepting the report for further work (presumably to develop a patch) with an _RA_ message. +This figure shows a Vendor accepting the report for further work (presumably to develop a patch) with an *RA* message. ```mermaid sequenceDiagram @@ -178,8 +178,8 @@ sequenceDiagram ### Vendor Defers Report -On the contrary, this figure shows the Vendor deferring the report with an _RD_ message. -In both cases, the Reporter acknowledges the Vendor's messages with an _RK_ message. +On the contrary, this figure shows the Vendor deferring the report with an *RD* message. +In both cases, the Reporter acknowledges the Vendor's messages with an *RK* message. ```mermaid sequenceDiagram @@ -197,8 +197,8 @@ sequenceDiagram The next two diagrams show the process of a Reporter engaging a Coordinator, who, in turn, engages a Vendor. The process begins in the first diagram with the Reporter sending a report along with an embargo proposal to the Coordinator ($RS,EP$). The Coordinator acknowledges receipt with an $RK,EK$ response. -After evaluating the proposed embargo, the Coordinator accepts it with an _EA_ message. -The Coordinator proceeds to validate and prioritize the report, emitting an _RV_ and _RA_ along the way. +After evaluating the proposed embargo, the Coordinator accepts it with an *EA* message. +The Coordinator proceeds to validate and prioritize the report, emitting an *RV* and *RA* along the way. ```mermaid sequenceDiagram @@ -233,11 +233,11 @@ sequenceDiagram In the next diagram, the Coordinator now acts as a proxy for the Reporter, notifying the Vendor and passing along the embargo information through an $RS,EP$ message of its own. -The Vendor accepts the existing embargo (_EA_) and proceeds to validate (_RV_) and prioritize (_RA_) the report. +The Vendor accepts the existing embargo (*EA*) and proceeds to validate (*RV*) and prioritize (*RA*) the report. Relevant responses from the Vendor are passed through to the Reporter. Having accepted the report for further work, the Vendor continues with creating a fix for the reported vulnerability. When complete, the Vendor conveys their readiness to the Coordinator, who in turn passes this information along -to the Reporter through the _CF_ message. +to the Reporter through the *CF* message. ```mermaid sequenceDiagram @@ -285,8 +285,8 @@ sequenceDiagram Any Participant can initiate an embargo teardown. We happened to show the case where the Coordinator initiates it in the following diagram, sending an embargo -termination message (_ET_) to all parties in the case (Reporter and Vendor in this scenario). -Recipients of the _ET_ message acknowledge receipt and update their EM state accordingly. +termination message (*ET*) to all parties in the case (Reporter and Vendor in this scenario). +Recipients of the *ET* message acknowledge receipt and update their EM state accordingly. !!! tip "Embargo Teardown, Publication, and Closure Can Start with Any Participant" @@ -319,7 +319,7 @@ sequenceDiagram Once the embargo has been exited, any Participant may now publish. In the following figure, we show the Vendor publishing first. -They notify the Coordinator that they have published using a _CP_ message to convey that information about the vulnerability +They notify the Coordinator that they have published using a *CP* message to convey that information about the vulnerability is now public. The Coordinator relays this information to the Reporter. Both the Reporter and the Coordinator publish their own reports shortly thereafter. @@ -357,7 +357,7 @@ sequenceDiagram ### Closing the Case Having no further work to be done on the case, the Reporter closes their -report and tells the Coordinator using an _RC_ message in the next diagram. +report and tells the Coordinator using an *RC* message in the next diagram. This prompts the Coordinator to review their outstanding tasks and decide to initiate the closure of their own report. In turn, the Coordinator relays this to the Vendor, who also closes their report. diff --git a/docs/topics/future_work/cvd_directory.md b/docs/topics/future_work/cvd_directory.md index 40c10bec..90bc309f 100644 --- a/docs/topics/future_work/cvd_directory.md +++ b/docs/topics/future_work/cvd_directory.md @@ -7,8 +7,8 @@ The idea of CVD embargoes implies a means of dividing the world into 1. those who belong in the embargo 2. those who do not -Because _authentication_ is not the same as _authorization_, we cannot simply rely on knowing who a Participant -is; we also have to be able to identify _why_ they are _relevant_ to a particular case. +Because *authentication* is not the same as *authorization*, we cannot simply rely on knowing who a Participant +is; we also have to be able to identify *why* they are *relevant* to a particular case. Thus, we must ask: @@ -43,7 +43,7 @@ problems: Others ask for submissions via a customized web form. These and [other examples](https://vuls.cert.org/confluence/display/CVD/4.2+Reporting) hinder the interoperability of MPCVD processes. -3. It is not always clear which _other_ Vendors' products contain the +3. It is not always clear which *other* Vendors' products contain the affected product, which limits the ability for an MPCVD cases to follow the software supply chain. diff --git a/docs/topics/future_work/ontology.md b/docs/topics/future_work/ontology.md index eaa90bd2..228049e8 100644 --- a/docs/topics/future_work/ontology.md +++ b/docs/topics/future_work/ontology.md @@ -17,7 +17,7 @@ beginning of this effort. ## Related Ontology and Data Definition Work It is currently unclear how this work might intersect with the NIST -[Vulnerability Data Ontology](https://github.com/usnistgov/vulntology) (a.k.a. _Vulntology_), but we anticipate that there may be some +[Vulnerability Data Ontology](https://github.com/usnistgov/vulntology) (a.k.a. *Vulntology*), but we anticipate that there may be some opportunity for further collaboration. Also, we recognize that the OASIS [Common Security Advisory Framework](https://oasis-open.github.io/csaf-documentation/) is addressing a different abstraction of a closely related problem (representing vulnerability reports and advisories), diff --git a/docs/topics/process_models/cs/index.md b/docs/topics/process_models/cs/index.md index c9c65cbb..3b9a45b4 100644 --- a/docs/topics/process_models/cs/index.md +++ b/docs/topics/process_models/cs/index.md @@ -7,8 +7,8 @@ Here we revisit the CS model from [A State-Based Model for Multi-Party Coordinat The CVD Case State (CS) model provides a high-level view of the state of a CVD case. In it we model two main aspects of the case: -1. A Participant-specific _Vendor Fix Path_ from initial vendor awareness through the deployment of a fix. -2. A Participant-agnostic _Public State_ summarizing both public and attacker awareness of the vulnerability. +1. A Participant-specific *Vendor Fix Path* from initial vendor awareness through the deployment of a fix. +2. A Participant-agnostic *Public State* summarizing both public and attacker awareness of the vulnerability. These processes run in parallel, and the CS model captures the interactions between them. @@ -28,8 +28,8 @@ status of all the events in the vulnerability lifecycle model described in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513). We describe the relevant factors as substates below. For notational purposes, each substate status is represented by a letter for that part -of the state of the world. For example, _v_ means no Vendor awareness -and _V_ means the Vendor is aware. The complete set of status labels is +of the state of the world. For example, *v* means no Vendor awareness +and *V* means the Vendor is aware. The complete set of status labels is shown in the table below. {% include-markdown "./cs_substates_table.md" %} @@ -42,16 +42,16 @@ shown in the table below. - [Modeling the Security Ecosystem—The Dynamics of (In)Security](https://doi.org/10.1007/978-1-4419-6967-5_6) by Frei et al. - [Before we knew it: an empirical study of zero-day attacks in the real world](https://doi.org/10.1145/2382196.2382284) by Bilge and Dumitraş -### The _Vendor Awareness_ Substate (_v_, _V_) +### The *Vendor Awareness* Substate (*v*, *V*) -The _Vendor Awareness_ substate corresponds to _Disclosure_ in the +The *Vendor Awareness* substate corresponds to *Disclosure* in the Arbaugh, Fithen, and McHugh article, [Windows of Vulnerability: A Case -Study analysis](https://doi.org/10.1109/2.889093) and _vulnerability discovered by -Vendor_ in Bilge and Dumitraş's article, [Before we knew it: an +Study analysis](https://doi.org/10.1109/2.889093) and *vulnerability discovered by +Vendor* in Bilge and Dumitraş's article, [Before we knew it: an empirical study of zero-day attacks in the real world](https://doi.org/10.1145/2382196.2382284). In the interest of model simplicity, we are -not concerned with _how_ the Vendor finds out about the vulnerability's +not concerned with *how* the Vendor finds out about the vulnerability's existence—whether it was found via internal testing, reported within a CVD process, or noticed as the result of incident or malware analysis. @@ -83,15 +83,15 @@ stateDiagram-v2 also possible, and somewhat more likely, for *Public Awareness* to occur before *Fix Deployed* in the SAAS mode as well. -### The _Fix Readiness_ Substate (_f_, _F_) +### The *Fix Readiness* Substate (*f*, *F*) -The _Fix Readiness_ substate refers to the Vendor's creation and possession of a fix that _could_ be deployed to a -vulnerable system _if_ the system owner knew of its existence. +The *Fix Readiness* substate refers to the Vendor's creation and possession of a fix that *could* be deployed to a +vulnerable system *if* the system owner knew of its existence. Here we differ somewhat from previous models ([1](https://doi.org/10.1109/2.889093), [2](https://doi.org/10.1007/978-1-4419-6967-5_6), and [3](https://doi.org/10.1145/2382196.2382284))—their -models address the _release_ of the fix rather than its _readiness_ for release. +models address the *release* of the fix rather than its *readiness* for release. This distinction is necessary because we are interested in modeling the activities and states leading up to disclosure. -Fix _release_ is a goal of the CVD process, whereas fix _readiness_ is a significant process milestone along the way. +Fix *release* is a goal of the CVD process, whereas fix *readiness* is a significant process milestone along the way. ```mermaid stateDiagram-v2 @@ -101,9 +101,9 @@ stateDiagram-v2 f --> F : fix is ready ``` -### The _Fix Deployed_ Substate (_d_, _D_) +### The *Fix Deployed* Substate (*d*, *D*) -The _Fix Deployed_ substate reflects the deployment status of an +The *Fix Deployed* substate reflects the deployment status of an existing fix. The model in [A State-Based Model for Multi-Party Coordinated Vulnerability Disclosure](https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=735513) was initially designed to treat this substate as a singular binary state for a case, but we intend to relax that here to reflect a more realistic perspective in which each Deployer maintains @@ -118,16 +118,16 @@ stateDiagram-v2 d --> D : fix is deployed ``` -### The _Public Awareness_ Substate (_p_, _P_) +### The *Public Awareness* Substate (*p*, *P*) -The _Public Awareness_ substate corresponds to _Publication_ in the -Arbaugh, Fithen, and McHugh [article](https://doi.org/10.1109/2.889093), _time of -public disclosure_ in Frei et al.'s article [Modeling the Security +The *Public Awareness* substate corresponds to *Publication* in the +Arbaugh, Fithen, and McHugh [article](https://doi.org/10.1109/2.889093), *time of +public disclosure* in Frei et al.'s article [Modeling the Security Ecosystem—The Dynamics of (In)Security](https://doi.org/10.1007/978-1-4419-6967-5_6) and *vulnerability disclosed publicly* in Bilge and Dumitraş's [article](https://doi.org/10.1145/2382196.2382284). The public might find out about a vulnerability through the Vendor's announcement of a fix, a news report about a security breach, a conference presentation by a researcher, or a variety of other means. -As above, we are primarily concerned with the occurrence of the event itself rather than the details of _how_ the public +As above, we are primarily concerned with the occurrence of the event itself rather than the details of *how* the public awareness event arises. ```mermaid @@ -138,9 +138,9 @@ stateDiagram-v2 p --> P : public becomes aware ``` -### The _Exploit Public_ Substate (_x_, _X_) +### The *Exploit Public* Substate (*x*, *X*) -The _Exploit Public_ substate reflects whether the method of exploiting +The *Exploit Public* substate reflects whether the method of exploiting a vulnerability has been made public in sufficient detail to be reproduced by others. Posting PoC code to a widely available site or including the exploit code in a commonly available exploit tool meets @@ -154,16 +154,16 @@ stateDiagram-v2 x --> X : exploit is public ``` -### The _Attacks Observed_ Substate (_a_, _A_) +### The *Attacks Observed* Substate (*a*, *A*) -The _Attacks Observed_ substate reflects whether attacks have been +The *Attacks Observed* substate reflects whether attacks have been observed in which the vulnerability was exploited. This substate requires evidence that the vulnerability was exploited; we can then presume the existence of exploit code regardless of its availability to the public. Analysis of malware from an incident might meet -_Attacks Observed_ but not _Exploit Public_, depending on how closely +*Attacks Observed* but not *Exploit Public*, depending on how closely the attacker holds the malware. Use of a public exploit in an attack -meets both _Exploit Public_ and _Attacks Observed_. +meets both *Exploit Public* and *Attacks Observed*. ```mermaid stateDiagram-v2 diff --git a/docs/topics/process_models/em/working_with_others.md b/docs/topics/process_models/em/working_with_others.md index 7dc06010..9ba539c7 100644 --- a/docs/topics/process_models/em/working_with_others.md +++ b/docs/topics/process_models/em/working_with_others.md @@ -9,9 +9,9 @@ As anyone who has tried to schedule a meeting with multiple attendees can attest, multi-party scheduling can be difficult. When that schedule must also accommodate work completion schedules for an MPCVD case, it becomes even harder. In [Default Embargoes](#default-embargoes), -we laid out a heuristic for resolving multiple embargo proposals, _The Shortest Embargo Proposed -Wins_. -More specifically, we recommended that Participants _accept_ the +we laid out a heuristic for resolving multiple embargo proposals, *The Shortest Embargo Proposed +Wins*. +More specifically, we recommended that Participants *accept* the earliest proposed end date and immediately propose and evaluate the rest as potential revisions. This principle applies to any MPCVD case, even at its outset. @@ -130,7 +130,7 @@ the new Participant to accept the embargo prior to receiving the report. In MPCVD there are practical considerations to be made regarding the timing of *when* to notify individual Participants. The primary factor in these decisions -stems from the interaction of the _Active_ embargo with the potential +stems from the interaction of the *Active* embargo with the potential Participant's existing (explicit or implicit) disclosure policy. ### Participants with Disclosure Policies Shorter Than an Existing Embargo @@ -181,9 +181,9 @@ options to choose from: 3. Avoid including the potential Participant in the embargo entirely. -In the case of a Vendor with a _longer_ default policy than the existing +In the case of a Vendor with a *longer* default policy than the existing embargo, it is still preferable to give them as much lead time as -possible _even_ if it is not possible to extend the embargo to their +possible *even* if it is not possible to extend the embargo to their preferred timing. !!! note "" @@ -240,7 +240,7 @@ vulnerability information. historical fact SHOULD be treated similar to Participants with brief disclosure policies. -!!! tip "My Adversary Is _Not Necessarily_ Your Adversary" +!!! tip "My Adversary Is *Not Necessarily* Your Adversary" Trustworthiness has a strong subjective component, and individual perspectives on who is or is not trustworthy can vary widely. @@ -292,7 +292,7 @@ However, it falls short in some cases, such as the following: ## Consequences of Non-Compliance Considering multiple cases over time, MPCVD can be thought of as an [iterated game](https://vuls.cert.org/confluence/display/CVD/5.5+Response+Pacing+and+Synchronization) analogous to the Prisoner's Dilemma. -One notable strategy for the Prisoner's Dilemma is _tit for tat_ in which non-cooperation from one party in one round +One notable strategy for the Prisoner's Dilemma is *tit for tat* in which non-cooperation from one party in one round can be met with non-cooperation from the opposite party in the next. While MPCVD is usually much bigger than a toy two-player game, we feel it is necessary to encode the possibility that non-cooperation will have downstream consequences. diff --git a/docs/topics/process_models/model_interactions/index.md b/docs/topics/process_models/model_interactions/index.md index fce82ab6..b4e5b676 100644 --- a/docs/topics/process_models/model_interactions/index.md +++ b/docs/topics/process_models/model_interactions/index.md @@ -48,12 +48,12 @@ stateDiagram-v2 ### Global vs. Participant-Specific Aspects of the CS Model The [CS model](../cs/index.md) encompasses both Participant-specific and Participant-agnostic aspects of a -CVD case. In particular, the Vendor fix path substates—Vendor unaware (_vfd_), -Vendor aware (_Vfd_), fix ready (_VFd_), and fix deployed (_VFD_)—are +CVD case. In particular, the Vendor fix path substates—Vendor unaware (*vfd*), +Vendor aware (*Vfd*), fix ready (*VFd*), and fix deployed (*VFD*)—are specific to each Vendor Participant in a case. On the other hand, the remaining substates represent Participant-agnostic facts about the case -status—public awareness (_p,P_), exploit public (_x,X_), and attacks -observed (_a,A_). This distinction in perspectives will become +status—public awareness (*p,P*), exploit public (*x,X*), and attacks +observed (*a,A*). This distinction in perspectives will become important in the [Formal Protocol](../../formal_protocol/index.md) definition. {% include-markdown "./cs_global_local.md" %} diff --git a/docs/topics/process_models/model_interactions/rm_em_cs.md b/docs/topics/process_models/model_interactions/rm_em_cs.md index b2f81e03..015c19dc 100644 --- a/docs/topics/process_models/model_interactions/rm_em_cs.md +++ b/docs/topics/process_models/model_interactions/rm_em_cs.md @@ -24,7 +24,7 @@ As a reminder, a list of the CS model transition symbols is reproduced in the in $$q^{cs} \in vfd\cdot\cdot\cdot \xrightarrow{\mathbf{V}} Vfd\cdot\cdot\cdot$$ Vendor Awareness (**V**) occurs when a Participant—typically a -Finder, Coordinator, or another Vendor—is in RM _Accepted_ and notifies the Vendor. +Finder, Coordinator, or another Vendor—is in RM *Accepted* and notifies the Vendor. In turn, the Vendor starts in $q^{rm} = Received$ and proceeds to follow their validation and prioritization routines. We previously outlined this in [RM Interactions Between CVD Participants](../rm/rm_interactions.md). @@ -120,7 +120,7 @@ stateDiagram-v2 ## Fix Ready {#sec:cs_f_em} Fix Readiness (**F**) can occur only when a Vendor is in the -_Accepted_ state. As a reminder, in MPCVD cases, each affected Vendor has their own +*Accepted* state. As a reminder, in MPCVD cases, each affected Vendor has their own [RM](../rm/index.md) state, so this constraint applies to each Vendor individually. --- @@ -258,8 +258,8 @@ stateDiagram-v2 Revise \xrightarrow{terminate} eXited \\ \end{cases}$$ -As with the _Fix Ready_ scenario [above](#sec:cs_f_em), MPCVD cases may have Vendors in varying states of _Fix Deployment_. -Therefore the embargo extension caveats from that section apply to the _Fix Deployed_ state as well. +As with the *Fix Ready* scenario [above](#sec:cs_f_em), MPCVD cases may have Vendors in varying states of *Fix Deployment*. +Therefore the embargo extension caveats from that section apply to the *Fix Deployed* state as well. ## Public Awareness @@ -267,10 +267,10 @@ Within the context of a coordinated publication process, (**P**) requires at least one Participant to be in the $q^{rm} = Accepted$ state because Participants are presumed to publish only on cases they have accepted. Ideally, the Vendor is among those Participants, but as -outlined in the [_CERT Guide to Coordinated Vulnerability Disclosure_](https://vuls.cert.org/confluence/display/CVD), +outlined in the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD), that is not strictly necessary. -That said, the publishing party might be outside of _any_ existing +That said, the publishing party might be outside of *any* existing coordination process. For example, this is the situation when a report is already in the midst of a CVD process and a party outside the CVD case reveals the vulnerability publicly (e.g., parallel discovery, embargo leaks). @@ -325,7 +325,7 @@ stateDiagram-v2 ## Exploit Public Exploit publishers may also be presumed to have a similar [RM](../rm/index.md) state model for their own work. -Therefore, we can expect them to be in an RM _Accepted_ state at the time of exploit code publication (**X**). +Therefore, we can expect them to be in an RM *Accepted* state at the time of exploit code publication (**X**). However, we cannot presume that those who publish exploit code will be Participants in a pre-public CVD process. That said, diff --git a/docs/topics/process_models/rm/index.md b/docs/topics/process_models/rm/index.md index cd1780a0..9ecddc30 100644 --- a/docs/topics/process_models/rm/index.md +++ b/docs/topics/process_models/rm/index.md @@ -57,9 +57,9 @@ the state names. Each Participant in a CVD case will have their own RM state. in [Case State Model](../cs/index.md). Further discussion of the interactions of the RM and CS models is found in [Model Interactions](../model_interactions/index.md). -#### The _Start_ (_S_) State +#### The *Start* (*S*) State -The _Start_ state is a simple placeholder state for reports that have +The *Start* state is a simple placeholder state for reports that have yet to be received. It is, in effect, a null state that no CVD Participant would be expected to reflect in their report tracking system. We include it here because it is useful when modeling coordination @@ -72,9 +72,9 @@ stateDiagram-v2 [*] --> Start ``` -#### The _Received_ (_R_) State +#### The *Received* (*R*) State -Reports initially arrive in the _Received_ state. +Reports initially arrive in the *Received* state. ```mermaid stateDiagram-v2 @@ -101,12 +101,12 @@ are not capable of coordinating vulnerability disclosures. Hence, Coordinators MUST have a clearly defined and publicly available mechanism for receiving reports. -Exiting the _Received_ state requires a Participant to assess the +Exiting the *Received* state requires a Participant to assess the validity of a report. Note that validation is distinct from -prioritization, as covered in our description of the [_Valid_](#the-valid-v-state) state. -In other words, the _Received_ state corresponds to the +prioritization, as covered in our description of the [*Valid*](#the-valid-v-state) state. +In other words, the *Received* state corresponds to the [Validation phase](https://vuls.cert.org/confluence/display/CVD/4.3+Validation+and+Triage) -of the [_CERT Guide to Coordinated Vulnerability Disclosure_](https://vuls.cert.org/confluence/display/CVD). +of the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD). !!! note "" @@ -117,10 +117,10 @@ of the [_CERT Guide to Coordinated Vulnerability Disclosure_](https://vuls.cert. Validity criteria need not be limited to technical analysis. For instance, a Coordinator might only accept reports within their specific scope of concern and consider reports outside their scope to be -_Invalid_ even if they believe the report accurately describes a real +*Invalid* even if they believe the report accurately describes a real vulnerability. Alternatively, a Vendor might institute a policy designating reports unaccompanied by a working proof-of-concept exploit -as _Invalid_ by default. +as *Invalid* by default. !!! note "" @@ -160,12 +160,12 @@ as _Invalid_ by default. Participants MAY create a case object to track any report in the _Received_ state. -#### The _Invalid_ (_I_) State +#### The *Invalid* (*I*) State -Reports in the _Invalid_ state have been evaluated and found lacking by +Reports in the *Invalid* state have been evaluated and found lacking by the recipient. This state allows time for the Reporter to provide additional information and for the receiver to revisit the validation -before moving the report to _Closed_. +before moving the report to *Closed*. ```mermaid stateDiagram-v2 @@ -177,7 +177,7 @@ stateDiagram-v2 The reasons for a report to be put in this state will vary based on each recipient's validation criteria, and their technical capability and -available resources. The _Invalid_ state is intended to be used as a +available resources. The *Invalid* state is intended to be used as a temporary holding place to allow for additional evidence to be sought to contradict that conclusion. @@ -197,15 +197,15 @@ contradict that conclusion. Participants MAY set a timer to move reports from _Invalid_ to _Closed_ after a set period of inactivity. -#### The _Valid_ (_V_) State +#### The *Valid* (*V*) State -Reports in the _Valid_ state are ready to be prioritized for possible +Reports in the *Valid* state are ready to be prioritized for possible future work. The result of this prioritization process will be to either accept the report for follow-up or defer further effort. -The _Valid_ state is equivalent to the [Prioritization +The *Valid* state is equivalent to the [Prioritization (Triage)](https://vuls.cert.org/confluence/display/CVD/4.3+Validation+and+Triage) phase -of the [_CERT Guide to Coordinated Vulnerability Disclosure_](https://vuls.cert.org/confluence/display/CVD). -As an example, a Vendor might later choose to _defer_ further response on a _Valid_ report due to other priorities. +of the [*CERT Guide to Coordinated Vulnerability Disclosure*](https://vuls.cert.org/confluence/display/CVD). +As an example, a Vendor might later choose to *defer* further response on a *Valid* report due to other priorities. ```mermaid stateDiagram-v2 @@ -254,13 +254,13 @@ action". [SSVC Crosswalk](../../../reference/ssvc_crosswalk.md) takes a closer look at how SSVC fits into the protocol we are defining. -#### The _Accepted_ (_A_) State +#### The *Accepted* (*A*) State -The _Accepted_ state is where the bulk of the work for a given +The *Accepted* state is where the bulk of the work for a given CVD Participant occurs. Reports reach this state for a Participant only once the Participant has deemed the report to be both valid and of sufficient -priority to warrant further action. The _Accepted_ state has a different +priority to warrant further action. The *Accepted* state has a different meaning for each different Participant. ```mermaid @@ -274,7 +274,7 @@ stateDiagram-v2 Valid --> Accepted ``` -- For our purposes, Finders/Reporters enter the _Accepted_ state only +- For our purposes, Finders/Reporters enter the *Accepted* state only for reports that they intend to put through the CVD process. If they have no intention of pursuing CVD, there is no need for them to track @@ -287,7 +287,7 @@ stateDiagram-v2 them, and possibly negotiate embargoes. We provide additional elaboration on the sorts of activities that might -happen in the _Accept_ state in [Do Work Behavior](../../behavior_logic/do_work_bt.md). +happen in the *Accept* state in [Do Work Behavior](../../behavior_logic/do_work_bt.md). !!! note "" @@ -295,11 +295,11 @@ happen in the _Accept_ state in [Do Work Behavior](../../behavior_logic/do_work_ in its lifespan as a Participant resumes or pauses work (i.e., transitions to/from the _Deferred_ state). -#### The _Deferred_ (_D_) State +#### The *Deferred* (*D*) State -The _Deferred_ state is reserved for valid, unclosed reports that are -otherwise not being actively worked on (i.e., those in _Accepted_). It -parallels the _Invalid_ state for reports that fail to meet the +The *Deferred* state is reserved for valid, unclosed reports that are +otherwise not being actively worked on (i.e., those in *Accepted*). It +parallels the *Invalid* state for reports that fail to meet the necessary validation criteria in that both states are awaiting closure once it is determined that no further action is necessary. @@ -317,7 +317,7 @@ stateDiagram-v2 Deferred --> Accepted ``` -For example, a Participant might use the _Deferred_ state when a valid +For example, a Participant might use the *Deferred* state when a valid report fails to meet their [prioritization criteria](#prioritize-report), or when a higher priority task takes precedence over an active case. @@ -338,12 +338,12 @@ precedence over an active case. state to ensure they are moved to _Closed_ after a set period of inactivity. -#### The _Closed_ (_C_) State +#### The *Closed* (*C*) State -The _Closed_ state implies no further work is to be done; therefore, any +The *Closed* state implies no further work is to be done; therefore, any pre-closure review (e.g., for quality assurance purposes) should be -performed before the case moves to the _Closed_ state (i.e., while the -report is in _Invalid_, _Deferred_, or _Accepted_). +performed before the case moves to the *Closed* state (i.e., while the +report is in *Invalid*, *Deferred*, or *Accepted*). ```mermaid stateDiagram-v2 @@ -421,9 +421,9 @@ protocol. Every state transition implies a different message type. ##### Receive Report -To begin, a Participant must receive a report. Recall that the _Start_ +To begin, a Participant must receive a report. Recall that the *Start* state is a placeholder, so this action simply puts the receiving -Participant into the _Received_ state at the beginning of their +Participant into the *Received* state at the beginning of their involvement in the case. ```mermaid @@ -437,13 +437,13 @@ stateDiagram-v2 ##### Validate Report -The Participant must validate the report to exit the _Received_ state. +The Participant must validate the report to exit the *Received* state. Depending on the validation outcome, the report will be in either the -_Valid_ or _Invalid_ state. _Invalid_ reports are often waiting for +*Valid* or *Invalid* state. *Invalid* reports are often waiting for additional information from the reporter, but they may also be reports that are not in scope for the Participant. Some Participants may choose -to close _Invalid_ reports immediately, while others may choose to -periodically revalidate them to see if they have become _Valid_. +to close *Invalid* reports immediately, while others may choose to +periodically revalidate them to see if they have become *Valid*. !!! note "" @@ -485,7 +485,7 @@ stateDiagram-v2 ##### Prioritize Report Once a report has been validated (i.e., it is in the -RM _Valid_ state, +RM *Valid* state, $q^{rm} \in V$), the Participant must prioritize it to determine what further effort, if any, is necessary. @@ -495,13 +495,13 @@ further effort, if any, is necessary. Our [SSVC Crosswalk](../../../reference/ssvc_crosswalk.md) contains an example of how the SSVC model can be applied here, although any prioritization scheme could be substituted. -Prioritization ends with the report in either the _Accepted_ or _Deferred_ state. +Prioritization ends with the report in either the *Accepted* or *Deferred* state. -A Participant might choose to pause work on a previously _Accepted_ +A Participant might choose to pause work on a previously *Accepted* report after revisiting their prioritization decision. When this -happens, the Participant moves the report to the _Deferred_ state. -Similarly, a Participant might resume work on a _Deferred_ report, -moving it to the _Accepted_ state. +happens, the Participant moves the report to the *Deferred* state. +Similarly, a Participant might resume work on a *Deferred* report, +moving it to the *Accepted* state. !!! note "" @@ -548,10 +548,10 @@ stateDiagram-v2 Some Participants (e.g., Finders and Coordinators) need to engage someone else (e.g., a Vendor) to resolve a case. To do this, the -_sender_ Participants must also be in the _Accepted_ state; otherwise, +*sender* Participants must also be in the *Accepted* state; otherwise, why are they working on the case? In the following diagram, we show the interaction between two -instances of the RM model: the left side represents the _sender_ while the right side represents the _recipient_. -Although the _sender_'s state does not change, the _recipient_'s state moves from _Start_ to _Received_. +instances of the RM model: the left side represents the *sender* while the right side represents the *recipient*. +Although the *sender*'s state does not change, the *recipient*'s state moves from *Start* to *Received*. !!! note "" @@ -578,8 +578,8 @@ stateDiagram-v2 ##### Case Closure -Finally, a Participant can complete work on an _Accepted_ report or -abandon further work on an _Invalid_ or _Deferred_ report. +Finally, a Participant can complete work on an *Accepted* report or +abandon further work on an *Invalid* or *Deferred* report. !!! note "" @@ -596,15 +596,15 @@ stateDiagram-v2 Invalid --> Closed: close ``` -Our model assumes that _Valid_ reports cannot be closed directly without -first passing through either _Accepted_ or _Deferred_. It is reasonable -to wonder why _close_ is not a valid transition from the _Valid_ state. +Our model assumes that *Valid* reports cannot be closed directly without +first passing through either *Accepted* or *Deferred*. It is reasonable +to wonder why *close* is not a valid transition from the *Valid* state. The answer is that we wanted to allow prioritization and closure to be distinct activities; deferral is reversible, whereas closure is not. -Often a Participant might initially _defer_ a case only to resume work +Often a Participant might initially *defer* a case only to resume work later, once more information has arrived. However, there is nothing -stopping a Participant from instituting a process that goes from _Valid_ -to _Deferred_ to _Closed_ in rapid (even immediate) succession. +stopping a Participant from instituting a process that goes from *Valid* +to *Deferred* to *Closed* in rapid (even immediate) succession. !!! note "" @@ -629,12 +629,12 @@ to _Deferred_ to _Closed_ in rapid (even immediate) succession. The strings generated in the language defined by this grammar can be useful for exploring the possible sequences of states each report might -encounter for each Participant. The 15 shortest paths are _ric_, _rvac_, -_rvdc_, _rivac_, _rivdc_, _rvadc_, _rvdac_, _rivadc_, _rvadac_, -_rvdadc_, _rivdac_, _rivdadc_, _rvdadac_, _rivadac_, and _rvadadc_. Due +encounter for each Participant. The 15 shortest paths are *ric*, *rvac*, +*rvdc*, *rivac*, *rivdc*, *rvadc*, *rvdac*, *rivadc*, *rvadac*, +*rvdadc*, *rivdac*, *rivdadc*, *rvdadac*, *rivadac*, and *rvadadc*. Due to the structure of the RM DFA, longer strings just add more -_defer_-_accept_ (_da_) or _accept_-_defer_ (_ad_) cycles prior to -closure (_c_). The usually limited duration of the +*defer*-*accept* (*da*) or *accept*-*defer* (*ad*) cycles prior to +closure (*c*). The usually limited duration of the RM process coupled with the tendency for CVD Participants to prefer to avoid frequent starts and stops means that we expect the vast majority of reports to diff --git a/docs/topics/process_models/rm/rm_interactions.md b/docs/topics/process_models/rm/rm_interactions.md index 61020904..8c25bb57 100644 --- a/docs/topics/process_models/rm/rm_interactions.md +++ b/docs/topics/process_models/rm/rm_interactions.md @@ -4,7 +4,7 @@ Each Participant in a case has their own instance of the RM state model. Participants can change their local state independent of the state of other Participants. Events within a CVD case may trigger a state transition in one Participant while no transition occurs in another. For example, in [particpants interact from the accepted state](#participants-interact-from-the-accepted-state) we showed -that even though the _sender_ is the one taking the action, it is the _recipient_'s state that changes. +that even though the *sender* is the one taking the action, it is the *recipient*'s state that changes. The table below lists role-based actions. | Finder/Reporter | Vendor | Coordinator | Action | RM Transition | @@ -25,15 +25,15 @@ A few examples of this model applied to common CVD and MPCVD case scenarios foll ## The Secret Lives of Finders -While the Finder's _Received_, _Valid_, and _Invalid_ states are useful +While the Finder's *Received*, *Valid*, and *Invalid* states are useful for modeling and simulation purposes, they are less useful to us as part of a potential CVD protocol. Why? Because for anyone else to know about the vulnerability (and as a prerequisite to CVD happening at all), the Finder must have already validated the report and prioritized it as worthy of further effort to have any reason to attempt to coordinate its disclosure. In -other words, CVD only starts _after_ the Finder has already reached the -_Accepted_ state for any given vulnerability to be reported. -Correspondingly, this also represents their transition from _Finder_ to +other words, CVD only starts *after* the Finder has already reached the +*Accepted* state for any given vulnerability to be reported. +Correspondingly, this also represents their transition from *Finder* to *Reporter*. Nevertheless, for now, we retain these states for completeness. We revisit this topic in our [formal derivation](../../../reference/formal_protocol/states.md#finder-reporters) @@ -80,8 +80,8 @@ stateDiagram-v2 A simple Finder-Vendor CVD scenario is shown below. As explained [above](#the-secret-lives-of-finders), many of the Finder's states would be -hidden from view until they reach the _Accepted_ ($A_f$) state. The -_receive_ action bridging $A_f \xrightarrow{r} R_v$ corresponds to the +hidden from view until they reach the *Accepted* ($A_f$) state. The +*receive* action bridging $A_f \xrightarrow{r} R_v$ corresponds to the [participants interact from the accepted state](#participants-interact-from-the-accepted-state) scenario above. ```mermaid diff --git a/docs/topics/user_stories/index.md b/docs/topics/user_stories/index.md index 2a02b37a..1b49a3d4 100644 --- a/docs/topics/user_stories/index.md +++ b/docs/topics/user_stories/index.md @@ -30,14 +30,14 @@ Where appropriate, we intend to provide a reference implementation for each appl Each story page indicates a categorization according to the level of support provided by the originally published Vultron Protocol (version 0.4.0): -- _Provided_ - Stories in this category are directly supported by the Vultron Protocol v0.4.0. -- _Allowed_ - Stories in this category are indirectly supported by the Vultron Protocol v0.4.0. -- _Unsupported_ - Stories in this category are not supported by the Vultron Protocol v0.4.0. -- _Out-of-scope_ - Stories in this category are out of scope for the Vultron Protocol v0.4.0. +- *Provided* - Stories in this category are directly supported by the Vultron Protocol v0.4.0. +- *Allowed* - Stories in this category are indirectly supported by the Vultron Protocol v0.4.0. +- *Unsupported* - Stories in this category are not supported by the Vultron Protocol v0.4.0. +- *Out-of-scope* - Stories in this category are out of scope for the Vultron Protocol v0.4.0. -In the future, we expect these categories will change toward simply _Supported_, _Unsupported_ and _Out-of-scope_. +In the future, we expect these categories will change toward simply *Supported*, *Unsupported* and *Out-of-scope*. We also anticipate that as we learn more about ActivityPub and make progress on the protocol development, some of -the stories in the _Unsupported_ category could move to _Supported_. +the stories in the *Unsupported* category could move to *Supported*. ## User Stories Table