Awesome

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:

Schema

JSON Schema

OTM object

Project object

The project node represents the entity within all the other elements are grouped. Its the unit of work.

name: Project name

id: project-example-id

description: This is the threat model for the app 'MuCustomApp123

owner: John Doe

ownerContact: email@email.com

tags:
    - microservice
    - spring

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:

name: Architecture diagram

id: architecture-diagram-id

type: diagram

description: This is a diagram of the project's architecture

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:

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:

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.

representation: architecture-diagram

name: Component Box

id: component-box-id

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.

representation: code-repository

name: Example Class

id: org.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

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.

representation: architecture-threat-model

name: Threat model representation

id: threat-model-representation-id

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.

id: cc-data

name: Credit card data

description: This is our customer’s credit card numbers

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-

confidentiality: 50

integrity: 50

availability: 50

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.

assets:
  processed:
    - asset1
    - asset2

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:

name: Payments service

id: payment-service

type: ec2-instance

tags:
  - web
  - server

description: This is the server in charge of processing the payments in the platform

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.

name: Internet

id: 730df42e-69a4-11ed-bd69-9b318e4f98c5

type: internet

description: >
  This is the world
  wide web accesible
  for every one with
  an internet
  connection

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.

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

trustZone: private

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.

name: Credit card reporting

id: credit-card-reporting

description: Credit card information being exchanged in between the web app and the database

tags:
  - http
  - https

By default, it is false.</td>

bidirectional: true

source: web-service

destination: psotgress-db

assets:
  - cc-data
  - public-info

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:

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
  - Authentication

cwes:
  - CWE-79
  - CWE-787

tags:
  - unauthorized-access
  - loss-control

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.

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

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.

 threat: 22724267-be7e-44c0-8b1f-d7d33e9a34ec

state: mitigated

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.

name: Use strong passwords

id: use-strong-passwords

description: Force users to use passwords over 10 characters, containing letters numbers and symbols

riskReduction: 75

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.

mitigation: fd6136f4-e2ff-11eb-ba80-0242ac130004

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.

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.

width: 400

height: 300

Position object

Represents very basic information about the position of an element.

x: 200

y: 100

Example

position:
  x: 0
  y: 0