How chomnr/brute works
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.