3. How it works

3.1 Project structure

flowchart TD
    A[launcher.sh] -->|run main.py| B
    B[python/main.py]
    C[machines-startup-script] -->|used from| B
    D[machines-configurations] -->|used from| B
    C1[backbone] --> C
    C2[lan_a] --> C
    C3[...] --> C
    C4[lan_o] --> C
    C11[nat64] --> C1
    C12[...] --> C1
    C13[fw] --> C1
    D1[bind1] --> D
    D2[...] --> D
    D3[wsn] --> D

Loading

3.1.1 Launcher

The launcher.sh script automates the setup and prepares the host environment, updates local network configurations, cleans old lab instances, and finally runs the main Python orchestrator.

1. Adding Tayga route - Ensures the 172.17.0.128/25 route via 172.17.0.2 exists for NAT64 connectivity.
2. Updating /etc/hosts - Adds internal domain mappings (e.g., theboys.it) for local name resolution.
3. Cleaning environment - Runs kathara wipe -f to reset any previous lab state.
4. Starting the lab - Executes python3 python/main.py to deploy and configure all virtual machines and networks.

3.1.2 Python Component Overview

The Python component of the project is responsible for the creation, configuration, and deployment of the virtual network using the Kathará Framework. This part of the system is fully modular — each network segment and service is implemented as an independent Python module, allowing easy customization, extension, and maintenance.

• main.py - The central orchestrator
  Initializes the Kathará environment, enables IPv6, imports network modules (e.g., lan_A, lan_B, backbone), and deploys the full lab.
  It also prints a summary of network interfaces and connected machines for quick topology verification.

• LAN Modules - (e.g., lan_A.py, lan_B.py, lan_C.py) Define the structure and nodes of each network segment, specifying machine images, MAC/IP addresses, startup scripts and machine onfigurations.

  • Example of how create machine

      machine = lab.new_machine("machine_name", image="docker_image") 

  • Example of how load machine startup script

    lab.create_startup_file_from_path(machine, "machines_startup_script/machine.sh")

  • Example of how load machine configuration

    lab.get_machine("machine_name").copy_directory_from_path("machines_configurations/path", "/path_machine")

• meta.py Contains the shared lab object and metadata used by all network modules.

3.1.3 Files

This section describes the directories that store the scripts and configuration files used to initialize and configure the machines within the system.

• machines_startup_script/ Stores the startup scripts executed by each machine when launched (e.g., service initialization, routing setup). Each machine has its own subdirectory containing the corresponding bash scripts.

• machines_configurations/ Stores configuration files for machine daemonsdemons (e.g., /etc/bind, /etc/rsyslog), which are copied into containers to apply service-specific settings.

3.2 Docker Images

All the Docker images used in Beeware can be found at the following link: Docker Hub - theb0ys. The Dockerfiles are in the DockerBuild directory. Here is a list of available Docker images:

• theb0ys/apache: A docker image with apache server web.

• theb0ys/base: A base Docker image that includes essential tools and utilities used by the other images.

• theb0ys/bind: A docker image with bind as DNS server.

• theb0ys/dns64: A DNS server for translating IPv4 addresses to IPv6.

• theb0ys/mariadb: A docker image with maridb serer.

• theb0ys/nginx: A docker image with nxig use as web server.

• theb0ys/nat64: A docker image running Tayga, used to provide NAT64 translation between IPv6 and IPv4 networks.

• theb0ys/oldap: A docker image implementing the Lightweight Directory Access Protocol (LDAP), used for managing and accessing directory information.

• theb0ys/postfix-dovecot: A docker image with combined email solution with Postfix for mail delivery and Dovecot for retrieval.

• theb0ys/red-hornet: A docker image wirth tools for pensting or used for network or application monitoring...

• theb0ys/rsyslog: A docker image providing a high-performance system for logging messages in Unix-like environments.

• theb0ys/samba: A docker image providing Samba, a software suite that enables file and printer sharing between different operating systems.

• theb0ys/suricata: A docker image running Suricata, an intrusion detection and prevention system for monitoring network traffic.

• theb0ys/ubuntu-desktop: A complete desktop environment for the Ubuntu operating system, suitable for personal use and development.

Each image can be tagged in two different ways:

• latest - the general/latest version of the service.
• CVE-XXXX-XXXXX - a version containing a specific vulnerability, identified by its CVE number.

3.3 Deploy of lab

1. Run ./pull-images.sh to download and install the necessary Docker images.
2. Run ./launcher.sh to start the lab environment. This script creates all the containers; depending on your system, the complete deployment may take up to one minute. Monitor the script output for progress and any potential errors.

Warning Remember to run /launcher.sh as root because you need elevated privileges to start certain containers in --privileged mode, such as NAT64. This is essential for ensuring proper network functionality and access to restricted operations.

3.4 Tips and tricks

• To test individual containers without opening an interactive shell, you can pipe the script network-test.sh into the container like this: cat network-test.sh | docker exec -i <container-name> bash

• To run tests for particular LANs, open python/main.py and comment out any import statements for modules you do not wish to include in the current run. Leave the backbone import active at all times because it represents the network’s core/dorsal topology.