Commands Stream Reference

Schema, provenance column, baseline cadences, and a worked customer example for the commands.ndjson artifact in every Virtual-SCADA bundle.

What this artifact records

commands.ndjsonis the canonical record of every write the plant’s control surface received during the run — setpoint updates, actuator commands, mode changes, alarm acknowledgements, and the baseline supervisor and watchdog emissions a real PLC fleet broadcasts even when no operator is active.

Each row pairs the operator’s intended_value with the process’s applied_value so write-path attacks (T0831 / T0836 families) are recoverable by diff. The write_source column tags the originator so IDS training data can learn provenance, not just value.

Row schema

Field	Type	Description
timestamp_utc	ISO-8601 string	UTC time the write was issued, millisecond precision.
sequence_number	int	Monotonic order within the run, aligned with the telemetry stream.
source_sink	string	HMI / engineering workstation that originated the write (or the supervisor/watchdog virtual sink for baseline rows).
target_asset	string	Process path: `process` for setpoints, `actuator` for physical-output writes.
command_name	string	Signal name the write targets (e.g. `feed_pump.flow_setpoint` or `tank.watchdog.heartbeat`).
intended_value	number / string	The value the operator — or supervisor — asked for.
applied_value	number / string	The value the process actually received. Diverges from `intended_value` when a write-path attack is active.
command_state	string	`intact` / `manipulated` / `blocked` / `frozen` / `parameter_modified` / `limit_overridden` / `mode_changed`.
write_source	string	Originator role — see the next section.
ground_truth	string	`clean` / `control_attack` — paired with the ICS-Security label stream for training.
technique_id	string	MITRE ATT&CK ICS technique id if a write-path attack mutated this row (empty for clean rows).

The four write_source roles

Value	Who produced it	Typical cadence
operator	Controller / HMI setpoint & actuator writes emitted by the kernel loop every SCADA tick.	1–60 Hz depending on scenario.
supervisor	Plant-wide supervisory publishes: mode status, integrity checks, setpoint read-backs, alarm-ack sweeps, regime-transition markers.	30–120 s per asset category; one-shot on regime change.
watchdog	PLC / RTU heartbeat & time-sync pulses emitted per asset category.	10 s heartbeat, 60 s time-sync per category.
attacker	Cyber-write attacks that mutated `applied_value` away from `intended_value`.	Scheduled by the ICS-security scenario.

Baseline supervisor and watchdog rows fire even when no operator is actively driving the plant, so commands_distinct stays realistic across the run — the engine targets at least 15 distinct command names within the first minute for any plant with three or more asset categories.

Worked customer example

Describe the plant in natural language and submit through the SDK. The platform builds the scenario, runs the simulation, and seals the bundle. The customer downloads commands.ndjson as part of the normal artifact list.

from radmah_sdk import RadMah

sdk = RadMah(api_key="...", base_url="https://api.radmah.ai")

job = sdk.jobs.create(
    kind="simulate",
    engine="virtual_scada",
    seed=42,
    options={
        "description": (
            "wastewater treatment plant with two positive-displacement pumps, "
            "one aeration tank with a dissolved-oxygen sensor, and one "
            "clarifier with a level transmitter"
        ),
        "total_seconds": 90,
    },
)

# Poll job.state until "succeeded"
artifacts = sdk.list_artifacts(job.id)
commands_art = next(a for a in artifacts if a.name == "commands")
body = sdk.download_artifact(job.id, commands_art.id)

# body is newline-delimited JSON, one row per command.

A representative short sample produces hundreds of rows in commands.ndjson, distributed across the operator, watchdog, and supervisor role categories and spanning multiple distinct command names — what an IDS training pipeline would see from a real multi-asset plant at minute-scale cadence.

Back to SCADA overview

Virtual SCADA Simulator for the engine’s kernel tiers, archetype list, sensor model, and validation gate.