Skip to content

The Open Threat Modeling Format (OTM) defines a platform independent way to define the threat model of any system.

Notifications You must be signed in to change notification settings

iriusrisk/OpenThreatModel

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

36 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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@email.com
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: john.doe@example.com
  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

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

About

The Open Threat Modeling Format (OTM) defines a platform independent way to define the threat model of any system.

Topics

Resources

Stars

Watchers

Forks

Packages

No packages published