Blixtbird: A Simulation Framework for Attacks in DFL networks

Blixtbird is a modular simulation framework for Decentralized Federated Learning (DFL) networks operating under adversarial conditions. It models peer-to-peer communication using a Message Passing Interface (MPI) and currently supports normal and adversarial nodes, implementing free-rider and model poisoning attacks. The framework is built for extensibility, allowing users to easily register custom node classes and implement new attack types or defense strategies through a flexible factory-based architecture.

Prerequisites

Before installing and using Blixtbird, ensure that your system meets the following requirements:

• Operating System: Windows, macOS, or Linux
• Python Version: Python 3.11 or higher
• MPI: An installed MPI distribution. This framework was built and tested using Microsoft MPI v10.0 download link.
• Virtual Environment (Recommended): It's advisable to use a virtual environment to manage dependencies

---

Installation

Installing via pip

1. Clone the Repository:

   git clone https://github.com/yourusername/blixtbird.git
   cd blixtbird

2. Create and Activate a Virtual Environment (Optional but Recommended):

   • Windows:

     python -m venv venv
     venv\Scripts\activate

   • Unix/Linux:

     python3 -m venv venv
     source venv/bin/activate

3. Install Required Dependencies:

   Ensure you have pip updated to the latest version:

   pip install --upgrade pip

4. Install the Package in Editable Mode:

   This allows you to modify the code without reinstalling the package each time.

   pip install -e .

   Note: The setup.py is configured to install all required dependencies.

5. Verify Installation:

   After installation, the blixtbird command-line tool should be available.

   blixtbird

   Expected Output:

   ______ _     _______   _____________ _________________ 
   | ___ \ |   |_   _\ \ / /_   _| ___ \_   _| ___ \  _  \
   | |_/ / |     | |  \ V /  | | | |_/ / | | | |_/ / | | |
   | ___ \ |     | |  /   \  | | | ___ \ | | |    /| | | |
   | |_/ / |_____| |_/ /^\ \ | | | |_/ /_| |_| |\ \| |/ /
   \____/\_____/\___/\/   \/ \_/ \____/ \___/\_| \_|___/
   
   
   
   Welcome to BLIXTBIRD Shell! Type 'help' to see available commands.
   

Configuration

Blixtbird uses a config.yaml file to manage simulation parameters. Proper configuration ensures that simulations run as intended with the desired settings.

Parameters in config.yaml

Below is an explanation of the primary parameters you can configure:

simulations:
  simulation1:
    rounds: 10                  # Number of simulation rounds
    epochs: 10                  # Number of training epochs per simulation round
    num_nodes: 4                # Total number of nodes in the simulation
    node_type_map:              # Define a node class for each node id
      0: 'poison'
      1: 'base'
      2: 'freerider'
      3: 'base'
    use_attackers: true         # Flag to enable or disable attacker simulation 
    topology: fully_connected   # Network topology type
    topology_file: null         # Path to a custom topology edge list file
    max_attacks: 5              # Maximum number of attacks 
    gossip_steps: 3             # Number of gossiping steps during aggregation
    protocol: neighboring       # Aggregation protocol 
    alpha: 0.5                  # Dirichlet distribution parameter
    model_type: cnn             # Model type to use ('cnn')

Usage

Blixtbird provides a command-line interface called Blixtbird Shell to interact with the simulator. Below are instructions on how to set up and run simulations.

Using the Blixtbird Shell

1. Launch the Fenics Shell:

   blixtbird

   Sample Output:

   ______ _     _______   _____________ _________________ 
   | ___ \ |   |_   _\ \ / /_   _| ___ \_   _| ___ \  _  \
   | |_/ / |     | |  \ V /  | | | |_/ / | | | |_/ / | | |
   | ___ \ |     | |  /   \  | | | ___ \ | | |    /| | | |
   | |_/ / |_____| |_/ /^\ \ | | | |_/ /_| |_| |\ \| |/ / 
   \____/\_____/\___/\/   \/ \_/ \____/ \___/\_| \_|___/  
   
   
   Welcome to BLIXTBIRD Shell! Type 'help' to see available commands.
   
   BLIXTBIRD> 
   

2. Setup the Simulation Environment:

   Use the setup command to initialize simulation parameters defined in the configuration file.

   setup --config config.yaml --simulation_name simulation1

   Explanation:

   • --config: Specifies the path to the config.yaml file.
   • --simulation_name: Identifies which simulation parameters to load from the configuration file.

3. Run the Simulation:

   After setup, execute the simulation using the run command.

   run

   Sample Output:

   BLIXTBIRD> run
   Final Simulation Arguments:
   Rounds: 3
   Epochs: 1
   Num nodes: 3
   Node type map: {0: 'base', 1: 'base', 2: 'freerider'}
   Use attackers: True
   Max attacks: 5
   Participation rate: 0.6
   Topology: fully_connected
   Topology file: None
   Gossip steps: 3
   Protocol: neighboring
   Alpha: 0.5
   Model type: cnn
   Starting simulation...
   data saved
   
   --- Standard Output (stdout): Starting MPI---
   Node: 2 created node instance:freerider
   Node: 1 created node instance:base
   Node: 0 created node instance:base
   Node: 2 with negighbors:[0, 1], type: freerider, data_path: ./results/federated_data/node_2_train_data.pt and epochs: 1
   Node: 1 with negighbors:[0, 2], type: base, data_path: ./results/federated_data/node_1_train_data.pt and epochs: 1
   Node: 0 with negighbors:[1, 2], type: base, data_path: ./results/federated_data/node_0_train_data.pt and epochs: 1
   [Free-rider node 2] fakes training...
   [Node 1] Training for 1 epochs...
   [Node 0] Training for 1 epochs...
   

   Explanation:

   • results directory: contains plots showing network topology, data distribution and average performance of all nodes' models.
     • The partitioned data for each node is saved in federated_data.
     • The metrics folder contains detailed results after evaluating a specific node's model for the test and training dataset.
     • The (middle-man) MPI configuration created by an MPI instance is saved in mpi_config.

4. Exit the Fenics Shell:

   Use the exit or quit command to exit.

   exit

License

This project is licensed under the MIT License.

---

Authors

This framework was implemented by Gabriel Bengtsson, Zaid Haj-Ibrhaim, Piotr Krzyczkowski and Anna Lithell.

---

Acknowledgments

This project was part of a course project (DAT-300: Data-diven support for cyberphysical systems) at Chalmers University of Technology under the supervision of Romaric Duvignau and Yixing Zhang.