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 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"}]
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 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", ], ]
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 arepicture
,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]
- accounts – specifies the accounts tied to the VM.
- 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"}]
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 |
Condition
[condition]
- Action – path to the executable file.
- Interval – the interval between command executions in seconds.
[condition]
action = "executable/path.sh"
interval = 30
Variable | Mandatory | Type |
---|---|---|
action | yes | string |
interval | yes | integer |
Feature
[feature]
- Type – defines the feature type, can be
service
,configuration
orartifact
. If type =service
, thenaction
field is also defined, otherwise the field is not defined. - 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 = "ping google.com"
restarts = true
Variable | Mandatory | Type |
---|---|---|
type | yes | string |
action | no | string |
restarts | yes | bool, default false |
Inject
[inject]
- 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 = "ping google.com"
restarts = true
Variable | Mandatory | Type |
---|---|---|
action | no | string |
restarts | yes | bool, default false |
Event
[event]
- 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]
- Action – path to the executable file.
[malware]
action = "installer/install_something.sh"
Variable | Mandatory | Type |
---|---|---|
action | yes | string |
Exercise
[exercise]
- 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]
- No fields under
other
package type, but it is mandatory to define the section.