Merge branch 'main' of https://github.com/CERTCC/SSVC into publish

Author: ahouseholder

.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."
     }
   ]
-}
+}