Skip to content

Commit 6ec41a6

Browse files
stevespringettstevespringett
committed
Added control as first-class citizen and expanded use of controls to related areas in the spec.
Signed-off-by: Steve Springett <steve@springett.us>
1 parent cc44d4b commit 6ec41a6

6 files changed

Lines changed: 252 additions & 98 deletions

‎schema/2.0/cyclonedx-2.0.schema.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,9 @@
7070
"risks": {
7171
"$ref": "model/cyclonedx-risk-2.0.schema.json#/$defs/risks"
7272
},
73+
"controls": {
74+
"$ref": "model/cyclonedx-control-2.0.schema.json#/$defs/controls"
75+
},
7376
"annotations": {
7477
"$ref": "model/cyclonedx-annotation-2.0.schema.json#/$defs/annotations"
7578
},

‎schema/2.0/model/cyclonedx-control-2.0.schema.json‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://cyclonedx.org/schema/2.0/model/cyclonedx-control-2.0.schema.json",
4+
"type": "null",
5+
"title": "CycloneDX Control Model",
6+
"$comment": "OWASP CycloneDX is an Ecma International standard (ECMA-424) developed in collaboration between the OWASP Foundation and Ecma Technical Committee 54 (TC54). The standard is published under a royalty-free patent policy. This JSON schema is the reference implementation and is licensed under the Apache License 2.0.",
7+
"$defs": {
8+
"controls": {
9+
"type": "array",
10+
"title": "Controls",
11+
"uniqueItems": true,
12+
"items": {
13+
"$ref": "#/$defs/control"
14+
},
15+
"description": "The safeguards and countermeasures that are recommended or in place. Controls may be declared on their own for governance, risk, and compliance use cases, or referenced from threats, trust boundaries, and risk responses."
16+
},
17+
"control": {
18+
"type": "object",
19+
"title": "Control",
20+
"description": "A safeguard or countermeasure that protects systems, data, or operations. A control binds the elements that implement it to the requirements it satisfies, and records its implementation status and assessed effectiveness.",
21+
"required": [
22+
"bom-ref",
23+
"name"
24+
],
25+
"additionalProperties": false,
26+
"properties": {
27+
"bom-ref": {
28+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType",
29+
"description": "An identifier which can be used to reference the control elsewhere using a bom-ref or bom-link."
30+
},
31+
"name": {
32+
"type": "string",
33+
"minLength": 1,
34+
"title": "Name",
35+
"description": "The name of the control."
36+
},
37+
"description": {
38+
"type": "string",
39+
"title": "Description",
40+
"description": "A description of the control."
41+
},
42+
"category": {
43+
"title": "Category",
44+
"description": "The category of the control. Use the custom option for a category specific to an organization's taxonomy.",
45+
"oneOf": [
46+
{
47+
"title": "Predefined Control Category",
48+
"type": "string",
49+
"enum": [
50+
"preventive",
51+
"detective",
52+
"corrective",
53+
"compensating",
54+
"deterrent",
55+
"recovery"
56+
],
57+
"meta:enum": {
58+
"preventive": "Prevents an unwanted event from occurring.",
59+
"detective": "Identifies and records that an unwanted event has occurred or is occurring.",
60+
"corrective": "Remedies the condition that allowed an unwanted event.",
61+
"compensating": "Provides an alternative safeguard where a primary control is not feasible.",
62+
"deterrent": "Discourages an actor from attempting an unwanted action.",
63+
"recovery": "Restores operations after an unwanted event."
64+
}
65+
},
66+
{
67+
"title": "Custom Control Category",
68+
"type": "object",
69+
"required": [
70+
"name"
71+
],
72+
"additionalProperties": false,
73+
"properties": {
74+
"name": {
75+
"type": "string",
76+
"minLength": 1,
77+
"title": "Name",
78+
"description": "The name of the custom category."
79+
},
80+
"description": {
81+
"type": "string",
82+
"title": "Description",
83+
"description": "A description of the custom category."
84+
}
85+
}
86+
}
87+
]
88+
},
89+
"status": {
90+
"title": "Status",
91+
"description": "The implementation status of the control.",
92+
"$ref": "#/$defs/implementationStatus"
93+
},
94+
"appliesTo": {
95+
"type": "array",
96+
"title": "Applies To",
97+
"uniqueItems": true,
98+
"minItems": 1,
99+
"items": {
100+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
101+
},
102+
"description": "References using bom-link or bom-ref to the elements the control protects, such as components, services, zones, or boundaries. A control without this property applies to the organization or system as a whole."
103+
},
104+
"implementedBy": {
105+
"type": "array",
106+
"title": "Implemented By",
107+
"uniqueItems": true,
108+
"minItems": 1,
109+
"items": {
110+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
111+
},
112+
"description": "References using bom-link or bom-ref to the components, services, formulation workflows, or parties that implement the control."
113+
},
114+
"satisfies": {
115+
"type": "array",
116+
"title": "Satisfies",
117+
"uniqueItems": true,
118+
"minItems": 1,
119+
"items": {
120+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
121+
},
122+
"description": "References using bom-link or bom-ref to the requirements the control satisfies, including requirements defined within standards."
123+
},
124+
"effectiveness": {
125+
"title": "Effectiveness",
126+
"description": "The assessed effectiveness of the control.",
127+
"$ref": "#/$defs/effectiveness"
128+
},
129+
"owner": {
130+
"$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice",
131+
"description": "The party accountable for the control. May be an inline party object or a reference to a previously declared party."
132+
},
133+
"externalReferences": {
134+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReferences"
135+
},
136+
"properties": {
137+
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties"
138+
}
139+
}
140+
},
141+
"implementationStatus": {
142+
"title": "Implementation Status",
143+
"description": "The implementation status of a control or response. Use the custom option for a status specific to an organization's process.",
144+
"oneOf": [
145+
{
146+
"title": "Predefined Implementation Status",
147+
"type": "string",
148+
"enum": [
149+
"recommended",
150+
"proposed",
151+
"approved",
152+
"rejected",
153+
"planned",
154+
"in-progress",
155+
"implemented",
156+
"verified",
157+
"decommissioned"
158+
],
159+
"meta:enum": {
160+
"recommended": "Suggested by a producer, standard, or assessor. Not yet entered into the adopting organization's decision process.",
161+
"proposed": "Entered into the adopting organization's decision process but not yet approved.",
162+
"approved": "Approved for implementation.",
163+
"rejected": "Considered and declined, with no intent to implement.",
164+
"planned": "Implementation is planned.",
165+
"in-progress": "Implementation is in progress.",
166+
"implemented": "Implemented and in effect.",
167+
"verified": "Implemented and verified as effective.",
168+
"decommissioned": "Removed from service."
169+
}
170+
},
171+
{
172+
"title": "Custom Implementation Status",
173+
"type": "object",
174+
"required": [
175+
"name"
176+
],
177+
"additionalProperties": false,
178+
"properties": {
179+
"name": {
180+
"type": "string",
181+
"minLength": 1,
182+
"title": "Name",
183+
"description": "The name of the custom status."
184+
},
185+
"description": {
186+
"type": "string",
187+
"title": "Description",
188+
"description": "A description of the custom status."
189+
}
190+
}
191+
}
192+
]
193+
},
194+
"effectiveness": {
195+
"type": "object",
196+
"title": "Effectiveness",
197+
"description": "The measured or assessed effectiveness of a control or response.",
198+
"additionalProperties": false,
199+
"properties": {
200+
"percentage": {
201+
"type": "number",
202+
"minimum": 0,
203+
"maximum": 1,
204+
"title": "Percentage",
205+
"description": "Effectiveness as a decimal from 0 to 1."
206+
},
207+
"rating": {
208+
"type": "string",
209+
"title": "Rating",
210+
"enum": [
211+
"ineffective",
212+
"marginal",
213+
"adequate",
214+
"good",
215+
"excellent"
216+
],
217+
"meta:enum": {
218+
"ineffective": "Does not meaningfully reduce risk.",
219+
"marginal": "Slightly reduces risk.",
220+
"adequate": "Adequately reduces risk.",
221+
"good": "Significantly reduces risk.",
222+
"excellent": "Nearly eliminates risk."
223+
},
224+
"description": "Effectiveness as a qualitative rating."
225+
}
226+
}
227+
}
228+
}
229+
}

‎schema/2.0/model/cyclonedx-declaration-2.0.schema.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@
105105
"mitigationStrategies": {
106106
"type": "array",
107107
"title": "Mitigation Strategies",
108-
"description": "The list of `bom-ref` to the evidence provided describing the mitigation strategies.",
108+
"description": "References using bom-link or bom-ref to the controls that mitigate identified gaps in conformance with the requirement. Each mitigation strategy should be substantiated by evidence.",
109109
"items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" }
110110
}
111111
}
@@ -158,7 +158,7 @@
158158
"target": {
159159
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType",
160160
"title": "Target",
161-
"description": "The `bom-ref` to a target representing a specific system, application, API, module, team, person, process, business unit, company, etc... that this claim is being applied to."
161+
"description": "Reference using bom-link or bom-ref to the target of the claim, such as a control, system, application, module, team, person, process, or business unit."
162162
},
163163
"predicate": {
164164
"type": "string",
@@ -168,7 +168,7 @@
168168
"mitigationStrategies": {
169169
"type": "array",
170170
"title": "Mitigation Strategies",
171-
"description": "The list of `bom-ref` to the evidence provided describing the mitigation strategies. Each mitigation strategy should include an explanation of how any weaknesses in the evidence will be mitigated.",
171+
"description": "References using bom-link or bom-ref to the controls that mitigate identified weaknesses in the evidence supporting the claim. Each mitigation strategy should be substantiated by evidence.",
172172
"items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" }
173173
},
174174
"reasoning": {

‎schema/2.0/model/cyclonedx-risk-2.0.schema.json‎

Lines changed: 4 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -975,74 +975,15 @@
975975
"items": {
976976
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
977977
},
978-
"description": "References using bom-link or bom-ref to the controls, requirements, or components that implement this response."
979-
},
980-
"function": {
981-
"type": "string",
982-
"title": "Function",
983-
"description": "The control function this response performs, following a prevent, detect, respond, and recover model.",
984-
"enum": [
985-
"prevent",
986-
"detect",
987-
"respond",
988-
"recover"
989-
],
990-
"meta:enum": {
991-
"prevent": "Prevents the risk from occurring.",
992-
"detect": "Detects when the risk occurs.",
993-
"respond": "Responds to the risk when detected.",
994-
"recover": "Recovers from the impact."
995-
}
978+
"description": "References using bom-link or bom-ref to the controls that implement this response."
996979
},
997980
"status": {
998981
"title": "Status",
999-
"description": "The implementation status of the response. Use the custom option for a status specific to an organization's process.",
1000-
"oneOf": [
1001-
{
1002-
"title": "Predefined Response Status",
1003-
"type": "string",
1004-
"enum": [
1005-
"proposed",
1006-
"approved",
1007-
"planned",
1008-
"in-progress",
1009-
"implemented",
1010-
"verified"
1011-
],
1012-
"meta:enum": {
1013-
"proposed": "The response has been proposed.",
1014-
"approved": "The response has been approved.",
1015-
"planned": "Implementation is planned.",
1016-
"in-progress": "Implementation is in progress.",
1017-
"implemented": "The response has been implemented.",
1018-
"verified": "Effectiveness has been verified."
1019-
}
1020-
},
1021-
{
1022-
"title": "Custom Response Status",
1023-
"type": "object",
1024-
"required": [
1025-
"name"
1026-
],
1027-
"additionalProperties": false,
1028-
"properties": {
1029-
"name": {
1030-
"type": "string",
1031-
"minLength": 1,
1032-
"title": "Name",
1033-
"description": "The name of the custom status."
1034-
},
1035-
"description": {
1036-
"type": "string",
1037-
"title": "Description",
1038-
"description": "A description of the custom status."
1039-
}
1040-
}
1041-
}
1042-
]
982+
"description": "The implementation status of the response.",
983+
"$ref": "cyclonedx-control-2.0.schema.json#/$defs/implementationStatus"
1043984
},
1044985
"effectiveness": {
1045-
"$ref": "#/$defs/effectiveness"
986+
"$ref": "cyclonedx-control-2.0.schema.json#/$defs/effectiveness"
1046987
},
1047988
"cost": {
1048989
"type": "string",
@@ -1094,35 +1035,6 @@
10941035
}
10951036
}
10961037
},
1097-
"effectiveness": {
1098-
"type": "object",
1099-
"additionalProperties": false,
1100-
"properties": {
1101-
"percentage": {
1102-
"type": "number",
1103-
"minimum": 0,
1104-
"maximum": 1,
1105-
"description": "Effectiveness as a decimal from 0 to 1."
1106-
},
1107-
"rating": {
1108-
"type": "string",
1109-
"enum": [
1110-
"ineffective",
1111-
"marginal",
1112-
"adequate",
1113-
"good",
1114-
"excellent"
1115-
],
1116-
"meta:enum": {
1117-
"ineffective": "Does not meaningfully reduce risk.",
1118-
"marginal": "Slightly reduces risk.",
1119-
"adequate": "Adequately reduces risk.",
1120-
"good": "Significantly reduces risk.",
1121-
"excellent": "Nearly eliminates risk."
1122-
}
1123-
}
1124-
}
1125-
},
11261038
"assessment": {
11271039
"type": "object",
11281040
"required": [

‎schema/2.0/model/cyclonedx-threat-2.0.schema.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"threats": {
99
"type": "object",
1010
"title": "Threats",
11-
"description": "Threat-modelling content, including the documented threats, the scenarios that realize them, the attack patterns and attack trees that describe how they are carried out, the trust boundaries they cross, and the security policies that govern the system.",
11+
"description": "Threat-modelling content, including the documented threats, the scenarios that realize them, the attack patterns and attack trees that describe how they are carried out, and the trust boundaries they cross.",
1212
"additionalProperties": false,
1313
"properties": {
1414
"threats": {
@@ -1293,7 +1293,7 @@
12931293
"items": {
12941294
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
12951295
},
1296-
"description": "References using bom-link or bom-ref to the controls implemented at this boundary."
1296+
"description": "References using bom-link or bom-ref to the controls in place at this boundary. Intended primarily for referencing externally defined controls. Where the control and boundary are declared together, prefer the control's appliesTo property."
12971297
},
12981298
"properties": {
12991299
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties"

0 commit comments

Comments
 (0)