### Example package.toml File

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

This is a complete example of a package.toml file, illustrating the structure and common fields.

```toml
[package]
name = "debian11"
description = "Debian 11.4.0 minimal CLI."
version = "1.3.0"
authors = ["Developer developers@cyber-range.no"]
license = "MIT"
readme = "src/readme.md"
categories = ["exercise", "testing"]

[content]
type = "vm"

[virtual-machine]
operating_system = "Debian"
architecture = "amd64"
type = "OVA"
file_path = "src/debian11.ova"
accounts = [{name = "root", password = "password"}, {name = "user", password ="password"}]


```

--------------------------------

### Install core dependencies

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Install wget, gnupg, and unzip using your system's package manager.

```bash
apt install wget gnupg unzip
```

--------------------------------

### Example .env Configuration

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/switcher

Provides a complete example of environment variables for configuring the Switcher handler and its dependencies.

```dotenv
# Global Settings
GLOBAL_HOST=0.0.0.0
GLOBAL_INSECURE=True

# Service Ports
SWITCHER_PORT=6000

# DevStack Credentials
AUTH_URL=https://openstack-auth-url:5000/v3
CREDENTIAL_ID=openstack_client_id
CREDENTIAL_SECRET=openstack_application_secret
DOMAIN=openstack_domain
PROJECT=openstack_project
GATEWAY_NETWORK=openstack_gateway_network
REGION=openstack_region
HYPERVISOR=qemu+tcp://hostname/system
HYPERVISOR_USER=openstack_hypervisor_user
HYPERVISOR_PASSWORD=openstack_hypervisor_password

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=/var/log
LOG_FILE_NAME=ocr_openstack_plugin

# Redis Configuration
REDIS_HOST=redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# Optional
HYPERVISOR_WAIT_TIMEOUT=300
HYPERVISOR_WAIT_INTERVAL=5

```

--------------------------------

### Example .env Configuration

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Provides an example `.env` file demonstrating how to configure the General handler's global settings, service ports, logging, and Redis connection.

```dotenv
# Global Settings
GLOBAL_HOST=0.0.0.0
GLOBAL_INSECURE=True

# Service Ports
GENERAL_PORT=5000

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=/var/log
LOG_FILE_NAME=ocr_openstack_plugin

# Redis Configuration
REDIS_HOST=redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# Optional
HYPERVISOR_WAIT_TIMEOUT=300
HYPERVISOR_WAIT_INTERVAL=5

```

--------------------------------

### Install Deputy CLI

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Install the Deputy CLI package using APT.

```bash
sudo apt install deputy
```

--------------------------------

### Full Conditions List Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

An example of a complete conditions list including command, source, and environment variables. Demonstrates various condition configurations.

```yaml
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  


```

--------------------------------

### Example SDL Schema

Source: https://ncr.ntnu.no/docs/toolsets/ranger/user_guides/manager-user-guide

An example SDL schema for defining a small deployment scenario, including nodes, infrastructure, metrics, and evaluations.

```yaml
name: example-scenario
description: some-description
conditions:
    test-condition:
        source: api-health-check
nodes:
    switch:
        type: switch
    user-machine:
        type: VM
        resources:
            ram: 2gib
            cpu: 1
        source: debian10
        roles:
            admin:
                username: "root"
            user:
                username: "user"
                entities:
                    - player-1
        conditions:
            test-condition: admin
infrastructure:
        switch:
            count: 1
            properties:
                cidr: 10.10.10.0/24
                gateway: 10.10.10.1
        user-machine:
            count: 1
            links:
                - switch
            properties:
                    - switch: 10.10.10.10
metrics:
    test-metric:
        type: conditional
        max-score: 50
        condition: test-condition
evaluations:
    evaluation-1:
        min-score:
            absolute: 50
        metrics:
            - test-metric
tlos:
    tlo-1:
        evaluation: evaluation-1
entities:
    player-1:
        name: "Some person"
        description: "This entity is Blue"
        role: Blue
        tlos:
            - tlo-1

```

--------------------------------

### Full Evaluation Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

An example of a complete evaluation block, including description, metrics, and minimum score.

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

```

--------------------------------

### Content Section with Preview

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

This example demonstrates the [content] section, including the 'preview' field for specifying package preview content.

```toml
[content]
type = "vm"
preview = [
    {type = "picture", value = ["pic.jpg", "src/pic2.jpg"]},
    ]


```

--------------------------------

### Package Section with Assets

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

This example shows the [package] section, including the 'assets' field which specifies files to be copied to the guest OS.

```toml
[package]
name = "debian11"
description = "Debian 11.4.0 minimal CLI."
version = "1.3.0"
authors = ["Developer developers@cyber-range.no", "Someone someone@cyber-range.no"]
license = "MIT"
readme = "src/readme.md"
categories = ["exercise", "testing"]
assets = [ ["src/configs/my-cool-config1.yml", "/var/opt/my-cool-service1", "744", ], ]


```

--------------------------------

### Example .env Configuration for Executor Handler

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Provides a sample .env file demonstrating how to configure the Executor handler with various settings.

```dotenv
# Global Settings
GLOBAL_HOST=0.0.0.0
GLOBAL_INSECURE=True

# Service Ports
EXECUTOR_PORT=7000

# DevStack Credentials
AUTH_URL=https://openstack-auth-url:5000/v3
CREDENTIAL_ID=openstack_client_id
CREDENTIAL_SECRET=openstack_application_secret
DOMAIN=openstack_domain
PROJECT=openstack_project
GATEWAY_NETWORK=openstack_gateway_network
REGION=openstack_region
HYPERVISOR=qemu+tcp://hostname/system
HYPERVISOR_USER=openstack_hypervisor_user
HYPERVISOR_PASSWORD=openstack_hypervisor_password

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=/var/log
LOG_FILE_NAME=ocr_openstack_plugin

# Redis Configuration
REDIS_HOST=redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# Optional
HYPERVISOR_WAIT_TIMEOUT=300
HYPERVISOR_WAIT_INTERVAL=5

```

--------------------------------

### Goals Configuration Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Describes goals, including optional name and description, and a list of associated TLOs.

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

```

--------------------------------

### Define a VM Node with Resources

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining a virtual machine node with specified CPU and RAM resources.

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

```

--------------------------------

### Example .env Configuration

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/templater

Provides a sample .env file for configuring the Templater handler, covering global settings, service ports, DevStack credentials, logging, and Redis.

```dotenv
# Global Settings
GLOBAL_HOST=0.0.0.0
GLOBAL_INSECURE=True

# Service Ports
TEMPLATER_PORT=8000

# DevStack Credentials
AUTH_URL=https://openstack-auth-url:5000/v3
CREDENTIAL_ID=openstack_client_id
CREDENTIAL_SECRET=openstack_application_secret
DOMAIN=openstack_domain
PROJECT=openstack_project
GATEWAY_NETWORK=openstack_gateway_network
REGION=openstack_region
HYPERVISOR=qemu+tcp://hostname/system
HYPERVISOR_USER=openstack_hypervisor_user
HYPERVISOR_PASSWORD=openstack_hypervisor_password

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=/var/log
LOG_FILE_NAME=ocr_openstack_plugin

# Redis Configuration
REDIS_HOST=redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

```

--------------------------------

### Define a Switch Node

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining a simple switch node with a name and type.

```yaml
my-cool-switch-1:
	type: switch

```

--------------------------------

### Initialize a New Deputy Package

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-deputy-package

Use the 'deputy create' command to start a new package. You will be prompted to select a package type, such as 'vm'.

```bash
deputy create
```

--------------------------------

### Example Nodes List

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines various nodes including switches and virtual machines with their configurations, resources, roles, features, conditions, and injects.

```yaml
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

```

--------------------------------

### Node Properties Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines properties like CIDR and gateway for switches, and mapped IP addresses for virtual machines.

```yaml
switch-1:
  count: 1
  properties:
    cidr: 10.10.10.0/24
    gateway: 10.10.10.1
windows-10-vuln-1:
  Count: 1
  links:
    - switch-1
  properties:
    - switch-1: 10.10.10.10

```

--------------------------------

### Example package.toml Configuration

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-deputy-package

This TOML file defines the metadata and content for a virtual machine package. It specifies package details, content type, and virtual machine specifics like accounts, OS, architecture, and file path.

```toml
[package]
name = "debian11-network-manager"
description = "Debian11 CLI with network-manager, curl, wget installed."
version = "0.3.0"
authors = ["Developers developers@cyber-range.no"]
license = "MIT"
readme = "README.md"
categories = ["debian", "nmcli"]

[content]
type = "vm"

[virtual-machine]
accounts = [
    { name = "root", password = "password" },
    { name = "user", password = "password" },
]
default_account = "root"
operating_system = "Debian"
architecture = "amd64"
type = "OVA"
file_path = "src/debian11-network-manager.ova"
readme_path = "README.md"

```

--------------------------------

### Get Packages Response Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Defines the response structure containing a list of packages.

```protobuf
message GetPackagesResponse {
  repeated Package packages = 1;
}

```

--------------------------------

### Metric Configuration Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Configures evaluation metrics, specifying type (manual/conditional), artifact presence, maximum score, and conditions.

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

```

--------------------------------

### Feature Type Enum

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Enumerates the types of features that can be installed on a VM: service, configuration, or artifact.

```protobuf
enum FeatureType {
  service = 0;
  configuration = 1;
  artifact = 2;
}

```

--------------------------------

### Condition Create

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Installs a Condition script on the VM, which runs at specified intervals and streams results back to Ranger.

```APIDOC
## Condition Create

### Description
Installs the Condition on the VM. Conditions are scripts that run every Interval seconds on the VM and return a value between 0 and 1.0 to indicate its current state. They are installed on the VM during its creation and then continuously run with their results streamed back to Ranger unless closed by Ranger.

### Method
gRPC

### Endpoint
`/condition/create`

### Request Body
(Note: The request body for Condition create is not fully detailed in the source. The following is based on the description and typical gRPC patterns.)
- **name** (string) - Required - The name of the condition.
- **virtual_machine_id** (string) - Required - The ID of the virtual machine.
- **interval** (integer) - Required - The interval in seconds at which the condition script should run.
- **source** (Source) - Required - Information about the source of the condition script.
- **account** (Account) - Required - Account credentials for accessing the source.

### Request Example
```json
{
  "name": "example-condition",
  "virtual_machine_id": "vm-12345",
  "interval": 60,
  "source": {
    "name": "my-repo",
    "version": "1.0.0"
  },
  "account": {
    "username": "user",
    "password": "pass",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  }
}
```

### Response
(Note: The successful response for Condition create is not explicitly defined in the source. It is assumed to be similar to other create operations.)
#### Success Response (200)
- **identifier** (Identifier) - An identifier for the created condition.
- **stdout** (string) - Standard output from the execution.
- **stderr** (string) - Standard error from the execution.

#### Response Example
```json
{
  "identifier": {
    "value": "condition-abcde"
  },
  "stdout": "Condition installed and streaming.",
  "stderr": ""
}
```
```

--------------------------------

### Get Packages Query Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Defines the request structure for querying Deputy packages by type.

```protobuf
message GetPackagesQuery {
  string package_type = 1;
}

```

--------------------------------

### Feature Create

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Installs listed assets and runs accompanying actions on a VM immediately after creation. Feature create requests are sent by Ranger.

```APIDOC
## Feature Create

### Description
Installs the listed assets on the VM and runs its accompanying action. Feature `create` requests are sent by Ranger immediately after the VM is created.

### Method
gRPC

### Endpoint
`/feature/create`

### Request Body
- **name** (string) - Required - The name of the feature.
- **virtual_machine_id** (string) - Required - The ID of the virtual machine.
- **featureType** (FeatureType) - Required - The type of feature (service, configuration, artifact).
- **source** (Source) - Required - Information about the source of the feature.
- **account** (Account) - Required - Account credentials for accessing the source.
- **environment** (repeated string) - Optional - Environment variables to set.

### Request Example
```json
{
  "name": "example-feature",
  "virtual_machine_id": "vm-12345",
  "featureType": "service",
  "source": {
    "name": "my-repo",
    "version": "1.0.0"
  },
  "account": {
    "username": "user",
    "password": "pass",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  },
  "environment": ["ENV_VAR=value"]
}
```

### Response
#### Success Response (200)
- **identifier** (Identifier) - An identifier for the created feature.
- **stdout** (string) - Standard output from the execution.
- **stderr** (string) - Standard error from the execution.

#### Response Example
```json
{
  "identifier": {
    "value": "feature-abcde"
  },
  "stdout": "Feature installed successfully.",
  "stderr": ""
}
```
```

--------------------------------

### Example .env Configuration for Machiner

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/machiner

Provides a sample environment file demonstrating the necessary configuration variables for the Machiner handler, including global settings, service ports, and OpenStack credentials.

```dotenv
# Global Settings
GLOBAL_HOST=0.0.0.0
GLOBAL_INSECURE=True

# Service Ports
MACHINER_PORT=9000

# DevStack Credentials
AUTH_URL=https://openstack-auth-url:5000/v3
CREDENTIAL_ID=openstack_client_id
CREDENTIAL_SECRET=openstack_application_secret
DOMAIN=openstack_domain
PROJECT=openstack_project
GATEWAY_NETWORK=openstack_gateway_network
REGION=openstack_region
HYPERVISOR=qemu+tcp://hostname/system
HYPERVISOR_USER=openstack_hypervisor_user
HYPERVISOR_PASSWORD=openstack_hypervisor_password

# Logging Configuration
LOG_LEVEL=INFO
LOG_DIR=/var/log
LOG_FILE_NAME=ocr_openstack_plugin

# Redis Configuration
REDIS_HOST=redis-host
REDIS_PORT=6379
REDIS_PASSWORD=redis_password

# Optional
HYPERVISOR_WAIT_TIMEOUT=300
HYPERVISOR_WAIT_INTERVAL=5

```

--------------------------------

### Define a VM Node with Latest Source

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining a virtual machine node using the latest available source image by omitting the version and name fields.

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

```

--------------------------------

### Inject Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines an inject with source, entities, TLOs, description, and environment variables. Used to specify events within exercise scenarios.

```yaml
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  


```

--------------------------------

### Get Scenario Response Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Defines the response structure containing the SDL for a given Deputy package.

```protobuf
message GetScenarioResponse {
  string sdl = 1;
}

```

--------------------------------

### Training and Learning Objectives (TLOs) Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines training objectives with a name, description, and associated evaluation.

```yaml
tlos:
  my-first-objective:
    name: 'Training/Learning objective name'
    description: 'some description'
    evaluation: evaluation-1

```

--------------------------------

### Define a VM Node with Specific Source Version

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining a virtual machine node with a specific source image name and version.

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

```

--------------------------------

### Define Vulnerabilities

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining technical and non-technical vulnerabilities with names, descriptions, and CWE classes.

```yaml
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'

```

--------------------------------

### Source Condition Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines a condition based on a source from the digital library. Used when a command and interval are not specified.

```yaml
condition-2:  
  source: digital-library-package  


```

--------------------------------

### Define Features

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Example of defining various types of features: service, configuration, and artifact. Includes source, destination, environment variables, dependencies, and vulnerabilities.

```yaml
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

```

--------------------------------

### Entity Definition Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines a hierarchical structure for organizations, including sub-departments and individuals, with various attributes.

```yaml
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

```

--------------------------------

### Command Condition Example

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines a condition that executes a command at a specified interval. Used for periodic state checking in virtual machines.

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


```

--------------------------------

### Define Event Timing with Scripts

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Sets the time window for triggering events, defining start and end times, and event eligibility.

```yaml
scripts:
  demo_script:
    start-time: 0
    end-time: 2h
    speed: 1
    events:
      example-event: 5m

```

--------------------------------

### Add NCR Repository to APT Sources

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Add the NCR repository to your system's APT sources list to enable package installation from NCR.

```bash
su -c "echo 'deb [arch=amd64] https://repository.ncr.ntnu.no/repository/ncr-apt-hosted/ noble main' >> /etc/apt/sources.list.d/ncr.list"
```

--------------------------------

### Define WordPress Service Feature

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

This snippet defines a feature to install a WordPress service using a specific Docker package from the Deputy Digital Library.

```yaml
features:
  wordpress:
    type: service
    source: wordpress-4-8-0-docker

```

--------------------------------

### Complete SDL File for First Exercise

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

This snippet shows the full SDL configuration for a simple exercise involving a WordPress server and a scoring machine.

```yaml
name: 'My First Exercise'  
  
stories:  
  demo_story:  
    speed: 1  
    scripts:  
      - demo_script  
  
scripts:  
  demo_script:  
    start-time: 0  
    end-time: 2h  
    speed: 1  
    events:  
      example-event: 5m  
  
events:  
  example-event:  
    name: Bonus Tasks  
    source: demo-event-info  
    conditions:  
      - wordpress-check-credentials  
    injects:  
      - demo_inject  
  
injects:  
  demo_inject:  
    source: flag-generator  
  
conditions:  
  wordpress-check-credentials:  
    source: wordpress-check-credentials  
    environment:  
      - WP_URL=10.1.1.1:8000  
  
features:  
  wordpress:  
    type: service  
    source: wordpress-4-8-0-docker  
  static-ip-1:  
    type: service  
    source: debian-ip-setter  
    environment:  
      - STATIC_IP=10.1.1.1/24  
  static-ip-2:  
    type: service  
    source: debian-ip-setter  
    environment:  
      - STATIC_IP=10.1.1.2/24  
  
nodes:  
  wordpress-server:  
    type: vm  
    source: debian-12-gui-docker  
    resources:  
      cpu: 2  
      ram: 4 GiB  
    roles:  
      admin:  
        username: root  
        entities:  
          - blue-team.participant  
    features:  
      static-ip-1: admin  
      wordpress: admin  
    injects:  
      demo_inject: admin  
  
  scoring-machine:  
    type: vm  
    source: debian11-network-manager  
    resources:  
      cpu: 2  
      ram: 4 GiB  
    roles:  
      admin: root  
    features:  
      static-ip-2: admin  
    conditions:  
      wordpress-check-credentials: admin  
  
  switch:  
    type: switch  
  
infrastructure:  
  switch: 1  
  wordpress-server:  
    count: 1  
    links:  
      - switch  
  scoring-machine:  
    count: 1  
    links:  
      - switch  
  
metrics:  
  wordpress-credentials-metric:  
    type: conditional  
    max-score: 100  
    condition: wordpress-check-credentials  
  
evaluations:  
  wordpress-credentials-evaluation:  
    min-score: 100  
    metrics:  
      - wordpress-credentials-metric  
  
tlos:  
  wordpress-credentials-tlo:  
    evaluation: wordpress-credentials-evaluation  
  
entities:  
  blue-team:  
    role: Blue  
    entities:  
      participant:  
        role: Blue  
        tlos:  
          - wordpress-credentials-tlo  
        events:  
          - example-event  

```

--------------------------------

### Script Definition

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines a script within a story, including start and end times, speed, events, and an optional description. Event timings are relative to the script's start.

```yaml
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"

```

--------------------------------

### Feature Delete

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Deletes listed assets from the VM. Note that currently, installed files or services are not removed.

```APIDOC
## Feature Delete

### Description
Deletes the listed assets from the VM. Currently, if the feature installs additional files or services on the VM, they are not removed.

### Method
gRPC

### Endpoint
`/feature/delete`

### Request Body
- **value** (string) - Required - The identifier of the feature to delete.

### Request Example
```json
{
  "value": "feature-abcde"
}
```

### Response
#### Success Response (200)
An empty response indicates successful deletion.

#### Response Example
```json
{} 
```
```

--------------------------------

### Download and extract OVFTool

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Download the OVFTool binaries and extract them. This is necessary for managing virtual machine images.

```bash
wget https://github.com/rgl/ovftool-binaries/raw/main/archive/VMware-ovftool-4.4.3-18663434-lin.x86_64.zip
unzip VMware-ovftool-4.4.3-18663434-lin.x86_64.zip
```

--------------------------------

### Create Deputy Configuration Directory

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Create the necessary directory for the Deputy CLI configuration files.

```bash
mkdir ~/.deputy
```

--------------------------------

### Basic YAML Syntax Overview

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

This snippet illustrates the fundamental YAML syntax for key-value pairs, lists, and maps, which is essential for writing SDL files.

```yaml
# A key value pair
key: value

# A list - YAML uses indentation to define structure
key:
  - value
  - value2

# A map
key:
  key2: value
  key3: value2
  key4:
    - value3
    - value4

```

--------------------------------

### Create Template

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/templater

Creates a virtual machine template from a given Deputy package. The template is named after the checksum of the source package to prevent duplicates. Existing network devices are removed during creation.

```APIDOC
## create

### Description
Creates a template from a given Deputy package. Duplicate templates of the same Deputy source package are not uploaded. This is achieved by naming the templates after the checksum of the source package.
During the creation of the template the existing network devices are removed. It is still recommended to remove them by hand when before creating the VM Deputy package as it may be prone to errors depending on the openstack version.
If the template already exists in the openstack environment, the deputy package is not downloaded into the handler and the Accounts info is not extracted from it. The Accounts field will be empty in the response. The accounts information is stored on the Rangers database as well as in redis storage, if that is lost the template will need to be deleted and then reuploaded for it to populate the Database again.

### Request
#### Message `Source`
```proto
message Source {
    string name = 1;
    string version = 2;
}
```

### Response
#### Success Response
Message `TemplateResponse`
```proto
message TemplateResponse {
  Identifier identifier = 1;
  repeated Account accounts = 2;
}
```

#### Nested Messages
Message `Identifier`:
```proto
message Identifier {
    string value = 1;
}
```

Message `Account`:
```proto
message Account {
    string username = 1;
    string password = 2;
    string private_key = 3;
}
```
```

--------------------------------

### Exercise Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Specifies the file path for an exercise.

```ini
[exercise]
file_path = file_path = "exercise.yml"
```

--------------------------------

### Create Virtual Machine

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/machiner

Creates a virtual machine in the OpenStack environment. If links are assigned to the VM, network devices are added and connected to the specified networks.

```APIDOC
## create

### Description
Creates a virtual machine in the OpenStack environment. If links are assigned to the VM, network devices are added and connected to the specified networks.

### Request Body
```protobuf
message DeployVirtualMachine {
    VirtualMachine virtualMachine = 1;
    MetaInfo metaInfo = 2;
}

message VirtualMachine {
    string name = 1;
    Configuration configuration = 2;
    string templateId = 3;
    repeated string links = 4;
}

message Configuration {
    uint32 cpu = 1;
    uint64 ram = 2;
}

message MetaInfo {
  string exerciseName = 1;
  string deploymentName = 2;
  Properties properties = 3;
}

message Properties {
    string cidr = 1;
    string gateway = 2;
}
```

### Response
(Details not provided in source)
```

--------------------------------

### Assigning Roles to Nodes

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Assign roles to VMs to grant access to accounts, such as the 'root' account, which is necessary for installing features and connecting participants.

```yaml
nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 1
      ram: 2 GiB
    roles:
      admin: root

```

--------------------------------

### Defining Nodes (VMs and Switch)

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Define virtual machines and network switches, specifying their type, source image, and resource requirements. This is a fundamental part of setting up the exercise environment.

```yaml
nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB

  switch:
    type: switch

```

--------------------------------

### Switch, MetaInfo, and Properties Message Definitions

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/switcher

Defines the core data structures for switch configuration, metadata, and network properties.

```protobuf
message Switch {
  string name = 1;
  repeated string links = 2;
}

message MetaInfo {
  string exerciseName = 1;
  string deploymentName = 2;
  Properties properties = 3;
}

message Properties {
    string cidr = 1;
    string gateway = 2;
}

```

--------------------------------

### Virtual Machine Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Defines the settings for a virtual machine, including accounts, operating system, architecture, type, and file path.

```ini
[virtual-machine]
accounts = [{name = "user1", password = "password1"},{name = "user2", password = "password2"}]
operating_system = "Debian"
architecture = "amd64"
type = "OVA"
file_path = "src/some-image.ova"
```

--------------------------------

### Publish Deputy Package

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-deputy-package

Run this command in your package's directory to upload it to the Digital Library. Ensure the version number in package.toml is updated for new versions.

```bash
deputy publish
```

--------------------------------

### Inject Create

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Injects are similar to Features but are run during the runtime of an exercise, not immediately after VM creation.

```APIDOC
## Inject Create

### Description
Injects are run on the VM during the runtime of the exercise and not immediately after the VM is created. They are essentially the same as `Feature` type packages.

### Method
gRPC

### Endpoint
`/inject/create`

### Request Body
- **name** (string) - Required - The name of the inject.
- **virtual_machine_id** (string) - Required - The ID of the virtual machine.
- **source** (Source) - Required - Information about the source of the inject.
- **account** (Account) - Required - Account credentials for accessing the source.
- **to_entities** (repeated string) - Optional - Entities to apply the inject to.
- **environment** (repeated string) - Optional - Environment variables to set.

### Request Example
```json
{
  "name": "example-inject",
  "virtual_machine_id": "vm-12345",
  "source": {
    "name": "my-repo",
    "version": "1.0.0"
  },
  "account": {
    "username": "user",
    "password": "pass",
    "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
  },
  "to_entities": ["entity1", "entity2"],
  "environment": ["ENV_VAR=value"]
}
```

### Response
#### Success Response (200)
- **identifier** (Identifier) - An identifier for the created inject.
- **stdout** (string) - Standard output from the execution.
- **stderr** (string) - Standard error from the execution.

#### Response Example
```json
{
  "identifier": {
    "value": "inject-abcde"
  },
  "stdout": "Inject executed successfully.",
  "stderr": ""
}
```
```

--------------------------------

### Deputy Package File Structure

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-deputy-package

After creation, a Deputy package includes a package.toml for metadata, a README.md for overview, and a src folder for package files.

```tree
my-first-package  
├── package.toml  
├── README.md  
└── src  
    └── // package files //  

```

--------------------------------

### Deputy CLI Configuration TOML

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Configure the Deputy CLI by adding Digital Library Package Server registries and specifying the download path for packages.

```toml
[registries]
main-registry = { api = "https://your_deputy_subdomain" }

[package]
download_path = "~/.deputy/downloads/" # Path for temporary files during package fetching

```

--------------------------------

### DeploySwitch Message Definition

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/switcher

Defines the structure for deploying a switch, including switch details and metadata.

```protobuf
message DeploySwitch {
    Switch switch = 1;
    MetaInfo metaInfo = 2;
}

```

--------------------------------

### DeployVirtualMachine gRPC Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/machiner

Defines the structure for deploying a virtual machine, including VM details and metadata.

```protobuf
message DeployVirtualMachine {
    VirtualMachine virtualMachine = 1;
    MetaInfo metaInfo = 2;
}

```

--------------------------------

### Package Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Defines the structure for a Deputy package, including its name, version, and type.

```protobuf
message Package {
  string name = 1;
  string version = 2;
  string type = 3;
}

```

--------------------------------

### Event Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Specifies the file path for an event.

```ini
[event]
file_path = "event.md"
```

--------------------------------

### Account Message Definition

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/templater

Defines the structure for account credentials, including username, password, and private key.

```protobuf
message Account {
    string username = 1;
    string password = 2;
    string private_key = 3;
}

```

--------------------------------

### Event create

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

The Event `create` gRPC endpoint converts Markdown pages to HTML and prepares them for Ranger. Redis is used to track created files and their metadata.

```APIDOC
## Event create

### Description
Converts Markdown pages to HTML and prepares them for Ranger. Uses Redis for tracking files and metadata.

### Service
gRPC

### Method
Event.create

### Request Body
```
message Source {
    string name = 1;
    string version = 2;
}
```

### Response
#### Success Response (200)
```
message EventCreateResponse {
  string id = 1;
  string checksum = 2;
  string filename = 3;
  int64 size = 4;
}
```
```

--------------------------------

### Infrastructure Definition with Properties

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines infrastructure with counts, links, and specific properties like CIDR and gateway for nodes.

```yaml
infrastructure:
  switch-1:
    count: 1
    properties:
      cidr: 10.10.10.0/24
      gateway: 10.10.10.1
  windows-10: 3
  windows-10-vuln-1:
    Count: 1
    links:
      - switch-1
    properties:
      - switch-1: 10.10.10.10
  switch-2:
    Count: 2
    LINKS:
      - switch-1
  ubuntu-10:
    Links:
      - switch-1
    dependencies:
      - windows-10
      - windows-10-vuln-1

```

--------------------------------

### Setting Exercise Name

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Define the name for your exercise using the 'name' key in the SDL file.

```yaml
name: 'My First Exercise'

```

--------------------------------

### Malware Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Defines the path to an executable file for malware.

```ini
[malware]
action = "installer/install_something.sh"
```

--------------------------------

### Feature Create Request Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Defines the structure for a Feature create request, including name, VM ID, feature type, source, account, and environment details.

```protobuf
message Feature {
  string name = 1;
  string virtual_machine_id = 2;
  FeatureType featureType = 3;
  Source source = 4;
  Account account = 5;
  repeated string environment = 7;
}

```

--------------------------------

### Inject Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Configures an injection, specifying the action to perform and if a restart is needed.

```ini
[inject]
action = "ping google.com"
restarts = true
```

--------------------------------

### Login to Deputy CLI

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-deputy-package

Use this command to log in to the Deputy CLI. You will be prompted to paste your Deputy Token.

```bash
deputy login
```

--------------------------------

### OpenStack VM and Metadata Message Definitions

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/machiner

Defines the core data structures for virtual machines, their configurations, metadata, and properties within the OpenStack environment.

```protobuf
message Configuration {
    uint32 cpu = 1;
    uint64 ram = 2;
}

message VirtualMachine {
    string name = 1;
    Configuration configuration = 2;
    string templateId = 3;
    repeated string links = 4;
}


message MetaInfo {
  string exerciseName = 1;
  string deploymentName = 2;
  Properties properties = 3;
}

message Properties {
    string cidr = 1;
    string gateway = 2;
}

```

--------------------------------

### Feature Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Defines a feature, including its type, action, and whether a restart is required.

```ini
[feature]
type = "service"
action = "ping google.com"
restarts = true
```

--------------------------------

### Defining Infrastructure and Links

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Specify the count of nodes and network switches, and define their interconnections using the 'links' field. This sets up the network topology for the exercise.

```yaml
infrastructure:
  switch: 1

  wordpress-server:
    count: 1
    links:
      - switch

  scoring-machine:
    count: 1
    links:
      - switch

nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin: root

  scoring-machine:
    type: vm
    source: debian11-network-manager
    resources:
      cpu: 2
      ram: 4 GiB

  switch:
    type: switch

```

--------------------------------

### Condition Configuration

Source: https://ncr.ntnu.no/docs/toolsets/deputy/package

Specifies the action to execute and the interval between executions for a condition.

```ini
[condition]
action = "executable/path.sh"
interval = 30
```

--------------------------------

### Create Switch

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/switcher

Creates a virtual switch (network, subnet, and port) in the OpenStack environment. This involves defining the switch's name, associated links, and metadata including exercise name, deployment name, CIDR, and gateway.

```APIDOC
## create

### Description
Creates a virtual switch (network, subnet, and port) in the OpenStack environment.

### Request
```protobuf
message DeploySwitch {
    Switch switch = 1;
    MetaInfo metaInfo = 2;
}

message Switch {
  string name = 1;
  repeated string links = 2;
}

message MetaInfo {
  string exerciseName = 1;
  string deploymentName = 2;
  Properties properties = 3;
}

message Properties {
    string cidr = 1;
    string gateway = 2;
}
```

### Successful Response (200)
Returns an identifier for the created switch.

```protobuf
message Identifier {
    string value = 1;
}
```
```

--------------------------------

### Role Definition Shorthand and Longhand

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Illustrates two ways to define roles: a shorthand string for a username and a longhand object with username and entities.

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

```

--------------------------------

### Condition Message Format

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/executor

Defines the structure for a condition to be executed on a virtual machine.

```protobuf
message Condition {
  string name = 1;
  string virtual_machine_id = 2;
  Account account = 3;
  Source source = 4;
  string command = 5;
  int32 interval = 6;
  repeated string environment = 7;
}

```

--------------------------------

### Link Configuration for Switches

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Defines links between switches and other nodes, indicating dependencies and deployment order. Includes properties like IP addresses.

```yaml
switch-1:
  count: 1
ubuntu-10:
  links:
    - switch-1
windows-10-vuln-1:
  Count: 1
  links:
    - switch-1
  properties:
    - switch-1: 10.10.10.10

```

--------------------------------

### Dependency Configuration for Virtual Machines

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Lists virtual machines that depend on other nodes, controlling deployment order. A VM can have multiple dependencies.

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

```

--------------------------------

### Infrastructure Definition Shorthand

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

A concise way to define infrastructure by mapping node names to a count.

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

```

--------------------------------

### Add NCR Repository GPG Key

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Fetch the NCR Repository GPG key and add it to your system's trusted keyring to verify package authenticity.

```bash
sudo wget -qO - https://repository.ncr.ntnu.no/repository/ncr-raw-hosted/hosted/gpg | gpg --dearmor -o /etc/apt/trusted.gpg.d/ncr.gpg
```

--------------------------------

### Update Package Lists

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/pre-requisites

Refresh your system's package lists to include the newly added NCR repository.

```bash
apt update
```

--------------------------------

### Configure Node with Inject

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

Associates an Inject with a Node, specifying its deployment to specific roles and VMs.

```yaml
nodes:
  wordpress-server:
    type: vm
    source: debian-12-gui-docker
    resources:
      cpu: 2
      ram: 4 GiB
    roles:
      admin:
        username: root
        entities:
          - blue-team.participant
    features:
      wordpress: admin
    conditions:
      wordpress-check-credentials: admin
    injects:
      demo_inject: admin

```

--------------------------------

### Event stream

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

The `stream` gRPC endpoint streams previously prepared HTML pages to Ranger.

```APIDOC
## Event stream

### Description
Streams previously prepared HTML pages to Ranger.

### Service
gRPC

### Method
Event.stream

### Request Body
```
message Identifier {
    string value = 1;
}
```

### Response
#### Success Response (200)
```
stream message EventStreamResponse {
  bytes chunk = 1;
}
```
```

--------------------------------

### Count Configuration for Virtual Machines

Source: https://ncr.ntnu.no/docs/toolsets/sdl/reference

Specifies the number of virtual machines to use. For machines running conditions, the count is limited to 1.

```yaml
windows-10:
  count: 3

```

--------------------------------

### Define Static IP Features

Source: https://ncr.ntnu.no/docs/toolsets/getting-started/first-exercise

This snippet defines two features for assigning static IP addresses to VMs using the debian-ip-setter package.

```yaml
features:
  wordpress:
    type: service
    source: wordpress-4-8-0-docker

  static-ip-1:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.1/24

  static-ip-2:
    type: service
    source: debian-ip-setter
    environment:
      - STATIC_IP=10.1.1.2/24

```

--------------------------------

### Event Create Response Message

Source: https://ncr.ntnu.no/docs/toolsets/handlers/openstack-handlers/general

Defines the structure for a successful response from the Event create gRPC endpoint.

```protobuf
message EventCreateResponse {
  string id = 1;
  string checksum = 2;
  string filename = 3;
  int64 size = 4;
}

```