Skip to content

Commit

Permalink
Markdownlint cli2 (#32)
Browse files Browse the repository at this point in the history
* improve markdown lint config for emphasis and strong

* Run markdownlint on content

markdownlint-cli2 --config .markdownlint-cli2.yaml --fix "**/*.md" "#node_modules"
  • Loading branch information
ahouseholder authored Nov 30, 2023
1 parent 24eac5d commit 719b061
Show file tree
Hide file tree
Showing 26 changed files with 300 additions and 296 deletions.
4 changes: 4 additions & 0 deletions .markdownlint-cli2.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,8 @@ config:
"MD033": false
"MD041": false
"MD046": false
"MD049":
style: "asterisk"
"MD050":
style: "asterisk"
"MD051": false
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/howto/case_object.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
24 changes: 12 additions & 12 deletions docs/howto/em_icalendar.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,15 +23,15 @@ A mapping of EM concepts to `iCalendar` field mappings is provided in the table
| Embargo ID | `SUMMARY:<case id> embargo expiration` | - |
| Embargo End Time and Date | `DSTART = DTEND` (0 duration event) | - |
| Proposer | `ORGANIZER` | - |
| Participant (proposed) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=NEEDS-ACTION` | _EP_, _EV_ |
| Participant (acknowledge without acceptance) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=TENTATIVE` | _EK_ |
| Participant (accept) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=ACCEPTED` | _EA_, _EC_ |
| Participant (reject) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=DECLINED` | _ER_, _EJ_ |
| Participant (proposed) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=NEEDS-ACTION` | *EP*, *EV* |
| Participant (acknowledge without acceptance) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=TENTATIVE` | *EK* |
| Participant (accept) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`PARTSTAT=ACCEPTED` | *EA*, *EC* |
| Participant (reject) | `ATTENDEE;`<br/>`ROLE=OPT-PARTICIPANT;`<br/>`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`<br/>`RSVP: TRUE` | - |

!!! note ""
Expand Down Expand Up @@ -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).
Expand All @@ -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
Expand Down
32 changes: 16 additions & 16 deletions docs/howto/process_implementation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/formal_protocol/conclusion.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/reference/formal_protocol/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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.

Expand Down
16 changes: 8 additions & 8 deletions docs/reference/formal_protocol/states.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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 *)$$

Expand All @@ -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 *$$

Expand Down Expand Up @@ -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$$

Expand Down Expand Up @@ -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.
Expand Down
Loading

0 comments on commit 719b061

Please sign in to comment.