How To Use TTX Gym

Running a cyber security exercise is an immersive and effective way to evaluate and practise the skills and decision-making mechanisms you need to respond to cyber incidents. TTX Gym helps by providing a custom-designed tool to produce consistent, effective, and insightful exercising experiences.

Planning Your Exercise

TTX Gym is best suited for use in interactive, facilitator-led training. The tool can be used in a standalone manner, but it is designed to present a participant view to those interacting with the scenario, as well as a separate facilitator view for the organiser to control exercise progression and ensure appropriate notes and outcomes are recorded.

Exercising is one of the most cost-effective ways an organisation can test its ability to respond to cyber incidents. By running an exercise using TTX Gym, you can establish how effective your current defence and response mechanisms are, improve colleagues' internal relationships and skills, and identify areas for further improvement.

Using the Exercise Library

Choosing an existing exercise from the Exercise Library is the easiest way for beginners to get started. The Library is populated with a wide range of scenarios covering a variety of themes and situations, and can be searched and filtered using the controls in the sidebar.

To find out more about an exercise, click on the thumbnail and a description will appear.

The duration slider in the sidebar sets an upper bound rather than an exact match: drag it to 45 minutes and you see everything that would fit in 45 minutes, not only the exercises written to exactly that length. Most facilitators are working to the slot they have been given rather than to a specific number. The library is grouped into sections — the audience an exercise is written for, or the series it belongs to. The technical exercises are progressions rather than a loose pile: the Malware set works from a first suspicious file through to forensic recovery, and the Supply Chain set through compromise arriving via software, hardware, identity and service. The number on each card is its place in that order, though any of them stands on its own.

The pills across the top of the gallery are those same sections — pick one to see it on its own. Beside them, the cards or list toggle switches between browsing and comparing: cards when you are looking for something, a list when you are weighing several against each other.

From here you have three choices. Run Exercise opens TTX Gym with the scenario loaded and ready to go. Customise opens it in the Exercise Builder, so you can tailor it to your own organisation — swapping in the names of your systems, teams and suppliers — before you run it. Download saves the .ttxf file to edit or share however you like (see Creating and Modifying Scenarios below).

Using the TTX Gym Tool

TTX Gym has two views: the primary facilitator window and the participant window. The facilitator window shows the scenario laid out in stages — each stage can be expanded to see the content, facilitator prompts, and questions.

To begin the exercise, use the controls at the bottom to navigate through each stage. The active stage will be coloured blue, and once all stage questions are answered the stage will turn green to indicate completion. Stages can be freely navigated in any order; the completion of stages or the answering of questions is at the discretion of the facilitator. Note that responses and notes cannot be altered unless the stage is active.

At the completion of the exercise, or when desired by the facilitator, an output report can be generated to record progress.

The Participant Window

The participant window allows people attending the exercise to experience a specific, tailored view that relays content stage by stage. It can be spawned by the facilitator as a separate tab and presented on a second screen or over video conferencing. This will automatically update as the facilitator moves through the stages. At the completion of the exercise, an exercise summary can be shown via the participant window.

Creating and Modifying Scenarios

The Exercise Builder is the way to write an exercise. It is a normal editor: you type into the stage as it will look, and everything else — the picture gallery, the timing, the questions, the file itself — is handled for you. You never need to see the file format to build a complete exercise.

Open it empty and it offers you a shape to start from — the detection-to-lessons arc most of the library follows, a supplier incident, or a short decision exercise — with every stage named and waiting. Or open an existing exercise from the library with Customise, drop a .ttxf file anywhere on the page, or use Import.

What the builder gives you

The running order, down the left. The opening, every stage, and the debrief, in the order the room will meet them. Click to move between them; drag to reorder. Each row shows its planned time as a bar, so you can see at a glance where the exercise is lopsided — and the builder will tell you when a stage's clock looks wrong for the amount in it.

Two halves to every stage. On screen is what participants see; Your notes is what only you see. Moving a question from one to the other is how you make it private — there is no flag to remember, and nothing that reaches the room by accident.

You edit what the room will read. Bold, italics, lists, quotes and inline code are buttons. Pictures, news headlines and log extracts go in as themselves: drag a picture's corner to resize it, type straight into a news headline or an artefact's label, and use the remove button on any of them to take it out. Source on any field shows the underlying text if you want it — but you can ignore it entirely.

Pictures are already there. The Image button opens a gallery that ships with TTX Gym. Stock photos are the places an exercise gets set — an A&E entrance, a data centre aisle, a contact centre, a council office, a motorway, a comms cabinet, a police car on a residential street. Screenshots, documents and diagrams are the artefacts no stock library sells: a ransom note, a SIEM console, a terminal session, a fraudulent invoice, a regulator's letter, a network diagram. Those are drawn as SVG, so they stay sharp on a projector and the words inside them are editable text if you want your own system names in them. Or paste any URL.

The participant view, live. Participant view floats the real participant screen over your work — the same page the room gets, not an impression of it — and it follows every change as you make it. Drag it anywhere, resize it, or collapse it out of the way.

It tells you what is wrong. The status beside the title counts anything that needs attention and lists it; each entry names the stage it is in and takes you there.

Two ways out. Preview in TTX Gym opens the exercise in the player so you can walk it through. Download .ttxf saves the file to keep, share or put under version control. Your work is saved in the browser as you go, so closing the tab does not lose it.

The file underneath

Everything the builder makes is a TTXF file: plain text, Markdown-flavoured, one file per exercise. It is worth knowing it exists even if you never edit one by hand, because it is what you send someone, commit to a repository, or diff to see what changed between two versions of an exercise.

The format is set out in full at the end of this page, as a reference. Read it if you want to write or edit exercises in a text editor, understand what the builder is producing, or use something the builder does not yet expose. If you are happy in the builder, you never need to go there at all — carry on to Running the Room.

Running the Room

Everything below is in the facilitator sidebar, and none of it changes the scenario file — it is all about driving the session in front of you.

Moving through stages

As well as the Next and Prev buttons, the exercise responds to Page Down / Page Up and the arrow keys, so a presenter remote works without any setup. Keys are ignored while you are typing in notes or actions.

You can also go straight to any stage by clicking its number in the row of stage markers, without stepping through the ones in between. That is useful for skipping a stage that is not landing, or returning to one the room wants to revisit — and it is what makes branching exercises possible. A scenario can offer the room a choice, put the destination for each option in the facilitator prompts where only you can see it, and send everyone wherever the vote goes. Night Shift in the Just for Fun section of the library is built this way: twenty-three stages, four endings, and a different route each time you run it.

The participant view mirror

A small live copy of the participant screen sits in the bottom-right of the facilitator window, so you can see exactly what the room sees without switching windows. Collapse it with the – button if it is in the way.

It stays above everything else in the facilitator window, including the paused overlay and the summary — while the exercise is paused or the summary is up, what the room is looking at is exactly the thing you still want to see.

It is a genuine second view of the same thing, not a snapshot. The stage, the response tallies, the theme, the text size and the scroll position all follow, in both directions — scroll the mirror and the room's screen scrolls with it, which is the easiest way to walk a room down a long inject without leaving your own window.

Drag its header to move it, and the corner at its top-left to resize it — the whole participant screen scales with it, so you can push it up to something you can properly read while working through a long inject, then drop it back down. Double-click either the header or the corner to put that back to where it started. Both the size and the position are remembered, and the corner takes focus if arrow keys suit you better than a drag.

The preview takes its shape from the screen the room is actually looking at. When you open a participant window it reports its size, and the mirror renders at exactly those dimensions and scales the whole thing down — so a 4:3 projector previews as 4:3, a 4K television previews at 4K proportions, and an ultrawide previews wide. Because it is scaled rather than re-laid-out, the line breaks and the amount of content above the fold are the same as the room sees. The pixel size is shown in the header so you know what you are previewing, and it updates if that window is resized or made fullscreen.

The mirror's own header carries the controls worth having at full size: A− and A+ set the text size on the participant screen, ◐ switches it between the screen and projector themes, and ⤢ returns the panel itself to its default size and place if you have moved it somewhere awkward. The frame itself is live, so you can scroll and click inside it too — though at quarter scale the header buttons are the easier target.

Blanking the screen

Blank Screen — or pressing B — covers the participant display for a break or a side conversation, without losing your place. Press it again to bring the content back.

Running it offline

Download the tool as a single HTML file and open it from your own machine — useful if the exercise is being run somewhere without reliable network, or if your organisation would rather it never touched the internet at all. Everything works: load a scenario, drive the participant window, capture notes and actions, export the report.

Two caveats. Scenario cover images and any embedded pictures still come from the network, so scenarios that use them will show the text without the images. And some browsers refuse to let a page opened from a file:// path save anything locally, which turns off autosave — TTX Gym will tell you if that happens, and Save Session still writes a file you can keep.

The participant window works the same way offline as it does online. Open it with Participant Window and leave it open; if you close it and open a new one, it will pick up whatever stage you are on by itself.

The facilitator pack

Under More, Facilitator Pack lays the whole scenario out as a single document — every stage in order with its planned duration, content, discussion points, facilitator prompts and questions, with correct quiz answers marked. It is meant for the hour before the exercise: read it through, or print it and take it into the room. Prompts are labelled as not shown to participants, so there is no risk of putting the wrong page on the projector.

Ad-hoc injects

Exercises rarely go exactly to plan. Send Inject pushes a one-off line of text to the participant screen — "the press have just called", "your primary site has lost power" — without editing the scenario. Moving to the next stage clears it.

Light and dark

The two windows are themed independently, because a laptop in a dim room and a projector in a lit one want opposite things.

The participant window opens dark; the half-moon icon in its bottom-right switches to a light, high-contrast theme for projectors. The facilitator window has its own Light Theme switch under More in the sidebar — useful if you are sharing your own screen, or simply prefer it. Both remember your choice.

Recording What Happened

Responses are a tally, not a single answer

Each answer option is a button, and every click records one response. Click once and it behaves like a simple choice; take a show of hands and click an option once per hand, and the exercise records the spread. The small − on an option removes a response if you over-count.

This matters because the interesting signal in a tabletop is usually disagreement. If half the room is confident and half is not, that gap is the finding — and a single answer would have averaged it away before anyone saw it.

The count appears on the participant screen as you record it, so the room watches the split form on the answer options rather than waiting for the summary. The option with the most responses is highlighted, and options with none fade back. Taking a response off with the small −, or clearing the question, updates the room straight away too — a miscount is not something you have to live with.

Where you are

The participant screen shows the current stage and a marker for each stage of the exercise, so the room can see how far through they are without asking.

Actions

Every stage has an Actions panel for what needs to happen afterwards, with an owner and a due date. These are collected into a table at the top of the exported report, which is usually the part of the report anyone actually acts on.

Session details

The intro card carries the date, facilitator, attendees, and the objectives and scope of the exercise. Filling these in turns the report from a printout into a record of what was tested, by whom, and what was deliberately left out.

The summary

Present Summary puts the same summary on your screen and on the participant screen — the headline figures, the questions the room was least confident about, the actions with their owners, and each stage with its response distributions. What you are reading is what they are reading.

Your facilitator notes are deliberately not on either summary screen. They are your working record of the discussion, and they go into the exported report rather than onto a projector. Actions and their owners are shown, since agreeing who does what is the point of the debrief.

Confidence and quiz accuracy are reported separately

Rating questions measure what the room believes about itself. Quiz questions measure whether someone knew a fact. These are different things, so the summary reports them as two numbers and never averages them together. The report leads with the questions the room was least confident about, because that is the list worth taking away.

Treat the confidence figure as a map of where to look, not as a grade. A low score on a well-run exercise is a good outcome — it means people were honest.

Saving and resuming a session

Save Session writes a .ttxs file containing everything: the scenario itself, every response, your notes, the actions and the timings. Because the scenario travels inside it, Open Session will resume the exercise on any machine — useful for handing over to a co-facilitator, or for finishing a session that ran out of time.

Compare With Previous Run loads an older .ttxs alongside the current one and shows the movement in confidence since then. Running the same scenario a year later and seeing where the numbers moved is the point of exercising in the first place.

The TTXF File Structure and Syntax

Stages, questions, variables and facilitator prompts, with Markdown-enhanced content. This is the format the Exercise Builder reads and writes, so anything described here can be done either way.

The configuration file is structured into stages, which contain information content along with optional questions, facilitator prompts, and discussion points. Each 'content' type has specific indicators to denote its purpose.

Each scenario file should begin with a title and summary variable. An optional image variable can also be provided — if present, it will appear as a thumbnail in the facilitator sidebar and as a blurred background on the participant screen:

! title: Example Scenario Title
! image: https://example.com/cover.jpg
! summary
Example scenario summary.
This can spread across multiple lines or paragraphs.

1. Stages @ sigil

Stages define major sections in your file. Use @ followed by the stage name. Everything after this line belongs to this stage until the next stage declaration. Each stage should always have a content variable that defines the content displayed to participants on the presenter view.

@ Initial Incident

2. Key-Value Variables ! sigil

Define variables using ! followed by a key and value separated by a colon. For multi-line values, omit the colon — everything on subsequent lines until the next directive becomes the value. Blank lines within a multi-line value are preserved and rendered as paragraph breaks.

! author: Jane Doe
! content
This is the first paragraph of a description.

A blank line above creates a new paragraph.
This line continues the same paragraph.

The following global variables are recognised at the top of the file (before any @ stage declarations):

Inside a stage, one further key is recognised:

3. Questions ? sigil

Use ? to define an assessment question for the stage. Answers are listed under it, each starting with +. There can be multiple questions per stage — each will contribute towards the indicative score for the stage. Scoring assumes an order of preference increasing from first (0%) to last (100%).

? What core systems are included in vulnerability assessments?
+ None
+ Some centrally managed systems
+ Most centrally managed systems
+ All centrally managed systems

By default all questions are shown on both the facilitator view and the participant screen. To define a question that is only visible to the facilitator — for example an internal scoring note or a question you don't want to prompt participants with — use ?- instead of ?. The question will still be answered and scored normally, but will not appear on the participant screen.

?- How would you rate the team's overall response readiness?
+ Poor
+ Developing
+ Proficient
+ Exemplary

'Quiz' style questions are also supported, where only one option is correct and the rest are false. For these question types, answers are scored as 100% for a correct answer and 0% for an incorrect one. To use this type, define a question as normal but denote the correct answer using ++ instead of +.

4. Facilitator Prompts # prompts

Use # prompts to declare facilitator prompts. These will not appear on the participant view, but will be shown below the stage content in the facilitator view. Each prompt starts with +.

# prompts
+ Ask the team about their incident response plan.
+ Discuss the potential risks of delaying action.
+ Encourage brainstorming on containment strategies.

5. Discussion Points # discussion

Use # discussion to declare discussion points. These will appear on the participant view, to encourage discussion and enable fuller answers to stage questions. Each prompt starts with +.

# discussion
+ Do you regularly update and test your incident response plan?
+ Discuss the potential risks of delaying action.
+ Do you have a designated board member with responsibility for security incidents?

Markdown Syntax

Enhance your stage content using Markdown. The following features are supported within multi-line content fields:

Checking Your File

Both the Exercise Builder and the TTX Gym player check a scenario as they read it, and report anything that looks wrong rather than failing silently. The Builder counts it beside the title as you type — click that to see the list, and click an entry to be taken to the stage it is in. The player shows it above the stage list when a file is loaded. The same checks run either way, so a file written by hand and a file built in the Builder are held to the same standard.

Things they will tell you about:

• An unrecognised ! key — a mistyped ! conten would otherwise leave that stage blank on screen with no warning at all.
• A stage with no ! content, so participants would see an empty screen.
• A question with fewer than two answers, which cannot be scored.
• A question where two answers share the same text and one of them is marked correct, so the right option is ambiguous.
• More than one answer marked with ++.
• A + item or # list that has no question or stage above it.
• A line that is not part of any directive and is being ignored.
• A multi-line value long enough to be cut short.

Full Example

Here is a complete configuration file demonstrating all features:

! title: Security Breach Response Plan
! author: Jane Doe
! image: https://example.com/cover-photo.jpg
! summary
This scenario depicts an unusual login to a critical system.
Participants will be asked to consider their organisation's response procedures.

@ Stage 1: Identification
! duration: 15 mins
! content
An unusual login attempt was detected on a critical system at 02:14.

A blank line above creates a new paragraph when rendered.
%(https://example.com/diagram.png | 80%)

The incident response process should be invoked immediately.

# prompts
+ Ask the team to identify possible attack vectors.
+ Discuss recent security training and preparedness.
+ Explore options for immediate response.

# discussion
+ What does your incident response plan say about out-of-hours alerts?
+ Who holds the authority to invoke the response process?

? What action should be taken first?
+ Notify the security team
+ Investigate the login origin
+ Block the IP address

?- How would you rate the team's initial response readiness?
+ Poor
+ Developing
+ Proficient
+ Exemplary

@ Stage 2: Containment
! content
Contain the breach by isolating affected systems.

# prompts
+ Review logs for additional suspicious activity.
+ Coordinate with IT to isolate compromised systems.
+ Plan a communication strategy for stakeholders.

? How confident are you in your response procedures?
+ Not at all
+ Somewhat
+ Mostly
+ Completely

? Which system was used to detect the initial alert?
+ No detection system in place
+ Manual log review
++ SIEM / automated monitoring
+ Third-party managed detection

Use this guide to create structured, readable, and actionable scenario files.