Generator Design

[sehkone]

Generator Design

This document describes the design of the Generator, the core component of the Security Dataset Generation Platform. For overall platform vision and architecture, see the overview document.

---

1. Purpose

The Generator takes a Scenario Definition as input and produces raw artifacts:

• PCAP (network traffic captures)
• Sysmon JSONL (Windows host telemetry)
• Falco JSONL (Linux/container telemetry)
• DB access logs
• Cloud access logs

These artifacts are packaged into a Dataset Bundle with accompanying Ground Truth records, then fed into the QFlow pipeline for validation.

Scenario Definition
      |
      v
  Generator
      |
      v
Raw Artifacts (PCAP / JSONL / logs)
      |
      v
Dataset Bundle (+ Ground Truth)

---

2. Emulation-Centered Approach

The Generator uses an emulation-centered approach: it provisions actual VMs and containers, runs real tools inside them, and captures the resulting traffic and logs.

2.1 Why Emulation

Benefit	Explanation
Data realism	Protocol quirks, OS-specific behaviors, and timing patterns are naturally captured
QFlow compatibility	Generated data passes through the same pipeline as production data without adaptation
Multi-artifact generation	A single emulated scenario naturally produces PCAP, host logs, and application logs simultaneously
Ground truth accuracy	The Orchestrator knows exactly what activity is running at each moment

2.2 Known Challenges and Mitigations

Challenge	Mitigation
Speed	Pre-baked container/VM images with tools pre-installed; parallel execution of independent scenarios
Infrastructure cost	Container-first design (lightweight); VMs only when necessary (Windows/Sysmon)
Reproducibility	Seed-based scenario control; environment snapshots; deterministic activity scheduling
Attack tool maintenance	Version-pinned container images; automated image rebuild pipeline

2.3 Where Simulation Supplements Emulation

Not all data generation benefits from full emulation. The following areas may use simulation (synthetic generation) to supplement:

• Bulk background traffic: tcpreplay can replay sanitized real traffic patterns more efficiently than generating fresh browsing sessions
• High-volume DNS queries: dnsperf can generate realistic query load without running actual resolvers
• Bandwidth filling: iperf3 can generate volume to match realistic network utilization levels

The boundary is clear: attack behaviors and their surrounding context are always emulated; background volume can be simulated.

---

3. Language Selection

3.1 Rust vs TypeScript — Per-Task Comparison

Task	Rust	TypeScript
Scenario parsing (JSON/YAML)	serde + serde_yaml (compile-time type checking)	Native JSON, js-yaml (runtime validation with zod)
Container orchestration	bollard (mature Docker API)	dockerode (mature)
VM management	libvirt bindings (available)	libvirt bindings (weak)
Network configuration	netlink bindings (direct kernel control)	Shell command wrapping
PCAP processing	pnet, etherparse (strong)	Limited library support
Async orchestration	tokio (powerful but complex)	Native async/await (simpler)
Process execution	tokio::process	execa, child_process
Development speed	Slower	Faster
Team proficiency	High (existing aicers expertise)	Variable

3.2 Decision: Rust

The Generator is not a pure orchestrator — it needs to:

• Directly configure network topologies via netlink
• Process and potentially post-process PCAP files
• Manage VMs through libvirt for Windows/Sysmon environments
• Integrate with existing aicers tools (QFlow, etc.) written in Rust

Combined with the team's existing Rust expertise, Rust is the appropriate choice.

---

4. Internal Architecture

The Generator consists of five layers:

+-----------------------------------------------+
|              Orchestrator (Rust)               |
|  Reads Scenario Definition, coordinates all   |
+-----------------------------------------------+
        |              |              |
        v              v              v
+-------------+ +-------------+ +-------------+
| Environment | |  Activity   | | Collection  |
|    Layer    | |    Layer    | |    Layer    |
+-------------+ +-------------+ +-------------+
        |              |              |
        +-------+------+------+------+
                |             |
                v             v
        +-------------+ +-------------+
        |  Bundling   | |Ground Truth |
        |    Layer    | |  Recording  |
        +-------------+ +-------------+

4.1 Orchestrator

• Parses the Scenario Definition file
• Coordinates the lifecycle: provision → run activities → collect → bundle
• Manages the timeline: schedules normal and attack activities according to the scenario
• Automatically records Ground Truth as activities are triggered

4.2 Environment Layer

• Provisions containers (Linux/Falco environments) via Docker API (bollard)
• Provisions VMs (Windows/Sysmon environments) via libvirt
• Configures virtual network topologies (bridges, VLANs, routing rules) via netlink
• Sets up encryption infrastructure per scenario (TLS certificates, proxy configurations)

4.3 Activity Layer

• Runs normal behavior generators inside provisioned environments
• Runs attack tools inside provisioned environments
• Receives scheduling commands from the Orchestrator
• Reports activity start/stop events back to the Orchestrator (for Ground Truth)

4.4 Collection Layer

• tcpdump/tshark agents capture PCAP on virtual network interfaces
• Sysmon runs on Windows VMs, collecting event logs in JSONL
• Falco runs on Linux containers, collecting event logs in JSONL
• Database audit log collection from DB instances
• Collection agents are deployed during environment provisioning

4.5 Bundling Layer

• Assembles all collected artifacts into the Dataset Bundle structure
• Generates meta.json with scenario metadata
• Writes Ground Truth manifest from Orchestrator's activity log
• Validates bundle completeness before output

---

5. Environment Provisioning

5.1 Container-Based Environments

Used for Linux hosts, network infrastructure, and most attack tools.

• Base images: Pre-baked with common tools (curl, openssh, etc.)
• Attack tool images: Version-pinned images for each tool (Metasploit, nmap, Sliver, etc.)
• Falco sidecar: Falco deployed alongside application containers for host telemetry
• Networking: Docker networks with configurable subnets and routing

5.2 VM-Based Environments

Used when Windows or full OS fidelity is required.

• Windows VMs: Pre-configured with Sysmon, common applications
• Management: libvirt for lifecycle management
• Snapshots: Base snapshots for quick rollback and reproducibility

5.3 Network Topology

• Bridges and VLANs: Simulate network segmentation (DMZ, internal, management)
• Routing: Configurable routing between segments
• Capture points: tcpdump/tshark positioned at strategic interfaces (edge, internal)

5.4 Encryption Architecture

Each scenario specifies an encryption architecture, which the Environment Layer configures:

Architecture	Configuration
TLS-encrypted	Services use TLS; PCAP contains encrypted traffic
TLS termination	TLS terminated at load balancer; internal traffic is plaintext
HTTPS proxy decryption	Proxy with CA certificate performs TLS interception
End-to-End encryption	Full E2E; no decryption point in the network

---

6. Per-Artifact Generation Strategy

6.1 PCAP

• Method: tcpdump/tshark capture on virtual network interfaces
• Capture points: Edge interface (external traffic) and inner interfaces (internal traffic)
• Output: Separate PCAP files per capture point (edge.pcap, inner.pcap)
• Encryption handling: PCAP reflects the scenario's encryption architecture naturally

6.2 Sysmon JSONL

• Method: Actual Sysmon running on Windows VMs
• Configuration: Sysmon config tuned per scenario (which events to capture)
• Collection: Event logs exported as JSONL
• Scope: Process creation, network connections, file operations, registry changes, etc.

6.3 Falco JSONL

• Method: Actual Falco running on Linux containers
• Configuration: Falco rules tuned per scenario
• Collection: Falco output in JSONL format
• Scope: System calls, container events, file access, network activity

6.4 DB Logs

• Method: Real database instances (PostgreSQL, MySQL) with audit logging enabled
• Activity: Normal and attack queries executed against the database
• Collection: Audit log files collected after scenario completion

6.5 Cloud Logs

• Method: Mock cloud services (e.g., LocalStack for AWS) or real cloud service audit logs
• Activity: API calls, resource access patterns
• Collection: CloudTrail-style logs in JSON format

---

7. Activity Generation

7.1 Normal Behavior Generation

Normal activities run inside containers and are controlled by the Orchestrator.

Activity Type	Tools	Notes
Web browsing	Playwright (headless Chromium), curl/wget, k6	Playwright for realistic browser behavior; k6 for load patterns
Email	Postfix + Dovecot (full stack), swaks/msmtp	Full SMTP/IMAP flow between internal mail servers
File sharing	smbclient (SMB), rsync/scp (Linux), rclone (cloud)	Inter-host file transfers
Database access	psql/mysql clients, pgbench/sysbench	Normal query patterns and load generation
SSH sessions	openssh	Routine admin tasks (login, command execution)
Background traffic	tcpreplay, iperf3, dnsperf	tcpreplay replays sanitized real PCAP for realism; iperf3/dnsperf fill volume

7.2 Attack Behavior Generation

Attack generation uses a hybrid approach: frameworks as the primary source, supplemented with individual tools where frameworks lack coverage.

Frameworks

Framework	Role	Why
Atomic Red Team	ATT&CK technique-level unit tests	Easiest starting point; granular, self-contained tests
CALDERA	Automated multi-step adversary emulation	End-to-end attack chains with decision logic
PurpleSharp	Windows adversary simulation	Generates Sysmon telemetry directly; highly relevant to this project
Infection Monkey	Automated breach and lateral movement	Self-propagating simulation

Individual Tools by Attack Phase

Phase	Tools
Reconnaissance	nmap, masscan, ffuf/feroxbuster (web fuzzing), enum4linux-ng (AD enumeration)
Initial Access	Metasploit, Responder (LLMNR/NBT-NS poisoning), SQLMap
Credential Access	Mimikatz, Rubeus (Kerberos attacks), LaZagne (stored credential extraction)
Lateral Movement	Impacket (psexec/wmiexec/smbexec — essential), NetExec, Evil-WinRM
Command & Control	Sliver (primary, open source), Mythic (multi-agent), Covenant (.NET-based)
Exfiltration	dnscat2 (DNS tunneling), iodine (DNS tunneling), rclone (cloud exfil), PacketWhisper (steganographic DNS)

All attack tools are managed as version-pinned container images to ensure reproducibility.

7.3 Incremental Rollout

The tool set expands incrementally, starting with the easiest to integrate:

Phase 1 — Early

• Normal: curl/wget HTTP traffic, basic file operations
• Attack: Atomic Red Team single techniques, nmap scanning

Phase 1 — Late

• Normal: Playwright headless browsing, Postfix/Dovecot email
• Attack: CALDERA multi-step scenarios, Metasploit automation

Phase 2+

• Normal: Complex multi-service business patterns
• Attack: C2 frameworks (Sliver), Impacket lateral movement, DNS tunneling, AI Actor behaviors

7.4 Temporal Mixing

• The Orchestrator schedules activities along a timeline defined in the Scenario Definition
• Normal and attack activities are interleaved realistically
• Business-hours traffic concentration, quiet periods, gradual attack progression
• Attack activities may span hours or days of simulated time

---

8. Ground Truth Integration

Because the Generator uses emulation, it has precise knowledge of what happens and when.

• The Orchestrator records every activity trigger in the Ground Truth manifest:
  • Timestamp (start and end)
  • Activity type (normal or attack)
  • For attacks: technique ID (e.g., MITRE ATT&CK T1046), attack phase, source/target hosts
• This recording happens automatically as part of the Orchestrator's scheduling loop
• The resulting ground_truth/manifest.jsonl is included in the Dataset Bundle

Example Ground Truth entry:

{
  "timestamp_start": "2026-03-01T06:15:00Z",
  "timestamp_end": "2026-03-01T06:18:30Z",
  "type": "attack",
  "technique": "T1046",
  "phase": "reconnaissance",
  "tool": "nmap",
  "source": "attacker-001",
  "target": "win-002",
  "artifacts": ["net/edge.pcap", "host/win-002/sysmon.jsonl"]
}

---

9. Scaling Strategy

9.1 Single Machine (Phase 1)

• All containers and VMs run on a single host
• Suitable for small-scale scenarios and development
• Docker Compose or direct Docker API for orchestration

9.2 Multi-Machine (Phase 3)

• Orchestrator distributes environments across multiple hosts
• Shared storage for artifact collection
• Network overlay for cross-host virtual networking

9.3 Cloud Scaling (Phase 4)

• Cloud VMs for large-scale parallel scenario execution
• Each scenario runs independently — natural parallelism
• Artifact collection to object storage (S3-compatible)
• Month-scale dataset generation through parallel batch execution