Skip to content

Commit 4e524f9

Browse files
ahouseholderahouseholder
authored
Merge branch 'main' into reference
2 parents a29f509 + 39233c2 commit 4e524f9

File tree

337 files changed

+20531
-2138
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

337 files changed

+20531
-2138
lines changed

‎.github/workflows/link_checker.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ jobs:
2525
- name: Set up Python
2626
uses: actions/setup-python@v5
2727
with:
28-
python-version: '3.10'
28+
python-version: '3.12'
2929

3030
- name: Install dependencies
3131
run: |

‎Makefile‎

Lines changed: 34 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,60 @@
11
# Project-specific vars
2-
PFX=ssvc
3-
DOCKER=docker
4-
DOCKER_BUILD=$(DOCKER) build
5-
DOCKER_RUN=$(DOCKER) run --tty --rm
6-
PROJECT_VOLUME=--volume $(shell pwd):/app
72
MKDOCS_PORT=8765
8-
9-
# docker names
10-
TEST_DOCKER_TARGET=test
11-
TEST_IMAGE = $(PFX)_test
12-
DOCS_DOCKER_TARGET=docs
13-
DOCS_IMAGE = $(PFX)_docs
3+
DOCKER_DIR=docker
144

155
# Targets
16-
.PHONY: all dockerbuild_test dockerrun_test dockerbuild_docs dockerrun_docs docs docker_test clean help
6+
.PHONY: all test docs docker_test clean help mdlint_fix up down regenerate_json
177

188
all: help
199

2010
mdlint_fix:
2111
@echo "Running markdownlint..."
2212
markdownlint --config .markdownlint.yml --fix .
2313

24-
dockerbuild_test:
25-
@echo "Building the test Docker image..."
26-
$(DOCKER_BUILD) --target $(TEST_DOCKER_TARGET) --tag $(TEST_IMAGE) .
14+
test:
15+
@echo "Running tests locally..."
16+
pytest -v src/test
2717

28-
dockerrun_test:
29-
@echo "Running the test Docker image..."
30-
$(DOCKER_RUN) $(PROJECT_VOLUME) $(TEST_IMAGE)
18+
docker_test:
19+
@echo "Building the latest test image..."
20+
pushd $(DOCKER_DIR) && docker-compose build test
21+
@echo "Running tests in Docker..."
22+
pushd $(DOCKER_DIR) && docker-compose run --rm test
3123

32-
dockerbuild_docs:
33-
@echo "Building the docs Docker image..."
34-
$(DOCKER_BUILD) --target $(DOCS_DOCKER_TARGET) --tag $(DOCS_IMAGE) .
24+
docs:
25+
@echo "Building and running docs in Docker..."
26+
pushd $(DOCKER_DIR) && docker-compose up docs
3527

36-
dockerrun_docs:
37-
@echo "Running the docs Docker image..."
38-
$(DOCKER_RUN) --publish $(MKDOCS_PORT):8000 $(PROJECT_VOLUME) $(DOCS_IMAGE)
28+
up:
29+
@echo "Starting Docker services..."
30+
pushd $(DOCKER_DIR) && docker-compose up -d
3931

32+
down:
33+
@echo "Stopping Docker services..."
34+
pushd $(DOCKER_DIR) && docker-compose down
4035

41-
docs: dockerbuild_docs dockerrun_docs
42-
docker_test: dockerbuild_test dockerrun_test
36+
regenerate_json:
37+
@echo "Regenerating JSON files..."
38+
rm -rf data/json/decision_points
39+
export PYTHONPATH=$(PWD)/src && ./src/ssvc/doctools.py --jsondir=./data/json/decision_points --overwrite
4340

4441
clean:
45-
@echo "Cleaning up..."
46-
$(DOCKER) rmi $(TEST_IMAGE) $(DOCS_IMAGE) || true
42+
@echo "Cleaning up Docker resources..."
43+
pushd $(DOCKER_DIR) && docker-compose down --rmi local || true
4744

4845
help:
4946
@echo "Usage: make [target]"
5047
@echo ""
5148
@echo "Targets:"
5249
@echo " all - Display this help message"
53-
@echo " mdlint_fix - Run markdownlint with --fix"
54-
@echo " docs - Build and run the docs Docker image"
55-
@echo " docker_test - Build and run the test Docker image"
56-
@echo ""
57-
@echo " dockerbuild_test - Build the test Docker image"
58-
@echo " dockerrun_test - Run the test Docker image"
59-
@echo " dockerbuild_docs - Build the docs Docker image"
60-
@echo " dockerrun_docs - Run the docs Docker image"
61-
@echo ""
62-
@echo " clean - Remove the Docker images"
63-
@echo " help - Display this help message"
64-
50+
@echo " mdlint_fix - Run markdownlint with fix"
51+
@echo " test - Run tests locally"
52+
@echo " docker_test - Run tests in Docker"
53+
@echo " docs - Build and run documentation in Docker"
54+
@echo " up - Start Docker services"
55+
@echo " down - Stop Docker services"
56+
@echo " regenerate_json - Regenerate JSON files from python modules"
57+
@echo " clean - Clean up Docker resources"
58+
@echo " help - Display this help message"
6559

6660

‎README.md‎

Lines changed: 29 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,19 @@ These json files are generated examples from the python `ssvc` module.
6161

6262
These files are used by the `ssvc-calc` module.
6363

64+
## `/docker/*`
65+
66+
The `docker` directory contains Dockerfiles and related configurations for to
67+
create images that can run the SSVC documentation site and unit tests.
68+
69+
Example:
70+
71+
```bash
72+
cd docker
73+
docker-compose up test
74+
docker-compose up docs
75+
```
76+
6477
## `/src/*`
6578

6679
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:
103116
make -n <command>
104117
```
105118

106-
### Run Local Server With Docker
107-
108-
The easiest way to get started is using make to build a docker image and run the site:
109-
110-
```bash
111-
make docs
112-
```
119+
### Run Local Docs Server
113120

114-
Then navigate to <http://localhost:8765/SSVC/> to see the site.
121+
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.
115122

116-
Note that the docker container will display a message with the URL to visit, for
117-
example: `Serving on http://0.0.0.0:8000/SSVC/` in the output. However, that port
118-
is only available inside the container. The host port 8765 is mapped to the container's
119-
port 8000, so you should navigate to <http://localhost:8765/SSVC/> to see the site.
120-
121-
Or, if make is not available:
122-
123-
```bash
124-
docker build --target docs --tag ssvc_docs .
125-
docker run --tty --rm -p 8765:8000 --volume .:/app ssvc_docs
126-
```
127-
128-
### Run Local Server Without Docker
129-
130-
If you prefer to run the site locally without Docker, you can do so with mkdocs.
131-
We recommend using a virtual environment to manage dependencies:
132-
133-
```bash
134-
python3 -m venv ssvc_venv
135-
pip install -r requirements.txt
136-
```
123+
| Environment | Command |
124+
|-------------|---------|
125+
| Make, Docker | `make docs` |
126+
| ~~Make~~, Docker | `cd docker && docker-compose up docs` |
127+
| ~~Make~~, ~~Docker~~ | `mkdocs serve` |
137128

138-
Start a local server:
139-
140-
```bash
141-
mkdocs serve
142-
```
143-
144-
By default, the server will run on port 8001.
145-
This is configured in the `mkdocs.yml` file.
146-
Navigate to <http://localhost:8001/> to see the site.
147-
148-
(Hint: You can use the `--dev-addr` argument with mkdocs to change the port, e.g. `mkdocs serve --dev-addr localhost:8000`)
129+
Then navigate to <http://localhost:8000/SSVC/> to see the site.
149130

150131
## Run tests
151132

152133
We include a few tests for the `ssvc` module.
153-
154-
### Run Tests With Docker
155-
156-
The easiest way to run tests is using make to build a docker image and run the tests:
157-
158-
```bash
159-
make docker_test
160-
```
161-
162-
Or, if make is not available:
163-
164-
```bash
165-
docker build --target test --tag ssvc_test .
166-
docker run --tty --rm --volume .:/app ssvc_test
167-
```
168-
169-
### Run Tests Without Docker
170-
171-
```bash
172-
pip install pytest
173-
pytest src/test
174-
```
134+
Options for running the test suite are provided below.
135+
136+
| Environment | Command | Comment |
137+
|-------------|---------|---------|
138+
| Make, Docker | `make docker_test` | runs in docker container |
139+
| ~~Make~~, Docker | `cd docker && docker-compose run -rm test` | runs in docker container |
140+
| Make, ~~Docker~~ | `make test` | runs in host OS |
141+
| ~~Make~~, ~~Docker~~ | `pytest src/test` | runs in host OS |
175142

176143
## Environment Variables
177144

‎data/json/decision_points/basic/do_schedule_delegate_delete_1_0_0.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"namespace": "basic",
3+
"key": "IKE",
4+
"version": "1.0.0",
5+
"name": "Do, Schedule, Delegate, Delete",
6+
"description": "The Eisenhower outcome group.",
7+
"schemaVersion": "2.0.0",
8+
"values": [
9+
{
10+
"key": "D",
11+
"name": "Delete",
12+
"description": "Delete"
13+
},
14+
{
15+
"key": "G",
16+
"name": "Delegate",
17+
"description": "Delegate"
18+
},
19+
{
20+
"key": "S",
21+
"name": "Schedule",
22+
"description": "Schedule"
23+
},
24+
{
25+
"key": "O",
26+
"name": "Do",
27+
"description": "Do"
28+
}
29+
]
30+
}

data/json/outcomes/CVSS.json renamed to data/json/decision_points/basic/lowmediumhigh_1_0_0.json

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
{
2+
"namespace": "basic",
3+
"key": "LMH",
24
"version": "1.0.0",
3-
"schemaVersion": "1-0-1",
4-
"name": "CVSS Levels",
5-
"description": "The CVSS outcome group.",
6-
"outcomes": [
5+
"name": "LowMediumHigh",
6+
"description": "A Low/Medium/High decision point / outcome group.",
7+
"schemaVersion": "2.0.0",
8+
"values": [
79
{
810
"key": "L",
911
"name": "Low",
@@ -18,11 +20,6 @@
1820
"key": "H",
1921
"name": "High",
2022
"description": "High"
21-
},
22-
{
23-
"key": "C",
24-
"name": "Critical",
25-
"description": "Critical"
2623
}
2724
]
28-
}
25+
}

‎data/json/decision_points/basic/moscow_1_0_0.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"namespace": "basic",
3+
"key": "MSCW",
4+
"version": "1.0.0",
5+
"name": "MoSCoW",
6+
"description": "The MoSCoW (Must, Should, Could, Won't) outcome group.",
7+
"schemaVersion": "2.0.0",
8+
"values": [
9+
{
10+
"key": "W",
11+
"name": "Won't",
12+
"description": "Won't"
13+
},
14+
{
15+
"key": "C",
16+
"name": "Could",
17+
"description": "Could"
18+
},
19+
{
20+
"key": "S",
21+
"name": "Should",
22+
"description": "Should"
23+
},
24+
{
25+
"key": "M",
26+
"name": "Must",
27+
"description": "Must"
28+
}
29+
]
30+
}

‎data/json/decision_points/basic/value_complexity_1_0_0.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"namespace": "basic",
3+
"key": "VALUE_COMPLEXITY",
4+
"version": "1.0.0",
5+
"name": "Value, Complexity",
6+
"description": "The Value/Complexity outcome group.",
7+
"schemaVersion": "2.0.0",
8+
"values": [
9+
{
10+
"key": "D",
11+
"name": "Drop",
12+
"description": "Drop"
13+
},
14+
{
15+
"key": "R",
16+
"name": "Reconsider Later",
17+
"description": "Reconsider Later"
18+
},
19+
{
20+
"key": "E",
21+
"name": "Easy Win",
22+
"description": "Easy Win"
23+
},
24+
{
25+
"key": "F",
26+
"name": "Do First",
27+
"description": "Do First"
28+
}
29+
]
30+
}

‎data/json/decision_points/basic/yesno_1_0_0.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"namespace": "basic",
3+
"key": "YN",
4+
"version": "1.0.0",
5+
"name": "YesNo",
6+
"description": "A Yes/No decision point / outcome group.",
7+
"schemaVersion": "2.0.0",
8+
"values": [
9+
{
10+
"key": "N",
11+
"name": "No",
12+
"description": "No"
13+
},
14+
{
15+
"key": "Y",
16+
"name": "Yes",
17+
"description": "Yes"
18+
}
19+
]
20+
}

data/json/outcomes/CISA.json renamed to data/json/decision_points/cisa/cisa_levels_1_0_0.json

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
{
2+
"namespace": "cisa",
3+
"key": "CISA",
24
"version": "1.0.0",
3-
"schemaVersion": "1-0-1",
45
"name": "CISA Levels",
56
"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.",
6-
"outcomes": [
7+
"schemaVersion": "2.0.0",
8+
"values": [
79
{
810
"key": "T",
911
"name": "Track",
@@ -25,4 +27,4 @@
2527
"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."
2628
}
2729
]
28-
}
30+
}

0 commit comments

Comments
 (0)