# onionj/pybotnet architecture

> Architecture diagram of the GitHub repository onionj/pybotnet, 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/onionj/pybotnet
- Repository: https://github.com/onionj/pybotnet

## Overview

##### Main Components
- BotNet Core: At the heart is the BotNet class (located in pybotnet/botnet.py) which acts as the central orchestrator.
- Engines: Under the pybotnet/engines directory you have various engine implementations (for example, TelegramEngine in telegram_engine.py and a test engine in test_engine.py). These translate incoming commands and messages between the admin (or control panel) and the botnet.
- Scripts: Situated in the pybotnet/scripts directory are multiple default scripts (reverse shell, screenshot, keylogger, put/get file, etc.). They represent the actions your botnet can perform on a controlled system.
- Utilities: Comprising helper functions, proxies, serializers, and even third-party proxy integrations located in pybotnet/utils.
- Exception Handling & Package Info: Additional modules (like exceptions.py and package_info.py) provide support and metadata for the system.

##### Relationships and Interactions
- The BotNet Core instantiates and manages an Engine (e.g., TelegramEngine) that provides the communication interface.
- The Engine receives incoming commands (for example, through Telegram messages) and forwards these to the BotNet Core.
- BotNet then selects and invokes the appropriate script (like reverse shell, screenshot, etc.) from the scripts repository.
- Utilities (e.g., proxy or serializer modules) are used by both the Enginess and Scripts for data processing, network communication, or logging.
- The relationship between custom scripts (which can be added or imported easily) and the core engine emphasizes extensibility.

##### Architectural Patterns and Principles
- Modularity: Each major feature is separated into distinct modules (engines, scripts, utilities) which enables maintainability and extensibility.
- Plug-In Architecture: The use of engine and script classes indicates that the system is designed to allow custom extensions (for instance swapping the Telegram engine with an alternative custom control panel).
- Clear Separation of Concerns: The core BotNet functionality, engine interface, and script functionalities are well-isolated.

- "Telegram Engine" receiving commands and passing them onto the "BotNet Core".
- The "BotNet Core" should then be split out into:
- A controller for managing client connections.
- An interface with the "Scripts Module" (listing scripts like reverse_shell, screenshot, keylogger, etc.).
- An "Utilities" block connected to both the Engine and Scripts for shared services like proxy handling and serialization.
- Optionally, add supporting components like configuration files or installation scripts to show the deployment side—though these are secondary to the runtime architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        Admin["User/Administrator"]:::admin
    end

    %% Engines
    subgraph "Engines"
        TelegramEngine["Communication Engine (TelegramEngine)"]:::engine
        TestEngine["Additional Engine (TestEngine)"]:::engine
    end

    %% Core System
    subgraph "Core System"
        BotNetCore["BotNet Core"]:::core
    end

    %% Runtime Scripts
    subgraph "Runtime Scripts"
        Scripts["Scripts Module"]:::script
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        Utilities["Utilities & Helpers"]:::utility
    end

    %% Support Modules
    subgraph "Support Modules"
        Exception["Exception Handling"]:::support
        Package["Package Info"]:::support
    end

    %% Deployment & Configurations
    subgraph "Deployment & Configurations"
        Config["Config Sample"]:::deployment
        Deployment["Deployment Scripts"]:::deployment
    end

    %% Connections
    Admin -->|"sendsCommand"| TelegramEngine
    TelegramEngine -->|"forwardsCommand"| BotNetCore
    BotNetCore <-->|"feedback"| TelegramEngine
    BotNetCore -->|"executesScript"| Scripts
    TelegramEngine -->|"usesUtilities"| Utilities
    Scripts -->|"usesUtilities"| Utilities
    BotNetCore -->|"handlesExceptions"| Exception
    BotNetCore -->|"readsPackageInfo"| Package
    BotNetCore -->|"usesConfig"| Config
    BotNetCore -->|"deploysVia"| Deployment
    TestEngine -.->|"alternativeEngine"| BotNetCore

    %% Click Events
    click BotNetCore "https://github.com/onionj/pybotnet/blob/master/pybotnet/botnet.py"
    click TelegramEngine "https://github.com/onionj/pybotnet/blob/master/pybotnet/engines/telegram_engine.py"
    click TestEngine "https://github.com/onionj/pybotnet/blob/master/pybotnet/engines/test_engine.py"
    click Scripts "https://github.com/onionj/pybotnet/tree/master/pybotnet/scripts/"
    click Utilities "https://github.com/onionj/pybotnet/tree/master/pybotnet/utils/"
    click Exception "https://github.com/onionj/pybotnet/blob/master/pybotnet/exceptions.py"
    click Package "https://github.com/onionj/pybotnet/blob/master/pybotnet/package_info.py"
    click Config "https://github.com/onionj/pybotnet/blob/master/configs.py.sample"
    click Deployment "https://github.com/onionj/pybotnet/tree/master/Makefile"

    %% Styles
    classDef admin fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef engine fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef script fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef utility fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef support fill:#F7DC6F,stroke:#B7950B,stroke-width:2px;
    classDef deployment fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
```
