Scenario Definition Schema

[sehkone]

Scenario Definition Schema

This document defines the schema for Scenario Definition files — the input that the Generator reads to produce dataset bundles. For the overall platform architecture and N-dimensional environment model, see the overview document.

---

1. Purpose

A Scenario Definition file declares one specific combination of the N-dimensional axes defined in the overview document, along with the concrete details the Generator needs for execution:

• Which environment axes are selected (scale, encryption, workload, threat, attacker, AI agent, AI control)
• What infrastructure to provision (hosts, network topology)
• What activities to run and when (normal behavior, attack behavior, timeline)
• What artifacts to collect
• How long the scenario runs

Each file represents one dataset generation run. The Generator reads this file and produces a complete Dataset Bundle.

---

2. Format

Scenario Definition files use YAML:

• Human-readable and editable
• Supports comments (useful for documenting scenario rationale)
• Widely supported across tooling ecosystems
• Naturally represents the hierarchical structure of scenario configuration

File extension: .scenario.yaml

---

3. Top-Level Structure

# Top-level structure of a Scenario Definition file
metadata:       # Scenario identity and description
environment:    # N-dimensional axis selections
infrastructure: # Hosts, network topology, encryption setup
activities:     # Normal and attack behavior definitions + timeline
collection:     # What artifacts to capture and where
duration:       # Total scenario runtime

---

4. Field Definitions

4.1 metadata

Identifies the scenario and provides context.

Field	Type	Required	Description
name	string	yes	Unique identifier for this scenario (e.g., small-tls-exfil-human)
description	string	yes	Human-readable description of what this scenario generates
version	string	yes	Schema version (e.g., 1.0)
tags	string[]	no	Freeform tags for categorization (e.g., ["phase-1", "anchor-case"])

metadata:
  name: small-tls-exfil-human
  description: >
    Small office environment with TLS encryption.
    Human attacker performs staged data exfiltration over 24 hours.
  version: "1.0"
  tags: ["phase-1", "anchor-case", "data-exfiltration"]

4.2 environment

Declares the N-dimensional axis selections. Each field maps to one axis from the overview document.

Some axes accept a single value, others accept an array when multiple characteristics coexist in one scenario.

Field	Type	Required	Allowed Values	Description
scale	string	yes	small, medium, large	Network/org size
encryption	string[]	yes	tls, tls_termination, https_proxy, e2e	Encryption architecture(s)
workload	string[]	yes	endpoint, server, cloud	Workload profile(s)
threat	string[]	yes	insider, external, exfiltration, automated	Threat category/categories
attacker	string[]	yes	human, scripted, ai_assisted, ai_actor	Attacker model(s)
ai_agent	string[]	no	internal, external	AI Agent deployment(s). Omit if no AI Agent.
ai_control	string	no	monitoring, enforcement	AI Agent control mode. Omit if no AI Agent. Used with ai_agent.

# Simple scenario
environment:
  scale: small
  encryption: [tls]
  workload: [endpoint]
  threat: [exfiltration]
  attacker: [human]
  # ai_agent omitted — no AI Agent in this scenario

# Complex scenario
environment:
  scale: medium
  encryption: [tls, tls_termination]    # TLS on external, terminated at LB
  workload: [endpoint, server]           # Both endpoint and server workloads
  threat: [external, exfiltration]       # External attacker performing exfiltration
  attacker: [human, scripted]            # Human attacker using automated scripts
  ai_agent: [internal]
  ai_control: monitoring

4.3 infrastructure

Defines the hosts and network topology for this scenario.

4.3.1 infrastructure.hosts

A list of hosts to provision.

Field	Type	Required	Description
name	string	yes	Host identifier (e.g., win-001)
os	string	yes	windows or linux
role	string	yes	workstation, server, attacker, proxy, mail_server, db_server
provision	string	yes	container or vm
tools	string[]	no	Additional tools to install (e.g., ["sysmon", "curl"])

infrastructure:
  hosts:
    - name: win-001
      os: windows
      role: workstation
      provision: vm
      tools: ["sysmon"]

    - name: win-002
      os: windows
      role: workstation
      provision: vm
      tools: ["sysmon"]

    - name: linux-srv-001
      os: linux
      role: server
      provision: container
      tools: ["falco", "nginx", "postgresql"]

    - name: attacker-001
      os: linux
      role: attacker
      provision: container
      tools: ["nmap", "metasploit"]

4.3.2 infrastructure.network

Defines the network topology.

Field	Type	Required	Description
segments	object[]	yes	Network segments (subnets)
segments[].name	string	yes	Segment name (e.g., internal, dmz)
segments[].subnet	string	yes	CIDR notation (e.g., 10.0.1.0/24)
segments[].hosts	string[]	yes	Host names attached to this segment
routing	object[]	no	Routing rules between segments
routing[].from	string	yes	Source segment
routing[].to	string	yes	Destination segment
routing[].policy	string	yes	allow, deny, or nat

infrastructure:
  network:
    segments:
      - name: internal
        subnet: "10.0.1.0/24"
        hosts: ["win-001", "win-002", "linux-srv-001"]

      - name: external
        subnet: "10.0.2.0/24"
        hosts: ["attacker-001"]

    routing:
      - from: external
        to: internal
        policy: nat

4.3.3 infrastructure.encryption

Encryption-specific configuration. Content depends on the environment.encryption axis selection.

Field	Type	Required	Description
tls_versions	string[]	no	Allowed TLS versions (default: ["1.2", "1.3"])
termination_host	string	conditional	Host where TLS terminates (required when encryption: tls_termination)
proxy_host	string	conditional	HTTPS proxy host (required when encryption: https_proxy)
proxy_ca	string	conditional	CA certificate path for proxy decryption

infrastructure:
  encryption:
    tls_versions: ["1.2", "1.3"]

4.4 activities

Defines what happens during the scenario: normal behavior, attack behavior, and when each occurs.

4.4.1 activities.normal

A list of normal behavior generators to run.

Field	Type	Required	Description
type	string	yes	Activity type: web_browsing, email, file_sharing, database, ssh, background_traffic
hosts	string[]	yes	Which hosts perform this activity
start	string	yes	When to start (relative to scenario start, e.g., 0h, 2h30m)
end	string	no	When to stop (defaults to scenario duration end)
intensity	string	no	low, medium, high (default: medium)
config	object	no	Type-specific configuration

activities:
  normal:
    - type: web_browsing
      hosts: ["win-001", "win-002"]
      start: "0h"
      intensity: medium

    - type: email
      hosts: ["win-001", "win-002"]
      start: "0h"
      intensity: low

    - type: database
      hosts: ["linux-srv-001"]
      start: "0h"
      intensity: low
      config:
        db_type: postgresql
        query_profile: oltp

    - type: background_traffic
      hosts: ["win-001", "win-002"]
      start: "0h"
      config:
        method: tcpreplay
        pcap_source: "templates/office-background.pcap"

4.4.2 activities.attack

A list of attack activities with their timing and configuration.

Field	Type	Required	Description
name	string	yes	Attack step name (for Ground Truth labeling)
technique	string	yes	MITRE ATT&CK technique ID (e.g., T1046)
phase	string	yes	Attack phase: reconnaissance, initial_access, credential_access, lateral_movement, c2, exfiltration
tool	string	yes	Tool to use (e.g., nmap, atomic_red_team, caldera)
source	string	yes	Attacking host
target	string or string[]	yes	Target host(s)
start	string	yes	When to start (relative to scenario start)
duration	string	no	How long the attack runs
config	object	no	Tool-specific configuration

activities:
  attack:
    - name: network_scan
      technique: T1046
      phase: reconnaissance
      tool: nmap
      source: attacker-001
      target: ["win-001", "win-002", "linux-srv-001"]
      start: "6h"
      duration: "15m"
      config:
        scan_type: syn
        ports: "1-1024"

    - name: exploit_smb
      technique: T1210
      phase: initial_access
      tool: metasploit
      source: attacker-001
      target: win-002
      start: "7h"
      duration: "30m"
      config:
        module: exploit/windows/smb/ms17_010_eternalblue

    - name: stage_exfil
      technique: T1048
      phase: exfiltration
      tool: custom
      source: win-002
      target: attacker-001
      start: "8h"
      duration: "2h"
      config:
        method: https
        data_size: "500MB"
        chunk_size: "10MB"

4.5 collection

Specifies what artifacts to collect and from where.

Field	Type	Required	Description
pcap	object[]	no	PCAP capture points
pcap[].interface	string	yes	Where to capture: segment name or all
pcap[].output	string	yes	Output filename (e.g., edge.pcap)
sysmon	object[]	no	Sysmon collection targets
sysmon[].hosts	string[]	yes	Hosts to collect from
falco	object[]	no	Falco collection targets
falco[].hosts	string[]	yes	Hosts to collect from
db_logs	object[]	no	Database audit log collection
db_logs[].host	string	yes	DB host
cloud_logs	object[]	no	Cloud service log collection

collection:
  pcap:
    - interface: external
      output: edge.pcap
    - interface: internal
      output: inner.pcap

  sysmon:
    - hosts: ["win-001", "win-002"]

  falco:
    - hosts: ["linux-srv-001"]

  db_logs:
    - host: linux-srv-001

4.6 duration

Total scenario runtime.

Field	Type	Required	Description
total	string	yes	Total scenario duration (e.g., 24h, 7d)

duration:
  total: "24h"

---

5. Example

This example illustrates the schema format. Actual anchor cases are defined in a separate document (Anchor Case Selection).

metadata:
  name: small-tls-exfil-human
  description: >
    Small office environment with TLS encryption.
    Human attacker performs staged data exfiltration over 24 hours.
  version: "1.0"
  tags: ["phase-1", "anchor-case", "data-exfiltration"]

environment:
  scale: small
  encryption: [tls]
  workload: [endpoint]
  threat: [exfiltration]
  attacker: [human]
  # ai_agent omitted — no AI Agent in this scenario

infrastructure:
  hosts:
    - name: win-001
      os: windows
      role: workstation
      provision: vm
      tools: ["sysmon"]

    - name: win-002
      os: windows
      role: workstation
      provision: vm
      tools: ["sysmon"]

    - name: linux-srv-001
      os: linux
      role: server
      provision: container
      tools: ["falco", "nginx", "postgresql"]

    - name: attacker-001
      os: linux
      role: attacker
      provision: container
      tools: ["nmap", "metasploit"]

  network:
    segments:
      - name: internal
        subnet: "10.0.1.0/24"
        hosts: ["win-001", "win-002", "linux-srv-001"]
      - name: external
        subnet: "10.0.2.0/24"
        hosts: ["attacker-001"]
    routing:
      - from: external
        to: internal
        policy: nat

  encryption:
    tls_versions: ["1.2", "1.3"]

activities:
  normal:
    - type: web_browsing
      hosts: ["win-001", "win-002"]
      start: "0h"
      intensity: medium

    - type: email
      hosts: ["win-001", "win-002"]
      start: "0h"
      intensity: low

    - type: database
      hosts: ["linux-srv-001"]
      start: "0h"
      intensity: low
      config:
        db_type: postgresql
        query_profile: oltp

  attack:
    - name: network_scan
      technique: T1046
      phase: reconnaissance
      tool: nmap
      source: attacker-001
      target: ["win-001", "win-002", "linux-srv-001"]
      start: "6h"
      duration: "15m"
      config:
        scan_type: syn
        ports: "1-1024"

    - name: exploit_smb
      technique: T1210
      phase: initial_access
      tool: metasploit
      source: attacker-001
      target: win-002
      start: "7h"
      duration: "30m"
      config:
        module: exploit/windows/smb/ms17_010_eternalblue

    - name: credential_dump
      technique: T1003
      phase: credential_access
      tool: mimikatz
      source: win-002
      target: win-002
      start: "7h45m"
      duration: "10m"

    - name: stage_exfil
      technique: T1048
      phase: exfiltration
      tool: custom
      source: win-002
      target: attacker-001
      start: "8h"
      duration: "2h"
      config:
        method: https
        data_size: "500MB"
        chunk_size: "10MB"

collection:
  pcap:
    - interface: external
      output: edge.pcap
    - interface: internal
      output: inner.pcap
  sysmon:
    - hosts: ["win-001", "win-002"]
  falco:
    - hosts: ["linux-srv-001"]
  db_logs:
    - host: linux-srv-001

duration:
  total: "24h"

---

6. Schema Validation

The Generator validates every Scenario Definition file before execution:

• Required fields: All required fields must be present
• Axis values: Environment axis values must be from the allowed set
• Host references: All host names referenced in activities and collection must exist in infrastructure.hosts
• Segment references: All segment names referenced in collection must exist in infrastructure.network.segments
• Timeline consistency: Activity start + duration must not exceed scenario duration.total
• Encryption consistency: Encryption-specific fields (e.g., termination_host) must be present when the corresponding encryption architecture is selected

Validation errors are reported before any provisioning begins.