Introduction
The Open Threat Modeling Format (OTM) defines a platform independent way to define the threat model of any system.
OTM allows both humans and computers to understand what are the components of a system, how are they distributed, the security risks that could be exposed to attackers and the mitigations that could be implemented to avoid those vulnerabilities.
OTM can be used to document your system and threat model, to keep you threat model aware of the changes that happens in the system and many other use cases.
Complete example
For a complete example see EXAMPLE.yaml or EXAMPLE.json.
Versions
The Open Threat Model specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
Current schema version: 0.2.0
Format
An OTM document is itself a JSON object, which may be represented either in JSON or YAML format.
All field names in the specification are case sensitive. This includes all fields that are used as keys in a map.
The specification follows the same approach to JSON formats as the OpenAPI specification. See https://swagger.io/specification/ for more information.
Data Types
Primitive data types in the OTM are based on the types supported by the JSON Schema Specification Wright Draft 00. Note that integer
as a type is also supported and is defined as a JSON number without a fraction or exponent part. null
is not supported as a type (see nullable
for an alternative solution).
The formats available to be used within an OTM files are:
Type | Comment |
---|---|
integer |
signed 32 bits |
long |
signed 64 bits (a.k.a long) |
float |
|
double |
|
string |
|
richText |
Rich text fields are noted as supporting CommonMark markdown formatting. |
boolean |
|
date |
As defined by full-date - RFC3339 |
datetime |
As defined by date-time - RFC3339 |
Schema
OTM object
Field | Type | Description | Examples |
---|---|---|---|
otmVersion | string | REQUIRED This field states the OTM version used in the current file. It is an important field in order to ensure backwards compatibility. | otmVersion: 0.1.0 |
project | Project object | REQUIRED The project node represents the entity within all the other elements are grouped. It's the unit of work. | |
representations | Representations object | Representations define different ways in which the project may be represented. Representation is an abstract concept and there might be several implementations. | |
assets | Assets object | Assets are the different kinds of sensible information that take part in our threat model. | |
components | Components object | Components are the different pieces of software / hardware that make up our project. | |
dataflows | DataFlows object | Data flows are the elements that describe the movement of relevant information (assets) across our architecture. | |
trustZones | TrustZones object | Trust zones are the different areas within which components are located. They define how trustworthy an area is, based on how accessible it is: the more accessible, the less trustworthy. | |
threats | Threats object | Threats are the undesirable outcomes that can occur in our system and that we want to prevent. | |
mitigations | Mitigations object | Mitigations are the actions that we can take (or controls that we can put in place) in order to prevent a threat from taking place. |
Project object
The project node represents the entity within all the other elements are grouped. Its the unit of work.
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name of the project |
|
id | string | REQUIRED Unique identifier for the project. |
|
description | richText | Short description for the project. |
|
owner | string | Name of the project's owner. This is the person responsible for the project. |
|
ownerContact | string | Project's owner contact email. |
|
tags | array of strings | Array of labels to tag the project |
|
attributes | Map [string, string] | This is a free-form map of attributes that complete the information about the project. |
|
Example
project:
name: Test project
id: test-project
description: This is a test project for the OTM development
owner: John Doe
ownerContact: [email protected]
attributes:
filePath: โfile.xmlโ
cmdbId: MyApp123
Representations object
This node can define several ways on which the project can be represented.
Representation is an abstract concept and there might be several implementations.
These are the currently supported representation types:
diagram
code
threat-model
Each representation has these fields:
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name for the representation. |
|
id | string | REQUIRED Unique identifier for the representation. |
|
type | string | REQUIRED Type of representation. |
|
description | richText | Short description of the representation content and usage. |
|
attributes | Map [string, string] | This is a free-form list of attributes that complete the description of the representation. |
|
Example
representations:
- name: Architecture Diagram
id: architecture-diagram
description: This is a diagram of the project's architecture
type: diagram
size:
width: 1000
height: 1000
attributes:
platform: drawio
unit: pixel
- name: Application Code
id: application-code
type: code
repository:
url: https://github.com/my-project
attributes:
language: java
platform: github
vcs: git
Representation supported types
Depending on the type selected, some extra fields must be included in the representation. The supported representation types are:
Diagram
Represents a diagram with very basic information.
Under the type โdiagramโ we have the following extra fields:
Field | Type | Description | Examples |
---|---|---|---|
size | Size object | REQUIRED Object that contains the information regarding the diagram size |
Example
representations:
- name: Architecture Diagram
id: architecture-diagram
description: This is a diagram of the project's architecture
type: diagram
size:
width: 1000
height: 1000
attributes:
background-color: blue
transparent: 40
Code
Represents a repository of code.
Under the type โcodeโ we have the following extra fields:
Field | Type | Description | Examples |
---|---|---|---|
repository | Repository object | Contains information about the Repository where the referenced code is located |
Example
representations:
- name: Application Code
id: application-code
type: code
repository:
url: https://github.com/my-project
attributes:
language: java
framework: spring
Threat-Model
Represents a threat model.
Under the type โthreat-modelโ we have no extra fields.
Example
representations:
- name: Architecture Threat Model
id: architecture-threat-model
type: threat-model
attributes:
source: Microsoft Threat Model
template: custom
RepresentationElement object
The representation element stated how an element is represented with the available representations.
In the current version we support three types of representation types as was mentioned here OTM version 0.1.0 | Representations-object:
- diagram
- code
- threat-model
Therefore, there can be also three types of representation instances:
Representation element for diagram
Represents an element of a diagram.
Field | Type | Description | Examples |
---|---|---|---|
representation | string | REQUIRED Id of the representation on which this element is represented |
|
name | string | Name for the representation element. |
|
id | string | REQUIRED Unique identifier of the current representation instance |
|
position | Position object | REQUIRED This node contains all the information about the location of the element within the diagram. | |
size | Size object | REQUIRED This node contains all the information regarding the size of the shape. | |
attributes | Map <string, string> | This is a free-form map of attributes that complete the description of the representation. |
|
Example
representations:
representation: architecture-diagram
name: Private Box
id: private-box-shape
position:
x: 0
y: 0
size:
with: 100
height: 100
attributes:
color: red
shape: square
Representation element for code
Despite all fields being optional, at least one of them is required.
Field | Type | Description | Examples |
---|---|---|---|
representation | string | REQUIRED Id of the representation on which this element is represented |
|
name | string | Name for the representation element. |
|
id | string | REQUIRED Unique identifier of the current representation instance |
|
file | string | File where the representative code is located |
|
line | integer | Number of the code line that represents the element |
|
codeSnippet | richText | Code that represents the element |
|
attributes | Map <string, string> | This is a free-form list of attributes that complete the description of the representation. |
|
Example
representations:
representation: code-repository
id: org.example.class
name: Example Class
file: path/to/class.java
line: 324
codeSnippet: |
public void createOTM(String[] args) {
Scanner reader = new Scanner(System.in);
System.out.print("Enter a number: ");
int number = reader.nextInt()
System.out.println("You entered: " + number);
}
attributes:
source: sonar
author: John Doe
Representation element for threat-model
Represents an element of a threat model.
Field | Type | Description | Examples |
---|---|---|---|
representation | string | REQUIRED Id of the representation on which this element is represented |
|
name | string | Name for the representation element. |
|
id | string | REQUIRED Unique identifier of the current representation instance |
|
attributes | Map <string, string> | This is a free-form list of attributes that complete the description of the representation. |
|
Example
representations:
representation: architecture-threat-model
id: threat-model-representation-id
name: Threat model representation
attributes:
author: John Doe
Assets object
Assets are the different kinds of sensible information that take part in our threat model.
Field | Type | Description | Examples |
---|---|---|---|
id | string | REQUIRED Unique identifier for the asset |
|
name | string | REQUIRED Name for the defined assets |
|
description | richText | Short description for the asset |
|
risk | AssetRisk object | REQUIRED AssetRisk influences impact with regard to a threat. | |
attributes | Map [string, string] | This is a free-form map of attributes that complete the description of the asset. |
|
Example
assets:
- name: Credit Card Data
id: cc-data
description: Credit card numbers used for payments in the platform
risk:
confidentiality: 100
integrity: 100
availability: 100
comment: We have decided that the values are a 100 for all values since this highly sensitive information
attributes:
attr1: value1
attr2: value2
- name: Public Info
id: public-info
description: Public information meant to be seen by any interested customer
risk:
confidentiality: 0
integrity: 100
availability: 50
comment: Public information has no confidentiality at all but it is quite important for it to be available and to not be changed by attakers
attributes:
AssetRisk object
AssetRisk influences impact with regard to a threat.
Those values are passed through OTM into the IR rules engine which performs the calculation for inherent risk.
More information - https://support.iriusrisk.com/hc/en-us/articles/4412644787345-How-is-inherent-risk-calculated-
Field | Type | Description | Examples |
---|---|---|---|
confidentiality | integer | REQUIRED From 0 to 100. How bad would it be to have an attacker see this information? |
|
integrity | integer | REQUIRED From 0 to 100. How bad would it be to have an attacker modify this information? |
|
availability | integer | REQUIRED From 0 to a 100. How bad would it be to lose this information or have it inaccessible in our system? |
|
comment | richText | Short explanation on why we have selected the different risk values |
|
Asset Instance object
Object that describes the relationship between the component and the different assets.
Field | Type | Description | Examples |
---|---|---|---|
processed | array of strings | Array of ids that represent the assets that are processed in this component. |
|
stored | array of strings | Array of ids that represent the assets that are stored within the described component. |
|
Example
assets:
processed:
- 441b01ca-2653-4707-8be8-fd6addce9df6
- 4136bb34-e2ff-11eb-ba80-0242ac130004
stored:
- 441b01ca-2653-4707-8be8-fd6addce9df6
Components object
Components are the different pieces of software / hardware that make our project. These are the fields for them:
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name for the defined component |
|
id | string | REQUIRED Unique identifier for the component |
|
type | string | REQUIRED The kind of the described component |
|
tags | array of strings | List of tags related to the component. |
|
description | richText | Short description for the components |
|
parent | Parent object | REQUIRED Element in which this component is currently enclosed. It can be either a trust zone or another
component. It should contain an attribute name stating the component type to avoid ambiguity.
A component must have just one parent: another component or a trust zone. |
|
representations | array of Representation Element object | Array of the representations that this component has. | |
assets | Asset instance object | Object that describes the relationship between the component and the different assets | |
threats | array of Threat instance object | Array of threats that are related to the current component. | |
attributes | Map [string, string] | This is a free-form map of attributes that complete the description of the component. |
|
Example
components:
- name: Web Service
id: web-service
type: web-service
description: Runs our web application
parent:
trustZone: private
tags:
- tomcat
representations:
- representation: architecture-diagram
id: web-service-box
name: Web Service
position:
x: 100
y: 100
size:
width: 50
height: 50
assets:
processed:
- 441b01ca-2653-4707-8be8-fd6addce9df6
- 4136bb34-e2ff-11eb-ba80-0242ac130004
stored:
- 441b01ca-2653-4707-8be8-fd6addce9df6
threats:
- threat: 22724267-be7e-44c0-8b1f-d7d33e9a34ec
state: exposed
mitigations:
- mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004
state: implemented
attributes:
- owner: John Doe
- department: IT
- name: Customer Database
id: customer-database
description: Postgres database
parent:
trustZone: private
type: database
tags:
- postgres
representations:
- represetation: architecture-diagram
id: box-for-postgress-DB
position:
x: 200
y: 100
size:
width: 50
height: 50
- name: Class CustomerDatabase
id: class-customerdatabase
description: Managages customer database
type: code-class
parent:
trustZone: private
representations:
- representation: application-code
id: source-to-go-class
name: source.go
file: path/to/source.go
line: 644
TrustZones object
Trust zones are the different areas within which components are located. They define how trustworthy an area is, based on how accessible it is: the more accessible, the less trustworthy.
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name for the defined trust zone |
|
id | string | REQUIRED Unique identifier for the trust zone |
|
type | string | RECOMMENDED (required in the next major version) Type for the trust zone |
|
description | richText | Short description for the trust zone |
|
risk | TrustZoneRisk object | REQUIRED This is the object that describes the different aspects of risk associated with the trust zone | |
parent | Parent object |
Unique identifier of the component or trust zone enclosing this trust zone. It should contain an attribute name stating the element type. A trust zone can have zero or one parent: another component or a trust zone. |
|
representations | array of Representation Element object | Array of the representations that this trust zone has | |
attributes | Map [string, string] | This is a free-form map of attributes that complete the description of the trust zone. |
|
Example
trustzones:
- name: Internet
id: 730df42e-69a4-11ed-bd69-9b318e4f98c5
description: This is the internet trust zone
risk:
trustRating: 20
representations:
representation: architecture-diagram
id: internet-box-shape
name: Internet
position:
x: 600
y: 100
size:
width: 100
height: 100
attributes:
attr1: value1
attr2: value2
- name: Private
id: 3ae9b5de-69b2-11ed-8c2d-e7d4579196f4
type: private
description: Private trustzone for protected components
risk:
trustRating: 15
parent: internet
representations:
representation: architecture-diagram
id: private-box-shape
name: Private
postion:
x: 0
y: 0
size:
with: 100
height: 100
attributes:
TrustZoneRisk object
This is the object that describes the different aspects of risk associated with the trust zone.
Field | Type | Description | Examples |
---|---|---|---|
trustRating | integer | REQUIRED From 0 and 100. How trustworthy is this trust zone? |
|
Example
risk:
trustRating: 20
Parent object
Element that encloses another element. It can be either a trust zone or a component. Currently, we have two supported types of parents:
- trustZone
- component
Field | Type | Description | Examples |
---|---|---|---|
trustZone | string | Id of the element in which this component is currently enclosed. It can be either a trust zone or another component. It should contain an attribute name stating the component type to avoid ambiguity |
|
component | string | Id of the element in which this component is currently enclosed. It can be either a trust zone or another component. It should contain an attribute name stating the component type to avoid ambiguity |
|
Example
parent:
trustZone: private
parent:
component: web-server
Dataflows object
Data flows are the elements that describe the movement of relevant information (assets) across our architecture.
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name for the defined dataflow. |
|
id | string | REQUIRED Unique identifier for the dataflow. |
|
description | richText | Short description of the dataflow content and usage. |
|
tags | array of strings | Array of tags related to the dataflow. |
|
bidirectional | boolean | States if the information flows both ways.
By default, it is false. |
|
source | string | REQUIRED Unique identifier for the source component of the dataflow. |
|
destination | string | REQUIRED Unique identifier for the destination component of the dataflow. |
|
assets | array of strings | Array of assets that are transported by the dataflow. |
|
threats | array of Threat instance object | Array of threats that are related to the current dataflow. | |
attributes | Map [string, string] | This is a free-form map of attributes that complete the description of the dataflow. |
|
Example
dataflows:
- name: Dataflow between webservice and mongo.
id: cc-store-in-db
description: Creditcard information being exchanged in between the web app and the data base
bidirectional: true
source: web-service
target: customer-database
tags:
- http
- https
assets:
- cc-data
threats:
- threat: 22724267-be7e-44c0-8b1f-d7d33e9a34ec
state: exposed
mitigations:
- mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004
state: required
attributes:
attr1: value1
attr2: value2
Threats object
Threats are the undesirable outcomes that can occur in our system and that we want to prevent. These are its fields:
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED This is the name for the threat |
|
id | string | REQUIRED Unique identifier for the threat |
|
description | richText | Short description of the threat |
|
categories | array of strings | Array of categories that are applicable to the threat |
|
cwes | array of strings | Array of CWE identifiers of weaknesses associated with the threat |
|
risk | ThreatRisk object | REQUIRED This object describes different aspects of risk (likelihood and impact) posed by the threat | |
tags | array of strings | Array of tags related to the threat |
|
attributes | Map [string, string] | This is a free-form map of attributes that complete the description of the threat. |
|
Example
threats:
- name: Attackers gain unauthorized access to the control of the environment
id: LOSS-CONTROL_ENV
description: Attackers could potentially gain unauthorized access to the control of the environment, due to user accounts - or role groups - not being well defined and configured. As a consequence, attackers may be able to make changes without root approval.
categories:
- Spoofing
- Tampering
cwes:
- CWE-79
- CWE-787
risk:
likelihood: 50
likelihoodComment: It is reasonable to think this might happen but it requires for the attaketr to have a deep cyprografy knowledge
impact: 100
impactComment: If this threat becomes a rallity company will strruggle to keep customers and the monetory loss would jeopardise the whole company
attributes:
expirationDate: 2021-05-17
cmdbId: MyApp123
tags:
- loss-control
- environment
ThreatRisk object
Risk information for the associated threat.
Field | Type | Description | Examples |
---|---|---|---|
likelihood | integer | REQUIRED From 0 to 100. How likely is it that this threat will take place? |
|
likelihoodComment | richText | Short explanation of why we have selected such a value for the likelihood |
|
impact | integer | REQUIRED From 0 to 100. How bad would it be if this threat took place? |
|
impactComment | richText | Short explanation of why we have selected such a value for the impact |
|
Example
risk:
likelihood: 50
likelihoodComment: It is reasonable to think that this might happen, but it requires that the attacker has a deep knowledge of cryptography
impact: 100
impactComment: If this threat becomes a reality, the company will struggle to keep customers and the monetary loss would jeopardize the business
Threat instance object
This object stores a reference to a threat and add additional data enclosed in a particular scope.
Field | Type | Description | Examples |
---|---|---|---|
threat | string | REQUIRED Unique identifier of the related threat. It should be one of the threats described in the root node threats. |
|
state | string | REQUIRED Describes the state in which the threat currently is. |
|
mitigations | array of Mitigation instance object | Array of mitigation that can prevent the threat from taking place. |
Example
threats:
- threat: 22724267-be7e-44c0-8b1f-d7d33e9a34ec
state: exposed
mitigations:
- mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004
state: implemented
Mitigations object
Mitigations are the actions that we can take (or controls that we can put in place) in order to prevent a threat from taking place.
Field | Type | Description | Examples |
---|---|---|---|
name | string | REQUIRED Name for the mitigation |
|
id | string | REQUIRED Unique identifier for the mitigation |
|
description | richText | Short descriptions of how to implement the mitigation |
|
riskReduction | integer | REQUIRED From 0 to 100. How much will the threat risk decrease once this mitigation is implemented? |
|
attributes | Map [string, string] | This is a free-form list of attributes that complete the description of the threat. |
|
Example
mitigations:
- name: This is the name of mitigation 1
id: fd6136f4-e2ff-11eb-ba80-0242ac130004
description: Description for mitigation 1
riskReduction: 50
attributes:
standard: OWASP-ASVS
cmdbId: MyApp123
- name: Mitigation 2
id: 3b837730-e300-11eb-ba80-0242ac130004
description: Description for mitigation 2
riskReduction: 100
Mitigation instance object
Mitigation that can prevent the threat from taking place.
Field | Type | Description | Examples |
---|---|---|---|
mitigation | string | REQUIRED Unique identifier of the related mitigation. It should be declared in the root node mitigation. |
|
state | string | REQUIRED State of the mitigation |
|
Example
mitigations:
- mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004
state: implemented
Repository object
Contains information about the Repository where the referenced code is located.
Field | Type | Description | Examples |
---|---|---|---|
url | string | Connection URL of the described repository |
|
Example
repository:
url: https://github.com/my-project
Size object
Represents a very basic information about a size of an element.
Field | Type | Description | Examples |
---|---|---|---|
width | integer | REQUIRED Width in pixels |
|
height | integer | REQUIRED Height in pixels |
|
Position object
Represents very basic information about the position of an element.
Field | Type | Description | Examples |
---|---|---|---|
x | integer | REQUIRED This is the position of the element in the X-axis in units |
|
y | integer | REQUIRED This is the position of the element in the Y-axis in units |
|
Example
position:
x: 0
y: 0
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License