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:
- Import an existing CRADLE scenario and its supporting files.
- Optionally use AI to draft its Collection article.
- Review and validate the contribution.
- Open a draft pull request ready for review.
- 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
| Approach | What you do |
|---|---|
| AI-assisted | Use an OpenAI-compatible server to draft index.md, then verify and edit it. Follow step 2. |
| Manual | Import 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:
CI, maintainers and website automation handle review and publication:
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
| Field | Purpose |
|---|---|
title | Scenario name shown on the website. |
description | Short Collection summary. |
source | Original author, organisation or source. |
category | Main scenario category. |
tags | Search/filter terms; use a non-empty list. |
requirements | Important runtime and dependency requirements. |
draft | true 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)

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
drafthas 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.cradleor the named main specification is included and complete. -
index.mdhas 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.jsonis updated. -
npm run checkandnpm run library:catalogpass. - Local CXC and dependency validation passes, or the PR explains that it was not run and why.
- The article's
draftfield 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
| Problem | What to check or do |
|---|---|
library:new says the scenario exists | Choose a new ID or edit the existing folder. Imports never overwrite it. |
Multiple .cradle files found | Name the main specification scenario.cradle in the source folder before importing; review links if you rename it. |
| AI article generation fails | Check .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 found | Install CradleXC and check PATH, or state that local validation was not run and inspect PR validation results. |
npm run check reports a stale catalogue | Run npm run catalog:update, then rerun npm run check. |
| A supporting file is missing | Compare against the import selection rules; add required files manually. |
| The scenario does not appear on the website | Check 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
SERVERis the API base URL. Include/v1when your server requires it; generation callsPOST /chat/completionsrelative to that base.- If
REMOTE_LLM_MODELis omitted, the generator selects the first model returned byGET /models. REMOTE_LLM_API_KEYmay 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_CHARSto 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.