Quick Start

This guide walks you through fetching the open-source content library and running your first Tracemill scenario — an AWS CloudTrail event simulating defense-evasion via trail deletion.

Fetch the Content Library

Tracemill scenarios are packaged in an open source content library. Pull the latest open-source into ~/.tracemill/library/:

tracemill update

The library contains ready-to-run scenarios, jobs, pools, and event-type schemas covering AWS CloudTrail, Windows Sysmon, and Windows Event Log.

Run a Scenario

Run an AWS CloudTrail DeleteTrail scenario by its content ID:

tracemill run scenarios/aws/cloudtrail/delete-trail

This emits a single CloudTrail management event modelling an attacker who disables logging to evade detection (MITRE ATT&CK T1562.008). The event prints to stdout as JSONL — one self-contained JSON object per line, with envelope fields (tracemill_type, tracemill_timestamp, tracemill_seq) wrapping the event payload.

The scenario file defines:

State variables — resolved once per run (account ID, source IP, actor identity, trail name)
Steps — an ordered sequence of event emissions, each referencing an event type by id@version
Expressions — gen.ipv4(), gen.uuid(), gen.aws_identity(...), ref.aws_region — dynamically generating realistic, correlated values across fields

Browse Available Content

List the event types the engine discovered from the library:

tracemill list event-types

Or browse the content library directly:

ls ~/.tracemill/library/scenarios
ls ~/.tracemill/library/jobs

Run a Job

Jobs orchestrate multiple scenario invocations, share pools across workloads, and bind values into scenario state. Run the Splunk password-spray job, which loops a failed-login scenario 50 times against rotating NTLM authentication surfaces:

tracemill run jobs/splunk/windows/wineventlog/logon/detect-password-spray-attempts

The job binds an inline CSV pool into each iteration so authentication metadata (logon type, package, status code) varies row-by-row — exactly the kind of correlated noise a detection rule like Splunk ESCU's "Detect Password Spray Attempts" needs to fire.

Send Events to Splunk

By default, events stream to stdout. Use destination flags to deliver to a real backend. For Splunk HEC, the CLI auto-infers --target-type splunk so generated XML matches what the Splunk Universal Forwarder produces:

tracemill run jobs/splunk/windows/wineventlog/logon/detect-password-spray-attempts \
  --hec-url https://splunk.example.com:8088 \
  --hec-token your-hec-token

Other supported destinations include S3 (--s3-bucket, with optional CloudTrail layout), raw TCP (--tcp-host), and generic HTTP (--http-url). See the CLI reference for the full list.

Preview Without Emitting

Use --dry-run to validate a scenario or job and see an event-count summary without sending anything downstream:

tracemill run scenarios/aws/cloudtrail/delete-trail --dry-run

Next Steps

Scenarios — understand the scenario model in depth
Jobs — orchestrate multiple scenarios with shared pools
Expressions — the ExprStr grammar for dynamic values
CLI Reference — every command, flag, and environment variable

Prerequisites