Skip to main content
Creating a ThreatLab exercise takes you from filling in scenario metadata all the way through uploading log archives, defining ordered investigation steps, and publishing the exercise for analysts to start. This guide walks through each stage of that process so you can build polished, realistic training scenarios from scratch.
You need the manage_exercises capability to create and edit exercises. The Create exercise action is gated to that capability — if it does not appear on the exercises list view, ask your administrator to grant it.

​
Draft autosave

The create and edit forms autosave every change to the server as a draft. You do not need to click a save button while you work — once a title is set, ThreatLab debounces edits and persists exercise metadata, steps, and section shells in the background. What the autosave indicator means, shown in the command bar at the top of the form:
StatusMeaning
waiting for titleA title has not been entered yet. Autosave starts as soon as you type one.
unsaved changesThe form is dirty and a save is queued.
savingA save is in flight to the server.
saved HH:MMThe latest changes are persisted. The timestamp is the server-confirmed save time.
paused while publish is selectedYou have toggled Active on. Autosave pauses so it cannot overwrite a strict publish.
Error messageThe last autosave failed. The form keeps your edits and retries on the next change.
Draft autosave intentionally skips the heavy parts of the publish pipeline:
  • Archive uploads are not processed — pasted text, file uploads, and direct files stay client-side until you publish.
  • Live TCP intake is not finalized for the draft.
  • SIEM indexes are not provisioned for new sections.
Draft saves only require a title. Description, steps, archives, and section indexes can all be empty or incomplete and the draft will still persist. This lets you start an exercise, leave the page, and come back without losing your in-progress work.
Autosave is only available while the exercise is a draft. Once you toggle Active on, autosave pauses and any further changes must go through the strict publish path described below.

​
Creating an exercise

1

Open the creation form

Navigate to Exercises > Create exercise in the left sidebar. The creation form opens with all required fields shown at the top.
2

Fill in exercise metadata

Complete the following fields before moving on to archives:
  • Title — a clear, descriptive name for the scenario
  • Description — what the analyst will investigate and learn
  • Difficulty — choose Easy, Medium, Hard, or Expert
  • Estimated duration — enter a time in minutes to help analysts plan their session
  • Points — the score awarded on completion
  • MITRE ATT&CK tags — add one or more technique IDs (e.g. T1059, T1059.001) to signal which adversary techniques appear in the logs
3

Add archive sections

Each archive section holds the log data analysts will investigate. ThreatLab supports four source types:
Upload a .zip, .tar.gz, or .tgz archive containing your log files. The maximum upload size is 256 MB per archive.
ThreatLab inspects pasted and uploaded raw log rows to detect the source format. Each row is tagged with a per-row badge:
  • LEEF — the row matches a recognised LEEF header.
  • ECS — the row is valid JSON or NDJSON with an @timestamp field and at least one ECS-like field (event.*, host.*, source.*, destination.*, log.*, process.*, user.*, or a non-empty message).
  • syslog/unknown — the row does not match either detector and will require SyslogCanon conversion before publish.
The section also shows a source-aware notice listing which formats your enabled SIEM destinations require, and flags rows that need SyslogCanon to satisfy those requirements.
4

Convert to LEEF (optional)

If your raw logs are not already in LEEF or ECS format, enable Convert to LEEF on an archive section. This option requires a running SyslogCanon sidecar. When enabled, ThreatLab routes every row through SyslogCanon and produces a LEEF archive plus, where the destination needs it, a matching ECS archive in the same publish.Convert to LEEF is also the path you take when a row is detected as ECS but a LEEF-only destination (for example splunk_hec or syslog_tcp) is enabled — SyslogCanon generates the LEEF side so the destination has an archive it can ship.
5

Define investigation steps

Add one or more ordered steps that guide analysts through the investigation. Each step requires:
  • Title — a short label for this stage of the investigation
  • Investigation instructions — the prompt shown to the analyst
  • Expected artifact value(s) — the answer(s) ThreatLab checks submissions against
Steps appear in order on the analyst’s exercise workspace. You can drag to reorder them before publishing.
6

Configure per-section release rules (optional)

By default, every archive section ships to the SIEM the moment the analyst starts the exercise. If you want to release sections in stages — for example, holding later evidence until the analyst has solved earlier steps — open the Release block on each section and configure the rules described in Staged section release.
7

Publish the exercise

When your metadata, archives, and steps are complete, toggle the exercise to Active. On save, ThreatLab runs a release deadlock check and a QRadar log-source preflight before the exercise goes live — see Publish-time deadlock check and QRadar log-source preflight for what each validates and how to handle warnings.Active exercises are visible in the exercise catalogue and can be started by analysts immediately. Leave the exercise inactive while it is still a draft.

​
Draft vs publish validation

ThreatLab applies two different validation levels depending on whether you are autosaving a draft or toggling Active on.
Only the bare minimum needed to persist the working state:
  • Title is required and capped at 120 characters.
  • Description, when present, is capped at 2,000 characters.
  • Difficulty must be one of the supported tiers.
  • Duration must be a positive integer; points must be a non-negative integer.
  • MITRE ATT&CK tags, when present, must match the Tnnnn or Tnnnn.nnn pattern.
  • Steps and sections can be empty, partial, or in any order. Archive bytes are not inspected.
If publish validation fails, ThreatLab surfaces the offending field inline. Clicking the error in the cmdbar or the issue list scrolls to and focuses the exact input — the section title, the step description, the archive picker — so you can fix it without hunting through the form.

​
Staged section release

Every archive section has an optional set of release rules that control when its log archive ships to the SIEM during a live attempt. Sections with no rules configured ship at exercise start, exactly like before — staged release is purely opt-in. Configure each section’s release block with these controls:
ControlPurpose
Release conditionHow the delay and artifact gates combine. One of delay_only, artifacts_only, delay_and_artifacts, delay_or_artifacts.
Delay minutesMinutes to wait after the attempt starts before this section becomes eligible to ship. Must be between 0 and the exercise duration.
Artifact gatesOne or more expected artifacts (from any investigation step) that must be submitted before this section becomes eligible.
Artifact gate modeWhen two or more gates are linked, choose all linked (every gate must be satisfied) or any linked (one gate is enough).

​
Release conditions

The release condition decides how the delay and the artifact gates combine for a single section:
  • delay_only — ships once the delay elapses. Linked artifacts are ignored.
  • artifacts_only — ships once the artifact gate is satisfied. The delay is ignored.
  • delay_and_artifacts — ships only when both the delay has elapsed and the artifact gate is satisfied. This is the default for new sections.
  • delay_or_artifacts — ships as soon as either the delay has elapsed or the artifact gate is satisfied. Useful when the gate should be a shortcut with a guaranteed fallback time.
A section with no delay and no gates is always immediately releasable, regardless of the chosen condition.
Link a section’s gate to an artifact from an earlier step (or from a different section) so the analyst has a concrete reason to keep investigating before the next batch of evidence appears in their SIEM.

​
Release timeline summary

The editor shows a live release timeline panel above the section list summarising what each section will do at attempt start — immediate, delayed, gated, delayed-gated, or blocked-risk. Use it as a quick sanity check before publishing.

​
QRadar log-source preflight

If any of your enabled syslog_tcp destinations have QRadar API management with Provision log source turned on, publishing an exercise now runs a QRadar preflight before the exercise is marked Active. For each section in the exercise, ThreatLab ensures a matching QRadar log source exists in QRadar so that section’s logs have somewhere to land the moment an analyst starts the exercise. The preflight blocks activation in two cases:
  • Provisioning failed. QRadar returned an error while ThreatLab tried to create or update a section log source. The destination, section, and underlying error message are surfaced in the form’s warning list.
  • QRadar requires deploy. The log source was created or updated successfully but QRadar still needs an administrator to run Deploy Changes in the QRadar console before it will accept events. Deploy in QRadar, then publish the exercise again.
When the preflight blocks activation, the rest of your save still goes through — metadata, steps, sections, archives, and SIEM index provisioning all persist — but the exercise stays in Draft state. The form flips the Active toggle back off and shows the QRadar warnings inline so you know what to fix. Save again once you have addressed each warning to publish for real.
The preflight only runs when at least one enabled syslog_tcp destination has Provision log source turned on. Deployments without QRadar API management are unaffected and publish exactly as before.

​
Publish-time deadlock check

When you save an exercise as Active, ThreatLab analyses the section release plan and refuses to publish if it would deadlock the analyst. The analyzer raises a blocking issue in two situations:
  • No initial releasable section — every section is delayed or gated, so the analyst would start the exercise with no logs in their SIEM and no way to make progress.
  • Likely self-gated section — a section is gated by an artifact that almost certainly lives in that same section’s logs, so the gate can never be satisfied without the logs already being there.
When the analyzer blocks publish, the release timeline panel shows the specific issue and an override checkbox. Tick the override only when the deadlock is intentional — for example, you have an out-of-band trigger that will satisfy the gate, or you explicitly want analysts to wait before any logs arrive. The override is persisted with the exercise so reviewers can see it was a conscious choice.

​
Archive validation rules

ThreatLab validates every archive before storing it. Your archives must satisfy all of the following constraints:
  • Accepted container formats: .zip, .tar.gz, .tgz
  • Files inside the archive must have a .txt or .log extension
  • Nested archives are not permitted
  • Path traversal and absolute paths are rejected
  • Per-file uncompressed size limit: 10 MB
  • Total uncompressed size limit: 1 GB
  • Maximum number of entries per archive: 10,000
  • Maximum compression ratio: 200× (zip-bomb defence)

​
Format-aware validation

In addition to the structural checks above, ThreatLab performs format-aware validation on the contents of every archive section:
  • Each row is classified as LEEF, ECS, or unknown using the same detectors the authoring UI shows.
  • If every row in a section is detected as LEEF, the section can be stored as a LEEF archive without SyslogCanon.
  • If any row is detected as ECS or unknown, ThreatLab requires SyslogCanon to dual-parse the section into LEEF and ECS — or for you to enable Convert to LEEF so SyslogCanon runs explicitly. Unknown raw logs are no longer silently labelled as LEEF; the section fails closed with a specific error telling you what to do.
  • The required formats are derived from your enabled SIEM destinations (driver + payload format) and from the SIEM the exercise is assigned to. Only formats actually needed by an enabled destination are demanded.
Mixed sections that contain a blend of LEEF, ECS, and unknown rows cannot be stored as a single raw archive. Either upload uniformly-LEEF rows, or enable Convert to LEEF so SyslogCanon canonicalises every row before storage.

​
Artifact matching

When an analyst submits a step answer, ThreatLab trims leading and trailing whitespace from both the submission and the expected value, then compares them case-insensitively. The submission must be an exact match after that normalisation — partial matches are not accepted.

​
Multi-format archives

You can attach both a LEEF archive and an ECS archive to the same exercise section. When an analyst starts the exercise, ThreatLab inspects the destination SIEM’s payload format setting and ships the matching archive:
  • leef — used for Splunk, QRadar, and syslog TCP destinations
  • ecs — used for Elasticsearch destinations configured with the ECS path
If archives exist for only part of a requested payload format set, ThreatLab refuses to ship a partial section and returns an error. Make sure every section has a complete archive set for each payload format you intend to support.

​
Publishing as Active

When you toggle the exercise to Active, ThreatLab runs a publish-time readiness check before flipping the flag. This check:
  1. Reads every enabled SIEM destination (driver, payload format, enabled flag) and resolves which archive formats — leef, ecs, or both — are required.
  2. Adds the assigned SIEM (if set) to that set, falling back to the legacy destination hint when the exercise references a SIEM with no matching destination row.
  3. For each required format, verifies every section carries a complete archive in that format.
  4. If SyslogCanon is needed (because rows are ECS, unknown, or Convert to LEEF is enabled) but unavailable or unable to dual-parse, the publish is blocked.
Errors raised by the readiness check name the affected SIEM and the format that is missing, so you know exactly which destination and which side (LEEF or ECS) to fix. For example, attempting to publish with an Elastic destination enabled but no ECS archive returns an error citing that destination by name.
Editing a published exercise takes effect immediately. Consider setting the exercise to Inactive before making major structural changes — such as replacing archives or reordering steps — so analysts do not encounter a partially updated scenario mid-session.
MITRE tags help analysts understand which adversary techniques to look for before they open their SIEM. Use specific sub-technique IDs like T1059.001 where possible — they are more actionable than top-level technique IDs alone.