Visual Studio Code Extension

Information

This page contains information about an extension for Visual Studio Code that can be installed and used to develop exercise definitions for the Inject Exercise Platform (IXP). Visual Studio Code is an enhanced text editor featuring extensive language support, along with options for extensions that can add additional support for specific languages and settings files, such as exercise definitions. The extension provides syntax checking and multiple commands to enhance your design experience and minimize the number of mistakes made during exercise definition editing.

Known issues

• All the VSC extension features might not work correctly on Windows 11 (build 26200.7705).
• Role based exercises are not supported.
• All the features are compatible only with the latest version of the IXP platform. Compatibility with older versions of the IXP is not guaranteed.
• Using commands that interact with IXP are prone to networking errors, if the command fails, try to run it again.

Features

• Multiple templates (snippets) for parts of the exercise definition:

full-config
basic-email
template-email
info-inject
email-inject
time-inject
confirmation-inject
objective
activity
questionnaire
q-radio
q-multiple-choice
q-free-form
q-auto-free-form
basic-tool
multi-tool

• Instant syntax check for definition version 0.25.0.
• Upgrade of definition syntax from version 0.18.1 to 0.25.0 - the upgrade also works from any intermediate version.
• Ignoring of hidden files during definition zipping.
• Support for repository-like definition structure (multiple subdirectories).
• Validates definition through deployed instance of IXP in version 6.0.X.
• Removes previously stored credentials and URL for IXP instance.
• Run Test Environment and Stop Test Environment buttons for testing an exercise definition on the IXP instance.
• Automatic quotes removal on YAML file open - if the quotes are not necessary
• Automatic formating of exercise definitions.
• Upload exercise definition into IXP platform.
• Download public exercise definitions from the INJECT team.
• Support for semantic validation, see below.
• Generation of comments with duration translated to more human readable format e.g. time: 90 generates time: 90 # Duration: 1h30m.

Commands

Command: Create New Definition Folder:

• Creates a new definition folder with the selected name and prepopulated files like config.yml and channels.yml.

Command: Zip Definition:

• Zips selected definition to be uploaded to IXP.

Command: Upgrade Definition 0.18.1 to 0.25.0:

• Removes unnecessary quotes in all YAML files.
• Upgrades definition from version 0.18.1 (Citadel) to 0.25.0 (Fortress)

Command: Validate Definition:

• Validates definition through the deployed instance of IXP.

Command: Delete Saved IXP Credentials:

• Removes stored credentials and URL for the IXP instance used for validation.

Command: Run Test Environment:

• Creates exercise definition test environment on an instance of IXP - uploads definition, creates exercise with one team, starts the exercise.

Command: Stop and Clean Test Environment:

• Stops test environment - stops the exercise, deletes the exercises, and deletes the exercise definition.

Command: Upload Definition:

• Uploads definition into IXP using credentials.

Command: Load Exercise Definitions from Definition Registry:

• Downloads and unzips exercise definitions from INEJCT definition registry.
• The Definition Registry contain exercise definitions meantioned in documentation in available definitions page.

Keybindings

• Zip command - Windows: Ctrl + Alt + g, MacOS: Control + Option + g
• Open command palette - Windows: Ctrl + Shift + p, MacOS: Command + Shift + p

Semantic Validation Capabilities

• Validates YAML syntax correctness
• Ensures config.yml is a mapping and other definition files are lists where expected

Uniqueness Checks

• Ensures uniqueness of name in:
  • channels.yml
  • injects.yml
  • milestones.yml
  • tools.yml
  • roles.yml
  • questionnaires.yml
  • objectives.yml
  • commands.yml
• Ensures uniqueness of address in email.yml

Channel Validation

• Validates allowed channel types in channels.yml:
  • info
  • tool
  • email
  • form
  • command
• Ensures that at most one channel exists for each type (multiple info channels are allowed):
  • tool
  • email
  • form
  • command

Content & File Validation

• Ensures content and content_path are not both defined
• Validates that files referenced in content_path exist in /content
• Validates that files in attachments exist in /files
• Validates that files in milestones.file_names exist in /files
• Validates that files inside {{}} (embedding) exist in /files

LLM Assessment Validation

• Ensures persona and persona_path are not both defined
• Ensures assessment and assessment_path are not both defined
• Requires at least one of:
  • persona or persona_path
• Requires at least one of:
  • assessment or assessment_path
• Validates that referenced files exist in /llm

Milestone Validation

• Validates milestone name format:
  • Must start with a letter or _
  • Must not contain spaces
  • Only A-Z, a-z, 0-9, _ allowed
• Ensures milestone cannot have both:
  • initial_state: true
  • final: true

Milestone References

• Validates references in:
  • activate_milestone
  • deactivate_milestone
  • milestone_condition
  • related_milestones
• Ensures all referenced milestones exist in milestones.yml

Role Validation

• Ensures referenced roles exist in roles.yml
• Shows warning if roles are used but enable_roles is not enabled
• Shows error if enable_roles: true but roles.yml is missing or empty

Inject Validation

• Ensures target references an existing channel
• Ensures target references a channel of type info
• Ensures sender exists in email.yml

Cross-file Consistency

• Ensures:
  • tools.yml is not used without a tool channel
  • email.yml is not used without an email channel
  • questionnaires.yml is not used without a form channel
  • commands.yml is not used without a command channel

Control Object Validation

• Validates milestone references inside control objects
• Ensures forbidden fields are not used in restricted contexts:
  • milestone_condition
  • roles
• Applies restrictions in:
  • confirmation.control
  • email.control
  • email.templates[].control
  • auto-free-form (correct / incorrect)

Objectives Validation

• Ensures references exist in:
  • milestones

File Structure Support

• Supports both:
  • single-file structure (e.g. injects.yml)
  • multi-file structure (e.g. injects/*.yml)
• Applies to all supported structures except config.yml

Dependencies

• https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

ext install redhat.vscode-yaml

References

• Inject project website
• Inject Exercise Platform (IXP) documentation
• Cybersecurity Laboratory
• Faculty of Informatics MU

License

MIT license