Chronicle¶
Draft
Chronicle has a draft spec and a running API. Nothing in the spec is settled until the architecture team agrees on it; the schema design lists the decisions still open. The concept brief is src/chronicle/chronicle.html; open it in a browser or print it.
Chronicle is one living record of an event, from the first idea to the last lesson. The event can be training, an exercise or an experiment, run at a table or on a live range.
It starts as the scenario: what the world looks like, and what the event must achieve. Around it, apps publish and subscribe. Each one subscribes to the parts it needs and publishes what it built, did and saw. When the event ends, the Chronicle is the event: complete, attributable, and ready to seed the next one.
At a Glance¶
| What it is | One JSON record per event, with a published, versioned schema |
| How apps connect | Publish and subscribe around the record. No app calls another. |
| It starts as | The scenario: the world, and what the event must achieve |
| It ends as | The event itself: built, run and reviewed |
| Models | Local or frontier. Works on a closed range. |
Four Principles¶
- One record, many authors. Each app owns its part. It reads the rest, but writes only what it did.
- Publish and subscribe. Apps subscribe to the parts they need and publish what they add. A new app is a new subscriber, not a new integration.
- Nothing is overwritten. Every change keeps who made it, when and why, so the record is also the event's history.
- The right eyes only. Ground truth stays with exercise control. Participants see only what they should, everywhere.
The Record¶
A Chronicle has five parts, filled in the order the event fills them:
| Part | What it holds | Written by |
|---|---|---|
| World | Sides, organizations, networks, devices, services, personas and pools, vulnerabilities, facts | Scenario Builder |
| Intent | Objectives, teaching points, rules of play, vocabulary, summaries, the planned events | Scenario Builder |
| As Built | Deployments, what each planned item became, generated personas and content | GraySpace, GHOSTS, Pandora |
| As Run | Milestones, cyber and influence activity, injects delivered, participant actions, observations | GHOSTS, the exercise apps, exercise control |
| Lessons | Assessments against the objectives, lessons for the next event | After-action review |
Apps don't edit the record. They publish entries: each one adds, revises or retracts one item, and records who made the change, when and why. The parts are rebuilt from the entries, so the record is also its own history. A revise names the version it replaces, so two apps can't silently overwrite each other.
Every item is marked participant, excon (exercise control) or designer. An item nobody marked stays with exercise control, so a forgotten marking can't leak the ground truth. An item can also name the personas, pools or organizations that know it: a simulated bank clerk knows their own bank, but not the twist.
Built on the Standards¶
The spec borrows its names from SISO's standards, so a Chronicle can be exchanged with simulations that already use them:
- Cyber objects and events use the names of the Cyber Data Exchange Model (SISO-STD-025-2023): a host is a
Device, an attack is aPhishingAttack. Enumerated values are written as SISO-REF-010 writes them, such asMicrosoftWindows. ATT&CK ids are supporting detail. - Sides follow MSDL's and C2SIM's force sides.
- Personas meet the needs the GHOSTS team set out for the Cyber DEM: an account for each service, a pool form, where a persona came from, and no credentials on the persona.
- What the standards don't model is Ranger's own: vulnerabilities, injects for people, objectives, visibility, and who said what.
The Spec¶
The spec is the C# library Chronicle, in src/chronicle. Apps in other languages use its JSON Schemas, which are generated from it so the two can't drift:
| File | What |
|---|---|
schema/chronicle-record.v0.schema.json |
A whole record |
schema/chronicle-entry.v0.schema.json |
One entry, as apps publish it |
samples/harbor-ttx.chronicle.json |
A worked example: a fictional tabletop exercise through all four stages |
The API¶
The Chronicle API stores Chronicles and carries their entries. Locally it runs in Aspire as chronicle-api at http://localhost:5285, with Swagger at /swagger, and loads the sample exercise. See Local Development.
| Resource | Routes |
|---|---|
| Chronicles | GET /api/chronicles, POST /api/chronicles, GET /api/chronicles/{id}, GET /api/chronicles/{id}/findings, POST /api/chronicles/validate |
| Entries | GET /api/chronicles/{id}/entries, GET /api/chronicles/{id}/entries/{sequence}, POST /api/chronicles/{id}/entries |
| Subscription | GET /api/chronicles/{id}/entries/stream: server-sent events, the history first, a ready event, then each new entry, with a heartbeat every 15 seconds |
| Live | GET /api/chronicles/{id}/live: a WebSocket with the subscribers, activity, new entries and agents' words as they're written |
| Activity | POST /api/chronicles/{id}/activity (with an entry, it's notable and stored), GET /api/chronicles/{id}/activity |
| Subscribers | GET /api/chronicles/{id}/subscribers, PUT/DELETE /api/chronicles/{id}/subscribers/{subscriberId}, POST …/{subscriberId}/run |
| Context | GET /api/chronicles/{id}/context: a view as text a model can read, with what it withholds |
| Schema | GET /api/schema/record, GET /api/schema/entry |
Activity is the live feed, kept in memory (the last 1,000 per Chronicle). Only notable activity, the kind that carries an entry, becomes part of the record. Subscribers are stored with the Chronicle; one registered with an agent can be run, and its output is published back. The Chronicle UI shows all of it, live, on each event's Subscribers page.
Every read is an audience's view: ?audience=participant (the default), excon or designer, and ?viewers= for the personas or pools a simulated user speaks for. Entry reads and subscriptions also filter by parts, kinds and after.
No authentication yet
The API takes the audience a caller asks for on trust. Don't expose it beyond a development range.
Connecting an App¶
A .NET app connects with the C# library Chronicle.Client, in src/chronicle/Chronicle.Client. The library does the plumbing; the app keeps its own logic:
| The library does | The app does |
|---|---|
| Connects, reconnects, and resumes after the last entry | Decides what to subscribe to: which Chronicle, audience, viewers and parts |
| Reads entries into the spec's types | Decides what each entry means to it |
| Builds entries: ids, times, authors, what a revise replaces | Decides what to publish, and when |
| Retries what didn't get through, safely | Handles a conflict when someone else revised the item first |
| Keeps a subscriber's place across restarts, if asked | Makes handling an entry twice harmless (delivery is at least once) |
An app either writes one handler, which the library runs on every entry, or loops over a subscription itself:
builder.Services.AddChronicleClient(builder.Configuration);
builder.Services.AddChronicleSubscriber<NpcHandler>("office-staff", o =>
{
o.ChronicleId = "harbor-ttx";
o.Audience = Audience.Participant;
o.Viewers = ["office-staff"];
o.Parts = [Part.World, Part.AsRun];
});
public sealed class NpcHandler(ChronicleClient chronicle) : IChronicleHandler
{
public async Task HandleAsync(Entry entry, CancellationToken ct)
{
// The app's own logic. To publish back:
// await chronicle.AddAsync(entry.ChronicleId, Part.AsRun, new Observation { ... }, ct: ct);
}
}
Scenario Builder publishes through it. src/chronicle/examples/GhostsSubscriber is a working app shaped like GHOSTS: it subscribes as the simulated office staff, and when an inject reaches them, it reports what the NPCs did and records an observation. Apps in other languages use the API above and the JSON Schemas.
There are two kinds of subscriber. An app that does its own work, as GHOSTS does, connects with the library. A subscriber registered with an agent is run by the Chronicle itself, which publishes the model's output for it; that needs no code in any app.
Why It Matters for AI¶
A language model doesn't know your exercise. Give it the Chronicle and it stops guessing. Because the record is structured, each AI gets exactly the parts its job needs, not a pile of documents. That matters most on a closed range, where a smaller local model has room for less context.
| AI at work | Reads from the Chronicle | Never sees |
|---|---|---|
| Scenario agent (Scenario Builder) | The designer's sources and the scenario so far | Nothing held back: it works for the designer |
| Simulated users (GHOSTS) | Their persona and organization, their platforms, events as they happen | The ground truth and the plan |
| Content generation | The world, the information environment, the planned events | Designer-only notes |
| Exercise control assistant (next) | The intent, the ground truth, the escalation steps, what has happened | Nothing held back: it works for exercise control |
| After-action analyst (next) | Everything: intent, what was built, every inject, decision and action | Nothing held back: it reports to designers |
Where It Stands¶
- Today: Scenario Builder writes the world and intent. GraySpace builds a range from them. GHOSTS runs the simulated users. The Chronicle spec is drafted, and the Chronicle API stores Chronicles, takes entries and streams them to subscribers. Apps connect through the
Chronicle.Clientlibrary. - Next: agreeing the spec's open decisions, authentication for the API, and every app publishing what it built, did and saw through
Chronicle.Client: GHOSTS subscribing first.