# cyphysecurity/nefics architecture

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

- Interactive diagram: https://gitdiagram.com/cyphysecurity/nefics
- Repository: https://github.com/cyphysecurity/nefics

## Overview

##### Project Type and Purpose
- NEFICS is a simulation/emulation framework intended for researchers to mimic industrial control systems. It leverages Mininet to create virtual networks, alongside modules that emulate various industrial devices and their communication protocols.
- The README clearly states that the framework instantiates “devices” using a configuration file. The system is designed to simulate high-fidelity industrial control devices and their interconnections.

##### Analyzing the File Structure
- Top-level directories and files:
- The “nefics” directory contains the bulk of the simulation logic, including the main “launcher.py”, modules (device logic, honeypot, simple power grid, SWaT), protocol implementations (IEC61850, IEC10x, modbus, etc.), and utility scripts.
- The “conf” directory holds configuration files for Factory IO scenes, human-machine interface (HMI) configurations, and honeypot setups.
- The “html” directory appears to provide web-based content (in ASP/HTML/CSS/JS) that might serve as a user interface or legacy component.
- “run.py” acts as the primary entry point for running the simulation, reading configuration files to instantiate the virtual network and devices.
- The “tests” directory contains unit tests, ensuring that key protocol interactions and configurations work as intended.
- This structure implies a layered design where the configuration, simulation engine, device emulation modules, and network protocols are clearly separated.

##### Insights from the README
- The configuration file (scenario.json) feeds into run.py.
- run.py initializes both a virtual network (vNetwork) and virtual devices (vDevice).
- Each vDevice then triggers a launcher component (from the “nefics/modules” folder) which imports the required module.
- The launcher “Handler” uses protocol implementations (from “nefics/protos”) to create device-specific emulators.
- It also provides sample configurations (JSON) that define network topology (switches, devices, interfaces, and launch parameters).

##### Key Components
a. Main Components:
- Configuration Layer: Show the JSON configuration files (located in the “conf” directory, e.g., simple_powergrid.json) that define switches, devices, and their properties.
- Orchestration Layer: Represent “run.py” which parses the configuration and sets up the simulation.
- Virtual Network (vNetwork): Highlight the Mininet-powered virtual network that emulates real-world networking.
- Virtual Devices (vDevice): These are instantiated based on the configuration; each device interacts with the virtual network.
- Launcher Component: Within “nefics/launcher.py” (and in each module of “nefics/modules”), the launcher is responsible for initializing device emulators.
- Device Handlers and Protocols: Include the “Handler” logic that uses modules from “nefics/protos” (IEC61850, IEC10x, modbus, simproto, etc.) to map virtual memory to communication interfaces.
- Additional Components: Optionally include the “html” directory contents as a visualization or management interface, and any testing framework components (tests).

b. Relationships and Interactions:
- That each vDevice, via the launcher, imports and instantiates specific modules (device emulators) and associates with protocol handlers.
- That the device handlers manage incoming and outgoing communications, interfaced by the protocols contained under “nefics/protos”.
- Interactions such as termination signals being handled by the Handler to stop a device.

c. Architectural Patterns and Design Principles:
- Modular Design: Emphasize how the project is built around interchangeable modules (see “nefics/modules” and “nefics/protos”), making it extensible.
- Separation of Concerns: The configuration, network emulation (Mininet), device instantiation (launcher and handlers), and protocol implementations are clearly modularized.
- Emulation/Simulation Workflow: The layered process—from configuration parsing to network creation to protocol assignment—is central to the design.

d. Relevant Technologies and Frameworks:
- Python as the primary language.
- Mininet for virtual network instantiation.
- Custom protocol implementations (IEC61850, IEC10x, Modbus, etc.) for simulating industrial control communications.
- ASP/HTML/JS used for the web-based components in the “html” directory.
- Testing using unittest or similar frameworks (as indicated by the “tests” directory).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        CF1["simple_powergrid.json"]:::config
        CF2["SWaT.json"]:::config
        CF3["honeypot configs"]:::config
    end

    subgraph "Orchestration Layer"
        RS["Run Script (run.py)"]:::orchestration
    end

    subgraph "Emulation Layer"
        VN["Virtual Network (Mininet Simulation)"]:::network
        VD["Virtual Devices"]:::devices
        LC["Launcher Component"]:::launcher
        PH["Protocol Handlers"]:::protocols
    end

    subgraph "Presentation Layer"
        WI["Web Interface (HTML)"]:::web
    end

    subgraph "Testing Layer"
        TF["Testing Framework"]:::tests
    end

    %% Connections
    CF1 -->|"parses"| RS
    CF2 -->|"parses"| RS
    CF3 -->|"parses"| RS
    RS -->|"creates"| VN
    RS -->|"instantiates"| VD
    VD -->|"invokes"| LC
    LC -->|"loads"| PH
    RS -->|"updates"| WI
    TF -->|"validates"| PH
    TF -->|"monitors"| RS

    %% Click Events
    click CF1 "https://github.com/cyphysecurity/nefics/blob/master/conf/simple_powergrid.json"
    click CF2 "https://github.com/cyphysecurity/nefics/blob/master/conf/SWaT.json"
    click CF3 "https://github.com/cyphysecurity/nefics/blob/master/conf/honeypot_*.json"
    click RS "https://github.com/cyphysecurity/nefics/blob/master/run.py"
    click VD "https://github.com/cyphysecurity/nefics/tree/master/nefics/modules"
    click LC "https://github.com/cyphysecurity/nefics/blob/master/nefics/launcher.py"
    click PH "https://github.com/cyphysecurity/nefics/tree/master/nefics/protos"
    click WI "https://github.com/cyphysecurity/nefics/tree/master/html"
    click TF "https://github.com/cyphysecurity/nefics/tree/master/tests"

    %% Styles
    classDef config fill:#f9c,stroke:#333,stroke-width:2px;
    classDef orchestration fill:#ccf,stroke:#333,stroke-width:2px;
    classDef network fill:#cfc,stroke:#333,stroke-width:2px;
    classDef devices fill:#fc9,stroke:#333,stroke-width:2px;
    classDef launcher fill:#9cf,stroke:#333,stroke-width:2px;
    classDef protocols fill:#cff,stroke:#333,stroke-width:2px;
    classDef web fill:#ffc,stroke:#333,stroke-width:2px;
    classDef tests fill:#c9f,stroke:#333,stroke-width:2px;
```
