From d3b0b02a0b01f1cbd5f7e6403a2840e82d537e21 Mon Sep 17 00:00:00 2001 From: Fabien POLLY Date: Wed, 10 Dec 2025 16:39:59 +0100 Subject: [PATCH] feat: Added ARCHITECTURE.md file --- web_utils/ARCHITECTURE.md | 148 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 web_utils/ARCHITECTURE.md diff --git a/web_utils/ARCHITECTURE.md b/web_utils/ARCHITECTURE.md new file mode 100644 index 0000000..bf5e464 --- /dev/null +++ b/web_utils/ARCHITECTURE.md @@ -0,0 +1,148 @@ + +# Bjorn Cyberviking Architecture + +This document describes the internal workings of **Bjorn Cyberviking**. +> The architecture is designed to be **modular and asynchronous**, using multi-threading to handle the display, web interface, and cyber-security operations (scanning, attacks) simultaneously. + +----- + +## 1\. High-Level Overview + +The system relies on a **"Producer-Consumer"** model orchestrated around shared memory and a central database. + +### System Data Flow + + * **User / WebUI**: Interacts with the `WebApp`, which uses `WebUtils` to read/write to the **SQLite DB**. + * **Kernel (Main Thread)**: `Bjorn.py` initializes the `SharedData` (global state in RAM). + * **Brain (Logic)**: + * **Scheduler**: Plans actions based on triggers and writes them to the DB. + * **Orchestrator**: Reads the queue from the DB, executes scripts from `/actions`, and updates results in the DB. + * **Output (Display)**: `Display.py` reads the current state from `SharedData` and renders it to the E-Paper Screen. + +----- + +## 2\. Core Components + +### 2.1. The Entry Point (`Bjorn.py`) + +This is the global conductor. + + * **Role**: Initializes components, manages the application lifecycle, and handles stop signals. + * **Workflow**: + 1. Loads configuration via `SharedData`. + 2. Starts the display thread (`Display`). + 3. Starts the web server thread (`WebApp`). + 4. **Network Monitor**: As soon as an interface (Wi-Fi/Eth) is active, it starts the **Orchestrator** thread (automatic mode). If the network drops, it can pause the orchestrator. + +### 2.2. Central Memory (`shared.py`) + +This is the backbone of the program. + + * **Role**: Stores the global state of Bjorn, accessible by all threads. + * **Content**: + * **Configuration**: Loaded from the DB (`config`). + * **Runtime State**: Current status (`IDLE`, `SCANNING`...), displayed text, indicators (wifi, bluetooth, battery). + * **Resources**: File paths, fonts, images loaded into RAM. + * **Singleton DB**: A unique instance of `BjornDatabase` to avoid access conflicts. + +### 2.3. Persistent Storage (`database.py`) + +A facade (wrapper) for **SQLite**. + + * **Architecture**: Delegates specific operations to sub-modules (in `db_utils/`) to keep the code clean (e.g., `HostOps`, `QueueOps`, `VulnerabilityOps`). + * **Role**: Ensures persistence of discovered hosts, vulnerabilities, the action queue, and logs. + +----- + +## 3\. The Operational Core: Scheduler vs Orchestrator + +This is where Bjorn's "intelligence" lies. The system separates **decision** from **action**. + +### 3.1. The Scheduler (`action_scheduler.py`) + +*It "thinks" but does not act.* + + * **Role**: Analyzes the environment and populates the queue (`action_queue`). + * **Logic**: + * It loops regularly to check **Triggers** defined in actions (e.g., `on_new_host`, `on_open_port:80`, `on_interval:600`). + * If a condition is met (e.g., a new PC is discovered), it inserts the corresponding action into the database with the status `pending`. + * It manages priorities and avoids duplicates. + +### 3.2. The Orchestrator (`orchestrator.py`) + +*It acts but does not deliberate on strategic consequences.* + + * **Role**: Consumes the queue. + * **Logic**: + 1. Requests the next priority action (`pending`) from the DB. + 2. Dynamically loads the corresponding Python module from the `/actions` folder (via `importlib`). + 3. Executes the `run()` or `execute()` method of the action. + 4. Updates the result (`success`/`failed`) in the DB. + 5. Updates the status displayed on the screen (via `SharedData`). + +----- + +## 4\. User Interface + +### 4.1. E-Ink Display (`display.py` & `epd_manager.py`) + + * **EPD Manager**: `epd_manager.py` is a singleton handling low-level hardware access (SPI) to prevent conflicts and manage hardware timeouts. + * **Rendering**: `display.py` constructs the image in memory (**PIL**) by assembling: + * Bjorn's face (based on current status). + * Statistics (skulls, lightning bolts, coins). + * The "catchphrase" (generated by `comment.py`). + * **Optimization**: Uses partial refresh to avoid black/white flashing, except for periodic maintenance. + +### 4.2. Web Interface (`webapp.py`) + + * **Server**: A custom multi-threaded `http.server` (no heavy frameworks like Flask/Django to ensure lightness). + * **Architecture**: + * API requests are dynamically routed to `WebUtils` (`utils.py`). + * The frontend communicates primarily in **JSON**. + * Handles authentication and GZIP compression of assets. + +### 4.3. The Commentator (`comment.py`) + +Provides Bjorn's personality. It selects phrases from the database based on context (e.g., *"Bruteforcing SSH..."*) and the configured language, with a weighting and delay system to avoid spamming. + +----- + +Voici la section mise à jour avec le flux logique pour une attaque SSH sur le port 22 : + +*** + +## 5. Typical Data Flow (Example) + +Here is what happens when Bjorn identifies a vulnerable service: + +1. **Scanning (Action)**: The Orchestrator executes a scan. It discovers IP `192.168.1.50` has **port 22 (SSH) open**. +2. **Storage**: The scanner saves the host and port status to the DB. +3. **Reaction (Scheduler)**: In the next cycle, the `ActionScheduler` detects the open port. It checks actions that have the `on_open_port:22` trigger. +4. **Planning**: It adds the `SSHBruteforce` action to the `action_queue` for this IP. +5. **Execution (Orchestrator)**: The Orchestrator finishes its current task, sees the `SSHBruteforce` in the queue, picks it up, and starts the dictionary attack. +6. **Feedback (Display)**: `SharedData` is updated. The screen displays *"Cracking 192.168.1.50"* with the corresponding face. +7. **Web**: The user sees the attack attempt and real-time logs on the web dashboard. + +*** + +**Would you like me to create a diagram to illustrate this specific attack flow?** +----- + +## 6\. Folder Structure + +Although not provided here, the architecture implies this structure: + +```text +/ +├── Bjorn.py # Root program entry +├── orchestrator.py # Action consumer +├── shared.py # Shared memory +├── actions/ # Python modules containing attack/scan logic (dynamically loaded) +├── data/ # Stores bjorn.db and logs +├── web/ # HTML/JS/CSS files for the interface +└── resources/ # Images, fonts (.bmp, .ttf) +``` + +----- + +**Would you like me to generate a Mermaid.js diagram code block (Flowchart) to visualize the Scheduler/Orchestrator loop described in section 3?** \ No newline at end of file