Add markdownlint workflow

.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:
@@ -97,11 +95,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.
 
@@ -121,9 +119,6 @@ pip install pytest  # if you haven't already
 pytest # should find tests in src/test/*
 ```
 
-
-
-
 ## Contributing
 
 - [SSVC Community Engagement](https://certcc.github.io/SSVC/about/contributing/) has more detail on how to contribute to the project.
@@ -147,5 +142,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.
-

docs/about/changelog.md

@@ -9,29 +9,29 @@ In the 2024.3 release of the Stakeholder-Specific Vulnerability Classification (
 This release debuts the [certcc.github.io/SSVC](https://certcc.github.io/SSVC) web site to serve as the front-door for all things SSVC.
 
 - **Diátaxis Framework** - We adopted the [Diátaxis Framework](https://diataxis.fr/) as a document organization framework for SSVC documentation. High level content categories are: tutorials, how-to, topics, and reference. What used to be a linear paper format is now sectioned off into more digestible pieces.
-- **More call-outs and examples** - With our adoption of [_Material for MkDocs_](https://squidfunk.github.io/mkdocs-material/) as the underlying toolkit to construct our web site, we were able to better highlight examples, tips, and sidebar topics through the use of call-out boxes throughout the site.
+- **More call-outs and examples** - With our adoption of [*Material for MkDocs*](https://squidfunk.github.io/mkdocs-material/) as the underlying toolkit to construct our web site, we were able to better highlight examples, tips, and sidebar topics through the use of call-out boxes throughout the site.
 
-## New and Revised Content 
+## New and Revised Content
 
 - **Expanded Content** - We've included more examples of Decision Points and the like directly inline where they're mentioned so readers don't need to keep flipping back and forth to their definitions for reference.
-- **Bootstrapping advice** - Added a _Getting Started with SSVC_ process to help organizations go from being _potential_ SSVC users to being _actual_ SSVC users. This process is based on both our own experience helping organizations adopt SSVC as well as a few field reports of SSVC adoption from the community.
-- **Putting the Pieces Together** - _Added a Putting the Pieces Together_ page explaining some of our philosophy regarding how to use SSVC to model decisions. SSVC provides you with the pieces and some instructions on how to assemble them, but you can customize it however you like.
-- **Acuity Ramp** - Added an _Acuity Ramp_ explainer to show how an organization can grow into a decision model over time.
+- **Bootstrapping advice** - Added a *Getting Started with SSVC* process to help organizations go from being *potential* SSVC users to being *actual* SSVC users. This process is based on both our own experience helping organizations adopt SSVC as well as a few field reports of SSVC adoption from the community.
+- **Putting the Pieces Together** - *Added a Putting the Pieces Together* page explaining some of our philosophy regarding how to use SSVC to model decisions. SSVC provides you with the pieces and some instructions on how to assemble them, but you can customize it however you like.
+- **Acuity Ramp** - Added an *Acuity Ramp* explainer to show how an organization can grow into a decision model over time.
 - **Community Engagement** - Included in the new web site are a number of suggested ways for the community to interact with and contribute to the SSVC.
 
 ## Versioned Objects
 
-- **Semantic Versioning for Decision Points and Decision Point Groups** - Introduced Semantic Versioning (SemVer) for _Decision Points_ and _Decision Point Groups_ to improve communication around decision points and decision models
-- **Calendar Versioning for SSVC as a whole** - With the introduction of SemVer for _Decision Points_ and _Decision Point Groups_, it started to make less sense for us to talk in terms of "SSVC v2.2", especially as we were simultaneously moving away from a PDF document-focused development model towards a more flexible web-based documentation model. Beginning with this version, we anticipate that future tagged releases will use Calendar Versioning (CalVer) instead of SemVer.
+- **Semantic Versioning for Decision Points and Decision Point Groups** - Introduced Semantic Versioning (SemVer) for *Decision Points* and *Decision Point Groups* to improve communication around decision points and decision models
+- **Calendar Versioning for SSVC as a whole** - With the introduction of SemVer for *Decision Points* and *Decision Point Groups*, it started to make less sense for us to talk in terms of "SSVC v2.2", especially as we were simultaneously moving away from a PDF document-focused development model towards a more flexible web-based documentation model. Beginning with this version, we anticipate that future tagged releases will use Calendar Versioning (CalVer) instead of SemVer.
 
 ## Experimental & Emerging Features
 
 There are a few improvements we've begun but have not yet fully finished, and that are largely undocumented. Most of these in the current release are python-centric. Here's a brief overview for those who want to poke around at code.
 
-- **SSVC Python module** - This release introduces the `ssvc` python module to allow us to more easily work with _Decision Points_, _Decision Point Groups_, _Outcomes_, and _Policies_ that map from _Decision Points_ to _Outcomes_. We expect to have more to say about this module in the future, but for now it's geared towards helping us produce the site documentation.
-- **Policy Generator** - We're prototyping a Python tool that can generate a starting policy given any combination of a _Decision Point Group_  and _Outcomes_. It's not ready for prime-time yet, but folks with a bit of python skill might be in a position to try it out.
+- **SSVC Python module** - This release introduces the `ssvc` python module to allow us to more easily work with *Decision Points*, *Decision Point Groups*, *Outcomes*, and *Policies* that map from *Decision Points* to *Outcomes*. We expect to have more to say about this module in the future, but for now it's geared towards helping us produce the site documentation.
+- **Policy Generator** - We're prototyping a Python tool that can generate a starting policy given any combination of a *Decision Point Group*  and *Outcomes*. It's not ready for prime-time yet, but folks with a bit of python skill might be in a position to try it out.
 - **More Decision Points and Outcomes** - In the process of exercising our Semantic Versioning rules for decision points and groups, we needed some examples of versioning events for discussion purposes. As a result, the `ssvc.decision_points.cvss` and `ssvc.dp_groups.cvss` modules contain python implementations of CVSS vector elements from CVSS v1, v2, v3, v3.1, and v4. We anticipate some of these coming in handy in the future as we look toward modeling other decisions potentially based on CVSS vector elements as well as other decision points from SSVC and elsewhere. We also included decision points and groups from [CISA's customized SSVC implementation](https://www.cisa.gov/stakeholder-specific-vulnerability-categorization-ssvc).
- 
+
 ## Other project infrastructure improvements
 
 - Shifted from PDF-oriented to web-oriented workflow
@@ -55,16 +55,15 @@ The details of what changes were made can be viewed on the SSVC Github under the
 - Improved consistency of *Public Safety Impact* usage throughout the document and tooling
 - Improved consistency of *Human Impact* usage throughout the document
 - Clarified that known default passwords are an example of *Exploitation*:PoC
-- Clarified that unreachable code (as in unused library features) are _System Exposure_:small
-- Mention DoD MEF definition in _Mission Impact_
+- Clarified that unreachable code (as in unused library features) are *System Exposure*:small
+- Mention DoD MEF definition in *Mission Impact*
 - Updated references to EPSS to reflect recent publications
 - Refactored markdown files to better track chapter and section numbering, improving findability when editing
 - Automated HTML and PDF generation into a Github Workflow
 - Updated python tools to maintain sync with current SSVC decision models
 - Consolidated the SSVC document style guide into a single file in the repository
 - Miscellaneous typo fixes and readability improvements (e.g., headings, bulleted lists)
 
-
 ## Version 2 (2021.5) Changelog
 
 This section summarizes the changes between SSVC version 2 and SSVC version 1.1 as published at the Workshop on the Ecnomics of Information Security (WEIS 2020).
@@ -113,7 +112,6 @@ Either situation is sufficient to increase the priority, and there do not appear
 On the other hand, a low *Utility* or *System Exposure* may mitigate a high mission or well-being impact.
 So the Version 2 recommended tree is more usable than the Version 1 tree, thanks to these changes.
 
-
 ### Tree management and communication tools
 
 The section Tree Construction and Customization Guidance is largely new or revised.
@@ -127,4 +125,4 @@ Version 2 also addresses several other questions about SSVC information manageme
 
 ## Version 1.0 (2019.12) Changelog
 
-Initial release
+Initial release

docs/about/contact_us.md

@@ -7,4 +7,4 @@ Software Engineering Institute
 **Web**: [www.sei.cmu.edu](http://www.sei.cmu.edu)  
 **Email**: [[email protected]](mailto:[email protected])
 
-{% include-markdown "../_includes/helping_out.md" heading-offset=1 %}
+{% include-markdown "../_includes/helping_out.md" heading-offset=1 %}

docs/about/contributing.md

@@ -1,3 +1,3 @@
 {% include-markdown "../_includes/helping_out.md" %}
 
-{% include-markdown "../../CONTRIBUTING.md" %}
+{% include-markdown "../../CONTRIBUTING.md" %}