# beefproject/beef architecture

> Architecture diagram of the GitHub repository beefproject/beef, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beefproject/beef
- Repository: https://github.com/beefproject/beef

## Overview

##### Main Components
- Core Server/Backend:
– Represent the core Ruby-based backend, including components in the “core” directory.
– Highlight modules like API handling (core/api.rb and related subdirectories), the network stack (core/main/network_stack), migration and database initialization scripts (core/main/ar-migrations), and the main command/handler logic (core/main/console, core/main/model.rb).
- Client-Side Browser Hook:
– Identify the client scripts delivered when a browser is hooked. These reside under “core/main/client” (including beef.js, are.js, browser.js, and the various helper libraries).
– Indicate that these scripts run in a target’s web browser, establishing a communication channel back to the server.
- Modules and Extensions:
– Show the “modules” directory that includes various command modules split by category (e.g., browser modules, host modules, network modules, exploits, etc.).
– Include the “extensions” directory which houses pluggable components such as the Admin UI, DNS, proxy, metasploit integration, and others. These extensions provide additional functionality and enhance the core framework.
- External Interfaces & Dependencies:
– Database: SQLite (used via migration and model files) for storing hooked browser data, logs, commands, etc.
– External Tools & Environment: Ruby interpreter (version 3.0+), Node.js (for parts of the admin or other scripts), as well as operating system dependencies (Linux/Mac OS).
– Docker & Deployment: Note the presence of Dockerfile, .dockerignore, and configuration files which indicate containerized deployment options.

##### Relationships and Interactions
- Communication Flow:
– Detail how commands dispatched on the server side (via the REST or API modules) reach the client scripts.
- Data Layer:
– Illustrate the database where logged data, command executions, rule definitions (found in “core/main/models” and “core/main/ar-migrations”), and other state information are stored.
- Modular Architecture:
– Include separate nodes for the extensions (each extension can be drawn as a plug-in into the core system) and for the individual modules that execute specific command functions.
– Highlight how requests, logs, and responses flow among these components.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– The project separates client code (JavaScript) from server-side logic (Ruby), with a clear API boundary.
- Pluggability/Modularity:
– Both the “modules” and “extensions” directories illustrate a modular design where additional functionality can be added or updated independently.
- RESTful and WebSocket Communication:
– The existence of “core/main/rest” and “core/main/network_stack/websocket” indicates that the system leverages REST APIs and WebSockets for communications between components.

##### Relevant Technologies and Libraries
- Ruby & Rails-like Components:
– The core framework is built in Ruby using standard Ruby programming practices.
- JavaScript Libraries:
– Client-side libraries like jQuery, evercookie.js, and other utility JavaScript files under “core/main/client/lib” play a critical role.
- Database & OS Dependencies:
– SQLite and Node.js are also part of the technological stack.
- Supporting Tools:
– There is integration with Docker (via Dockerfile) and external test suites reflected in “spec” and “test” directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side Component
    subgraph "Client Side"
        ClientHook["Hooked Browser (Client Scripts)"]:::client
    end

    %% Server Side Components
    subgraph "Server Side"
        CoreServer["Core Server (Ruby Backend)"]:::server
        subgraph "Subsystems"
            cs1["API Handling"]:::server
            cs2["Network Stack (WebSockets)"]:::server
            cs3["Command & Handler Logic"]:::server
            cs4["Migrations & DB Init"]:::server
            cs5["Configuration & Models"]:::server
        end
        CoreServer --> cs1
        cs1 -->|"routes"| cs2
        cs2 -->|"processes"| cs3
        cs4 -->|"initializes"| DB
        cs5 -->|"manages"| DB
        cs3 -->|"invokes"| Modules
        cs3 -->|"invokes"| Extensions
        cs3 -->|"stores_logs"| DB
    end

    %% Modules and Extensions
    subgraph "Modules & Extensions"
        Modules["Modules (Command Modules)"]:::modules
        Extensions["Extensions (Plugins & Add-ons)"]:::modules
    end

    %% Database Component
    DB(["SQLite Database"]):::external

    %% External Dependencies
    subgraph "External Dependencies"
        Ruby["Ruby Interpreter"]:::external
        Node["Node.js Environment"]:::external
        Docker["Docker Environment"]:::external
    end

    %% Communication Flows
    ClientHook -->|"HTTP/REST/WebSocket"| cs1
    Ruby --> CoreServer
    Docker --> CoreServer
    Node --> Extensions

    %% Styles
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef server fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef modules fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events
    click CoreServer "https://github.com/beefproject/beef/tree/master/core/"
    click ClientHook "https://github.com/beefproject/beef/tree/master/core/main/client/"
    click Modules "https://github.com/beefproject/beef/tree/master/modules/"
    click Extensions "https://github.com/beefproject/beef/tree/master/extensions/"
```
