spolinovskiy/industrial-protocols-labs

Purpose and Entry Points

This repository is a unified Docker-based industrial-control-system (ICS) protocol testbed. It runs one selected protocol lab at a time, exposes a consistent FUXA HMI, and supports bounded packet capture/diagnostics. The primary operator interface is labctl (start, switch, stop); Docker Compose can also start a profile directly through platform/docker-compose.platform.yml. The supported architecture is platform/ plus protocols/; legacy/ preserves superseded per-protocol stacks.

Platform Orchestration

The central Compose definition provisions shared platform services and conditionally enables protocol profiles: platform/docker-compose.platform.yml. A selected profile starts its protocol server alongside the common gateway, HMI, diagnostics, and reset services. labctl is the control-plane boundary for selecting/stopping the active protocol; the optional switcher API/UI invokes that same command path through scripts/lab_switcher_server.py and platform/lab_switcher/index.html.

Protocol Simulation Layer

Each protocol is independently containerized and follows a server/client pattern around a common canonical tag model (digital/analog I/O, timer, counter). Representative implementations are:

• Modbus: protocols/modbus/server/modbus_server.py, protocols/modbus/client/modbus_client.py

• OPC UA: protocols/opcua/server/opcua_server.py, protocols/opcua/client/opcua_client.py

• BACnet: protocols/bacnet/server/bacnet_server.py, protocols/bacnet/client/bacnet_client.py

• MQTT: protocols/mqtt/broker/mosquitto.conf, protocols/mqtt/device-bridge/device_bridge.py

• S7: protocols/s7/plc-sim/s7_server.py, protocols/s7/client/s7_client.py

CIP, DNP3, and IEC-104 additionally include gateway adapters where needed: protocols/cip/gateway/app.py, protocols/dnp3/gateway/app.py, protocols/iec104/gateway/app.py. Protocol services are Python-based Docker workloads; MQTT uses a Mosquitto broker.

HMI, Access, and Routing Boundary

FUXA provides the common HMI, with protocol-specific project blueprints in platform/fuxa/seeds/modbus.project.json, platform/fuxa/seeds/opcua.project.json, and related seed files. Nginx is the external boundary separating guest view-only and admin/diagnostic access, including basic-auth credentials: platform/nginx/nginx.conf, platform/nginx/auth/guest.htpasswd, platform/nginx/auth/admin.htpasswd. The gateway routes HMI and diagnostics while protocol services remain on the internal Docker network.

Diagnostics and Lifecycle Management

The diagnostics container supplies a constrained terminal menu and protocol-aware packet capture scripts: platform/diagnostics/entrypoint.sh, platform/diagnostics/menu.sh, platform/diagnostics/capture/common.sh. Per-protocol captures bind to standard protocol ports and are retention-limited. The reset controller enforces TTL/idle reset policy, stops the active server, cleans captures, and attempts FUXA seed import: platform/reset/reset.sh, platform/reset/policy.yaml, platform/reset/Dockerfile.

Optional Web Frontend

frontend/ is a separate TypeScript/React application rather than the core lab runtime. Its browser entry is frontend/client/src/main.tsx, composed by frontend/client/src/App.tsx; the Labs and protocol-testing screens are frontend/client/src/pages/labs.tsx and frontend/client/src/pages/protocol-test.tsx. Its Node server can proxy or call the switcher backend via frontend/server/index.ts, frontend/server/routes.ts, and frontend/server/lib/lab-client.ts. Authentication integration is Replit-specific: frontend/server/replit_integrations/auth/replitAuth.ts.

External Dependencies and Operational Boundaries

Material runtimes are Docker/Compose, Python protocol simulators, Nginx, FUXA, Mosquitto, and the optional Node/Vite React frontend. The platform has no indicated cloud control plane; external exposure should terminate TLS at Nginx or an upstream reverse proxy. Protocol state, FUXA state, captures, and reset behavior are operationally isolated from the optional frontend and from archived legacy/ deployments.