# chomnr/brute architecture

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

- Interactive diagram: https://gitdiagram.com/chomnr/brute
- Repository: https://github.com/chomnr/brute

## Overview

##### Project Overview & Type
- The project “Brute” is a multi-component system designed to monitor authentication attempts (especially in OpenSSH) and record detailed information about each attempt.
- It is composed of several interacting components written in both Rust (brute-http and brute-daemon) and C/CMake for the PAM module (brute-pam). Additionally, there’s a patched OpenSSH server that integrates with the PAM module so that authentication attempts (via SSH and potentially other protocols such as FTP) get logged.
- The HTTP server (brute-http) acts as the primary endpoint for receiving and storing attack metrics, interfacing with a PostgreSQL database (as evidenced by the DATABASE_URL setting and the migrations directory) and integrating with external APIs (like Ipinfo for geolocation).

##### Analyzing the File Structure
- Top-level directories (brute-daemon, brute-http, brute-pam) indicate the separation of core functionalities:
– brute-http: Contains the HTTP server, API endpoints (e.g., /brute/attack/add), TLS support via certificates, and modules for request validation, error handling, and system operations.
– brute-daemon: Implements the daemon for monitoring protocols (SSH, FTP) and sending payloads to the /brute/attack/add endpoint.
– brute-pam: Implements a PAM module that plugs into the OpenSSH authentication flow.
- Other directories such as docs, migrations, and patches contribute supporting documentation, database schema changes, and update patches.
- The presence of configuration files (e.g., .env.example, DockerFile) shows support for both local (non-Docker) and containerized deployments.

##### Key Components
a. External Traffic Sources:
– Authentication attempts generated via SSH (and possibly FTP).
b. OpenSSH Server (Patched):
– The custom OpenSSH that requires the patched version.
– Integration with the PAM module for authentication event logging.
c. Brute PAM Module:
– A PAM module (built in C) that is attached to the system’s PAM stack and sends authentication attempt data to further components.
d. Brute Daemon:
– A dedicated daemon application in Rust that listens on specific protocols (SSH, FTP) and then sends payloads (attack data) to the HTTP endpoint.
e. Brute HTTP Server:
– A Rust-based HTTP server that provides an API endpoint (/brute/attack/add) for accepting attack data.
– Responsible for further processing such as logging, analysis, and storing metrics.
f. External Services & Database:
– IPinfo API integration for retrieving location data.
– PostgreSQL (or another SQL database) for storing logs/metrics, supported by the migrations.

##### Relationships & Data Flow
– From the OpenSSH server and PAM triggering, authentication attempts initiate and are captured.
– The PAM module (brute-pam) intercepts these events and forwards necessary data to the brute-daemon or directly to the HTTP server.
– The brute-daemon receives events (from protocols such as SSH or FTP) and communicates with the brute-http server via the endpoint (/brute/attack/add).
– The brute-http server, after further analysis (and optionally integrating with the IPinfo API for enhanced location data), writes logs and stats into a database.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Each major component (HTTP, daemon, PAM) focuses on a core area of functionality.
- Modular & Extendable Design: Metrics and protocols are designed to be extensible – for example, developers can easily add new protocols or metrics without overhauling the entire system.
- Microservice-esque Interaction: Although parts of the system run together, there is a clear delineation between “data collection” (brute-daemon, brute-pam) and “data processing/storage” (brute-http along with the database).
- Security Considerations: Special care is required because of the integration with OpenSSH and the handling of sensitive authentication attempt data. Environment variables and TLS/SSL (configured in the certs folder) play a part here.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Traffic Sources & Authentication Infrastructure"
        OS["OpenSSH (Patched)"]
        PAM["Brute PAM Module"]
    end

    subgraph "Data Collection & Transport"
        DAEM["Brute Daemon"]
    end

    subgraph "Data Processing & API Endpoint"
        HTTP["Brute HTTP API Server"]
    end

    subgraph "Supporting Infrastructure"
        DB["PostgreSQL Database"]
        IP["IPinfo API"]
        subgraph "Deployment Config"
            ENV["Env Config"]
            DOCKER["Docker Deployment"]
        end
    end

    OS -->|"AuthEvent"| PAM
    PAM -->|"ForwardData"| DAEM
    DAEM -->|"SendsPayload"| HTTP
    ENV -->|"Configures"| HTTP
    ENV -->|"Configures"| DAEM
    DOCKER -->|"Deployment"| HTTP
    DOCKER -->|"Deployment"| DAEM
    HTTP -->|"StoresMetrics"| DB
    HTTP -->|"FetchLocation"| IP

    click PAM "https://github.com/chomnr/brute/tree/main/brute-pam"
    click DAEM "https://github.com/chomnr/brute/tree/main/brute-daemon"
    click HTTP "https://github.com/chomnr/brute/tree/main/brute-http"
    click DB "https://github.com/chomnr/brute/tree/main/migrations"
    click ENV "https://github.com/chomnr/brute/blob/main/.env.example"
    click DOCKER "https://github.com/chomnr/brute/tree/main/DockerFile"

    classDef rust fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef c_component fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef db fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#cce5ff,stroke:#333,stroke-width:2px;
    
    class DAEM,HTTP rust;
    class PAM c_component;
    class DB db;
    class IP,ENV,DOCKER external;
```
