WaCSim is an open-source cyber–physical digital twin for water distribution systems. It simulates both the hydraulic behaviour of the network (tanks, pumps, valves, demands) and the cyber layer (PLCs, SCADA, network traffic, attacks and events) in a single, synchronized environment. That lets you study how control decisions, communication failures, and cyber-attacks affect the water system—and how the system responds.
WaCSim builds on DHALSIM and combines EPANET (via WNTR or epynet) for hydraulics with Mininet and MiniCPS for the industrial control network.
- Flexible control modes — PLC control (decentralized), SCADA control (centralized), or hybrid (both, with configurable conflict resolution).
- Custom algorithms — Replace or extend INP rules with your own Python code per actuator (PLC or SCADA). Use synthetic controls so actuators need no INP rules.
- Realistic attacks — Denial of service (DoS), Man-in-the-Middle (MitM) variants (naive, selective, concealment, replay, sequential), and device attacks. Time- or sensor-triggered; optional CSV-driven time-varying values for MitM.
- Network events — Simulate delay and packet loss on links (triggered by time or sensor conditions) without running attack processes.
- Configurable topology — Simple (flat) or complex (per-PLC subnets) network layout; assign sensors, actuators, and dependent sensors per PLC.
- Rich output — Ground truth, SCADA view, per-PLC caches, and PCAPs for traffic analysis.
Requirements: Linux (or a Linux VM), sudo, Python 3. See Installation for detailed setup (including VM).
-
Clone and install
git clone https://github.com/StavC/WaCSim.git cd WaCSim ./install.sh -
Run your first simulation
From the repo root:
cd examples/GettingStartedEdenTown sudo wacsim config.yamlThis runs the EdenTown network in PLC control mode for 100 iterations—no attacks, no custom algorithms. Output is written to
output/in that folder (ground_truth.csv,scada_values.csv,PLC*_values.csv, and*.pcap).You can also pass an absolute or relative path to the config, e.g.
sudo wacsim /path/to/WaCSim/examples/GettingStartedEdenTown/config.yaml.
-
User manual (recommended) — The Manual folder contains the structured manual:
- Part A — Quick Start (install, first run).
- Part B — Concepts (control modes, attacks, events, custom algorithms, output files, execution flow).
- Part C — Tutorials (evolving GettingStartedEdenTown, running the paper examples).
Content is in reStructuredText (
.rst); build with Sphinx fromManual/LegacyDocs/if you include Manual in your toctree, or read the.rstfiles directly. -
Legacy/reference docs (in Manual/LegacyDocs) — Getting started, Installation, Experiment config, Attack config, Event config, Custom algorithms.
| Example | Description |
|---|---|
| GettingStartedEdenTown | Minimal vanilla run (PLC control, no attacks). Includes optional attacks_dos.yaml and a simple custom algorithm for the tutorials. |
| PaperExamples | Configurations from the WaCSim paper: Ctown (hybrid + sequential MitM), EdenTown PLC_Case (DoS with/without custom guards), EdenTown Scada_Case (DoS with/without SCADA guard), PumpSpeed (variable pump speed via custom algorithms). Each scenario is self-contained; run from inside the scenario folder with sudo wacsim config.yaml. See Manual/tutorials/paper_examples.rst. |
| Other topologies | examples/ also includes Anytown, Ctown, EdenTown variants, ky3/ky14/ky15, Minitown, Wadi—each with configs and INP/PLC YAMLs. |
MIT License. See LICENSE.