Bjorn/ARCHITECTURE.md

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:

/
├── 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?