Creating a Plugin

Creating a plugin follows the Create → Test → Publish → Iterate lifecycle. This page covers the creation phase — writing your Ansible YAML and defining parameters.

Starting a New Plugin

From the Plugin Development homepage, click Create Plugin. You’ll be prompted for:

• Plugin Name — A unique, descriptive name
• Plugin Description — What this plugin does
• Category — Action, Role, Application, Vulnerability, Attack, Defense, or File Copy
• Compatible Templates — Which VM templates this plugin can run on

After creating the plugin, you’re taken to the Plugin Editor where you write your YAML.

Writing Ansible YAML

Plugins use a flat task list format. You write only the Ansible tasks — the system automatically injects the playbook headers (hosts, tasks, gather_facts, vars). Do not include playbook-level keys like hosts: or tasks: in your YAML.

Example: A Simple Plugin

- name: Install Apache
  apt:
    name: apache2
    state: present

- name: Start Apache service
  service:
    name: apache2
    state: started
    enabled: true

The system wraps this into a complete Ansible playbook at build time.

The Monaco Editor

The YAML editor is a full Monaco editor (the same engine behind VS Code) with:

• Syntax highlighting for Ansible YAML
• Dependency highlighting — plugin dependencies (referenced as {<PluginName>}) appear highlighted in purple
• Parameter highlighting — parameter references ({{ paramName }}) are visually distinct
• YAML validation — catches syntax errors before you save
• Undo/Redo support

Saving

Click Save or use the keyboard shortcut. The editor shows a checkmark when saved successfully. If you have unsaved changes, a dot indicator appears on the save button.

Defining Parameters

Parameters make your plugins configurable. Instead of hardcoding values, you define parameters that scenario builders fill in when they add your plugin to a machine.

Parameter Types

Type	Description	Editor
String	Single-line text input	Text field
Number	Numeric value	Number input
Boolean	True/false toggle	Checkbox
String Block	Multi-line text	Monaco editor
CSV	Comma-separated tabular data	CSV editor with PapaParse validation

Creating Parameters

Open the Parameters panel from the toolbar to manage your plugin’s parameters. For each parameter you define:

• Field Name — The name used in YAML references (e.g., DomainName)
• Description — Help text shown to scenario builders
• Type — One of the five types above
• Required — Whether the parameter must be filled before building
• Advanced Setting — Whether to show this in the “Advanced” section of the parameter form

For CSV parameters, you also define the column headers that the CSV editor will validate against.

Using Parameters in YAML

Reference parameters in your YAML using double curly braces:

- name: Set hostname
  hostname:
    name: "{{ HostName }}"

- name: Configure domain
  win_domain_membership:
    dns_domain_name: "{{ DomainName }}"
    domain_admin_user: "{{ DomainAdmin }}"
    domain_admin_password: "{{ DomainPassword }}"
    state: domain

The parameter name must exactly match the parameterFieldName you defined.

Plugin Directions

Add usage instructions in the Directions field. These are shown to scenario builders when they add your plugin and help them understand what parameters to set and what the plugin will do.

Previewing Your Plugin

Before testing in a real build, you can preview how your plugin will compile:

1. Open the Preview panel from the toolbar
2. Set example values for each parameter
3. Click Preview to generate the compiled YAML with all parameters resolved

This shows you exactly what Ansible will receive at build time — useful for catching parameter reference issues without launching a full build.

Testing Your Plugin

After writing your YAML and defining parameters:

1. Navigate to a scenario canvas
2. Add your plugin to a machine
3. Fill in the parameter values
4. Launch a build

Check the build logs to verify your plugin runs successfully. The Ansible output for each plugin is available in the build log viewer.

Publishing Your Plugin

Once tested and working:

1. Open the plugin editor
2. Click Publish in the toolbar
3. Add a changelog entry describing what this version does

Published versions become read-only. To make further changes, you’ll need to clone to a new version (see Cloning & Versioning).