Package

Package.toml file

Package always contains a package.toml file, that defines the package and the way it’s wrapped. This is an example of the package.toml file:

[package]
name = "debian11"
description = "Debian 11.4.0 minimal CLI."
version = "1.3.0"
authors = ["Developer [email protected]"]
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"}]

The file currently contains three sections: [package], [content] and a section depending on the package type, for example [virtual-machine].

First section – Package

The [package] section defines the following:

• Name – package name, that is used when searching the package. Does not have to be the same as the package file’s actual name.
• Description – package description, can be anything.
• Version – version of the package, uses the semantic versioning rules. When uploading a package, we check whether the same version of the package already exists.
• Authors – package authors, can be anything.
• License – the name of the software license that the package is released under. The license field interprets SPDX 2.1 license expression and the license name must be a known license from the SPDX license list. Multiple licenses can be used together with license expressions. See the SPDX specification for more information.
• Readme – defines the location of the readme file in the package
• Category – a list categories the package belongs to
• Assets – contains all the files that will be copied to the guest OS. Array members contain arrays that specify the file to be copied, the location on the target, and the file permissions to be set on the copied file. Package type for which it's mandatory: feature, condition, inject, event, malware

[package]
name = "debian11"
description = "Debian 11.4.0 minimal CLI."
version = "1.3.0"
authors = ["Developer [email protected]", "Someone [email protected]"]
license = "MIT"
readme = "src/readme.md"
categories = ["exercise", "testing"]
assets = [ ["src/configs/my-cool-config1.yml", "/var/opt/my-cool-service1", "744", ], ]

Variable	Mandatory	Type
name	yes	string
description	yes	string
version	yes	string
authors	no	array of strings
license	yes	string
readme	yes	string
category	no	array of strings
assets	no	array of arrays

Second section – Content

The [content] section specifies the package type and its content's preview if applicable:

• Type – specifies the type of the package, possible types: vm, condition, feature, inject, event, malware, exercise, other. Multiple content types per package is not supported.
• Preview – lists the preview content using type:value format. Preview valid types are picture, video, code. Value is a list of file paths to the preview files.

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

Variable	Mandatory	Type
type	yes	string
preview	no	array of hashmaps

Third section

The third section depends on the package type and is mandatory.

Virtual machine

[virtual-machine] type packages are used to define virtual machine images.

• Accounts – specifies the accounts tied to the VM. Access to the VM is granted by the account specified in the SDL which references an account in the package. Currently only name-password pairs are supported for authentication between the Vmware Handler and Vsphere hypervisor. However a private key can be defined as well which will be displayed to the connected participant in Ranger.
• Operating_system – operating system of the VM. We check whether the given operating system exists in our pre-defined enum; if not, it’s assigned “unknown” type. List of supported operating systems:

AlmaLinux, AmazonLinux, Asianux, CentOS, Debian, DebianGNULinux, EComStation, Fedora, Flatcar, FreeBSD, KylinLinuxAdvancedServer, MacOs, MiracleLinux, NeoKylinLinuxAdvancedServer, OpenSuse, OracleLinux, OSX, Pardus, Photon, RedHatEnterpriseLinux, RockyLinux, SCOOpenServer, SCOUnixWare, Solaris, SUSELinuxEnterprise, Ubuntu, Windows10, Windows11, Windows2000, Windows7, Windows8, WindowsServer2003, WindowsServer2008, WindowsServer2012, WindowsServer2016, WindowsServer2019, WindowsServer2022, WindowsVista, WindowsXP

• Architecture – architecture of the VM. We check whether the given architecture exists in our pre-defined enum; if not, it’s assigned “unknown” type. List of supported operating systems:

amd64, arm64, armhf, i386

• Type – file type of the VM. Currently, only “OVA” type is supported.
• File_path – defines the location of the file in the package.

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

Variable	Mandatory	Type
accounts	no	array of Accounts consisting of name and password string values
operating_system	no	string
architecture	no	string
type	yes	string
file_path	yes	string

NOTE: When using Vmware Handlers and vSphere, the VM must fully support and have vmware-tools pre-installed.

Condition

[condition] type packages are predefined scripts that are copied into the target VM and executed at a specified intervals. The output of the script must be within the range of 0..1. Which is then sent to Ranger. The output is used for scoring in combination with SDL Metrics and to trigger SDL Events. Condition package contents are installed on the VM after Feature type packages have been deployed and are executed continuously depending on the SDL configuration.

• Action – path to the executable file on the target VM.
• Interval – the interval between command executions in seconds. Very fast intervals may be throttled.

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

Variable	Mandatory	Type
action	yes	string
interval	yes	integer

Feature

[feature] type packages are used to define arbitrary software packages that are to be installed and depending on the subtype, to be executed on the target VM after the VM is created. The stdout and stderr are captured and sent to the Managers deployment view in Ranger.

• Type – defines the feature type, can be service, configuration or artifact.
  • Service - this is the most common type of feature. It is used to install packages and / or start services on the VM. Requires the action field which points to either the path of an installation script on the VM or defines some arbitrary console command.
  • Configuration - mainly used to be able to define Feature packages for purely config type files.
  • Artifact - used to copy arbitrary files to the target VM, functionally same as Configuration.
• Action – command to execute, or path to an executable file.
• Restarts – boolean that determines if a machine restarts after file copy or execution operations. If a machine is required to restart after a previously mentioned operation, set the value to true.

[feature]
type = "service"
action = "/installer.sh"
restarts = true

Variable	Mandatory	Type
type	yes	string
action	no	string
restarts	yes	bool, default false

Inject

[inject] type packages are functionally similar to Feature packages but are installed and executed on the VM only after an SDL Event has been triggered. The stdout and stderr are captured and sent to the Managers deployment element view in Ranger.

• Action – command to execute, or path to an executable file.
• Restarts – boolean that determines if a machine restarts after file copy or execution operations. If a machine is required to restart after a previously mentioned operation, set the value to true.

[inject]
action = "/installer.sh"
restarts = true

Variable	Mandatory	Type
action	no	string
restarts	yes	bool, default false

Event

[event] type packages define a markdown file that is displayed to the participant in the Ranger environment when an SDL Event is triggered.

• File_path – defines the location of the file in the package.

[event]
file_path = "event.md"

Variable	Mandatory	Type
file_path	yes	string

Malware

[malware] type packages are currently Work-In-Progress, are not implemented into SDL and have no functional components.

• Action – path to the executable file.

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

Variable	Mandatory	Type
action	yes	string

Exercise

[exercise] type packages define a YAML file containing the SDL of an exercise. In the Rangers manager view, the pre-made SDLs reference these packages.

• File_path – defines the location of the file in the package.

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

Variable	Mandatory	Type
file_path	yes	string

Other

[other] type packages are currently Work-In-Progress, are not implemented into SDL and have no functional components.

• No fields under other package type, but it is mandatory to define the section.

[other]