Trace Artifact Specification

Definition

A Trace is a structured, ordered sequence of observations (events and/or state facts) used as evidence for temporal and event-sequence claims.

Traces are most useful when:

An invariant uses temporal operators (ALWAYS, EVENTUALLY, LEADS_TO)
A finding depends on ordering ("A happened before B", "B never happened after A")
You need reproducible evidence instead of narrative log excerpts

Schema: trace.schema.yaml

Required Fields

Field	Type	Description
`id`	TraceID	Unique identifier for the trace (`T-*`)
`title`	string	Descriptive name for the trace
`exploration_ref`	ExplorationID	Exploration that produced or motivated the trace
`path`	enum	`BASELINE`, `ATTACK`, or `OTHER`
`steps`	TraceStep[]	Ordered steps of the trace (`t0, t1, ...`)

Optional Fields

Field	Type	Default	Description
`scenario_ref`	ScenarioID	-	Convenience link back to the scenario
`time_window`	TimeWindow	-	Time bounds of the evidence slice
`sources`	TraceSource[]	-	Where evidence came from (logs, CloudTrail, etc.)
`correlation`	Correlation	-	How events were grouped into this trace
`description`	string	-	Narrative context
`status`	ArtifactStatus	`DRAFT`	Lifecycle status
`version`	string	-	Semantic version

Field Details

steps

Each step represents a trace position ti. A step MAY contain:

events: actions/events that occurred at ti
states: facts assumed/observed true at ti

When using CFSE temporal operators, tools (including AI assistants) interpret temporal expressions over the sequence of steps.

Example: Baseline vs Attack Traces

yaml

id: T-SHOP-IDOR-DELETE-001-01-01
title: "Baseline trace: owner deletes own item"
exploration_ref: E-SHOP-IDOR-DELETE-001-01
scenario_ref: S-SHOP-IDOR-DELETE-001
path: BASELINE
sources:
  - type: app_log
    ref: "logs/shop-api-2026-01-24.log"
correlation:
  keys: ["request_id"]
  values:
    request_id: "req_123"
steps:
  - i: 0
    events:
      - "DELETE(\"alice\", \"item-xyz789\")"
  - i: 1
    states:
      - "P-SHOP-ITEM-EXISTS(\"item-xyz789\")" # Example predicate fact (optional)
    notes: "Item deleted successfully by owner"
status: ACTIVE
version: "1.0.0"

yaml

id: T-SHOP-IDOR-DELETE-001-01-02
title: "Attack trace: non-owner deletes victim item"
exploration_ref: E-SHOP-IDOR-DELETE-001-01
scenario_ref: S-SHOP-IDOR-DELETE-001
path: ATTACK
sources:
  - type: app_log
    ref: "logs/shop-api-2026-01-24.log"
correlation:
  keys: ["request_id"]
  values:
    request_id: "req_456"
steps:
  - i: 0
    events:
      - "DELETE(\"bob\", \"item-xyz789\")"
  - i: 1
    notes: "Unexpected success: item deleted by non-owner"
status: ACTIVE
version: "1.0.0"

Common Mistakes

Mistake	Problem	Fix
[ ] Missing correlation	Trace is ambiguous	Record correlation keys and values (request_id, trace_id, principal_id)
[ ] Mixing unrelated sessions	False ordering claims	Split into separate traces per correlation
[ ] Only prose	Not reproducible	Put ordering into `steps[]`
[ ] No source pointers	Not auditable	Add `sources[]` with refs/hashes when possible

Common Pitfalls

Using traces as a prose dump without structured steps (steps[]) and stable references.
Capturing ordering claims without linking to the producing exploration (exploration_ref) when applicable.
Missing provenance (sources, hashes, correlation IDs) for evidence that needs auditability.

Trace Artifact Specification

Definition#

Required Fields#

Optional Fields#

Field Details#

steps#

Example: Baseline vs Attack Traces#

Common Mistakes#

Common Pitfalls#