Publish v2025.2 to site

.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@v45
+      id: changed-files
+      with:
+        files: '**/*.md'
+        separator: ","
+    - uses: DavidAnson/markdownlint-cli2-action@v19
+      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.
-

Dockerfile

@@ -1,18 +1,23 @@
-FROM python:3.12-slim-bookworm
-
+FROM python:3.12-slim-bookworm AS base
+RUN pip install --upgrade pip
 WORKDIR /app
 
+FROM base AS dependencies
+
 # install requirements
 COPY requirements.txt .
 RUN pip install -r requirements.txt
-
 # Copy the files we need
-COPY src/ .
-COPY data ./data
+COPY . /app
+# Set the environment variable
+ENV PYTHONPATH=/app/src
 
+
+FROM dependencies AS test
 # install pytest
 RUN pip install pytest
-
 # run the unit tests \
-ENTRYPOINT ["pytest"]
-CMD ["test"]
+CMD ["pytest","src/test"]
+
+FROM dependencies AS docs
+CMD ["mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"]

LICENSE

@@ -3,7 +3,7 @@ The following license applies to software contained in this repository.
 ----
 MIT License
 
-Copyright (c) 2020 Carnegie Mellon University
+Copyright (c) 2020-2025 Carnegie Mellon University
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -0,0 +1,61 @@
+# Project-specific vars
+PFX=ssvc
+DOCKER=docker
+DOCKER_BUILD=$(DOCKER) build
+DOCKER_RUN=$(DOCKER) run --tty --rm
+PROJECT_VOLUME=--volume $(shell pwd):/app
+MKDOCS_PORT=8765
+
+# docker names
+TEST_DOCKER_TARGET=test
+TEST_IMAGE = $(PFX)_test
+DOCS_DOCKER_TARGET=docs
+DOCS_IMAGE = $(PFX)_docs
+
+# Targets
+.PHONY: all dockerbuild_test dockerrun_test dockerbuild_docs dockerrun_docs docs docker_test clean help
+
+all: help
+
+dockerbuild_test:
+	@echo "Building the test Docker image..."
+	$(DOCKER_BUILD) --target $(TEST_DOCKER_TARGET) --tag $(TEST_IMAGE) .
+
+dockerrun_test:
+	@echo "Running the test Docker image..."
+	$(DOCKER_RUN) $(PROJECT_VOLUME) $(TEST_IMAGE)
+
+dockerbuild_docs:
+	@echo "Building the docs Docker image..."
+	$(DOCKER_BUILD) --target $(DOCS_DOCKER_TARGET) --tag $(DOCS_IMAGE) .
+
+dockerrun_docs:
+	@echo "Running the docs Docker image..."
+	$(DOCKER_RUN) --publish $(MKDOCS_PORT):8000 $(PROJECT_VOLUME) $(DOCS_IMAGE)
+
+
+docs: dockerbuild_docs dockerrun_docs
+docker_test: dockerbuild_test dockerrun_test
+
+clean:
+	@echo "Cleaning up..."
+	$(DOCKER) rmi $(TEST_IMAGE) $(DOCS_IMAGE) || true
+
+help:
+	@echo "Usage: make [target]"
+	@echo ""
+	@echo "Targets:"
+	@echo " all         - Display this help message"
+	@echo " docs        - Build and run the docs Docker image"
+	@echo " docker_test - Build and run the test Docker image"
+	@echo ""
+	@echo " dockerbuild_test - Build the test Docker image"
+	@echo " dockerrun_test   - Run the test Docker image"
+	@echo " dockerbuild_docs - Build the docs Docker image"
+	@echo " dockerrun_docs   - Run the docs Docker image"
+	@echo ""
+	@echo " clean - Remove the Docker images"
+	@echo " help  - Display this help message"
+
+
+

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,12 +81,57 @@ 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:
+The simplest way to get started with local development is to use Docker.
+We provide a Dockerfile that builds an image with all the dependencies needed to build the site.
+We also provide a `Makefile` that simplifies the process of building the site and running a local server,
+so you don't have to remember the exact `docker build` and `docker run` commands
+to get started.
+
+### Make Commands
+
+To display the available `make` commands, run:
+
+```bash
+make help
+```
+
+To preview any `make` command without actually executing it, run:
 
 ```bash
+make -n <command>
+```
+
+### Run Local Server With Docker
+
+The easiest way to get started is using make to build a docker image and run the site:
+
+```bash
+make docs
+```
+
+Then navigate to <http://localhost:8765/SSVC/> to see the site.
+
+Note that the docker container will display a message with the URL to visit, for
+example: `Serving on http://0.0.0.0:8000/SSVC/` in the output. However, that port
+is only available inside the container. The host port 8765 is mapped to the container's
+port 8000, so you should navigate to <http://localhost:8765/SSVC/> to see the site.
+
+Or, if make is not available:
+
+```bash
+docker build --target docs --tag ssvc_docs .
+docker run --tty --rm -p 8765:8000 --volume .:/app ssvc_docs
+```
+
+### Run Local Server Without Docker
+
+If you prefer to run the site locally without Docker, you can do so with mkdocs.
+We recommend using a virtual environment to manage dependencies:
+
+```bash
+python3 -m venv ssvc_venv
 pip install -r requirements.txt
 ```
 
@@ -97,32 +141,47 @@ Start a local server:
 mkdocs serve
 ```
 
-Navigate to http://localhost:8001/ to see the site.
+By default, the server will run on port 8001.
+This is configured in the `mkdocs.yml` file.
+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.
 
-### With Docker
+### Run Tests With Docker
 
-```bash
+The easiest way to run tests is using make to build a docker image and run the tests:
 
-docker build -t ssvc_test .
-docker run -it --rm ssvc_test
+```bash
+make docker_test
 ```
 
-### Without Docker
+Or, if make is not available:
 
 ```bash
-pip install pytest  # if you haven't already
+docker build --target test --tag ssvc_test .
+docker run --tty --rm --volume .:/app ssvc_test
+```
+
+### Run Tests Without Docker
 
-pytest # should find tests in src/test/*
+```bash
+pip install pytest
+pytest src/test
 ```
 
+## Environment Variables
 
+If you encounter a problem with the `ssvc` module not being found, you may need to set the `PYTHONPATH` environment variable.
+The Dockerfile takes care of this in the Docker environment.
+When not running in Docker, make sure that the `src` directory is in your `PYTHONPATH`:
 
+```bash
+export PYTHONPATH=$PYTHONPATH:$(pwd)/src
+```
 
 ## Contributing
 
@@ -147,5 +206,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/json/decision_points/automatable_2_0_0.json

@@ -17,4 +17,4 @@
       "description": "Attackers can reliably automate steps 1-4 of the kill chain."
     }
   ]
-}
+}

data/json/decision_points/cvss/access_complexity_1_0_0.json

@@ -0,0 +1,20 @@
+{
+  "namespace": "cvss",
+  "version": "1.0.0",
+  "schemaVersion": "1-0-1",
+  "key": "AC",
+  "name": "Access Complexity",
+  "description": "This metric measures the complexity of the attack required to exploit the vulnerability once an attacker has gained access to the target system.",
+  "values": [
+    {
+      "key": "L",
+      "name": "Low",
+      "description": "Specialized access conditions or extenuating circumstances do not exist; the system is always exploitable."
+    },
+    {
+      "key": "H",
+      "name": "High",
+      "description": "Specialized access conditions exist; for example: the system is exploitable during specific windows of time (a race condition), the system is exploitable under specific circumstances (nondefault configurations), or the system is exploitable with victim interaction (vulnerability exploitable only if user opens e-mail)"
+    }
+  ]
+}