Merge pull request #277 from CERTCC/feature/fix_272

Update README docs to make finding recent pdf easier

README.md

@@ -10,16 +10,25 @@ SSVC aims to avoid one-size-fits-all solutions in favor of a modular decision-ma
 SSVC is mostly conceptual tools for vulnerability management.
 These conceptual tools (how to make decisions, what should go into a decision, how to document and communicate decisions clearly, etc.) are described here.
 
-`doc/*`
+## `/doc/*`
 
-Draft and final versions of reports. See [`doc/README.md`](doc/README.md) for
+Raw markdown and graphics files used to build document artifacts. 
+See [`doc/README.md`](doc/README.md) for
 more info.
 
-`doc/pdfs/*.pdf`
+## `/draft/*`
 
-Static versions of issued reports are stored in this directory.
+Generated drafts of reports. Usually these will be recent versions of the main document in both `pdf` and `html` formats.
+At the moment, these are manually generated using the `make all` target from within `/doc`.
+For the absolute latest version generated from the most recent commit on the `main` branch, 
+see the `output.zip` file artifact attached to the most recent run of the
+[pandoc_html_pdf.yaml](https://github.com/CERTCC/SSVC/actions/workflows/pandoc_html_pdf.yaml) workflow.
 
-`data/*.csv`
+## `/pdfs/*.pdf`
+
+Static versions of previously issued reports are stored in this directory.
+
+## `/data/*.csv`
 
 The data folder contains detailed data files that define suggested prioritization results based on each combination of information on a vulnerability work item.
 Also included in data are the lookup tables as csv files which `ssvc.py`
@@ -30,7 +39,7 @@ The tools in the `src` folder provide an interface to work with these data files
 Customizing the "outcome" column in this csv is the primary recommended way that stakehodlers might adapt SSVC to their environment.
 
 
-`src/ssvc.py`
+## `src/ssvc.py`
 
 A basic Python module for interacting with the SSVC trees. `ssvc.py` has
 two methods: `applier_tree()` and `developer_tree()`
@@ -39,11 +48,13 @@ The two methods just loop through their respective lookup tables until
 they hit a match, then return the outcome. Maybe not the best implementation,
 but it worked well enough for what was needed at the time.
 
-`ssvc-calc`
+## `ssvc-calc`
 
 Directory with SSVC calculator using D3 graph.
 See [`ssvc-calc/README.md`](ssvc-calc/README.md) for more info.
 
+A demo version of `ssvc-calc` can be found at https://certcc.github.io/SSVC/ssvc-calc/
+
 ## Citing SSVC
 
 To reference SSVC in an academic publication, please refer to the version presented at the 2020 Workshop on Economics of Information Security (WEIS):

doc/Makefile

@@ -26,7 +26,7 @@ FIX=`git rev-parse --short HEAD`
 # The fix version for the schema and the PDF document may mismatch
 
 HOME:=$(shell pwd)
-OUTDIR=$(HOME)
+OUTDIR=$(HOME)/../draft
 SRC=./md_src_files
 
 
@@ -36,9 +36,6 @@ COMPILE_DATE:="Compiled `date -u`"
 PDF_STYLING:=pdf-styling.yaml
 BIBLIOGRAPHY:=$(SRC)/sources_ssvc.bib
 
-# TODO decide whether to include FIX level in file name or not
-#PDF_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR)-$(FIX).pdf
-#HTML_OUT:=$(OUTDIR)/ssvc_v$(MAJOR)-$(MINOR)-$(FIX).html
 PDF_OUT:=$(OUTDIR)/ssvc.pdf
 HTML_OUT:=$(OUTDIR)/ssvc.html
 

doc/README.md

@@ -3,19 +3,28 @@
 This folder contains the text documents that describe the decision process, the decision points, the possible decision
 values, and the decision trees that should be used to reach prioritization decisions.
 
-The current draft should be compiled into `ssvc_v#.html` for easy viewing, though it may be behind the markdown source
+The current draft should be compiled into `/draft/ssvc.html` for easy viewing, though it may be behind the markdown source
 by a couple commits.
 
 The documents are in markdown for easy editing.
 All the source files needed to create a polished document are in the [`md_src_files`](md_src_files) folder.
 The work on version 1 started with the version of the paper published
 at [WEIS 2020](https://weis2020.econinfosec.org/wp-content/uploads/sites/8/2020/06/weis20-final6.pdf).
-A copy of this document and other prior drafts is in the `pdfs` folder.
+A copy of this document and other prior drafts is in the `/pdfs` folder.
 
-The `*.md` files should be limited to one file per section, for easier editing and merging. The current numbering scheme
-is important so the command line `*` ingests the files in the right order. Three digits (`010`, etc.) are used in case
-new sections need to be interleaved. A substantive edit to a section should probably be renamed `011`, etc., but we
-don't have guidance on what counts as "substantive" yet. A total re-write wold be, though.
+## Markdown file naming conventions
+
+The `*.md` files should be limited to one file per chapter or section, for easier editing and merging.
+The current numbering scheme is important so the command line `*` ingests the files in the right (i.e., ASCII-sort) order.
+File names follow the convention `CC_SS_name.md` where:
+
+- `CC` is a zero-padded two-digit chapter number
+- `SS` (optional) is a zero-padded two-digit section number
+- `name` is a string derived from the first heading in the file
+
+So for example, a file whose content starts with `## Foo` representing the third section of chapter two would likely be named `02_03_foo.md`. 
+
+## Makefile
 
 The [`Makefile`](Makefile) contains pandoc commands line for creating a single HTML and PDF document from the markdown. It also
 contains the document metadata (title, authors, date) as command-line arguments. You can:
@@ -29,11 +38,13 @@ $ make pdf
 $ make html
 ```
 for the respective output.
+Output of the `make` commands can be found in `/draft`.
 
 Note that the `Makefile` was used as the basis for the github action
 [`.github/workflows/pandoc_html_pdf.yaml`](./github/workflows/pandoc_html_pdf.yaml), which should be maintained in sync 
 with the `Makefile` in the future.
 
+
 The `*how-to` files contain discussion on document composition and style. Please align any commits with the existing
 how-to guidance. At present (Aug 2020), the how-to guidance is not yet fixed, but it should only change with community
 discussion.

doc/ssvc.html → draft/ssvc.html

@@ -12,7 +12,7 @@
  <meta name="author" content="Vijay Sarvapalli" />
  <meta name="author" content="Deana Shick" />
  <meta name="author" content="Laurie Tyzenhaus" />
- <title>SSVC – Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC version 2.1.51ea18a)</title>
+ <title>SSVC – Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization (SSVC version 2.1.66aa51a)</title>
  <style>
  html {
  line-height: 1.5;
@@ -189,7 +189,7 @@
 <header id="title-block-header">
 <h1 class="title">Prioritizing Vulnerability Response: A
 Stakeholder-Specific Vulnerability Categorization (SSVC version
-2.1.51ea18a)</h1>
+2.1.66aa51a)</h1>
 <p class="author">Jonathan M. Spring</p>
 <p class="author">Eric Hatleback</p>
 <p class="author">Allen D. Householder</p>
@@ -198,7 +198,7 @@ <h1 class="title">Prioritizing Vulnerability Response: A
 <p class="author">Vijay Sarvapalli</p>
 <p class="author">Deana Shick</p>
 <p class="author">Laurie Tyzenhaus</p>
-<p class="date">Compiled Wed Jul 5 13:20:54 UTC 2023</p>
+<p class="date">Compiled Tue Jul 11 19:39:43 UTC 2023</p>
 </header>
 <h1 id="introduction">Introduction</h1>
 <p>This document defines a testable Stakeholder-Specific Vulnerability
@@ -1239,12 +1239,12 @@ <h2 id="exploitation">Exploitation</h2>
 the vulnerability. The intent is not to predict future exploitation but
 only to acknowledge the current state of affairs. Predictive systems,
 such as EPSS, could be used to augment this decision or to notify
-stakeholders of likely changes <span class="citation" data-cites="jacobs2019exploit">(Jacobs et al. 2019)</span>.</p>
+stakeholders of likely changes <span class="citation" data-cites="jacobs2021epss">(Jacobs et al. 2021)</span>.</p>
 <table>
 <caption>Exploitation Decision Values</caption>
 <colgroup>
-<col style="width: 23%" />
-<col style="width: 76%" />
+<col style="width: 0%" />
+<col style="width: 99%" />
 </colgroup>
 <thead>
 <tr class="header">
@@ -1268,7 +1268,8 @@ <h2 id="exploitation">Exploitation</h2>
 condition (3) are open-source web proxies serve as the PoC code for how
 to exploit any vulnerability in the vein of improper validation of TLS
 certificates. As another example, Wireshark serves as a PoC for packet
-replay attacks on ethernet or WiFi networks.</td>
+replay attacks on ethernet or WiFi networks. A publicly-known hard-coded
+or default password would also meet this criteria.</td>
 </tr>
 <tr class="odd">
 <td style="text-align: left;">Active</td>
@@ -4224,8 +4225,8 @@ <h1 id="related-vulnerability-management-systems">Related Vulnerability
 <p>There are several other bodies of work that are used in practice to
 assist vulnerability managers in making decisions. Three relevant
 systems are CVSS <span class="citation" data-cites="cvss_v3-1">(CVSS SIG
-2019)</span>, EPSS <span class="citation" data-cites="jacobs2019exploit">(Jacobs et al. 2019)</span>, and
-Tenable&#39;s Vulnerability Priority Rating (<a href="https://www.tenable.com/blog/what-is-vpr-and-how-is-it-different-from-cvss">VPR</a>).
+2019)</span>, EPSS <span class="citation" data-cites="jacobs2021epss">(Jacobs et al. 2021)</span>, and Tenable&#39;s
+Vulnerability Priority Rating (<a href="https://www.tenable.com/blog/what-is-vpr-and-how-is-it-different-from-cvss">VPR</a>).
 There are other systems derived from CVSS, such as RVSS for robots <span class="citation" data-cites="vilches2018towards">(Vilches et al.
 2018)</span> and MITRE&#39;s effort to adapt CVSS to medical devices <span class="citation" data-cites="mitre2019medical">(Chase and Coley
 2019)</span>. There are also other nascent efforts to automate aspects
@@ -4323,7 +4324,7 @@ <h2 id="cvss">CVSS</h2>
 in SSVC and that SSVC accounts for the observation that most
 vulnerabilities with CVE-IDs do not have public exploit code <span class="citation" data-cites="householder2020historical">(Householder,
 Chrabaszcz, et al. 2020)</span> and are not actively exploited <span class="citation" data-cites="guido2011exploit">Jacobs et al.
-(2019)</span>.</p>
+(2021)</span>.</p>
 <blockquote>
 <p>Environmental metric group</p>
 </blockquote>
@@ -4336,19 +4337,20 @@ <h2 id="cvss">CVSS</h2>
 separately. SSVC does not have such customization as a bolt-on optional
 metric group because SSVC is stakeholder-specific by design.</p>
 <h2 id="epss">EPSS</h2>
-<p><a href="https://www.first.org/epss/">EPSS</a> is an “effort for
-predicting when software vulnerabilities will be exploited.” EPSS is
-currently based on a machine-learning classifier and proprietary IDS
-alert data from Kenna Security. While the group has made an effort to
-make the ML classifier transparent, ML classifiers are not able to
-provide an intelligible, human-accessible explanation for their behavior
-<span class="citation" data-cites="spring2019ml">(Jonathan M. Spring et
-al. 2019)</span>. The use of proprietary training data makes the system
-less transparent.</p>
+<p>The <a href="https://www.first.org/epss/">Exploit Prediction Scoring
+System (EPSS)</a> is “a data-driven effort for estimating the likelihood
+(probability) that a software vulnerability will be exploited in the
+wild.” EPSS is currently based on a machine-learning classifier and
+proprietary data from Fortiguard, Alienvault OTX, the Shadowserver
+Foundation and GreyNoise. While the group has made an effort to make the
+ML classifier transparent, ML classifiers are not able to provide an
+intelligible, human-accessible explanation for their behavior <span class="citation" data-cites="spring2019ml">(Jonathan M. Spring et al.
+2019)</span>. The use of proprietary training data makes the system less
+transparent.</p>
 <p>EPSS could be used to inform the <a href="#exploitation"><em>Exploitation</em></a> decision point.
 Currently, <a href="#exploitation"><em>Exploitation</em></a> focuses on
 the observable state of the world at the time of the SSVC decision. EPSS
-is about predicting if a transition will occur from the SSVC state of <a href="#xploitation"><em>none</em></a> to <a href="#exploitation"><em>active</em></a>. A sufficiently high EPSS score
+is about predicting if a transition will occur from the SSVC state of <a href="#exploitation"><em>none</em></a> to <a href="#exploitation"><em>active</em></a>. A sufficiently high EPSS score
 could therefore be used as an additional criterion for scoring a
 vulnerability as <a href="#exploitation"><em>active</em></a> even when
 there is no observed active exploitation.</p>
@@ -4871,11 +4873,10 @@ <h1 id="copyright">Copyright</h1>
 ISO. 2009. <span>“Risk Management – Vocabulary.”</span> 73:2009(en).
 Geneva, CH: International Organization for Standardization. <a href="https://www.iso.org/obp/ui/#iso:std:iso:guide:73:ed-1:v1:en">https://www.iso.org/obp/ui/#iso:std:iso:guide:73:ed-1:v1:en</a>.
 </div>
-<div id="ref-jacobs2019exploit" class="csl-entry" role="doc-biblioentry">
-Jacobs, Jay, Sasha Romanosky, Benjamin Edwards, Michael Roytman, and
-Idris Adjerid. 2019. <span>“Exploit Prediction Scoring System
-(<span>EPSS</span>).”</span> In <em>Workshop on the Economics of
-Information Security</em>. Boston, MA. <a href="https://arxiv.org/abs/1908.04856">https://arxiv.org/abs/1908.04856</a>.
+<div id="ref-jacobs2021epss" class="csl-entry" role="doc-biblioentry">
+Jacobs, Jay, Sasha Romanosky, Benjamin Edwards, Idris Adjerid, and
+Michael Roytman. 2021. <span>“Exploit Prediction Scoring System
+(EPSS).”</span> <em>Digital Threats</em> 2 (3). <a href="https://doi.org/10.1145/3436242">https://doi.org/10.1145/3436242</a>.
 </div>
 <div id="ref-manion2019sbom" class="csl-entry" role="doc-biblioentry">
 Jump, Michelle, and Art Manion. 2019. <span>“Framing Software Component