├── images └── STIX2.1-nested-property-extension.jpg ├── ACKNOWLEDGEMENTS.md ├── identity └── identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9.json ├── LICENSE ├── extension-definition └── extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c.json ├── examples ├── course-of-action--e06259ad-a154-4e23-bc0a-e229ccb3456f.json └── bundle--b52036d3-4b50-4f29-bb5d-943f3417ff21.json ├── README.md └── schema └── course-of-action_playbook.json /images/STIX2.1-nested-property-extension.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cyentific-rni/stix2.1-coa-playbook-extension/HEAD/images/STIX2.1-nested-property-extension.jpg -------------------------------------------------------------------------------- /ACKNOWLEDGEMENTS.md: -------------------------------------------------------------------------------- 1 | ### Acknowledgements 2 | 3 | This research was partially supported by the research projects CyberHunt (Grant No. 303585 - funded by the Research Council of Norway), JCOP (Grant No. INEA/CEF/ICT/A2020/2373266 - funded by the European Health and Digital Executive Agency through the Connected Europe Facility program), and PHOENI²X (Grant No. 101070586 funded by the Horizon Europe Programme). 4 | 5 | -------------------------------------------------------------------------------- /identity/identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9.json: -------------------------------------------------------------------------------- 1 | { 2 | "objects": [ 3 | { 4 | "id": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 5 | "name": "Vasileios Mavroeidis and Mateusz Zych", 6 | "contact_information": "vas.mavroidis@gmail.com, zychmateusz93@gmail.com", 7 | "identity_class": "group", 8 | "created": "2021-02-15T11:25:33.086853Z", 9 | "type": "identity", 10 | "spec_version": "2.1", 11 | "modified": "2021-07-02T10:57:28.592252Z" 12 | } 13 | ], 14 | "type": "bundle", 15 | "id": "bundle--47739b05-63e0-4170-a75a-6852cea17b86" 16 | } -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 fovea-research 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /extension-definition/extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "bundle", 3 | "id": "bundle--68754162-c445-4996-bf3a-30b0ed54850d", 4 | "objects": [ 5 | { 6 | "type": "extension-definition", 7 | "spec_version": "2.1", 8 | "id": "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c", 9 | "created_by_ref": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 10 | "created": "2022-01-18T23:22:03.933931Z", 11 | "modified": "2022-08-25T19:15:25.577633Z", 12 | "name": "Course of Action extension for Security Playbooks", 13 | "description": "This extension definition extends the Course of Action SDO with additional properties for representing, managing, and sharing machine-readable security playbooks.", 14 | "schema": "https://raw.githubusercontent.com/fovea-research/stix2.1-coa-playbook-extension/main/schema/course-of-action_playbook.json", 15 | "version": "3.0.0", 16 | "extension_types": [ 17 | "property-extension" 18 | ], 19 | "external_references": [ 20 | { 21 | "source_name": "GitHub", 22 | "description": "Documentation of the Extension Definition.", 23 | "url": "https://github.com/fovea-research/stix2.1-coa-playbook-extension" 24 | } 25 | ] 26 | } 27 | ] 28 | } 29 | -------------------------------------------------------------------------------- /examples/course-of-action--e06259ad-a154-4e23-bc0a-e229ccb3456f.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "bundle", 3 | "id": "bundle--5e04bf76-5971-418e-b145-4dad3158e843", 4 | "objects": [ 5 | { 6 | "type": "course-of-action", 7 | "spec_version": "2.1", 8 | "id": "course-of-action--e06259ad-a154-4e23-bc0a-e229ccb3456f", 9 | "created_by_ref": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 10 | "created": "2022-01-18T23:22:03.934698Z", 11 | "modified": "2022-08-25T19:14:15.437976Z", 12 | "name": "playbook", 13 | "description": "A course of action for CVE-2021-44228.", 14 | "extensions": { 15 | "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c": { 16 | "extension_type": "property-extension", 17 | "playbook_id": "cf5997e8-e387-426a-a32d-694e4f55f80b", 18 | "created": "2022-01-18T23:22:03.934698Z", 19 | "modified": "2022-08-25T19:14:15.437976Z", 20 | "playbook_creator": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 21 | "revoked": false, 22 | "labels": [ 23 | "CVE-2021-44228" 24 | ], 25 | "description": "A playbook that, via SBOM processing, detects assets vulnerable to CVE-2021-44228. The same playbook will investigate if there have been attempts to exploit vulnerable assets.", 26 | "playbook_valid_from": "2022-03-18T00:00:00.000000Z", 27 | "playbook_creation_time": "2022-01-09T08:00:33.432637Z", 28 | "playbook_impact": 1, 29 | "playbook_severity": 90, 30 | "playbook_priority": 0, 31 | "playbook_type": [ 32 | "detection", 33 | "investigation" 34 | ], 35 | "playbook_standard": "cacao", 36 | "playbook_abstraction": "executable", 37 | "playbook_base64": "U2VjdXJpdHkgUGxheWJvb2s=" 38 | } 39 | } 40 | } 41 | ] 42 | } 43 | -------------------------------------------------------------------------------- /examples/bundle--b52036d3-4b50-4f29-bb5d-943f3417ff21.json: -------------------------------------------------------------------------------- 1 | { 2 | "type": "bundle", 3 | "id": "bundle--c9661f66-3ff5-4431-9d52-64e18cc2c0b7", 4 | "objects": [ 5 | { 6 | "type": "extension-definition", 7 | "spec_version": "2.1", 8 | "id": "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c", 9 | "created_by_ref": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 10 | "created": "2022-01-18T23:22:03.933931Z", 11 | "modified": "2022-08-25T19:15:25.577633Z", 12 | "name": "Course of Action extension for Security Playbooks", 13 | "description": "This extension definition extends the Course of Action SDO with additional properties for representing, managing, and sharing machine-readable security playbooks.", 14 | "schema": "https://raw.githubusercontent.com/fovea-research/stix2.1-coa-playbook-extension/main/schema/course-of-action_playbook.json", 15 | "version": "3.0.0", 16 | "extension_types": [ 17 | "property-extension" 18 | ], 19 | "external_references": [ 20 | { 21 | "source_name": "GitHub", 22 | "description": "Documentation of the Extension Definition.", 23 | "url": "https://github.com/fovea-research/stix2.1-coa-playbook-extension" 24 | } 25 | ] 26 | }, 27 | { 28 | "type": "identity", 29 | "spec_version": "2.1", 30 | "id": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 31 | "created": "2021-02-15T11:25:33.086853Z", 32 | "modified": "2021-07-02T10:57:28.592252Z", 33 | "name": "Vasileios Mavroeidis and Mateusz Zych", 34 | "identity_class": "group", 35 | "contact_information": "vas.mavroidis@gmail.com, zychmateusz93@gmail.com" 36 | }, 37 | { 38 | "type": "course-of-action", 39 | "spec_version": "2.1", 40 | "id": "course-of-action--e06259ad-a154-4e23-bc0a-e229ccb3456f", 41 | "created_by_ref": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 42 | "created": "2022-01-18T23:22:03.934698Z", 43 | "modified": "2022-08-25T19:14:15.437976Z", 44 | "name": "playbook", 45 | "description": "A course of action for CVE-2021-44228.", 46 | "extensions": { 47 | "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c": { 48 | "extension_type": "property-extension", 49 | "playbook_id": "cf5997e8-e387-426a-a32d-694e4f55f80b", 50 | "created": "2022-01-18T23:22:03.934698Z", 51 | "modified": "2022-08-25T19:14:15.437976Z", 52 | "playbook_creator": "identity--ae82a5e5-ec07-4863-ad88-6504b29f24e9", 53 | "revoked": false, 54 | "labels": [ 55 | "CVE-2021-44228" 56 | ], 57 | "description": "A playbook that, via SBOM processing, detects assets vulnerable to CVE-2021-44228. The same playbook will investigate if there have been attempts to exploit vulnerable assets.", 58 | "playbook_valid_from": "2022-03-18T00:00:00.000000Z", 59 | "playbook_creation_time": "2022-01-09T08:00:33.432637Z", 60 | "playbook_impact": 1, 61 | "playbook_severity": 90, 62 | "playbook_priority": 0, 63 | "playbook_type": [ 64 | "detection", 65 | "investigation" 66 | ], 67 | "playbook_standard": "cacao", 68 | "playbook_abstraction": "executable", 69 | "playbook_base64": "U2VjdXJpdHkgUGxheWJvb2s=" 70 | } 71 | } 72 | } 73 | ] 74 | } 75 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## A STIX 2.1 Extension Definition for Sharing Machine-Readable Security Playbooks and Orchestration Workflows via the Course of Action SDO 2 | 3 | **This repository includes a STIX 2.1 nested property extension that augments the Course of Action (COA) STIX Domain Object (SDO) type to enable describing, embedding, storing, managing, and sharing cybersecurity playbooks and orchestration workflows**. 4 | 5 | The decision to extend the Course of Action SDO was based on the facts that the terms security playbook and course of action are semantically very close (i.e., security playbook can be a subclass of course of action) and that extending an object allows making use of the existing specification-defined relationships, such as the ones between the Course of Action and other objects. 6 | 7 | ![](https://github.com/fovea-research/stix2.1-coa-playbook-extension/blob/main/images/STIX2.1-nested-property-extension.jpg) 8 | 9 | The illustration above concisely explains what comprises an Extension Definition. The blue rectangles represent an instance of a COA SDO type with an extension. The red rectangle represents the associated Extension Definition object that provides information about the new or extended object type. The amber rectangle captures the normative definition of the extension, and it is a JSON schema. 10 | 11 | ### Reading Material 12 | 13 | A technical report that explains in detail the extension can be found at https://arxiv.org/abs/2203.04136. 14 | 15 | **Please note that the authoritative source of this work is this Github repository and its [README.md](https://github.com/fovea-research/stix2.1-coa-playbook-extension#readme) file and not the technical report mentioned above and uploaded on arxiv.** The report is not going to be updated and is only provided as a reference material that includes background information. 16 | 17 | ### Extension Definition Related Files: 18 | - [Example Instances](https://github.com/fovea-research/stix2.1-coa-playbook-extension/tree/main/examples) 19 | - [Extension Definition Object](https://github.com/fovea-research/stix2.1-coa-playbook-extension/tree/main/extension-definition) 20 | - [Normative Definition of the Extension - JSON Schema](https://github.com/fovea-research/stix2.1-coa-playbook-extension/tree/main/schema) 21 | 22 | ### Properties that Comprise the Nested Property Extension of the COA SDO to Support Sharing Machine-Readable Security Playbooks 23 | | Property Name | Data Type | Description | 24 | | :--- | :--- |:--- | 25 | | **extension_type** (required) | `string` | The value of this property **MUST** be `property-extension`. | 26 | | **playbook_id** (optional)| `string` | A value that (uniquely) identifies the playbook. If the playbook itself embeds an identifier then the playbook_id SHOULD use the same identifier (value) for correlation purposes.| 27 | | **description** (optional)| `string` | An explanation, details, and more context about what this playbook does and tries to accomplish. | 28 | | **created** (required)| `timestamp` | The time at which the playbook extension (instance) was created. This may be different than the time at which the "parent" Course of Action object instance was created. | 29 | | **modified** (required)| `timestamp` | The time at which the playbook extension (instance) was last modified. A modification in the extension requires updating the property **modified** in both the extension and the “parent” Course of Action object. | 30 | | **revoked** (optional)| `boolean` | A boolean that identifies if the playbook extension (instance) is no longer valid. | 31 | | **playbook_creation_time** (optional)| `timestamp` | The time at which the playbook was originally created. | 32 | | **playbook_modification_time** (optional)| `timestamp` | The time at which the playbook was last modified. | 33 | | **playbook_valid_from** (optional)| `timestamp` | The time from which the playbook is considered valid and the steps that it contains can be executed. | 34 | | **playbook_valid_until** (optional)| `timestamp` | The time from which the playbook should no longer be considered a valid playbook to be executed. | 35 | | **playbook_creator** (optional)| `identifier` | The identifier of the entity that created the playbook. | 36 | | **labels** (optional)| `list` of type `string` | A set of labels for the playbook (e.g., adversary persona names, associated groups, or malware family/variant/name that this playbook is related to). | 37 | | **organization_type** (optional)| `list` of type `open-vocab` | The type of organization that the playbook is intended for. The value for this property **SHOULD** come from the `industry-sector-ov` open vocabulary as defined in STIX Version 2.1.| 38 | | **playbook_standard** (optional)| `string` | The standard/format/notation the playbook conforms to (e.g., CACAO, BPMN). | 39 | | **playbook_abstraction** (optional)| `open-vocab` | The playbook’s level of abstraction (with regards to consumption). Open Vocabulary: `[template, executable]` | 40 | | **playbook_type** (optional)| `list` of type `open-vocab` | A list of playbook types that specifies the operational roles this playbook addresses. The open vocabulary is based on the available options in the CACAO standard and NIST SP 800-61 rev2. Open Vocabulary: `[notification, detection, investigation, prevention, mitigation, remediation, analysis, containment, eradication, recovery, attack]` | 41 | | **playbook_impact** (optional)| `integer` | From 0 to 100, an integer representing the impact the playbook has on the organization. A value of 0 means specifically undefined. Impact values range from 1, the lowest impact, to a value of 100, the highest. For example, a purely investigative playbook that is non-invasive could have a low impact value of 1. In contrast, a playbook that performs changes such as adding rules into a firewall should have a higher impact value. | 42 | | **playbook_severity** (optional)| `integer` | From 0 to 100, an integer representing the seriousness of the conditions that this playbook addresses. A value of 0 means specifically undefined. Severity values range from 1, the lowest severity, to a value of 100, the highest. | 43 | | **playbook_priority** (optional)| `integer` | From 0 to 100, an integer representing the priority of this playbook relative to other defined playbooks. A value of 0 means specifically undefined. Priority values range from 1, the highest priority, to a value of 100, the lowest. This property can support addressing different use cases and requirements of a producing or consuming entity. For example, a STIX 2.1 COA object that embeds more than one playbook can use this property to define a priority with regards to which one should be executed. | 44 | | **playbook_bin** (optional)| `binary` | The entire playbook encoded in base64. Security playbook producers and consumers use this property to share and retrieve entire playbooks. 45 | 46 | 47 | 48 | ## Maintainers 49 | - [Vasileios-Mavroeidis](https://github.com/Vasileios-Mavroeidis) 50 | 51 | - [Mateusz Zych](https://www.linkedin.com/in/mateuszzych/) 52 | -------------------------------------------------------------------------------- /schema/course-of-action_playbook.json: -------------------------------------------------------------------------------- 1 | { 2 | "$id": "https://raw.githubusercontent.com/fovea-research/stix2.1-coa-playbook-extension/main/schema/course-of-action_playbook.json", 3 | "$schema": "http://json-schema.org/draft/2020-12/schema", 4 | "title": "Schema for validating the playbook extension within the COA SDO.", 5 | "description": "This schema is the normative definition of the extension-definition 'extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c' that extends the STIX 2.1 Course of Action object to support sharing playbooks, otherwise known as orchestration workflows.", 6 | "type": "object", 7 | "allOf": [ 8 | { 9 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/sdos/course-of-action.json" 10 | }, 11 | { 12 | "properties": { 13 | "extensions": { 14 | "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c": { 15 | "$ref": "#/$defs/playbook-extension" 16 | }, 17 | "required": [ 18 | "extension-definition--1e1c1bd7-c527-4215-8e18-e199e74da57c" 19 | ] 20 | } 21 | } 22 | } 23 | ], 24 | "required": [ 25 | "extensions" 26 | ], 27 | "$defs": { 28 | "playbook-extension": { 29 | "type": "object", 30 | "description": "The set of properties that a COA instance can use to define playbooks.", 31 | "properties": { 32 | "extension_type": { 33 | "type": "string", 34 | "description": "The value of this property MUST be `property-extension`.", 35 | "enum": [ 36 | "property-extension" 37 | ] 38 | }, 39 | "playbook_id": { 40 | "type": "string", 41 | "description": "A value that (uniquely) identifies the playbook. If the playbook itself embeds an identifier then the playbook_id SHOULD use the same identifier (value) for correlation purposes." 42 | }, 43 | "created": { 44 | "description": "The time at which the extension (sub-component instance) was created. This may be different than the time at which the parent COA object instance was created. The timestamp value MUST be precise to the nearest millisecond.", 45 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json" 46 | }, 47 | "modified": { 48 | "description": "The time at which the extension (sub-component instance) was last modified. The timestamp value MUST be precise to the nearest millisecond.", 49 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json" 50 | }, 51 | "playbook_creation_time": { 52 | "description": "The time at which the playbook was originally created. The timestamp value MUST be precise to the nearest millisecond.", 53 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json" 54 | }, 55 | "playbook_modification_time": { 56 | "description": "The time at which the playbook was last modified. The timestamp value MUST be precise to the nearest millisecond.", 57 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json" 58 | }, 59 | "revoked": { 60 | "type": "boolean", 61 | "description": "A boolean that identifies if the playbook (COA sub-component instance) is no longer valid." 62 | }, 63 | "playbook_creator": { 64 | "description": "The identifier of the entity that created the playbook.", 65 | "pattern": "^identity--", 66 | "allOf": [ 67 | { 68 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/identifier.json" 69 | } 70 | ] 71 | }, 72 | "playbook_valid_from": { 73 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json", 74 | "description": "The time from which the playbook is considered valid and the steps that it contains can be executed. The timestamp value MUST be precise to the nearest millisecond." 75 | }, 76 | "playbook_valid_until": { 77 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/timestamp.json", 78 | "description": "The time from which the playbook should no longer be considered a valid playbook to be executed. The timestamp value MUST be precise to the nearest millisecond." 79 | }, 80 | "description": { 81 | "type": "string", 82 | "description": "An explanation, details, and more context about what this playbook does and tries to accomplish." 83 | }, 84 | "labels": { 85 | "type": "array", 86 | "description": "A set of labels for the playbook (e.g., adversary persona names, associated groups, or malware family/variant/name that this playbook is related to).", 87 | "items": { 88 | "type": "string" 89 | }, 90 | "minItems": 1 91 | }, 92 | "playbook_impact": { 93 | "type": "integer", 94 | "minimum": 0, 95 | "maximum": 100, 96 | "description": "From 0 to 100, an integer representing the impact the playbook has on the organization. A value of 0 means specifically undefined. Impact values range from 1, the lowest impact, to a value of 100, the highest. For example, a purely investigative playbook that is non-invasive could have a low impact value of 1. In contrast, a playbook that performs changes such as adding rules into a firewall should have a higher impact value." 97 | }, 98 | "playbook_severity": { 99 | "type": "integer", 100 | "minimum": 0, 101 | "maximum": 100, 102 | "description": "From 0 to 100, an integer representing the seriousness of the conditions that this playbook addresses. A value of 0 means specifically undefined. Severity values range from 1, the lowest severity, to a value of 100, the highest." 103 | }, 104 | "playbook_priority": { 105 | "type": "integer", 106 | "minimum": 0, 107 | "maximum": 100, 108 | "description": "From 0 to 100, an integer representing the priority of this playbook relative to other defined playbooks. A value of 0 means specifically undefined. Priority values range from 1, the highest priority, to a value of 100, the lowest." 109 | }, 110 | "organization_type": { 111 | "type": "string", 112 | "description": "The type of organization that the playbook is intended for. The value for this property SHOULD come from the industry-sector-ov open vocabulary." 113 | }, 114 | "playbook_type": { 115 | "type": "array", 116 | "items": { 117 | "type": "string" 118 | }, 119 | "minItems": 1, 120 | "description": "The security-related functions the playbook addresses. A playbook may account for multiple types (e.g., detection and investigation). The open vocabulary is based on the available options in the CACAO standard and NIST SP 800-61 rev2. Open Vocabulary: [notification, detection, investigation, prevention, mitigation, remediation, analysis, containment, eradication, recovery, attack]" 121 | }, 122 | "playbook_standard": { 123 | "type": "string", 124 | "description": "The standard/format/notation the playbook conforms to (e.g., CACAO, BPMN)." 125 | }, 126 | "playbook_abstraction": { 127 | "type": "string", 128 | "description": "The playbook's level of abstraction (with regards to consumption). Open Vocabulary: [template, executable]" 129 | }, 130 | "playbook_bin": { 131 | "$ref": "http://raw.githubusercontent.com/oasis-open/cti-stix2-json-schemas/stix2.1/schemas/common/binary.json", 132 | "description": "The entire playbook encoded in base64. Playbook producers and consumers use this property to share and retrieve playbooks." 133 | } 134 | }, 135 | "required": [ 136 | "extension_type", 137 | "created", 138 | "modified" 139 | ], 140 | "additionalProperties": false 141 | } 142 | } 143 | } --------------------------------------------------------------------------------