# zakharb/labshock architecture

> Architecture diagram of the GitHub repository zakharb/labshock, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zakharb/labshock
- Repository: https://github.com/zakharb/labshock

## Overview

##### Project Type and Purpose
- Labshock is a multi-container, Docker-based ICS/OT (Industrial Control Systems/Operational Technology) simulation and testing environment.
- It orchestrates various services—Portal, PLC, SCADA, Engineering Workstation, Pentest station, IDS, Collector, Router—via docker-compose to provide a turnkey industrial cyber lab.

##### File Structure Analysis
- Top-level files:
- docker-compose.yml: Orchestration of all services.
- README.md, LICENSE, .github/: Metadata, docs, CI settings.
- labshock/ subdirectory contains one folder per service, each with a Dockerfile and in some cases an entrypoint script or bundled data (e.g., PLC programs, SCADA projects).
- Key service folders:
- portal
- plc
- scada
- ews
- ids
- pentest
- collector
- router
- Each service likely connects to a common Docker network defined in docker-compose.yml, exposing distinct host ports.

##### README Insights
- The “Portal” is the central hub that provides links to all other services.
- PLC uses OpenPLC, SCADA uses FUXA, EWS uses a Kali-based noVNC setup, IDS is Network Swiftness, Collector is Tidal Collector, Pentest is Pentest Fury.
- Services expose web UIs or SSH/VNC on specific host ports (e.g., 8080 for PLC, 1881 for SCADA, 5911 for EWS, etc.).

##### Main Components and Interactions
a. Host Machine (Docker Engine)
– Runs all containers on a user-defined Docker network.
b. Portal Container
– Web UI on https://localhost
– Acts as an ingress point; reverse-proxies or links to other services.
c. ICS Services
– PLC Container (OpenPLC) on port 8080
– SCADA Container (FUXA) on port 1881
d. Engineering Workstation (EWS)
– noVNC interface on port 5911
– Connects to PLC and SCADA over the Docker network for programming and monitoring.
e. Pentest Station
– Web/SSH on port 3443/2222
– Simulates attacks against PLC/SCADA.
f. IDS (Network Swiftness)
– Web UI port 1443; monitors traffic on the ICS network.
g. Collector (Tidal Collector)
– Web UI port 2443; collects logs/metrics from PLC, SCADA, and other containers.
h. Router Container
– (Optional) Defines subnets, bridges, or packet forwarding between segments.
i. External IDS (Optional)
– Can be attached to the same network to ingest mirrored traffic.

Data flows:
- Users access Portal → click links → reach each service’s UI.
- EWS → programs PLC/SCADA via internal network traffic.
- Pentest → sends malicious/modbus/DNP3/S7 traffic → PLC/SCADA respond.
- IDS sniffs network traffic between all ICS components.
- Collector queries/logs events from PLC/SCADA/IDS.

##### Architectural Patterns & Principles
- Microservices via Docker containers, one responsibility per container.
- Single orchestrator (docker-compose) defines service dependencies and a shared network.
- Separation of concerns: UI layer (Portal), control layer (PLC, SCADA), attack layer (Pentest, EWS), security layer (IDS, Collector), and network layer (Router).

##### Final Checklist
- Call out host ports and internal container ports.
- Services logically (control, management, security, network).
- Shared Docker network and volumes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Management/UI"
        Portal["Portal (Central Hub)\\nHTTPS:443"]:::management
        EWS["Engineering Workstation\\nnoVNC:5911"]:::management
    end

    subgraph "Control Systems"
        PLC["PLC (OpenPLC)\\nHTTP:8080, Modbus"]:::control
        PLC_DB["OpenPLC DB"]:::db
        SCADA["SCADA (FUXA)\\nHTTP:1881"]:::control
        SCADA_DB["FUXA DB"]:::db
    end

    subgraph "Offensive"
        Pentest["Pentest Station\\nWeb:3443, SSH:2222"]:::pentest
    end

    subgraph "Security/Monitoring"
        IDS["IDS (Network Swiftness)\\nHTTPS:1443"]:::security
        Collector["Collector (Tidal Collector)\\nHTTPS:2443"]:::security
    end

    subgraph "Network Layer"
        Router["Router"]:::network
    end

    Docker["Docker Engine"]:::network

    %% Data Flows
    Portal -->|"HTTP links"| PLC
    Portal -->|"HTTP links"| SCADA
    Portal -->|"HTTP links"| EWS
    Portal -->|"HTTP links"| Pentest
    Portal -->|"HTTP links"| IDS
    Portal -->|"HTTP links"| Collector

    EWS -->|"modbus/S7"| PLC
    EWS -->|"HTTP API"| SCADA

    Pentest -->|"attack protocols"| PLC
    Pentest -->|"attack protocols"| SCADA

    PLC -->|"logs/events"| Collector
    SCADA -->|"logs/events"| Collector
    IDS -->|"alerts/events"| Collector

    PLC -->|"traffic"| IDS
    SCADA -->|"traffic"| IDS
    EWS -->|"traffic"| IDS
    Pentest -->|"traffic"| IDS

    Router -->|connects| PLC
    Router -->|connects| SCADA
    Router -->|connects| EWS
    Router -->|connects| Pentest
    Router -->|connects| IDS
    Router -->|connects| Collector
    Router -->|connects| Portal

    Docker --> PLC
    Docker --> SCADA
    Docker --> EWS
    Docker --> Pentest
    Docker --> IDS
    Docker --> Collector
    Docker --> Router
    Docker --> Portal

    %% Click Events
    click Docker "https://github.com/zakharb/labshock/blob/main/labshock/docker-compose.yml"
    click Portal "https://github.com/zakharb/labshock/tree/main/labshock/portal/Dockerfile"
    click PLC "https://github.com/zakharb/labshock/tree/main/labshock/plc/Dockerfile"
    click PLC "https://github.com/zakharb/labshock/blob/main/labshock/plc/entrypoint.sh"
    click PLC_DB "https://github.com/zakharb/labshock/tree/main/labshock/plc/appdata/"
    click SCADA "https://github.com/zakharb/labshock/tree/main/labshock/scada/Dockerfile"
    click SCADA "https://github.com/zakharb/labshock/blob/main/labshock/scada/entrypoint.sh"
    click SCADA_DB "https://github.com/zakharb/labshock/tree/main/labshock/scada/appdata/"
    click EWS "https://github.com/zakharb/labshock/tree/main/labshock/ews/Dockerfile"
    click EWS "https://github.com/zakharb/labshock/blob/main/labshock/ews/entrypoint.sh"
    click EWS "https://github.com/zakharb/labshock/blob/main/labshock/ews/start-vnc.sh"
    click EWS "https://github.com/zakharb/labshock/blob/main/labshock/ews/plc/plc-project.tar.gz"
    click EWS "https://github.com/zakharb/labshock/blob/main/labshock/ews/scada/scada-project.tar.gz"
    click Pentest "https://github.com/zakharb/labshock/tree/main/labshock/pentest/Dockerfile"
    click Pentest "https://github.com/zakharb/labshock/blob/main/labshock/pentest/entrypoint.sh"
    click IDS "https://github.com/zakharb/labshock/tree/main/labshock/ids/Dockerfile"
    click Collector "https://github.com/zakharb/labshock/tree/main/labshock/collector/Dockerfile"
    click Router "https://github.com/zakharb/labshock/tree/main/labshock/router/Dockerfile"

    %% Styles
    classDef management fill:#a3be8c,stroke:#2e3440,color:#2e3440;
    classDef control fill:#81a1c1,stroke:#2e3440,color:#2e3440;
    classDef pentest fill:#bf616a,stroke:#2e3440,color:#2e3440;
    classDef security fill:#d08770,stroke:#2e3440,color:#2e3440;
    classDef network fill:#b48ead,stroke:#2e3440,color:#2e3440;
    classDef db fill:#ebcb8b,stroke:#2e3440,color:#2e3440;
```
