SSVC Schemas and Example data

README.md

This is related to CERTCC/SSVC#289 to capture files that have example JSON Schema and example JSON data

Decision_Point.schema.json

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Decision Point schema definition for SSVC",
    "description": "This provides a schema for one or more Decision Point(s) to be defined as part of an SSVC Decisions",
    "type": "object",
    "definitions": {
	"option": {
	    "type": "object",
	    "properties": {
		"key": {
		    "type": "string",
		    "description": "A short \"key\" that identifies this Decision Value in SSVC vector form.  This is one or two letter(s) used in short-form vector representation."
		},
		"label": {
		    "type": "string",
		    "description": "A short label that captures a short name of this Decision Value e.g., \"Proof of Concept\""  
		},
		"description": {
		    "type": "string"
		}
	    },
	    "required": ["key","label"],
	    "additionalProperties": false
	},
	"decision_point": {
	    "type": "object",
	    "properties": {
		"description": {
		    "type":"string"
		},
		"label": {
		    "description": "A short label that captures a short name of this Decision Point e.g., Exploitation",
		    "type":"string"
		},
		"key": {
		    "type":"string",
		    "description": "A short \"key\" that identifies this Decision Point in SSVC vector form.  This is one or two letter(s) used in short-form vector representation."		    
		},
		"version": {
		    "type":"string"
		},	
		"options": {
		    "type": "array",
		    "items": {
			"$ref": "#/definitions/option"
		    },
		    "minItems": 1
		}
	    },
	    "required" : ["options","label","key","version"],
	    "additionalProperties": false
	}
    },
    "properties": {
	"decision_points": {
	    "type": "array",
	    "items": {
		"$ref": "#/definitions/decision_point" }
	}
    },
    "required": ["decision_points"],
    "additionalProperties": false
}

Exploitation.json

{
    "decision_points": [
        {
            "options": [
                {
                    "description": "There is no evidence of active exploitation and no public proof of concept (PoC) of how to exploit the vulnerability.",
                    "label": "None",
		    "key": "N"
                },
                {
                    "description": "(Proof of Concept)One of the following cases is true: (1) private evidence of exploitation is attested but not shared; (2) widespread hearsay attests to exploitation; (3) typical public PoC in places such as Metasploit or ExploitDB; or (4) the vulnerability has a well-known method of exploitation. Some examples of condition (4) are open-source web proxies serve as the PoC code for how to exploit any vulnerability in the vein of improper validation of TLS certificates. As another example, Wireshark serves as a PoC for packet replay attacks on ethernet or WiFi networks.",
                    "label": "PoC",
		    "key": "P"
                },
                {
                    "description": "Shared, observable, reliable evidence that the exploit is being used in the wild by real attackers; there is credible public reporting.",
                    "label": "Active",
		    "key": "A"
                }
            ],
            "label": "Exploitation",
	    "description": "Evidence of Active Exploitation of a Vulnerability. The intent of this measure is the present state of exploitation of the vulnerability. The intent is not to predict future exploitation but only to acknowledge the current state of affairs. Predictive systems, such as EPSS, could be used to augment this decision or to notify stakeholders of likely changes.",
	    "key": "E",
	    "version": "1.1.1"
        }
    ]
}

This looks good. I have a few thoughts/suggestions:

1. change "options" to "values" to reflect the terminology in the docs
2. s/label/name/g because "name" and "key" are more intuitively different than "label" and "key"?
3. consider adding a namespace to be prefixed to keys where it gets ambiguous?

On the last one, I'm thinking of a world where we want to include things like "cvss:E" vs "ssvc:E", and we don't get to pick what letters CVSS uses for their keys, nor do we want to force SSVC and CVSS to maintain a shared namespace (because we can't do that anyway).
I'd probably implement it as a separate namespace key that could occur at the decision point level.

so on (3) do we want to basically do something like below? Do we want SSVC version also apart from the namespace? Do we independently iterate Decision Points versioning so it is not needed to identify SSVC version. I am leaning towards the later.

{
    "decision_points": [
        {
            "values": [
                {
                    "description": "There is no evidence of active exploitation and no public proof of concept (PoC) of how to exploit the vulnerability.",
                    "name": "None",
		    "key": "N"
                },
                {
                    "description": "(Proof of Concept)One of the following cases is true: (1) private evidence of exploitation is attested but not shared; (2) widespread hearsay attests to exploitation; (3) typical public PoC in places such as Metasploit or ExploitDB; or (4) the vulnerability has a well-known method of exploitation. Some examples of condition (4) are open-source web proxies serve as the PoC code for how to exploit any vulnerability in the vein of improper validation of TLS certificates. As another example, Wireshark serves as a PoC for packet replay attacks on ethernet or WiFi networks.",
                    "label": "PoC",
		    "key": "P"
                },
                {
                    "description": "Shared, observable, reliable evidence that the exploit is being used in the wild by real attackers; there is credible public reporting.",
                    "name": "Active",
		    "key": "A"
                }
            ],
            "value": "Exploitation",
	    "description": "Evidence of Active Exploitation of a Vulnerability. The intent of this measure is the present state of exploitation of the vulnerability. The intent is not to predict future exploitation but only to acknowledge the current state of affairs. Predictive systems, such as EPSS, could be used to augment this decision or to notify stakeholders of likely changes.",
	    "key": "E",
            "namespace": "SSVC",
	    "version": "1.1.1"
        }
    ]
}

Yeah. See for example https://github.com/ahouseholder/SSVC/blob/feature/pyjson/docs/reference/examples/exploitation.json

I'm generating that from this https://github.com/ahouseholder/SSVC/blob/feature/pyjson/src/ssvc/decision_points/exploitation.py

(I took your json format an ran with it)

I created a separate "Decision Points Group" object that provides the decision_points: [...] wrapper.

Decision Points Group -contains-> Decision Points -contains-> Values