Publish v2025.9.3

.github/copilot-instructions.md

@@ -0,0 +1,168 @@
+# GitHub Copilot Instructions for SSVC
+
+This repository contains the **Stakeholder-Specific Vulnerability Categorization (SSVC)** project, which provides a system for prioritizing actions during vulnerability management.
+
+## Project Overview
+
+SSVC is a modular decision-making framework for vulnerability management that includes:
+- Python modules for decision points, decision tables, and outcomes
+- MkDocs-based documentation website
+- Interactive calculators and policy explorers
+- JSON/CSV data files for decision tables
+- Docker and Make-based development and deployment
+
+## Technology Stack
+
+- **Primary Language**: Python 3.x
+- **Package Management**: uv (package and project manager)
+- **Build Tool**: Make
+- **Documentation**: MkDocs with Material theme
+- **Testing**: pytest
+- **Data Models**: Pydantic for JSON schema validation
+- **Scientific Computing**: NumPy, SciPy, scikit-learn
+- **Web Framework**: FastAPI (for API endpoints)
+- **Containerization**: Docker and Docker Compose
+
+## Project Structure
+
+- `/src/ssvc/` - Core Python modules for SSVC functionality
+  - `decision_points/` - Decision point definitions
+  - `decision_tables/` - Decision table implementations
+  - `api/` - FastAPI application
+  - `outcomes/` - Outcome definitions
+  - `dp_groups/` - Decision point groups
+  - `registry/` - Registry functionality
+- `/docs/` - Markdown documentation source files
+- `/data/` - JSON and CSV data files for decision tables
+- `/src/test/` - Unit tests
+- `/docker/` - Docker configurations
+- `/obsolete/` - Deprecated code (do not modify)
+
+## Make Commands
+
+Use `make help` to see all available commands. Common targets include:
+
+- `make dev` - Set up development environment
+- `make test` - Run tests locally
+- `make docker_test` - Run tests in Docker
+- `make docs_local` - Serve documentation locally (http://localhost:8000/SSVC/)
+- `make docs` - Build and run documentation in Docker
+- `make api_dev` - Run API locally with auto-reload
+- `make api` - Build and run API in Docker
+- `make mdlint_fix` - Run markdown linting with auto-fix
+- `make regenerate_json` - Regenerate JSON files from Python modules
+
+## Development Workflow
+
+## Coding Conventions
+
+### Python Code
+
+- Follow PEP 8 style guidelines
+- Use type hints for function signatures and return types
+- Use Pydantic models for data validation
+- Document classes and functions with docstrings
+- Prefer explicit imports over wildcard imports
+- Module structure uses absolute imports from `ssvc` package
+
+### Naming Conventions
+
+- Python files: `snake_case.py`
+- Classes: `PascalCase`
+- Functions/variables: `snake_case`
+- Constants: `UPPER_SNAKE_CASE`
+
+## Testing Requirements
+
+### Test Structure
+
+- Unit tests use pytest framework
+- Tests are located in `/src/test/`
+- Test files follow pattern: `test_*.py`
+- Run tests with: `make test` or `uv run pytest -v`
+
+### Test Coverage
+
+- Write tests for new Python modules
+- Ensure decision points and tables have corresponding tests
+- Test JSON schema validation
+- Validate data model serialization/deserialization
+
+### Before Committing
+
+1. Run all tests: `make test`
+2. Ensure no test failures
+3. Fix any linting issues: `make mdlint_fix`
+4. Verify documentation builds: `make docs_local`
+
+## Documentation
+
+### Writing Documentation
+
+- Documentation uses MkDocs with Material theme
+- Files are in Markdown format in `/docs/`
+- Use Python exec blocks for dynamic content generation
+- Include examples and code snippets
+- Follow existing documentation structure
+
+### Documentation Features
+
+- Automatic API documentation via mkdocstrings
+- Python module imports for dynamic content generation
+- BibTeX citations via mkdocs-bibtex
+- Add markdown files to site navigation by specifying them in `mkdocs.yml`
+- Include markdown files in other markdown files with `mkdocs-include-markdown-plugin`
+- Dynamically generate content from python code blocks using the `markdown-exec` plugin
+
+## Data Files
+
+### JSON Files
+
+- Located in `/data/json/`
+- Generated from Python Pydantic models
+- Use JSON schema validation
+
+### CSV Files
+
+- Located in `/data/csv/`
+- Define decision table outcomes
+- Generated from python modules (The python data objects are authoritative)
+- Allows users to explore customizing SSVC for specific environments
+
+## Common Pitfalls
+
+1. **Import Paths**: Use absolute imports like `from ssvc.module import Class`, not relative imports
+2. **PYTHONPATH**: When running scripts directly, set `export PYTHONPATH=$PYTHONPATH:$(pwd)/src`
+3. **JSON Regeneration**: After modifying decision points/tables, regenerate JSON with `make regenerate_json`
+4. **Docker Context**: Some make targets use Docker, others run locally - check the Makefile
+5. **Package Management**: Use `make` commands or `uv` directly, not pip
+6. **Obsolete Code and Documentation**: Never modify files in `/obsolete/`, `/doc/`, or `/pdfs/` directories
+
+## API Development
+
+- FastAPI application is in `/src/ssvc/api/`
+- Run locally with auto-reload: `make api_dev` (serves on http://127.0.0.1:8000/docs)
+- Run in Docker: `make api` (serves on http://127.0.0.1:8001/SSVC/)
+
+## Git Workflow
+
+- Create feature branches for new work
+- Write descriptive commit messages
+- Reference issue numbers in commits when applicable
+- Keep commits focused and atomic
+- Run tests before pushing
+
+## Additional Resources
+
+- Main documentation: https://certcc.github.io/SSVC/
+- Source repository: https://github.com/CERTCC/SSVC
+- SSVC Calculator: https://certcc.github.io/SSVC/ssvc-calc/
+- Contributing guide: See CONTRIBUTING.md
+- Project wiki: https://github.com/CERTCC/SSVC/wiki
+
+## Special Notes
+
+- This project uses a MIT (SEI)-style license with Carnegie Mellon University copyright (see LICENSE file)
+- Decision points and tables follow SSVC specification
+- Backward compatibility is important for existing data files
+- Documentation changes should be reflected in both `/docs/` and `/src/README.md` when applicable

.github/dependabot.yml

@@ -8,7 +8,6 @@ updates:
   - package-ecosystem: "uv" # See documentation for possible values
     directories:
       - "/"
-      - "/src" # Location of package manifests
     schedule:
       interval: "weekly"
     groups:

.github/workflows/deploy_site.yml

@@ -43,15 +43,15 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install uv
-          uv sync --project=src --no-dev
+          uv sync --no-dev
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
       - name: Build Site
         run: |
           export PYTHONPATH=src:$PYTHONPATH
-          uv run --project=src mkdocs build --clean --config-file mkdocs.yml       
+          uv run mkdocs build --clean --config-file mkdocs.yml       
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v4

.github/workflows/link_checker.yml

@@ -11,8 +11,7 @@ on:
       # run on any PR that changes this workflow
       - .github/workflows/linkchecker.yml
       # run on any PR that changes the pip requirements
-      - requirements.txt
-      - src/pyproject.toml
+      - pyproject.toml
   # let us trigger it manually
   workflow_dispatch:
 
@@ -31,13 +30,13 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip uv
-          uv sync --dev --project=src
+          uv sync --dev
 
       - name: Build Site
         run: |
-          uv run --project=src mkdocs build --verbose --clean --config-file mkdocs.yml
+          uv run mkdocs build --verbose --clean --config-file mkdocs.yml
 
       - name: Check links
         run: |
-          uv run --project=src linkchecker site/index.html
+          uv run linkchecker site/index.html
 

.github/workflows/python-app.yml

@@ -28,16 +28,16 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip uv
-        uv sync --project=src --dev --frozen
+        uv sync --dev --frozen
 #    - uses: psf/black@stable
     - name: Test with pytest
       run: |
-        uv run --project=src pytest
+        uv run pytest
     - name: Build
       run: |
-        uv build --project=src
+        uv build 
     - name: Upload Artifacts
-      uses: actions/upload-artifact@v4
+      uses: actions/upload-artifact@v5
       with:
         name: ssvc
         path: src/dist/ssvc-*.tar.gz

.markdownlint.yml

@@ -1,3 +1,5 @@
+ignores:
+  - .github/**
 default: true
 # disable noisy rules
 # 0004 Unordered List style

Makefile

@@ -1,9 +1,8 @@
 # Project-specific vars
 MKDOCS_PORT=8765
 DOCKER_DIR=docker
-PROJECT_DIR = ./src
 DOCKER_COMPOSE=docker-compose --project-directory $(DOCKER_DIR)
-UV_RUN=uv run --project $(PROJECT_DIR)
+UV_RUN=uv run
 
 # Targets
 .PHONY: all test docs api docker_test clean help mdlint_fix up down regenerate_json
@@ -13,15 +12,15 @@ all: help
 
 dev:
 	@echo "Set up dev environment..."
-	uv sync --dev --project $(PROJECT_DIR)
+	uv sync --dev
 
 mdlint_fix:
 	@echo "Running markdownlint..."
 	markdownlint --config .markdownlint.yml --fix .
 
 test:
 	@echo "Running tests locally..."
-	uv run --project $(PROJECT_DIR) pytest -v
+	$(UV_RUN) pytest -v
 
 docker_test:
 	@echo "Building the latest test image..."
@@ -60,7 +59,7 @@ regenerate_json:
 clean:
 	@echo "Cleaning up Docker resources..."
 	$(DOCKER_COMPOSE) down --rmi local || true
-	rm -rf $(PROJECT_DIR)/.venv $(PROJECT_DIR)/uv.lock
+
 help:
 	@echo "Usage: make [target]"
 	@echo ""

docker/Dockerfile

@@ -3,35 +3,26 @@ RUN apt-get update && apt-get install -y --no-install-recommends git && rm -rf /
 RUN pip install --upgrade pip uv
 WORKDIR /app
 
-ENV VIRTUAL_ENV=/app/.venv
-ENV PATH="${VIRTUAL_ENV}/bin:${PATH}"
-
-RUN python -m venv "${VIRTUAL_ENV}"
 FROM base AS dependencies
 
-ARG BASE_DIR=..
-ARG SRC_DIR=${BASE_DIR}/src
-
 # Copy the files we need
-COPY ${BASE_DIR}/ /app
+COPY . /app
 # Set the environment variable
 ENV PYTHONPATH=/app/src
-COPY ${SRC_DIR}/pyproject.toml /app/src/pyproject.toml
-COPY ${SRC_DIR}/uv.lock /app/src/uv.lock
 
 # install requirements
-RUN uv sync --project=/app/src --frozen
-
+RUN uv sync --frozen
 
 FROM dependencies AS test
+
 ENV PYTHONPATH=/app/src
 # Install pytest and dev dependencies
-RUN uv sync --project=/app/src --frozen --dev
+RUN uv sync --frozen --dev
 # Run the unit tests
-CMD ["uv", "run", "--project=/app/src", "pytest"]
+CMD ["uv", "run", "pytest"]
 
 FROM dependencies AS docs
-CMD ["uv", "run", "--project=/app/src", "mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"]
+CMD ["uv", "run", "mkdocs", "serve", "--dev-addr", "0.0.0.0:8000"]
 
 FROM dependencies AS registry_api
-CMD ["uv", "run", "--project=/app/src", "uvicorn", "ssvc.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uv", "run", "uvicorn", "ssvc.api.main:app", "--host", "0.0.0.0", "--port", "8000"]

docker/env_example

@@ -0,0 +1,3 @@
+# copy or link this file to .env in this directory
+# this helps avoid docker image/container naming collisions
+COMPOSE_PROJECT_NAME=ssvc

docs/_includes/default_automatable_values.md

@@ -0,0 +1,5 @@
+!!! tip "Default Automatable Values"
+
+    If nothing is known about [*Automatable*](/reference/decision_points/automatable.md), the safer answer to assume is [*yes*](/reference/decision_points/automatable.md).
+    [*Value Density*](/reference/decision_points/value_density.md) should always be answerable; if the product is uncommon, it is probably
+    [*diffuse*](/reference/decision_points/value_density.md).

docs/_includes/default_exploitation_values.md

@@ -0,0 +1,4 @@
+!!! tip "Default Exploitation Values"
+
+    [*Exploitation*](../reference/decision_points/exploitation.md) needs no special default; if adequate searches are made for exploit code and none is
+    found, the answer is [*none*](../reference/decision_points/exploitation.md).

docs/_includes/default_mission_impact_values.md

@@ -0,0 +1,5 @@
+!!! tip "Default Mission Impact Values"
+
+    Similarly, with [*Mission Impact*](/reference/decision_points/mission_impact.md), the deployer should assume that the software is in use at the
+    organization for a reason, and that it supports essential functions unless they have evidence otherwise.
+    With a total lack of information, assume [*support crippled*](/reference/decision_points/mission_impact.md) as a default.

docs/_includes/default_safety_values.md

@@ -0,0 +1,6 @@
+!!! tip "Default Safety Values"
+
+    If the decision maker knows nothing about the environment in which the device is used, we suggest assuming a
+    [*marginal*](../reference/decision_points/safety_impact.md) [*Safety Impact*](../reference/decision_points/safety_impact.md).
+    This position is conservative, but software is thoroughly embedded in daily life now, so we suggest that the decision
+    maker provide evidence that no one's well-being will suffer.

docs/_includes/default_system_exposure_values.md

@@ -0,0 +1,5 @@
+!!! tip "Default System Exposure Values"
+
+    If the deployer does not know their exposure,<!--lowercase exposure on purpose, this is the general concept--> that
+    means they do not know where the devices are or how they are controlled, so they should assume
+    [*System Exposure*](../reference/decision_points/system_exposure.md) is [*open*](../reference/decision_points/system_exposure.md).