Merge branch 'main' into 705-model-national-cybersecurity-incident-scoring-system

Author: ahouseholder

.github/workflows/lint_md_changes.yml

@@ -16,12 +16,12 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0
+    - uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c
       id: changed-files
       with:
         files: '**/*.md'
         separator: ","
-    - uses: DavidAnson/markdownlint-cli2-action@v19
+    - uses: DavidAnson/markdownlint-cli2-action@v20
       if: steps.changed-files.outputs.any_changed == 'true'
       with:
         globs: ${{ steps.changed-files.outputs.all_changed_files }}

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -1,66 +1,58 @@
 # 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
+DOCKER_DIR=docker
 
 # Targets
-.PHONY: all dockerbuild_test dockerrun_test dockerbuild_docs dockerrun_docs docs docker_test clean help
+.PHONY: all test docs docker_test clean help mdlint_fix up down regenerate_json
 
 all: help
 
 mdlint_fix:
 	@echo "Running markdownlint..."
 	markdownlint --config .markdownlint.yml --fix .
 
-dockerbuild_test:
-	@echo "Building the test Docker image..."
-	$(DOCKER_BUILD) --target $(TEST_DOCKER_TARGET) --tag $(TEST_IMAGE) .
+test:
+	@echo "Running tests locally..."
+	pytest -v src/test
 
-dockerrun_test:
-	@echo "Running the test Docker image..."
-	$(DOCKER_RUN) $(PROJECT_VOLUME) $(TEST_IMAGE)
+docker_test:
+	@echo "Running tests in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose run --rm test
 
-dockerbuild_docs:
-	@echo "Building the docs Docker image..."
-	$(DOCKER_BUILD) --target $(DOCS_DOCKER_TARGET) --tag $(DOCS_IMAGE) .
+docs:
+	@echo "Building and running docs in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose up docs
 
-dockerrun_docs:
-	@echo "Running the docs Docker image..."
-	$(DOCKER_RUN) --publish $(MKDOCS_PORT):8000 $(PROJECT_VOLUME) $(DOCS_IMAGE)
+up:
+	@echo "Starting Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose up -d
 
+down:
+	@echo "Stopping Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose down
 
-docs: dockerbuild_docs dockerrun_docs
-docker_test: dockerbuild_test dockerrun_test
+regenerate_json:
+	@echo "Regenerating JSON files..."
+	rm -rf data/json/decision_points
+	export PYTHONPATH=$(PWD)/src && ./src/ssvc/doctools.py --jsondir=./data/json/decision_points --overwrite
 
 clean:
-	@echo "Cleaning up..."
-	$(DOCKER) rmi $(TEST_IMAGE) $(DOCS_IMAGE) || true
+	@echo "Cleaning up Docker resources..."
+	pushd $(DOCKER_DIR) && docker-compose down --rmi local || true
 
 help:
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
 	@echo " all         - Display this help message"
-	@echo " mdlint_fix  - Run markdownlint with --fix"
-	@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"
-
+	@echo " mdlint_fix  - Run markdownlint with fix"
+	@echo " test       - Run tests locally"
+	@echo " docker_test - Run tests in Docker"
+	@echo " docs       - Build and run documentation in Docker"
+	@echo " up         - Start Docker services"
+	@echo " down       - Stop Docker services"
+	@echo " regenerate_json - Regenerate JSON files from python modules"
+	@echo " clean      - Clean up Docker resources"
+	@echo " help       - Display this help message"
 
 

README.md

@@ -61,6 +61,19 @@ These json files are generated examples from the python `ssvc` module.
 
 These files are used by the `ssvc-calc` module.
 
+## `/docker/*`
+
+The `docker` directory contains Dockerfiles and related configurations for to
+create images that can run the SSVC documentation site and unit tests.
+
+Example:
+
+```bash
+cd docker
+docker-compose up test
+docker-compose up docs
+```
+
 ## `/src/*`
 
 This directory holds helper scripts that can make managing or using SSVC easier.
@@ -103,75 +116,29 @@ To preview any `make` command without actually executing it, run:
 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
-```
+### Run Local Docs Server
 
-Then navigate to <http://localhost:8765/SSVC/> to see the site.
+The easiest way to get started is using make to build a docker image and run the site. However, we provide a few other options below.
 
-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
-```
+| Environment | Command |
+|-------------|---------|
+| Make, Docker | `make docs` |
+| ~~Make~~, Docker | `cd docker && docker-compose up docs` |
+| ~~Make~~, ~~Docker~~ | `mkdocs serve` |
 
-Start a local server:
-
-```bash
-mkdocs serve
-```
-
-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`)
+Then navigate to <http://localhost:8000/SSVC/> to see the site.
 
 ## Run tests
 
 We include a few tests for the `ssvc` module.
-
-### Run Tests With Docker
-
-The easiest way to run tests is using make to build a docker image and run the tests:
-
-```bash
-make docker_test
-```
-
-Or, if make is not available:
-
-```bash
-docker build --target test --tag ssvc_test .
-docker run --tty --rm --volume .:/app ssvc_test
-```
-
-### Run Tests Without Docker
-
-```bash
-pip install pytest
-pytest src/test
-```
+Options for running the test suite are provided below.
+
+| Environment | Command | Comment |
+|-------------|---------|---------|
+| Make, Docker | `make docker_test` | runs in docker container |
+| ~~Make~~, Docker | `cd docker && docker-compose run -rm test` | runs in docker container |
+| Make, ~~Docker~~ | `make test` | runs in host OS |
+| ~~Make~~, ~~Docker~~ | `pytest src/test` | runs in host OS |
 
 ## Environment Variables
 

data/json/outcomes/CISA.json …ision_points/cisa/cisa_levels_1_0_0.jsondata/json/outcomes/CISA.json renamed to data/json/decision_points/cisa/cisa_levels_1_0_0.json data/json/outcomes/CISA.json renamed to data/json/decision_points/cisa/cisa_levels_1_0_0.json

@@ -1,9 +1,11 @@
 {
-  "version": "1.0.0",
-  "schemaVersion": "1-0-1",
   "name": "CISA Levels",
   "description": "The CISA outcome group. CISA uses its own SSVC decision tree model to prioritize relevant vulnerabilities into four possible decisions: Track, Track*, Attend, and Act.",
-  "outcomes": [
+  "namespace": "cisa",
+  "version": "1.0.0",
+  "schemaVersion": "1-0-1",
+  "key": "CISA",
+  "values": [
     {
       "key": "T",
       "name": "Track",
@@ -25,4 +27,4 @@
       "description": "The vulnerability requires attention from the organization's internal, supervisory-level and leadership-level individuals. Necessary actions include requesting assistance or information about the vulnerability, as well as publishing a notification either internally and/or externally. Typically, internal groups would meet to determine the overall response and then execute agreed upon actions. CISA recommends remediating Act vulnerabilities as soon as possible."
     }
   ]
-}
+}

data/json/decision_points/cisa/mission_prevalence_1_0_0.json

@@ -0,0 +1,25 @@
+{
+  "name": "Mission Prevalence",
+  "description": "Prevalence of the mission essential functions",
+  "namespace": "cisa",
+  "version": "1.0.0",
+  "schemaVersion": "1-0-1",
+  "key": "MP",
+  "values": [
+    {
+      "key": "M",
+      "name": "Minimal",
+      "description": "Neither Support nor Essential apply. The vulnerable component may be used within the entities, but it is not used as a mission-essential component, nor does it provide impactful support to mission-essential functions."
+    },
+    {
+      "key": "S",
+      "name": "Support",
+      "description": "The vulnerable component only supports MEFs for two or more entities."
+    },
+    {
+      "key": "E",
+      "name": "Essential",
+      "description": "The vulnerable component directly provides capabilities that constitute at least one MEF for at least one entity; component failure may (but does not necessarily) lead to overall mission failure."
+    }
+  ]
+}

data/json/decision_points/cvss/availability_impact_2_0_1.json

@@ -0,0 +1,35 @@
+{
+  "name": "CVSS Qualitative Severity Rating Scale",
+  "description": "The CVSS Qualitative Severity Rating Scale group.",
+  "namespace": "cvss",
+  "version": "1.0.0",
+  "schemaVersion": "1-0-1",
+  "key": "CVSS",
+  "values": [
+    {
+      "key": "N",
+      "name": "None",
+      "description": "None (0.0)"
+    },
+    {
+      "key": "L",
+      "name": "Low",
+      "description": "Low (0.1-3.9)"
+    },
+    {
+      "key": "M",
+      "name": "Medium",
+      "description": "Medium (4.0-6.9)"
+    },
+    {
+      "key": "H",
+      "name": "High",
+      "description": "High (7.0-8.9)"
+    },
+    {
+      "key": "C",
+      "name": "Critical",
+      "description": "Critical (9.0-10.0)"
+    }
+  ]
+}