Merge branch 'main' into 582-dockerize-the-mkdocs-dev-server

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,17 @@
+- Remove this template and add a description of the changes you are proposing.
+- Edit the title of the PR to be a concise summary of the changes. The title should
+  be descriptive enough to give a reviewer a good idea of what the PR is about, and
+  not just a reference to an issue number. PR titles are used in the commit log
+  and release notes, so they need to convey meaning on their own.
+- Most pull requests should be in response to an issue, and ideally a PR will
+  resolve or close one or more issues. 
+- If a PR only partially resolves an issue,
+  we suggest spawning one or more child issues from the main issue to identify what portion
+  of the issue is resolved by the PR, and what work remains to be done.
+- Please use [github keyword syntax](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests)
+  (closes, fixes, resolves, etc.) to reference relevant issues.
+- Using bulleted lists with the issue id at the end lets github automatically
+  link the issue and provide the title inline. E.g.: `- resolves #99999`
+- CoPilot summaries are welcome in the PR description, but please provide a brief
+description of the changes in your own words as well. CoPilot can be good at the _what_,
+but not so good at the _why_.

.github/workflows/lint_md_changes.yml

@@ -0,0 +1,30 @@
+name: "Lint Markdown (Changes)"
+on:
+  push:
+    paths:
+      - '**/*.md'
+      - .github/workflows/lint_md_changes.yml
+  pull_request:
+    paths:
+      - '**/*.md'
+      - .github/workflows/lint_md_changes.yml
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - uses: tj-actions/changed-files@v44
+      id: changed-files
+      with:
+        files: '**/*.md'
+        separator: ","
+    - uses: DavidAnson/markdownlint-cli2-action@v16
+      if: steps.changed-files.outputs.any_changed == 'true'
+      with:
+        globs: ${{ steps.changed-files.outputs.all_changed_files }}
+        separator: ","
+        config: .markdownlint.yml
+

.gitignore

@@ -129,3 +129,4 @@ dmypy.json
 .pyre/
 ssvc2-applier-wip.xlsx
 _version.py
+node_modules

.markdownlint.yml

@@ -0,0 +1,29 @@
+default: true
+# disable noisy rules
+# 0004 Unordered List style
+# Force dash style for unordered lists
+MD004:
+  style: "dash"
+# 013 Line length
+# Disabled because we have a lot of long lines. We should fix this eventually.
+MD013: false
+# 033 Inline HTML
+# Disabled because we use inline HTML (<br/> in table cells for example)
+MD033: false
+# MD040/fenced-code-language : Fenced code blocks should have a language specified : https://github.com/DavidAnson/markdownlint/blob/v0.37.4/doc/md040.md
+MD040: false
+# 041 First line in file should be a top level header
+# Disabled because we use `include-markdown` plugin for merging markdown files
+MD041: false
+# 046 Code block style
+# Disabled because mkdocs-material uses indented blocks for admonitions
+MD046: false
+# 049 emphasis style
+# Force asterisk style for emphasis
+MD049:
+  style: "asterisk"
+# 050 strong style
+# Force asterisk style for strong
+MD050:
+  style: "asterisk"
+

CONTRIBUTING.md

@@ -1,17 +1,16 @@
 # How to contribute
 
 Thanks for your help on improving our stakeholder-specific vulnerability categorization work.
-To account for different stakeholder perspectives, we benefit from a diverse group of contributors. 
+To account for different stakeholder perspectives, we benefit from a diverse group of contributors.
 
 Please see our project documentation in the [wiki](https://github.com/CERTCC/SSVC/wiki) that accompanies this repository
 for more information on how you can contribute to the project.
 
 ## Licenses
 
 See [LICENSE](https://github.com/CERTCC/SSVC/blob/main/LICENSE)
- 
+
 ## Questions
 
 If you have any questions, an [issue](https://github.com/CERTCC/SSVC/issues) or
 [discussion](https://github.com/CERTCC/SSVC/discussions) is the best way to get in touch with us.
-

README.md

@@ -10,7 +10,7 @@ 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.
 
-**Note:** This repository contains the _content_ for the main SSVC documentation hosted at
+**Note:** This repository contains the *content* for the main SSVC documentation hosted at
 
 ## [https://certcc.github.io/SSVC/](https://certcc.github.io/SSVC/)
 
@@ -19,7 +19,6 @@ These conceptual tools (how to make decisions, what should go into a decision, h
 
 ---
 
-
 # What's here
 
 Here's a quick overview of the main directories and files in this repository.
@@ -34,7 +33,7 @@ See [`project_docs/README.md`](project_docs/README.md) for more info.
 Directory with SSVC calculator using D3 graph.
 See [`ssvc-calc/README.md`](docs/ssvc-calc/README.md) for more info.
 
-A demo version of `ssvc-calc` can be found at https://certcc.github.io/SSVC/ssvc-calc/
+A demo version of `ssvc-calc` can be found at <https://certcc.github.io/SSVC/ssvc-calc/>
 
 ## `/pdfs/*`
 
@@ -82,7 +81,6 @@ 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.
 
-
 ## Local development
 
 Install prerequisites:
@@ -115,11 +113,11 @@ Start a local server:
 mkdocs serve
 ```
 
-Navigate to http://localhost:8001/ to see the site.
+Navigate to <http://localhost:8001/> to see the site.
 
 (Hint: You can use the `--dev-addr` argument with mkdocs to change the port, e.g. `mkdocs serve --dev-addr localhost:8000`)
 
-## Run tests 
+## Run tests
 
 We include a few tests for the `ssvc` module.
 
@@ -144,8 +142,6 @@ pip install pytest
 pytest src/test
 ```
 
-
-
 ## Contributing
 
 - [SSVC Community Engagement](https://certcc.github.io/SSVC/about/contributing/) has more detail on how to contribute to the project.
@@ -169,5 +165,5 @@ To reference SSVC in an academic publication, please refer to the version presen
 
 ## References
 
-1. Spring, J., Hatleback, E., Householder, A., Manion, A., and Shick, D. "Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization." White Paper, Software Engineering Institute, Carnegie Mellon University (2019). https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=636379
-2. Spring, J., Hatleback, E., Householder, A., Manion, A., and Shick, D. "Towards Improving CVSS." White Paper, Software Engineering Institute, Carnegie Mellon University (2018). https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=538368
+1. Spring, J., Hatleback, E., Householder, A., Manion, A., and Shick, D. "Prioritizing Vulnerability Response: A Stakeholder-Specific Vulnerability Categorization." White Paper, Software Engineering Institute, Carnegie Mellon University (2019). <https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=636379>
+2. Spring, J., Hatleback, E., Householder, A., Manion, A., and Shick, D. "Towards Improving CVSS." White Paper, Software Engineering Institute, Carnegie Mellon University (2018). <https://resources.sei.cmu.edu/library/asset-view.cfm?assetid=538368>

data/schema/README.MD

@@ -1,10 +1,6 @@
-# SSVC decision tree schemas 
+# SSVC decision tree schemas
 
-Two JSON schema files are embedded here that provide schema information for 
+Two JSON schema files are embedded here that provide schema information for
 
 1. Full Decision tree schema for represeting an SSVC decision tree for a Role
 2. Computed SSVC score schema of a vulnerability at a point of time, optionally includes the tree used in making the decision.
-
-
-
-

data/schema_examples/archive/index.md

@@ -1,8 +1,3 @@
 # Sample JSON files (Archived)
 
-
-There are a few examples of the old schema validated JSON files here, please follow the latest schema in [Decision_Point_Value_Selection.schema.json ](../../schema/current/Decision_Point_Value_Selection.schema.json)
-
-
-
-
+There are a few examples of the old schema validated JSON files here, please follow the latest schema in [Decision_Point_Value_Selection.schema.json](../../schema/current/Decision_Point_Value_Selection.schema.json)

data/schema_examples/index.md

@@ -1,10 +1,5 @@
 # Sample JSON files
 
-
 There is a sample JSON file that provides an example of a hypothetical CVE [CVE-1900-1234](CVE-1900-1234-Decision_Point_Value_Selection.json) that adheres to the [JSON schema](../schema/)
 
 The old JSON files are in the [archive](./archive/) folder
-
-
-
-

docs/_includes/helping_out.md

@@ -4,53 +4,52 @@ We welcome your feedback and contributions to SSVC. Here are some ways you can g
 
 <div class="grid cards" markdown>
 
-- :material-message-question: _Ask a question_
+- :material-message-question: *Ask a question*
 
     ---
 
-    If you have a specific question for the SSVC team, please feel free to 
+    If you have a specific question for the SSVC team, please feel free to
     [Ask a Question](https://github.com/CERTCC/SSVC/issues/new?template=question.md).
- 
+
     Questions of more general interest to the community of SSVC users might fit better in the
     [Q&A](https://github.com/CERTCC/SSVC/discussions/categories/q-a) section of the
     [Discussion](https://github.com/CERTCC/SSVC/discussions) area.
 
-- :fontawesome-solid-bug: _Report a problem_
+- :fontawesome-solid-bug: *Report a problem*
 
     ---
 
     If you find a problem with the SSVC documentation, the methodology, or accompanying code, we
     welcome your [Bug Reports](https://github.com/CERTCC/SSVC/issues/new?template=bug_report.md)
-    
-- :material-lightbulb-on: _Suggest an improvement_
+
+- :material-lightbulb-on: *Suggest an improvement*
 
     ---
     Got an idea for how to make SSVC better? We'd love to hear it! Please submit your
     [Feature Requests](https://github.com/CERTCC/SSVC/issues/new?template=feature_request.md)
- 
-- :fontawesome-regular-comments: _Join the conversation_
+
+- :fontawesome-regular-comments: *Join the conversation*
 
     ---
 
     More in-depth conversations that might not be actionable as issues are found in the
     [Discussions](https://github.com/CERTCC/SSVC/discussions) area.
 
-- :material-binoculars: _See what we're working on_
+- :material-binoculars: *See what we're working on*
 
     ---
 
     We manage the SSVC development effort via Github [Issues](https://github.com/CERTCC/SSVC/issues) and
-    [Pull Requests](https://github.com/CERTCC/SSVC/pulls). 
+    [Pull Requests](https://github.com/CERTCC/SSVC/pulls).
     Drop by and see what we're working on, or leave a comment to let us know what you're interested in.
 
-- :material-hub: _Get more involved_
+- :material-hub: *Get more involved*
 
     ---
 
     Want more information about engaging as a collaborator? Check out the [SSVC Project Wiki](https://github.com/CERTCC/SSVC/wiki)
-
-</div>
 
+</div>
 
 !!! tip "Footer Icons"
 
@@ -60,4 +59,3 @@ We welcome your feedback and contributions to SSVC. Here are some ways you can g
 
     If you are new to contributing to open source projects on Github, we've assembled some pointers
     to help you get started in the [Github Tips for SSVC contributors](https://github.com/CERTCC/SSVC/wiki/Github-Tips-for-SSVC-contributors)
-

docs/about/acknowledgements.md

@@ -5,8 +5,8 @@ of this report: Art Manion, Madison Oliver, and Deana Shick.
 
 The authors thank the [contributors](https://github.com/CERTCC/SSVC/graphs/contributors) to the
 [SSVC project](https://github.com/CERTCC/SSVC) on Github as well as the following individuals for helpful comments on
-prior drafts (listed in alphabetical order): 
-Muhammad Akbar, 
+prior drafts (listed in alphabetical order):
+Muhammad Akbar,
 Will Dormann,
 Manish Gaur,
 Ralph Langer,
@@ -23,4 +23,3 @@ Anonymous WEIS reviewers;
 Various staff members and analysts at CERT/CC, CISA, McAfee, and VMWare;
 FIRST CVSS SIG and EPSS SIG members;
 and others who wish to remain anonymous.
-