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

JSON 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	name: Project name
id	string	REQUIRED Unique identifier for the project.	id: project-example-id
description	richText	Short description for the project.	description: This is the threat model for the app 'MuCustomApp123
owner	string	Name of the project's owner. This is the person responsible for the project.	owner: John Doe
ownerContact	string	Project's owner contact email.	ownerContact: [email protected]
tags	array of strings	Array of labels to tag the project	tags: - microservice - spring
attributes	Map [string, string]	This is a free-form map of attributes that complete the information about the project.	attributes: filePath: “file.xml” cmdbId: MyApp123

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.	name: Architecture diagram
id	string	REQUIRED Unique identifier for the representation.	id: architecture-diagram-id
type	string	REQUIRED Type of representation.	type: diagram
description	richText	Short description of the representation content and usage.	description: This is a diagram of the project's architecture
attributes	Map [string, string]	This is a free-form list of attributes that complete the description of the representation.	attributes: language: java platform: github vcs: git

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	representation: architecture-diagram
name	string	Name for the representation element.	name: Component Box
id	string	REQUIRED Unique identifier of the current representation instance	id: component-box-id
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.	attributes: color: red shape: square

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	representation: code-repository
name	string	Name for the representation element.	name: Example Class
id	string	REQUIRED Unique identifier of the current representation instance	id: org.example.class
file	string	File where the representative code is located	file: path/to/class.java
line	integer	Number of the code line that represents the element	line: 324
codeSnippet	richText	Code that represents the element	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	Map <string, string>	This is a free-form list of attributes that complete the description of the representation.	attributes: source: sonar author: John Doe

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	representation: architecture-threat-model
name	string	Name for the representation element.	name: Threat model representation
id	string	REQUIRED Unique identifier of the current representation instance	id: threat-model-representation-id
attributes	Map <string, string>	This is a free-form list of attributes that complete the description of the representation.	attributes: author: John Doe

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	id: cc-data
name	string	REQUIRED Name for the defined assets	name: Credit card data
description	richText	Short description for the asset	description: This is our customer’s credit card numbers
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.	attributes: attr1: value1 attr2: value2

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?	confidentiality: 50
integrity	integer	REQUIRED From 0 to 100. How bad would it be to have an attacker modify this information?	integrity: 50
availability	integer	REQUIRED From 0 to a 100. How bad would it be to lose this information or have it inaccessible in our system?	availability: 50
comment	richText	Short explanation on why we have selected the different risk values	comment: We have decided that the values are a 100 for all values since this highly-sensitive information

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.	assets: processed: - asset1 - asset2
stored	array of strings	Array of ids that represent the assets that are stored within the described component.	assets: stored: - asset1 - asset2

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	name: Payments service
id	string	REQUIRED Unique identifier for the component	id: payment-service
type	string	REQUIRED The kind of the described component	type: ec2-instance
tags	array of strings	List of tags related to the component.	tags: - web - server
description	richText	Short description for the components	description: This is the server in charge of processing the payments in the platform
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.	attributes: attr1: value1 attr2: value2

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	name: Internet
id	string	REQUIRED Unique identifier for the trust zone	id: 730df42e-69a4-11ed-bd69-9b318e4f98c5
type	string	RECOMMENDED (required in the next major version) Type for the trust zone	type: internet
description	richText	Short description for the trust zone	description: > This is the world wide web accesible for every one with an internet connection
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.	attributes: attr1: value1 attr2: value2

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?	trustRating: 10

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	trustZone: private
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	component: web-server

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.	name: Credit card reporting
id	string	REQUIRED Unique identifier for the dataflow.	id: credit-card-reporting
description	richText	Short description of the dataflow content and usage.	description: Credit card information being exchanged in between the web app and the database
tags	array of strings	Array of tags related to the dataflow.	tags: - http - https
bidirectional	boolean	States if the information flows both ways. By default, it is false.	bidirectional: true
source	string	REQUIRED Unique identifier for the source component of the dataflow.	source: web-service
destination	string	REQUIRED Unique identifier for the destination component of the dataflow.	destination: psotgress-db
assets	array of strings	Array of assets that are transported by the dataflow.	assets: - cc-data - public-info
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.	attributes: attr1: value1 attr2: value2

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	name: Attackers gain unauthorized access to the control of the environment
id	string	REQUIRED Unique identifier for the threat	id: LOSS-CONTROL_ENV
description	richText	Short description of the threat	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	array of strings	Array of categories that are applicable to the threat	categories: - Spoofing - Authentication
cwes	array of strings	Array of CWE identifiers of weaknesses associated with the threat	cwes: - CWE-79 - CWE-787
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	tags: - unauthorized-access - loss-control
attributes	Map [string, string]	This is a free-form map of attributes that complete the description of the threat.	attributes: expirationDate: “2021-05-17” cmdbId: MyApp123

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?	likelihood: 50
likelihoodComment	richText	Short explanation of why we have selected such a value for the likelihood	likelihoodComment: It is reasonable to think that this might happen, but it requires that the attacker has a deep knowledge of cryptography
impact	integer	REQUIRED From 0 to 100. How bad would it be if this threat took place?	impact: 100
impactComment	richText	Short explanation of why we have selected such a value for the impact	impactComment: If this threat becomes a reality, the company will struggle to keep customers and the monetary loss would jeopardize the business

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.	threat: 22724267-be7e-44c0-8b1f-d7d33e9a34ec
state	string	REQUIRED Describes the state in which the threat currently is.	state: mitigated
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	name: Use strong passwords
id	string	REQUIRED Unique identifier for the mitigation	id: use-strong-passwords
description	richText	Short descriptions of how to implement the mitigation	description: Force users to use passwords over 10 characters, containing letters numbers and symbols
riskReduction	integer	REQUIRED From 0 to 100. How much will the threat risk decrease once this mitigation is implemented?	riskReduction: 75
attributes	Map [string, string]	This is a free-form list of attributes that complete the description of the threat.	attributes: standard: OWASP-ASVS cmdbId: MyApp123

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.	mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004
state	string	REQUIRED State of the mitigation	state: implemented

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	https://github.com/my-project

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	width: 400
height	integer	REQUIRED Height in pixels	height: 300

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	x: 200
y	integer	REQUIRED This is the position of the element in the Y-axis in units	y: 100

Example

position:
  x: 0
  y: 0

This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License