SDL Reference Guide

Stories

The story represents the fictive conditions and events of the scenario, that will take place during the exercise. A story can be divided into various scripts that include a series of events, that constitute a narrative. A script tells a part of the story through a timeline, taking the perspective of one (or more) entity, i.e., it represents the story from the entity’s perspective. Story has an internal speed, which is used to control the overall speed at which the exercise is taking place. An optional description can be added.

stories: 
   story-1: 
      speed: 1
      scripts: 
         - script-1
         - script-2
      description: "story description"

Variable	Mandatory	Type	Rules
speed	yes	float	Speed value must be at least 1.0
scripts	yes	array of Scripts	Story must have at least one Script Script must be defined under Scripts
description	no	string

Scripts

Scripts are the main elements of a story, think of them as movie scripts. Scripts define their start-time and end-time which parsed from string into u64 seconds and accept a mix of types specified below (or a 0 value for start-time). The speed field specifies how fast the script runs. They also contain the events map, that are happening in the scope of that script with the event start time specified as the value of the event in accepted format. So for the example below event-1 starts right when the deployment starts, event-2 starts 5 minutes after the start etc. An optional description can be added.

scripts:
    script-1:
        start-time: 0 
        end-time: 3 hour 30 min
        speed: 1
        events:
              event-1: 0
              event-2: 5 min
              event-3: 15 min
        description: "script description"

Variable	Mandatory	Type	Rules
start-time	yes	time
end-time	yes	time	End-time must be greater than start-time
speed	yes	float	Speed must have a positive value
events	yes	hashmap of Event:time	Script must have at least one Event Event must be defined under Events
description	no	string

Accepted formats for time specification

Unit	Description	Unit list option(one of)	Example
y	Year	["y" , "year" , "Y" , "YEAR" , "Year"]	1y
mon	Month	["mon" , "MON" , "Month" , "month" , "MONTH"]	1mon
w	Week	["w" , "W" , "Week" ,"WEEK" , "week"]	1w
d	Day	["d" , "D" , "Day" , "DAY" , "day"]	1d
h	Hour	["h" , "H" , "Hour" , "HOUR" , "hour"]	1h
m	Minute	["m" , "M" , "Minute" , "MINUTE" , "minute" , "min" , "MIN"]	1m
s	Second	["s" , "S" , "Second" , "SECOND" , "second" , "sec" , "SEC"]	1s

Millisecond (ms), microsecond (µs) and nanosecond (ns) are also accepted as a valid input, but the values are rounded up to the nearest second.

Events

Events are rules, that are used to trigger injects and show additional information to the participant. Events can either be triggered by condition or time. If an event contains a condition and that condition becomes true, the event will be triggered during the event time window. The time when the event can be triggered is specified in scripts. Also if event contains multiple conditions, all those conditions have to be true for the event to trigger. If the event does not contain conditions, it will be triggered when the event window opens. Source specifies the package of an Event markdown file in Deputy, which will then be converted into HTML and shown to the participant once the event has been triggered. For a longer explanation, please see Source under Node. An optional description can be added.

events:
   event-1:
      source: "event-package"
      conditions: 
          - condition-1
          - condition-2
          - condition-3
      injects: 
         - inject-1
         - inject-2
      description: "event description"

Variable	Mandatory	Type	Rules
source	no	string or object with fields: name, version	Time must have a float value between 0 and 1
conditions	no	array of Conditions	Condition must be defined under Conditions
injects	no	array of Injects	Event must have at least one Inject Inject must be defined under Injects
description	no	string

Injects

Injects describe the events that happen within the scripts of the exercise scenario. They can be technical or non-technical injects, such as, launching an attack from a particular entity to another entity or delivering a news report to an entity. Source specifies the location of the executable command. Injects also have TLOs attached to them. An optional description can be added. Environment field is a list of environment variables, which support executable Deputy packages. From-entity and to-entities fields don't currently carry functionality in the SDL parser but can be used for example in tabletop exercises.

injects:
    inject-1:
      source: executable/inject-1/path.sh
      from-entity: entity-1
      to-entities: 
        - entity-2
        - entity-3
      tlos:
        - tlo-1
        - tlo-2
      description: "inject description"
      environment: 
        - ENV_VAR_1=ENV_VALUE_1
        - ENV_VAR_2=ENV_VALUE_2

    inject-2:
      source: executable/inject-1/path.sh

Variable	Mandatory	Type	Rules
source	no	string or object with fields: name, version
from-entity	no	Entity	Inject must have from-entity declared if to-entities is declared
to-entities	no	array of Entities	Inject must have to-entities declared if from-entity is declared
tlos	no	array of TLOs	TLO must be defined under TLOs
description	no	string
environment	no	array of hashmaps of string:string

Conditions

Conditions is a list of commands or libraries that are tied to Virtual Machines and periodically check the state of something. They are always installed after all Features have been installed. They return a value between 0..1 to the Ranger and are used for both scoring purposes in Metrics or as triggers for Events.

Each condition in the list must have a unique alphanumeric name. There must be either a command and interval, or a source. If all fields under the condition are filled, then the source is overwritten and only command and interval are used. Environment field lists environment variables, which support executable Deputy packages and an optional description can be added.

Command condition

The command shows the path to the executable file and it returns a float value between 0 and 1. Interval indicates the interval between command executions in seconds.

condition-1:
     command: executable/path.sh
     interval: 30

Source condition

The source field defines the name and version of the image file or package in the Digital Library. In this example, the source image only has a name:

condition-2:
     source: digital-library-package

For a longer explanation, please see Source under Node.

Example conditions list

A fully defined Conditions list could look something like this:

conditions:
     condition-1:
          command: executable/path.sh
          interval: 30
     condition-2:
          source: digital-library-package
          description: "New condition"
     condition-3:
          command: executable/path.sh
          interval: 30
          environment: 
               - ENV_VAR_1=ENV_VALUE_1
               - ENV_VAR_2=ENV_VALUE_2

Variable	Mandatory	Type	Rules
command	no	string	Must be defined if interval is used
interval	no	integer	Must be defined if command is used
source	no	string or object with fields: name, version	Condition must have command and interval or source defined, not both
description	no	string
environment	no	array of hashmaps of string:string

Features

Feature may be a service, a configuration, a vulnerability, an artifact, or any other modification applied after the base OS and base configuration and policy application.

Features can be of 3 types: service, configuration, artifact. Source is either a string containing the Deputy package name or an object with package name and package version fields.
Features can be dependent on other features, which is specified with optional dependencies field, where feature names are listed.
Features can be vulnerable and reference a vulnerability, which is specified with optional vulnerabilities field, where vulnerability names are listed.
Destination field doesn't currently carry functionality in the parser.
Environment field is a list of environment variables, which support executable Deputy packages. Optional description field can be specified.

features:
    nginx:
      type: service
      source: dl_library
      destination: "destination"
      environment: 
        - ENV_VAR_1=ENV_VALUE_1
        - ENV_VAR_2=ENV_VALUE_2
      description: "description"
    web_cfg:
      type: configuration
      source: my-cool-nginx-conf
      dependencies:
        - nginx
      vulnerabilities:
        - vulnerability-1
    web_pictures:
      type: artifact
      source: dl_library
      dependencies:
        - web_cfg

Variable	Mandatory	Type	Rules
type	yes	enum with options service, configuration, artifact
source	no	string or object with fields: name, version
destination	no	string
environment	no	array of hashmaps of string:string
dependencies	no	array of Features	Feature must be defined under Features
vulnerabilities	no	array of Vulnerabilities	Vulnerability must be defined under Vulnerabilities
description	no	string

Vulnerabilities

Different nodes and entities can be vulnerable and reference technical or non-technical vulnerabilities.

Vulnerabilities contain informational name and description fields.
Technical field sets whether the vulnerability is a technical or non-technical vulnerability.
The class field represents the CWE-based class of the vulnerability.

vulnerabilities:
  vulnerability-1:
    name: "Vulnerability"
    description: "My vulnerability"
    technical: true/false
    class: "CWE-1189"

  vulnerability-2:
    name: "Vulnerability"
    description: "My vulnerability"
    technical: true/false
    class: "CWE-1343"

Variable	Mandatory	Type	Rules
name	yes	string
description	yes	string
technical	yes	boolean
class	yes	string	Vulnerability class must match CWE-based classes

Nodes

Nodes is a list made of named Virtual Machines or Switches containing their type, resources and so on, each of them making up a Node.

Switches

The switch is the simplest example of a node, it contains an alphanumeric name and a type:

my-cool-switch-1: 
    type: switch

Virtual Machines

A Virtual Machine is defined by its type field with the value vm. It also supports several optional fields for additional configuration.

Source

The source field defines the name and version of the image file or package in the Digital Library. In this example, we are explicitly defining the version of the source image:

my-cool-vm-1:
    type: vm
    source:
        name: digital-library-package-name
        version: 4.0.1

ℹ️ Note: The version field must follow the semantic versioning standard.

If the latest version of the source image is desired, the version and the name field can be omitted entirely:

my-cool-vm-1:
    type: vm
    source: digital-library-package-name

Resources

The Virtual Machine's parameters are defined in the resources field, if omitted, the default values set by the hypervisor are applied. In this example, we are defining the ram and cpu parameters:

my-cool-vm-1:
    type: vm
    source: digital-library-package-name
    resources:
        ram: 2 GiB
        cpu: 2

⚠️ Warning: ram is expressed in Mebibytes (MiB) or Gibibytes (GiB), cpu is expressed in number of cores.

Additional configuration

VMs have additional configuration fields: os field specifies the operation system running on the virtual machine. Features and conditions denote the optional modifications applied to the node. Vulnerabilities doesn't have direct effect on the VM, but rather can be used to provide supplementary context. Roles field specifies all the accounts under this node with optional entities field and features and conditions must have specified the account name, which will be executing these scripts. Nodes, that have conditions attached to them, must have a count of 1 (under Infrastructure). Injects field specifies the injects, that will be happening on the node.

Example Nodes list

nodes:
  switch-1:
    type: switch
    description: "switch 1"

  switch-2:
    type: switch

  ubuntu-10:
    type: vm
    source: digital-library-package-name
    resources:
      cpu: 2
      ram: 2 GiB
    roles:
      admin: "username"
      moderator:
        username: "name"
        entities:
          - "blue-team.bob"
    vulnerabilities:
      - vulnerability-1
      - vulnerability-2
    features:
      web_pictures: "admin"
      nginx: "moderator"
    conditions:
      condition-3: "admin"
    injects:
      demo_inject: "admin"


  windows-10-vuln-1:
    type: vm
    source: digital-library-package-name
    resources:
      cpu: 2
      ram: 2 GiB

  windows-10:
    type: vm
    source:
      name: digital-library-package-name
      version: 1.0.0
    resources:
      cpu: 2
      ram: 2 GiB

Roles can be written in either shorthand or longhand:

```yml
roles:
  admin: "username"
  user:
    username: "user"
    entities:
      - blue-team.bob

Variable	Mandatory	Type	Rules
type	yes	enum with options VM or switch
source	yes for VMs, no for switches	string or object with fields: name, version
resources	yes for VMs, no for switches	object with fields: cpu (integer), ram (integer)
roles	no	hashmap of string:string or object with fields username and entities
vulnerabilities	no	array of Vulnerabilities	Vulnerability must be defined under Vulnerabilities
features	no	hashmap of Feature:Role	Feature must be defined under Features
conditions	no	hashmap of Condition:Role	Condition must be defined under Conditions
description	no	string

Infrastructure

Infrastructure represents the physical and virtual infrastructure associated with different entities and the vulnerabilities present in them.

Infrastructure can be defined either shorthand:

infrastructure:
    switch-1: 1
    windows-10: 3

or longway:

windows-10-vuln-1:
    count: 1
switch-2:
    count: 2
    links:
        - switch-1
ubuntu-10:
    links:
        - switch-1
    dependencies:
        - windows-10
        - windows-10-vuln-1

Count

A count value shows how many virtual machines and switches you would like to use. For machines, that are running conditions, the count is limited to 1.

windows-10:
    count: 3

Dependencies

Dependencies are a list of virtual machines which are dependent upon other nodes. A virtual machine may be connected to none, one or more nodes. In practice this controls which nodes are deployed first.

windows-10-vuln-1:
    count: 1
ubuntu-10:
    dependencies:
        - windows-10-vuln-1

Links

Links are a list of switches which are dependent upon other nodes.

switch-1:
    count: 1
ubuntu-10:
    links:
        - switch-1

Variable	Mandatory	Type	Rules
count	yes	integer	For machines, that are running conditions, the count is limited to 1.
links	no	array of Nodes	Must be of type switch
dependencies	no	array of Nodes	Must be of type VM
description	no	string

Metrics

Metrics are used to evaluate TLOs and conditions.

Type specifies if the evaluation metric is manual or conditional. If it is manual, then artifact field is also specified, which can be true or false and denotes whether an artifact exists.
Max-score sets the metric's maximum value. Condition field is used when the metric's type is conditional.

metrics:
  metric-1:
    name: "Metric-1"
    type: manual/conditional
    artifact: true/false 
    max-score: 50
    condition: condition-2 
    description: "New metric"

Variable	Mandatory	Type	Rules
name	no	string
type	yes	enum with options manual or conditional
artifact	no	boolean	Conditional metric cannot have an artifact
max-score	yes	integer	Metric max-score cannot be 0
condition	no	Condition	Manual metric cannot have a condition Conditional metric must have a condition The same condition cannot be used under multiple metrics
description	no	string

Training and Learning Objectives (TLOs)

Training and Learning Objectives (TLOs) represent a specific individual's training objectives (e.g. developed and exercised capabilities and skillsets) to be reached throughout the exercise.

TLOs specify their name and textual description.
Evaluation field marks the evaluation value for the TLO.

tlos:
  my-first-objective:
    name: "Training/Learning objective name"
    description: "some description"
    evaluation: evaluation-1
  

Variable	Mandatory	Type	Rules
name	no	string
description	no	string
evaluation	yes	Evaluation	Evaluation must be defined under Evaluations

Goals

Goals block describes the goals with TLOs. It defines optional name and description fields, and a list of tlos.

goals:
  goal-1:
    name: "Secure Active Directory"
    description: "Ensure the security and stability of Active Directory"
    tlos:
      - tlo-1

Variable	Mandatory	Type	Rules
name	no	string
description	no	string
tlos	yes	array of TLOs	TLOs must be defined under TLOs

Evaluation

Evaluation block describes the evaluation metrics of a TLO.

Evaluation defines name, description, metrics and min-score.
Metrics is a list of metrics, that is used to evaluate the TLO.
Min-score represents the minimum score value that must be attained in order for the training and learning objective to be counted as passed. It can be described either in shorthand:

// shorthand for percentage
min-score: 50

or in longer version, that can be described either in absolute or percentage values:

// long-version
min-score:
    absolute: 50
// OR
    percentage: 70

Example of evaluations:

evaluations:
    evaluation-1:
         description: "This measures time to retrieve CTF"
         metrics:
              - metric-1
         min-score: 50

Variable	Mandatory	Type	Rules
description	no	string
metrics	yes	array of Metrics	Metric must be defined under Metrics
min-score	yes	integer	Min-score can only have one value
name	no	string

Entities

Entities are part of an exercise scenario, which represent individuals, organizations, countries, any stakeholder or anything, that has a role in the scenario. Entities represent the trainees, the exercise control (EXCON) teams, and other stakeholders present in the scenario. Trainee entities have training and learning objective associated with them. All entities have a mission connected to their role.

Entities specify their name and textual description.
An entity has an optional role, which represents their role in the exercise: WHITE/GREEN/RED/BLUE.
Every entity contains a textual description of their mission.
Entities can be of various pre-defined types can be of various types, e.g., Person, Organization, Role, Nodes, Systems etc., which is set by the categories field. Each entity can have multiple categories.
They can optionally be tied to multiple vulnerabilities and tlos.
Optionally, entities can also contain sub-entities. If some values are not specified in the sub-entities, they will be inherited from the parent-entity. Entities could have an optional events field, which can be used to show events to the participant in Ranger UI. If the field is not specified, the participant will still be able to experience the events, but they just won't be shown explicitly.

entities:
  my-organization:
    name: "My Organization"
    description: "This is my organization"
    role: GREEN
    mission: "defend"
    categories:
      - Foundation
      - Organization
    vulnerabilities:
      - vulnerability-2
    tlos:
      - tlo-1
      - tlo-2
      - tlo-3
    events:
      - conditional_event

    entities:
        my-organization-hr:
          name: "My Organization HR"
          description: "This is my organization HR"
          categories:
            - HR Department
          entities:
            helen-in-the-hr:
              name: "helen"
              description: "nice lady"
              vulnerabilities:
                vulnerability-1
                vulnerability-2
                vulnerability-3
  fish:
    name: "Shark"
    description: "This is my organization"
    mission: "swim around"
    categories:
      - Animal
     

Variable	Mandatory	Type	Rules
name	no	string
description	no	string
role	no	enum with options white, green, red, blue
mission	no	string
categories	no	array of strings
vulnerabilies	no	array of Vulnerabilities	Vulnerability must be defined under Vulnerabilities
tlos	no	array of TLOs	TLO must be defined under TLOs
entities	no	array of Entities
facts	no	hashmap of string:string