Skip to main content
Version: Current

Contribute a Scenario

Add an existing CRADLE scenario to the Cyber Range Collection through cradle-lang/scenario-lib.

By the end of this guide, you will:

  1. Import an existing CRADLE scenario and its supporting files.
  2. Optionally use AI to draft its Collection article.
  3. Review and validate the contribution.
  4. Open a draft pull request ready for review.
  5. Understand how the scenario reaches the website after approval.

:::info Start with a completed scenario This guide assumes you already have a completed CRADLE scenario. AI generates documentation only. It does not create, validate or test the scenario. You are responsible for verifying the article against the actual files. :::

Before you start​

You need:

  • Git, Node.js 22 or newer, and npm.
  • A GitHub account.
  • A completed CRADLE specification and its supporting files.
  • Permission to redistribute the code and assets you contribute.
  • Optionally, CradleXC for local compiler validation.
  • An OpenAI-compatible LLM server only if you choose AI article generation.

Run all commands from the scenario-lib repository root unless stated otherwise. Scenario folders belong in scenarios/; library/scenarios/ is the website's import destination.

Choose how to create the article​

ApproachWhat you do
AI-assistedUse an OpenAI-compatible server to draft index.md, then verify and edit it. Follow step 2.
ManualImport the same files and write the article yourself, or preserve an existing article. Skip step 2; no .env, API key or LLM server is needed.

Contribution workflow​

You control the contribution:

Scenario files
↓
Import and review article
↓
Local validation
↓
Draft PR

CI, maintainers and website automation handle review and publication:

CI validation and scenario PR review
↓
Scenario PR merged and main validated
↓
Website PR created and reviewed
↓
Website PR merged and Collection published

1. Set up the repository​

Fork scenario-lib if you do not have write access. Replace YOUR-GITHUB-USERNAME with your account; contributors with write access can clone upstream instead.

These commands work in PowerShell, Bash and Zsh:

git clone https://github.com/YOUR-GITHUB-USERNAME/scenario-lib.git
cd scenario-lib
git switch -c add-my-range
npm ci

For an existing checkout, start from an up-to-date main and create a contribution branch. You should now have a checkout with dependencies installed and a branch for your contribution.

2. Configure AI article generation​

Manual authors: skip to Import the scenario.

Create .env beside package.json without overwriting an existing file, then open it in your editor.

PowerShell​

if (!(Test-Path -LiteralPath .env)) {
Copy-Item -LiteralPath .env.example -Destination .env
}
notepad .env

Bash / Zsh​

if [ ! -f .env ]; then
cp .env.example .env
fi
nano .env

Enter your server's API base URL, an available model and your key. Replace the example values with your own connection details:

SERVER="https://your-llm-server.example/v1"
REMOTE_LLM_MODEL="your-model-name"
REMOTE_LLM_API_KEY="your-key-here"

The server must support OpenAI-compatible Chat Completions. See LLM configuration details for endpoint, model and input-limit options.

:::warning Credentials and scenario content Never commit .env or put credentials inside scenario files. .env is ignored by Git. Generation sends selected scenario text to your configured server; check that you have permission to share that content with the server. :::

3. Import the scenario​

Prepare a source folder containing the completed specification and supporting files. For the simplest import, name the main specification scenario.cradle. Choose a new folder ID using lowercase letters, digits and hyphens, such as my-range.

Run only one of the following import alternatives for a given ID.

AI-assisted import​

PowerShell​

npm run library:new -- scenario my-range --from "C:\path\to\MyRange" --generate-index

Bash / Zsh​

npm run library:new -- scenario my-range --from "$HOME/Downloads/MyRange" --generate-index

Manual import​

Omit --generate-index to create a starter article or preserve an existing one, without contacting an LLM.

PowerShell​

npm run library:new -- scenario my-range --from "C:\path\to\MyRange"

Bash / Zsh​

npm run library:new -- scenario my-range --from "$HOME/Downloads/MyRange"

Check the result​

You should now have a folder like this, depending on the supporting files in your source:

scenarios/
└── my-range/
├── scenario.cradle
├── index.md
├── configs/
├── heuristics/
└── scripts/

New starter and AI-generated articles contain draft: true. An authored index.md or index.mdx is preserved, including its metadata, even when you use --generate-index. Check its draft status yourself.

The source folder is unchanged, and existing scenario folders are never overwritten. The importer copies selected files, so compare the imported folder with your source and add any missing dependencies. A uniquely named specification such as MyRange.cradle keeps its filename; article links must match it. See What the importer copies for the selection rules.

4. Review the article​

Edit scenarios/my-range/index.md, whether it came from AI, a starter template or your source folder.

:::warning Verify every claim AI drafts documentation only. Verify every claim against the specification and supporting files. Describe intended behavior separately from recorded test results; generation is not evidence of successful validation or deployment. :::

What should be in index.md?​

The file has two parts: front matter, which controls its Collection metadata, and article content, which explains the scenario to readers. Use this example as a starting point and replace its guidance with scenario-specific information:

---
title: My Range
description: Short summary of the scenario.
source: Original author or organisation
category: ICS
tags: [Training, Network Security]
requirements: Required backend, images, configs and other dependencies.
draft: true
---

# My Range

## Overview
Explain what the scenario represents and what it is intended to demonstrate.

## Topology
Describe the main networks, systems and relationships between them.

## Scenario or Exercise Flow
Explain the exercise sequence, including important events and stages.

## Setup and Requirements
List the software, backend, images, configs, heuristics and other dependencies,
and explain any setup required.

## Expected Results
Explain the intended results of validation, compilation or deployment.
Separate these expectations from observed results.

## Validation
Record checks actually run and their results: CradleXC validation, dependency
validation, backend compilation, runtime deployment or exercise testing.
Include relevant versions and evidence. State which checks have not been run.
Do not present AI-generated or inferred behavior as tested.

## Supporting Files
[Download the specification](./scenario.cradle)

Link to the configs, heuristics, scripts and artifacts readers need.

## Attribution and Licensing
State the original source, authorship and relevant licence information.

The exact headings do not have to match this example. The article should give readers enough information to understand the scenario, its dependencies, how it is intended to work and what has actually been validated. Record unknown details as undocumented or unverified rather than inventing them.

Front matter and publication status​

FieldPurpose
titleScenario name shown on the website.
descriptionShort Collection summary.
sourceOriginal author, organisation or source.
categoryMain scenario category.
tagsSearch/filter terms; use a non-empty list.
requirementsImportant runtime and dependency requirements.
drafttrue keeps the entry hidden; false makes it eligible for publication.

Published articles require all six descriptive fields above. Set draft explicitly: draft: true keeps the entry hidden while it still undergoes validation; draft: false makes it eligible for publication after review. Omitting draft is treated as published. A GitHub draft PR and the article's draft field are separate controls.

Do not add id or slug; the folder supplies the scenario ID. Keep exactly one article and use index.md for website export; convert an index.mdx article before exporting.

Retain the specification download and link supporting files relative to the scenario folder, using their actual filenames:

[Download the specification](./scenario.cradle)
[Setup script](./scripts/setup.sh)
![Topology](./images/topology.png)

Article review checklist​

Before submitting, confirm that:

  • The purpose matches the actual scenario.
  • The topology, systems and exercise sequence are accurate.
  • Setup instructions and runtime requirements are documented.
  • Expected behavior is presented as tested only when supported by evidence.
  • Required configs, heuristics, scripts and artifacts are included or their external dependencies are documented.
  • Attribution, licensing and redistribution permissions are correct.
  • Links to the specification and supporting files work.
  • Front matter is complete and draft has the intended value.

5. Validate the contribution​

After reviewing the article and editing metadata, update the tracked catalogue and run the repository checks. These commands work in PowerShell, Bash and Zsh:

npm run catalog:update
npm run check
npm run library:catalog

npm run check checks articles, the root catalogue and script tests. library:catalog generates the published-article catalogue in ignored dist/catalog.json; commit the root catalog.json instead. With draft: true, your scenario belongs in the root catalogue but is excluded from the published-article catalogue.

Compiler and dependency validation​

For local validation, install CradleXC, ensure cxc is on your PATH, and clone the shared libraries if you do not already have checkouts:

git clone https://github.com/cradle-lang/cradle-lib.git .reference-cradle-lib
git clone https://github.com/cradle-lang/cradle-lib-cve.git .reference-cradle-lib-cve
npm run library:validate -- --library .reference-cradle-lib --cve-library .reference-cradle-lib-cve --scenario my-range

Skip each clone if its folder already exists, or supply paths to your existing checkouts. Validation checks the specification and resolves configuration and heuristic modules from the scenario and shared libraries. Reports are written to scenario-output/validation.json and scenario-output/validation.md.

The command fails if CXC is unavailable. If you cannot run it locally, state that in the PR and inspect the required GitHub validation results.

:::info Validation is not runtime testing These checks validate source and dependencies. They do not deploy or execute the cyber range, provision machines, verify runtime images, render or execute Ansible templates, run scripts or exercise events. Record any separate compilation and runtime tests, including compiler, backend and testbed versions. :::

6. Open a draft PR​

Before opening your PR​

  • scenario.cradle or the named main specification is included and complete.
  • index.md has been reviewed against the scenario.
  • Required supporting files are included and external dependencies are documented.
  • No credentials, .env, node_modules, generated reports or export bundles are staged.
  • The root catalog.json is updated.
  • npm run check and npm run library:catalog pass.
  • Local CXC and dependency validation passes, or the PR explains that it was not run and why.
  • The article's draft field is set correctly.

Stage the complete scenario folder and updated root catalogue. Inspect the staged files before committing. These commands work in PowerShell, Bash and Zsh:

git add scenarios/my-range/ catalog.json
git diff --cached
git status --short
git commit -m "Add my-range scenario"
git push -u origin add-my-range

Open a pull request targeting cradle-lang/scenario-lib's main and select Create draft pull request. Complete the repository's PR template: replace placeholders, list included files and dependencies, record actual checks and evidence, and explain checks not run or known limitations. Keep compilation and runtime evidence separate from repository checks.

You should now have a draft PR containing the scenario folder, reviewed article and catalogue changes. Inspect its CI results and resolve failures. When ready, mark the PR ready for review; maintainers decide whether to merge it.

7. What happens after submission​

CI validates your contribution and maintainers review it. After the scenario PR is merged and validation passes on the latest main, configured automation opens or updates a separate website PR. Maintainers review and merge that PR; its GitHub Pages workflow publishes entries with draft: false.

A scenario merge alone does not publish the website. After deployment succeeds, check the Collection entry (/collection/?scenario=my-range), article (/library/scenarios/my-range), specification download and supporting-file links, replacing my-range with your ID.

Maintainers can find integration setup, validation snapshot details and retry instructions in the website handoff documentation.

Troubleshooting​

ProblemWhat to check or do
library:new says the scenario existsChoose a new ID or edit the existing folder. Imports never overwrite it.
Multiple .cradle files foundName the main specification scenario.cradle in the source folder before importing; review links if you rename it.
AI article generation failsCheck .env, the server URL, model and API access. Copied files and the current article remain available; see Regenerate an article.
library:describe --force removed edits--force replaces the article. Restore edits from your saved copy or Git history.
cxc not foundInstall CradleXC and check PATH, or state that local validation was not run and inspect PR validation results.
npm run check reports a stale catalogueRun npm run catalog:update, then rerun npm run check.
A supporting file is missingCompare against the import selection rules; add required files manually.
The scenario does not appear on the websiteCheck draft: false, source validation, and website PR/build/deployment status.

See the scenario-lib README for the complete tooling and validation reference.

Optional customization​

Add a thumbnail​

Set thumbnail to a local PNG, JPEG, WebP, GIF, SVG or AVIF inside the scenario folder and provide descriptive thumbnailAlt text:

thumbnail: ./images/topology.png
thumbnailAlt: Network topology for My Range

Website handoff preserves these fields and copies the selected image (up to 5 MiB), including images in subfolders. Other image embeds and supporting-file links point to the source commit in scenario-lib.

The AI generator receives image paths, not image contents. If it does not select a thumbnail, generation picks a local image automatically when available, preferring preview/thumbnail/cover/topology/diagram filenames. Review the chosen image and its alt text yourself.

Choose built-in artwork​

Without a thumbnail, the website uses built-in artwork. The optional artwork field accepts auto, network, enterprise or monitoring. auto uses light blue artwork for one network and dark blue artwork for multiple networks.

Advanced and reference information​

LLM configuration details​

  • SERVER is the API base URL. Include /v1 when your server requires it; generation calls POST /chat/completions relative to that base.
  • If REMOTE_LLM_MODEL is omitted, the generator selects the first model returned by GET /models.
  • REMOTE_LLM_API_KEY may be empty only when the server allows unauthenticated access.
  • Shell environment variables take precedence over .env.
  • Image and binary contents are not sent. Hidden files and TOML files are excluded.
  • The default input budget is 100000 characters. Set LLM_MAX_INPUT_CHARS to an integer from 5000 to 1000000 to adjust it. Review the command's omitted/truncated-file report and fill any resulting gaps in the article.

What the importer copies​

The importer selects top-level .cradle files, README/article files, images and supported shell, PowerShell, batch, Python and JavaScript scripts. It also copies these folders recursively, including binary supporting files:

  • config/, configs/, configuration/, configurations/.
  • heuristic/, heuristics/, artifact/, artifacts/.
  • script/, scripts/, img/, imgs/, image/, images/.

TOML files, .git, node_modules and __pycache__ are skipped. Other top-level files and folders, such as objects/, must be added manually when needed. Selected symbolic links are rejected; replace them with actual files or folders. Copying files does not install their dependencies on a backend.

Advanced import behavior​

The source must contain scenario.cradle or exactly one top-level .cradle file. When multiple specifications exist, scenario.cradle selects the main one. Import preserves filenames and authored article links. Only website export normalizes the selected main specification to scenario.cradle and adapts article links for the website copy.

For a named main specification, entrypoint: MyRange.cradle can be supplied in the article's front matter or colocated README.md. Without an explicit entrypoint, the website uses scenario.cradle or the only top-level .cradle file. Download links in the source article should point to the actual file. See the native README reference for existing scenarios that use README metadata instead of an article.

To start from an empty template instead of importing a folder, run this in PowerShell, Bash or Zsh:

npm run library:new -- scenario my-range

Replace the comment-only scenario.cradle stub with a completed specification and add supporting files before validation or article generation.

Regenerate an article​

Use library:describe for an existing scenario. Without --force, it reports an error rather than replacing an existing article.

:::warning Save your edits first --force replaces the current article. Commit or save manual edits before running this command. :::

npm run library:describe -- my-range --force

Failed generation keeps copied source files and the current article intact. Invalid formatting or local links receive one correction attempt before generation fails. Review a regenerated article and rerun the validation steps before submitting it.