From 4128a1f4fe4a2aff9cff21b316be98908b3b4396 Mon Sep 17 00:00:00 2001 From: "Allen D. Householder" Date: Wed, 27 Sep 2023 10:58:28 -0400 Subject: [PATCH] Feature/bootstrapping docs (#308) * Create bootstrapping docs * add feature/* deploy_site.yml * Update deploy_site.yml * revise diagrams --- docs/howto/bootstrap/collect.md | 45 ++++++ docs/howto/bootstrap/index.md | 24 +++ docs/howto/bootstrap/prepare.md | 234 ++++++++++++++++++++++++++++ docs/howto/bootstrap/steps_table.md | 6 + docs/howto/bootstrap/summary.md | 99 ++++++++++++ docs/howto/bootstrap/use.md | 84 ++++++++++ mkdocs.yml | 6 + 7 files changed, 498 insertions(+) create mode 100644 docs/howto/bootstrap/collect.md create mode 100644 docs/howto/bootstrap/index.md create mode 100644 docs/howto/bootstrap/prepare.md create mode 100644 docs/howto/bootstrap/steps_table.md create mode 100644 docs/howto/bootstrap/summary.md create mode 100644 docs/howto/bootstrap/use.md diff --git a/docs/howto/bootstrap/collect.md b/docs/howto/bootstrap/collect.md new file mode 100644 index 00000000..10707ac6 --- /dev/null +++ b/docs/howto/bootstrap/collect.md @@ -0,0 +1,45 @@ +# Data Operations + +!!! note inline end + + The diagram below shows two kinds of data emanating from the Data Operations process: _Vulnerability Data_ and _Environment Data_. + Vulnerability Data is data about the vulnerability itself, such as the technical impact or exploit availability. + Environment Data is data about the environment in which the vulnerable systems exist, such as network topology or system criticality. + We generally expect that Environment Data will be more stable than Vulnerability Data, but that is not always the case. + +While the actual collection of operational data is outside the scope of SSVC, it is an important part of any implementation +of the process. +SSVC is designed to be flexible enough to accommodate a variety of data collection methods. +The [Data Mapping](prepare.md#data-mapping) step defines the data that is needed to assign a value to each decision point. +The Data Operations process collects that data so that it can be used to assign values to decision points in the +[Use SSVC](use.md) step. + +We include a feedback loop on the data collection node to indicate that it is expected to be a continuous process. + +```mermaid +flowchart LR + subgraph dmp[Data Mapping] + dd[/Data Definition/] + end + subgraph do[Data Operations] + cd[Collect Data] + vd[/Vulnerability Data/] + ed[/Environment Data/] + dt[\Available Data/] + end + dd --> cd + cd --> cd + cd --> vd + cd --> ed + vd --> dt + ed --> dt +``` + +!!! example + + Having defined a data map that translates certain values from specific threat feeds to the _Exploitation_ decision + point values _PoC_ or _Active_, an organization maintains a subscription to those threat feeds and collects the + data from them on a continuous basis. + They also write a script that parses the data from the threat feeds and applies the data map to assign a value to + the _Exploitation_ decision point. + diff --git a/docs/howto/bootstrap/index.md b/docs/howto/bootstrap/index.md new file mode 100644 index 00000000..b31ab0b8 --- /dev/null +++ b/docs/howto/bootstrap/index.md @@ -0,0 +1,24 @@ +# Bootstrapping an SSVC Process from Scratch + +Using SSVC to prioritize vulnerability response requires a few steps. The steps are: + +!!! note inline end "Bootstrapping SSVC Overview" + + ```mermaid + flowchart + start([Start]) + prep[Prepare to use SSVC] + dataops[Data Operations] + runtime[Use SSVC] + r[Vulnerability Response] + start --> prep + prep --> dataops + dataops --> runtime + runtime --> r + r --> dataops + ``` + +{% include-markdown "howto/bootstrap/steps_table.md" %} + +We cover each of these in the following sections, starting with [Prepare to Use SSVC](prepare.md). +If you want to skip ahead to the full process, see [Bootstrapping SSVC Summary](summary.md). \ No newline at end of file diff --git a/docs/howto/bootstrap/prepare.md b/docs/howto/bootstrap/prepare.md new file mode 100644 index 00000000..bd6132c8 --- /dev/null +++ b/docs/howto/bootstrap/prepare.md @@ -0,0 +1,234 @@ +# Prepare to Use SSVC + +Preparing to use SSVC involves defining a decision you want to make, +the information you need to make that decision, and the policy you want to use to make that decision. + +Here is a diagram of the preparation process: + +```mermaid +flowchart + subgraph prep [Prepare to use SSVC] + dcd{{Choose Decision to Model}} + outcomes[Define Outcomes] + decisionpoints[Define Inputs] + dataeng[Data Mapping] + dm[/Data Map/] + policy[Policy Development] + p[/Policy/] + end + dcd --> outcomes + outcomes --> decisionpoints + dcd --> decisionpoints + decisionpoints --> dataeng + outcomes --> policy + decisionpoints --> policy + policy --> p + dataeng --> dm +``` + +We will go through each step in detail. + +## Choose a Decision to Model + +!!! example inline end + + Decisions we have modeled with SSVC include: + + - [Patch Supplier Prioritization](supplier_tree.md) + - [Patch Deployer Prioritization](deployer_tree.md) + - [Coordinator Triage](coordinator_trees.md) + - [Coordinator Publication](coordinator_publish_tree.md) + +The first step in preparing to use SSVC is to choose a decision to model. +SSVC is designed to help you make decisions about how to respond to a vulnerability. +In the SSVC documentation, we provide a number of example decisions that you might want to make. +You can use one of these decisions, or you can define your own decision. + + +
+ +```mermaid +flowchart LR + subgraph dd[Choose Decision] + dcd{{Choose Decision to Model}} + d[/Decision/] + end + dcd --> d +``` + +## Define Outcomes + +!!! example inline end + + In the [Patch Supplier](supplier_tree.md) and [Patch Deployer](deployer_tree) prioritization examples, the outcomes are: + _Defer_, _Scheduled_, _Out-of-Cycle_, and _Immediate_. In the [Coordinator Triage](coordinator_trees.md) example, + the outcomes are _Coordinate_, _Track_, and _Decline_. In the [Coordinator Publication](coordinator_publish_tree.md) example, + the outcomes are _Publish_ and _Do Not Publish_. + +Once you have chosen a decision to model, you need to define the outcomes for that decision. +An outcome is the result of making a decision. +Outcomes are often tailored specifically to the stakeholder context in which the decision is being made. +We call the set of possible outcomes for a decision an outcome set. + +We have provided a number of example outcome sets in the SSVC documentation, but you can define your own outcome set to meet your needs. + +```mermaid +flowchart LR + subgraph dd[Choose Decision] + d[/Decision/] + end + subgraph outcomes [Define Outcomes] + oc1[/Use available
outcome sets?\] + dos{{Define Outcome Sets}} + oss[\Outcome Sets/] + cos{{Choose Outcome Set}} + os[/Outcome Set/] + end + d --> oc1 + oc1 -->|y| oss + oc1 -->|n| dos + dos --> oss + cos --> os + oss --> cos +``` + +!!! example + + Imagine two different Service Providers, each of which is responsible for managing vulnerabilities in their + respective environments. + One Service Provider might use a 5-tier incident response model, and so might define their outcome set as: + _Severity 1_, _Severity 2_, _Severity 3_, _Severity 4_, and _Severity 5_. + Another Service Provider might only have three tiers, and so might define their outcome set as: + _High_, _Medium_, and _Low_. + So even though both Service Providers are making the same prioritization decision about their response to the same, + vulnerability, they can use different outcome sets. + +## Define Inputs + +Once you know what decision you want to make and what the possible outcomes are, you need to define the information you need to make that decision. +A decision usually requires more than one piece of information. +SSVC organizes this information into decision points. +A single decision point enumerates a set of options for a particular aspect of the decision. +We have defined a number of decision points in the [SSVC documentation](../reference/decision_points/index.md). +You can choose from these decision points, or you can define your own decision points to meet your needs. + +Whether you choose from the existing decision points or define your own, the set of decision points you use to make a +decision is called a {== decision point set TODO RENAME? ==}. + +```mermaid +flowchart LR + subgraph dd[Choose Decision] + d[/Decision/] + end + subgraph do[Define Outcomes] + oc[/Outcome Set/] + end + + subgraph decisionpoints [Define Inputs] + dp1[/Use available
decision points?\] + ddp{{Define Decision Points}} + dpt[\Decision Points/] + cdp{{Choose Decision Points}} + dps[/Decision Point Set/] + end + oc --> dp1 + d --> dp1 + + dp1 -->|y| dpt + dp1 -->|n| ddp + ddp --> dpt + dpt --> cdp + cdp --> dps +``` + +!!! example + + A medical device manufacturer has specific regulatory requirements for how they respond to vulnerabilities. + As an organization, they have divided their product line into three categories: regulated devices, non-regulated devices, and support services. + Vulnerability reports for regulated devices are handled differently than vulnerability reports for + non-regulated devices. Also, vulnerability reports for support services are handled differently than vulnerability + reports for devices of any kind because support services are covered by medical privacy regulations in addition to + device safety regulations. So, the medical device manufacturer might define a decision point called _Regulated_ with + the values _Regulated Device_, _Non-Regulated Device_, and _Support Service_. + + +## Define Policy + +So far, you have chosen a decision to model, defined the possible outcomes for that decision, and defined the information you need to make that decision. +Now, you need to define the policy you want to use to make that decision. +A policy is a function that takes a set of decision point values as input and returns an outcome as output. +While we often choose to represent policies as decision trees, they can be represented in other ways as well. +In fact, we find that it is often useful to represent policies in tabular form, for example as a CSV file. +We have provided a number of example policies in the [SSVC documentation](../prioritization.md), but you can define your own policy to meet your needs. + +```mermaid +flowchart LR + subgraph do[Define Outcomes] + oc[/Outcome Set/] + end + subgraph di [Define Inputs] + dps[/Decision Point Set/] + end + subgraph policy [Policy Development] + dfp{{Define Policy}} + p[/Policy/] + end + oc --> dfp + dps --> dfp + dfp --> p +``` + +!!! example + + A small bank has a policy that they must deploy patches within 48 hours of release if the vulnerability affects systems + that could lead to customer data being exposed. They examine the example [Deployer Prioritization](supplier_tree.md) + decision model and decide that both the outcome set and the decision point set that define the structure of the + decision model are appropriate for their needs. They map the 48 hour requirement to the _Immediate_ outcome, because + it essentially represents their highest priority response. + However, they notice that the specific policy given in the [Deployer Prioritization](supplier_tree.md) + example—that is, the mapping from decision point values to outcomes—is not appropriate for their needs + because it has too few _Immediate_ outcomes to suit their policy. + Therefore, the bank decides to reuse the same decision point set and outcome set but define their own policy. + +## Data Mapping + +In SSVC, data mapping is the process of defining what data can be used to assign a value to each decision point. +The resulting data map indicates which data sources are relevant to each decision point, and how to interpret the data +from each data source to assign a value to the decision point. + +```mermaid +flowchart LR + subgraph di[Define Inputs] + dps[/Decision Point Set/] + end + subgraph dataeng [Data Mapping] + dd1[/Use existing data?\] + dpm[/Data Map/] + dp2d{{Map Decision Points to Data}} + dd{{Define Data}} + ddf[/Data Definition/] + end + dps --> dd1 + dps --> dp2d + dd1 -->|y| ddf + dd1 -->|n| dd + dd --> ddf + ddf --> dp2d + dp2d --> dpm +``` + +!!! example + + A Software-as-a-Service Provider differentiates its service levels into three categories: silver, gold, and platinum. + In the [Define Inputs](#define-inputs) step, they defined a custom decision point called _Service Level_ with the values + _Silver_, _Gold_, and _Platinum_. + Now, they need to define a data map that will assign a value to the _Service Level_ decision point. + The data they need to assign a value to the _Service Level_ decision point originates in the service level + agreement (SLA) for each service. + These SLAs are stored in a database. + They decide to write a script that will query the database for the SLA for each service and assign a value to the + _Service Level_ decision point based on the SLA. + As these SLAs do not change very often, they decide to run the script once a day and store the results in a file. + They define a data map that indicates that the data source for the _Service Level_ decision point is the file + containing the SLA data, and document that the script they wrote will assign a value to the _Service Level_ decision + point based on the SLA data. diff --git a/docs/howto/bootstrap/steps_table.md b/docs/howto/bootstrap/steps_table.md new file mode 100644 index 00000000..baf712d4 --- /dev/null +++ b/docs/howto/bootstrap/steps_table.md @@ -0,0 +1,6 @@ +| Step | Description | +| ---- |-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [**Prepare**](prepare.md) | Define the decision you want to make, the outcomes you care about, the decision points you will use to make the decision, the decision policy, and the data you need to inform the decision points. | +| [**Collect**](collect.md) | Collect the data you need to make informed decisions. | +| [**Use SSVC**](use.md) | Use SSVC to make decisions about how to respond to vulnerabilities. | +| [**Respond**](use.md#respond-to-vulnerabilities) | Respond to vulnerabilities according to the prioritization. | diff --git a/docs/howto/bootstrap/summary.md b/docs/howto/bootstrap/summary.md new file mode 100644 index 00000000..48b26486 --- /dev/null +++ b/docs/howto/bootstrap/summary.md @@ -0,0 +1,99 @@ +# Bootstrapping SSVC Summary + +Using SSVC to prioritize vulnerability response requires a few steps. The steps are: + +{% include-markdown "howto/bootstrap/steps_table.md" %} + +We covered each of these in the previous sections, see the links in the table above for more information. + +The diagram below shows the complete process of using SSVC. + + +```mermaid +flowchart +start([Start]) +subgraph prep [Prepare to use SSVC] + dcd{{Choose Decision to Model}} + d[/Decision/] + subgraph outcomes [Define Outcomes] + oc1[/Use available
outcome sets?\] + dos{{Define Outcome Sets}} + oss[\Outcome Sets/] + cos{{Choose Outcome Set}} + os[/Outcome Set/] + end + subgraph decisionpoints [Define Inputs] + dp1[/Use available
decision points?\] + ddp{{Define Decision Points}} + dpt[\Decision Points/] + cdp{{Choose Decision Points}} + dps[/Decision Point Set/] + end + subgraph dataeng [Data Mapping] + dd1[/Use existing data?\] + dpm[/Data Map/] + dp2d{{Map Decision Points to Data}} + dd{{Define Data}} + ddf[/Data Definition/] + end + subgraph policy [Policy Development] + dfp{{Define Policy}} + p[/Policy/] + end +end +subgraph dataops [Data Operations] + cd[Collect Data] + vd[/Vulnerability Data/] + ed[/Environment Data/] + dt[\Available Data/] + +end +subgraph runtime [Use SSVC] + mdp[[Apply Decision Point Mapping to Data]] + dp[/Decision Point Values/] + ap[[Apply Policy]] + oc[/Outcome/] +end +r[Vulnerability Response] +start --> dcd +dcd --> d +d --> oc1 +dps --> dd1 +oc1 -->|y| oss +oc1 -->|n| dos +dp1 -->|y| dpt +dp1 -->|n| ddp +dd1 -->|y| ddf +dd1 -->|n| dd +ddp --> dpt +dos --> oss +dpt --> cdp +cdp --> dps +cos --> os +oss --> cos +os --> dfp +os --> dp1 +d --> dp1 +dps --> dp2d +dp2d --> dpm +dps --> dfp +dpm --> mdp +dd --> ddf +ddf --> dp2d +ddf --> cd +cd --> cd +cd --> vd +cd --> ed +vd --> dt +ed --> dt +dt --> mdp +mdp --> dp +dfp --> p +p --> ap +dp --> ap +ap --> oc +oc --> r +r --> l1((1)) +l2((1)) --> cd +``` + diff --git a/docs/howto/bootstrap/use.md b/docs/howto/bootstrap/use.md new file mode 100644 index 00000000..8651473c --- /dev/null +++ b/docs/howto/bootstrap/use.md @@ -0,0 +1,84 @@ +# Use SSVC + +The [preparation](prepare.md) is complete, data is being [collected](collect.md), and now it is time to use +SSVC to make decisions about how to [respond to vulnerabilities](#respond-to-vulnerabilities). + +```mermaid +flowchart LR + subgraph pd[Policy Development] + p[/Policy/] + end + subgraph dmp[Data Mapping] + dm[/Data Map/] + end + subgraph do[Data Operations] + vd[/Vulnerability Data/] + ed[/Environment Data/] + end + subgraph runtime [Use SSVC] + mdp[[Apply Decision Point Mapping to Data]] + dp[/Decision Point Values/] + ap[[Apply Policy]] + oc[/Outcome/] + end + dm --> mdp + vd --> mdp + ed --> mdp + mdp --> dp + p --> ap + dp --> ap + ap --> oc +``` + + +!!! example + + A government agency has a need to prioritize vulnerability response as part of their vulnerability management process. + Certain vulnerabilities require special handling as a matter of government policy, and the agency wants to make sure + that they are not overlooked. + + The agency completed the [preparation steps](prepare.md) and has defined the decision, the outcome set, and the + decision points and values they want to use. + Because of some special requirements for government agencies, they chose to use a custom outcome set that more closely + matches their existing process. + These same requirements also led them to define a decision function based on a custom selection of existing decision + points. + They've mapped their agency policy to a decision policy that assigns specific decision point values to specific outcomes. + They have also enumerated the data they need to inform the relevant decision point values. + The agency has a process for collecting the data they need, and they have collected the data for a particular + vulnerability. + Now they are ready to use SSVC to decide how to respond to a vulnerability. + + Taking the data they have collected, they first combine it with the data map to produce a set of decision point values. + Then they apply the policy to the decision point values to produce an outcome. + The outcome is a prioritization decision that they can use to inform their response to the vulnerability. + +## Respond to Vulnerabilities + +The actual response to vulnerabilities is outside the scope of SSVC. +But since SSVC is intended to support the vulnerability response process, we include a node to indicate that the +vulnerability response process is the ultimate consumer of the prioritization decision. +We also include a feedback loop from the response node to the data operations node to indicate that the response +process may generate new data that can be used to inform future prioritization decisions. + +```mermaid +flowchart LR + use[Use SSVC] + r[Vulnerability Response] + dataops[Data Operations] + use --> r + r --> dataops + dataops --> use +``` + +!!! example + + Different organizations will have different vulnerability response processes. + The government agency in the previous example might need to notify system owners of the vulnerability and + track other information about the vulnerability for reporting and auditing purposes. + The service providers in previous examples might need to notify customers of the vulnerability and schedule + maintenance windows to apply patches. + Medical device manufacturers might need to develop patches, notify regulators of the vulnerability, and provide + instructions to hospital users for applying patches. + SSVC does not prescribe any particular response process, but it does provide a structured way to make decisions + within the response process. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 56a9a2ec..ee1534a3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -45,6 +45,12 @@ nav: - Evidence Gathering: 'howto/evidence_gathering.md' - Asset Management: 'howto/asset_management.md' - Communicating Results: 'howto/communicating_results.md' + - Bootstrapping SSVC: + - Intro: 'howto/bootstrap/index.md' + - Prepare: 'howto/bootstrap/prepare.md' + - Collect: 'howto/bootstrap/collect.md' + - Use & Respond: 'howto/bootstrap/use.md' + - Summary: 'howto/bootstrap/summary.md' - Reference: - Intro: 'reference/index.md' - Decision Points: