SSVC v2024.3

[ahouseholder]

In the 2024.3 release of the Stakeholder-Specific Vulnerability Classification (SSVC) system, we've made a number of significant changes:

New Web Site

This release debuts the 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 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 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

• 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.
• 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 project on Github.

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.

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.
• 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.

Other project infrastructure improvements

• Shifted from PDF-oriented to web-oriented workflow
• Adopted MkDocs and Material for MkDocs for static site production
• Adopted Markdown Any Decision Records to preserve rationale and record decisions that are of significant impact to the project
• Added documentation to the SSVC project wiki with tips for current and future contributors.
• Began using Github's Dependabot to help maintain dependency versions.

What's Changed

• Convert docs to mkdocs, material, mermaid by @ahouseholder in Convert docs to mkdocs, material, mermaid #301
• Create CODEOWNERS by @ahouseholder in Create CODEOWNERS #305
• Fix video links by @ahouseholder in Fix video links #312
• Fix links by @ahouseholder in Fix links #310
• Feature/bootstrapping docs by @ahouseholder in Feature/bootstrapping docs #308
• Move project meta-docs from main repo into Github wiki by @ahouseholder in Move project meta-docs from main repo into Github wiki #320
• add drop column importance by @ahouseholder in add drop column importance #327
• Add print-site plugin to restore all-in-one page feature by @ahouseholder in Add print-site plugin to restore all-in-one page feature #338
• Add new json schemas for decision points and dp groups by @ahouseholder in Add new json schemas for decision points and dp groups #340
• Add SSVC python module by @ahouseholder in Add SSVC python module #342
• Begin recording architecture decisions by @ahouseholder in Begin recording architecture decisions #341
• Add python decision points for critical software and high value assets by @ahouseholder in Add python decision points for critical software and high value assets #346
• add ADR proposals for decision point versioning. by @ahouseholder in add ADR proposals for decision point versioning. #350
• Add Decision Point Group Versioning ADRs by @ahouseholder in Add Decision Point Group Versioning ADRs #368
• Add build steps to python-app.yml by @ahouseholder in Add build steps to python-app.yml #371
• Add CVSS-based (v1, v2, v3) decision points as python classes by @ahouseholder in Add CVSS-based (v1, v2, v3) decision points as python classes #343
• Add CWE-PoC list file by @koscinv in Add CWE-PoC list file #376
• Policy Generator tool, first pass by @ahouseholder in Policy Generator tool, first pass #365
• Reorganize HowTo section by @ahouseholder in Reorganize HowTo section #379
• Tool to auto populate documentation examples for decision point objects by @ahouseholder in Tool to auto populate documentation examples for decision point objects #370
• Add sanity checks to policy generator by @ahouseholder in Add sanity checks to policy generator #387
• Add CVSSv4 Decision Points by @ahouseholder in Add CVSSv4 Decision Points #377
• Add ADR excluding examples from object descriptions by @ahouseholder in Add ADR excluding examples from object descriptions #391
• Fix policygenerator slowness by @ahouseholder in Fix policygenerator slowness #397
• Two small typofixes by @ahouseholder in Two small typofixes #396
• Add grid to homepage by @ahouseholder in Add grid to homepage #399
• Pin versions in requirements.txt by @ahouseholder in Pin versions in requirements.txt #400
• Create dependabot.yml by @ahouseholder in Create dependabot.yml #402
• Bump mkdocs-material from 9.5.4 to 9.5.6 by @dependabot in Bump mkdocs-material from 9.5.4 to 9.5.6 #410
• Bump jsonschema from 4.19.2 to 4.21.1 by @dependabot in Bump jsonschema from 4.19.2 to 4.21.1 #408
• Bump pandas from 2.1.2 to 2.2.0 by @dependabot in Bump pandas from 2.1.2 to 2.2.0 #406
• Bump mkdocs-include-markdown-plugin from 6.0.3 to 6.0.4 by @dependabot in Bump mkdocs-include-markdown-plugin from 6.0.3 to 6.0.4 #407
• Bump networkx from 3.1 to 3.2.1 by @dependabot in Bump networkx from 3.1 to 3.2.1 #409
• Add GH actions to dependabot config by @ahouseholder in Add GH actions to dependabot config #411
• Bump mkdocs-table-reader-plugin from 2.0.3 to 2.1.0 by @dependabot in Bump mkdocs-table-reader-plugin from 2.0.3 to 2.1.0 #413
• Bump thefuzz from 0.20.0 to 0.22.1 by @dependabot in Bump thefuzz from 0.20.0 to 0.22.1 #414
• Bump actions/upload-pages-artifact from 2 to 3 by @dependabot in Bump actions/upload-pages-artifact from 2 to 3 #421
• Bump actions/deploy-pages from 2 to 4 by @dependabot in Bump actions/deploy-pages from 2 to 4 #422
• Bump dataclasses-json from 0.6.1 to 0.6.3 by @dependabot in Bump dataclasses-json from 0.6.1 to 0.6.3 #415
• Bump actions/configure-pages from 3 to 4 by @dependabot in Bump actions/configure-pages from 3 to 4 #419
• Bump actions/checkout from 3 to 4 by @dependabot in Bump actions/checkout from 3 to 4 #420
• Bump actions/setup-python from 3 to 5 by @dependabot in Bump actions/setup-python from 3 to 5 #418
• Bump scikit-learn from 1.3.2 to 1.4.0 by @dependabot in Bump scikit-learn from 1.3.2 to 1.4.0 #416
• Bump mkdocstrings from 0.23.0 to 0.24.0 by @dependabot in Bump mkdocstrings from 0.23.0 to 0.24.0 #417
• Improve Reference section intro pages by @ahouseholder in Improve Reference section intro pages #423
• Revise topics/ home page by @ahouseholder in Revise topics/ home page #424
• Add OutcomeGroup for TheParanoids PrioritizedRiskRemediation by @ahouseholder in Add OutcomeGroup for TheParanoids PrioritizedRiskRemediation #425
• Add OutcomeGroup for CISA's customized version of SSVC by @ahouseholder in Add OutcomeGroup for CISA's customized version of SSVC #426
• Bump mkdocs-bibtex from 2.11.0 to 2.12.0 by @dependabot in Bump mkdocs-bibtex from 2.11.0 to 2.12.0 #432
• Bump dataclasses-json from 0.6.3 to 0.6.4 by @dependabot in Bump dataclasses-json from 0.6.3 to 0.6.4 #433
• Bump mkdocs-material from 9.5.6 to 9.5.7 by @dependabot in Bump mkdocs-material from 9.5.6 to 9.5.7 #434
• Bump actions/upload-artifact from 3 to 4 by @dependabot in Bump actions/upload-artifact from 3 to 4 #437
• Bump mkdocstrings-python from 1.7.3 to 1.8.0 by @dependabot in Bump mkdocstrings-python from 1.7.3 to 1.8.0 #436
• Bump mkdocs-material-extensions from 1.3 to 1.3.1 by @dependabot in Bump mkdocs-material-extensions from 1.3 to 1.3.1 #435
• Add CISA custom decision points by @ahouseholder in Add CISA custom decision points #427
• Add acuity_ramp.md to HowTo section by @ahouseholder in Add acuity_ramp.md to HowTo section #429
• Revise compound decision points documentation by @ahouseholder in Revise compound decision points documentation #428
• Realign Safety decision points IEC 61508 by @ahouseholder in Realign Safety decision points IEC 61508 #439
• Move asset management to topics from howto by @ahouseholder in Move asset management to topics from howto #453
• Bump mkdocs-material from 9.5.7 to 9.5.9 by @dependabot in Bump mkdocs-material from 9.5.7 to 9.5.9 #456
• Update Exploitation:PoC definition by @ccullen-cert in Update Exploitation:PoC definition #442
• merge report credibility description with its decision point page by @ahouseholder in merge report credibility description with its decision point page #446
• Unlink text in changelog.md by @ahouseholder in Unlink text in changelog.md #452
• ADRs for Decision Points and Outcomes as ordered sets by @ahouseholder in ADRs for Decision Points and Outcomes as ordered sets #440
• ADR: Outcome sets are separate from decision point group (tree) identity by @ahouseholder in ADR: Outcome sets are separate from decision point group (tree) identity #444
• Add mkdocs group to dependabot.yml by @ahouseholder in Add mkdocs group to dependabot.yml #457
• Remove abbreviated format from docs by @ahouseholder in Remove abbreviated format from docs #451
• Bump site copyright by @ccullen-cert in Bump site copyright #464
• Link coordinator-specific decision points from coordination_decisions.md by @laurie-tyz in Link coordinator-specific decision points from coordination_decisions.md #462
• Fix broken links by @ahouseholder in Fix broken links #443
• Create link_checker.yml by @ahouseholder in Create link_checker.yml #465
• Fix how we load csv files by @ahouseholder in Fix how we load csv files #470
• Add building block analogy explainer by @ahouseholder in Add building block analogy explainer #447
• Revise howto/index.md by @ahouseholder in Revise howto/index.md #469
• Expand SSVC acronym in site name by @ahouseholder in Expand SSVC acronym in site name #474
• Add community engagement links by @ahouseholder in Add community engagement links #468
• Make link_checker.yml run automatically on push to main by @ahouseholder in Make link_checker.yml run automatically on push to main #471
• Bump the mkdocs group with 1 update by @dependabot in Bump the mkdocs group with 1 update #477
• Bump scikit-learn from 1.4.0 to 1.4.1.post1 by @dependabot in Bump scikit-learn from 1.4.0 to 1.4.1.post1 #478
• Human impact change proposal by @sei-bkoo in Human impact change proposal #476
• make safety table formats look better by @ahouseholder in make safety table formats look better #479
• Add topo sort to csv analyzer and policy generator by @ahouseholder in Add topo sort to csv analyzer and policy generator #473
• Reorder howto section navigation by @ahouseholder in Reorder howto section navigation #484
• Consolidate stakeholder specific decision model content into individual howto pages by @ahouseholder in Consolidate stakeholder specific decision model content into individual howto pages #485
• Add Establish Governance to Prepare step of bootstrap process description by @ahouseholder in Add _Establish Governance_ to _Prepare_ step of bootstrap process description #488
• Add link to github tips wiki page by @ahouseholder in Add link to github tips wiki page #491
• Reorder HowTo and Understanding in site nav by @ahouseholder in Reorder HowTo and Understanding in site nav #490
• Bump the mkdocs group with 1 update by @dependabot in Bump the mkdocs group with 1 update #498
• Bump pandas from 2.2.0 to 2.2.1 by @dependabot in Bump pandas from 2.2.0 to 2.2.1 #499
• add initial draft of ADR by @j--- in add initial draft of ADR #492
• Ccullen cert patch 2 by @ccullen-cert in Ccullen cert patch 2 #512
• SSVC Calculator minor updates by @sei-vsarvepalli in SSVC Calculator minor updates #513
• Add Calculator blurb to Learning SSVC by @ahouseholder in Add Calculator blurb to Learning SSVC #515
• Add Google Analytics by @ahouseholder in Add Google Analytics #517
• Bump the mkdocs group with 3 updates by @dependabot in Bump the mkdocs group with 3 updates #521
• SSVC calculator display updates for iframe by @sei-vsarvepalli in SSVC calculator display updates for iframe #520
• Copy edits & punch list by @ahouseholder in Copy edits & punch list #524
• Update references in Risk Tolerance by @ahouseholder in Update references in Risk Tolerance #525
• Add js to fix latex rendering on page load by @ahouseholder in Add js to fix latex rendering on page load #527
• Inline refs by @ahouseholder in Inline refs #526
• draft of update for cvss v4 by @j--- in draft of update for cvss v4 #528
• Catch up README.md to current state by @ahouseholder in Catch up README.md to current state #518
• Remove WIP disclaimer from home page by @ccullen-cert in Remove WIP disclaimer from home page #507
• Fix license link in CONTRIBUTING.md by @ahouseholder in Fix license link in CONTRIBUTING.md #532
• Set up site deployment on publish branch by @ahouseholder in Set up site deployment on publish branch #533
• Update enumerating_stakeholders.md by @cgyarbrough in Update enumerating_stakeholders.md #535

New Contributors

• @koscinv made their first contribution in Add CWE-PoC list file #376
• @dependabot made their first contribution in Bump mkdocs-material from 9.5.4 to 9.5.6 #410
• @ccullen-cert made their first contribution in Update Exploitation:PoC definition #442
• @sei-bkoo made their first contribution in Human impact change proposal #476

Full Changelog: v2023.9...v2024.3

---

This discussion was created from the release SSVC v2024.3.