# 1n3/brutex architecture

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

- Interactive diagram: https://gitdiagram.com/1n3/brutex
- Repository: https://github.com/1n3/brutex

## Overview

##### Project type and purpose
- BruteX is an open-source, CLI-driven security tool that automates brute-forcing of all exposed services on a target host or network.
- It ships as a single script/executable (`brutex`), uses local wordlists, writes out “loot,” and can be packaged in Docker or installed via `install.sh`.

##### File structure
- Top-level files:
- `brutex` (the main script/entrypoint)
- `install.sh` (installer)
- `Dockerfile` (container build)
- `brutex.desktop` (desktop launcher metadata, optional GUI integration)
- `CHANGELOG.md`, `README.md` (documentation)
- Directories:
- `loot/` – where successful credentials and results are stored
- `wordlists/` – a large collection of service-specific username/password lists
- No separate “backend” or “frontend”—it’s a modular CLI tool, with each service handler embedded or loaded by the main script.

##### Extract architecture hints from the README
- Single entrypoint: `brutex target <port>`
- Support for Docker: isolate runtime in a container
- License constraints: branding must remain intact

A. User Interface (CLI)
- Component: `brutex` script/executable
- Responsibility: accepts target and port(s), orchestrates scanning & brute-force
B. Scanner/Orchestrator
- Module inside `brutex` that invokes port scanning (e.g., nmap or built-in checks)
- Determines which services are alive on each port
C. Service Brute-Force Plugins
- Sub-components: FTP, SSH, MySQL, MSSQL, PostgreSQL, SMB, SNMP, etc.
- Each plugin uses its own wordlists (pulled from `wordlists/`) and protocol logic
D. Wordlist Data Store
- Location: `wordlists/` directory
- Contains: default username/password pairs, weak/medium/hybrid lists
E. Loot Storage
- Location: `loot/` directory
- Stores: per-service subfolders or files containing successful creds
F. Environment/Packaging
- `install.sh` installs dependencies and places `brutex` in PATH
- `Dockerfile` builds a container image bundling all scripts & wordlists

##### Relationships & data flows
2. CLI calls Scanner module → scans target → returns list of open ports/services
3. For each service: CLI calls corresponding Brute-Force Plugin
4. Plugin reads appropriate wordlists from the Wordlist Data Store
5. Plugin attempts logins against target service
6. On success, Plugin writes credentials to Loot Storage
7. CLI aggregates results and prints summary to console
8. Optional: user may read files under `loot/` for raw output

##### Important architectural patterns & design principles
- Modular plugin architecture: separate brute-force logic per service
- Data-driven design: behavior determined by external wordlists
- Single responsibility: each component (scanner, orchestrator, plugin, datastore) has a clear role
- Extensibility: new service modules can be added by following plugin structure
- Environmental isolation: Docker image vs. host install via `install.sh`

##### Details
- Optional packaging paths:
- Host install via `install.sh` → places `brutex` in `/usr/local/bin`
- Docker build/run → container boundary around modules
- If desired, show version control artifacts (e.g., GitHub) to indicate where developers push/pull

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Target
    Target["Target Host/Network\n(Services: SSH, FTP, MySQL, SMB, SNMP)"]:::external

    %% BruteX System Boundary
    subgraph "BruteX System"
        direction TB
        CLI["CLI Entrypoint\n(brutex)"]:::cli
        Scanner["Scanner/Orchestrator"]:::cli
        subgraph "Plugins"
            direction TB
            FTP["FTP Plugin"]:::plugin
            SSH["SSH Plugin"]:::plugin
            MySQL["MySQL Plugin"]:::plugin
            MSSQL["MSSQL Plugin"]:::plugin
            PostgreSQL["PostgreSQL Plugin"]:::plugin
            SMB["SMB Plugin"]:::plugin
            SNMP["SNMP Plugin"]:::plugin
        end
        Wordlists["Wordlist Data Store\n(wordlists/)"]:::data
        Loot["Loot Storage\n(loot/)"]:::data
    end

    %% Packaging
    Installer["Host Installer\n(install.sh)"]:::pack
    Docker["Docker Build\n(Dockerfile)"]:::pack
    Desktop["Desktop Launcher\n(brutex.desktop)"]:::pack

    %% Documentation
    README["README.md"]:::doc
    CHANGELOG["CHANGELOG.md"]:::doc
    LootReadme["loot/README.md"]:::doc

    %% Connections
    Target -->|"open port list"| CLI
    CLI -->|"scan request"| Scanner
    Scanner -->|"services list"| CLI
    CLI -->|"dispatch"| FTP
    CLI -->|"dispatch"| SSH
    CLI -->|"dispatch"| MySQL
    CLI -->|"dispatch"| MSSQL
    CLI -->|"dispatch"| PostgreSQL
    CLI -->|"dispatch"| SMB
    CLI -->|"dispatch"| SNMP
    FTP -->|"read wordlists"| Wordlists
    SSH -->|"read wordlists"| Wordlists
    MySQL -->|"read wordlists"| Wordlists
    MSSQL -->|"read wordlists"| Wordlists
    PostgreSQL -->|"read wordlists"| Wordlists
    SMB -->|"read wordlists"| Wordlists
    SNMP -->|"read wordlists"| Wordlists
    FTP -->|"write creds"| Loot
    SSH -->|"write creds"| Loot
    MySQL -->|"write creds"| Loot
    MSSQL -->|"write creds"| Loot
    PostgreSQL -->|"write creds"| Loot
    SMB -->|"write creds"| Loot
    SNMP -->|"write creds"| Loot
    CLI -->|"print summary"| UserConsole("Console Output")
    Installer -->|"installs"| CLI
    Docker -->|"bundles"| CLI
    CLI -->|"desktop entry"| Desktop

    README --- CLI
    CHANGELOG --- CLI
    LootReadme --- Loot

    %% Click Events
    click CLI "https://github.com/1n3/brutex/tree/master/brutex"
    click Scanner "https://github.com/1n3/brutex/tree/master/brutex"
    click FTP "https://github.com/1n3/brutex/tree/master/brutex"
    click SSH "https://github.com/1n3/brutex/tree/master/brutex"
    click MySQL "https://github.com/1n3/brutex/tree/master/brutex"
    click MSSQL "https://github.com/1n3/brutex/tree/master/brutex"
    click PostgreSQL "https://github.com/1n3/brutex/tree/master/brutex"
    click SMB "https://github.com/1n3/brutex/tree/master/brutex"
    click SNMP "https://github.com/1n3/brutex/tree/master/brutex"
    click Wordlists "https://github.com/1n3/brutex/tree/master/wordlists/"
    click Loot "https://github.com/1n3/brutex/tree/master/loot/"
    click Installer "https://github.com/1n3/brutex/blob/master/install.sh"
    click Docker "https://github.com/1n3/brutex/tree/master/Dockerfile"
    click Desktop "https://github.com/1n3/brutex/blob/master/brutex.desktop"
    click README "https://github.com/1n3/brutex/blob/master/README.md"
    click CHANGELOG "https://github.com/1n3/brutex/blob/master/CHANGELOG.md"
    click LootReadme "https://github.com/1n3/brutex/blob/master/loot/README.md"

    %% Styles
    classDef cli fill:#a2f5a2,stroke:#333,stroke-width:1px;
    classDef plugin fill:#a2d2f7,stroke:#333,stroke-width:1px;
    classDef data fill:#f7f7a2,stroke:#333,stroke-width:1px;
    classDef external fill:#f7a2a2,stroke:#333,stroke-width:1px;
    classDef pack fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef doc fill:#e0e0e0,stroke:#333,stroke-width:1px;
```
