# jamesbinford/rustbucket architecture

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

- Interactive diagram: https://gitdiagram.com/jamesbinford/rustbucket
- Repository: https://github.com/jamesbinford/rustbucket

## Overview

##### Project Type and Purpose
- Rustbucket is a standalone, full-stack (self-contained) network honeypot written in Rust.
- It emulates multiple protocols on configurable ports, captures attacker interactions, logs them, and optionally uses the ChatGPT API to generate dynamic responses.

##### Main Components
a. Configuration Loader
– Reads Config.toml (or environment) to determine:
- Ports to monitor
- Emulated services (SMTP, HTTP, FTP, etc.)
- ChatGPT API key & prompts
- Logging targets & batch sizes
b. Network Listener & Service Registry
– “registration.rs” registers which ports/protocols to emulate
– A Tokio‐based listener accepts TCP connections on those ports
c. Protocol Handler
– “handler.rs” dispatches each connection to the correct emulator
– Emulators follow protocol state machines (e.g., SMTP handshake, HTTP responses)
– Integrates with chatgpt.rs when configured to generate dynamic replies
d. ChatGPT Integration
– “chatgpt.rs” encapsulates API calls to OpenAI
– Manages rate limits, retries, and injects prompt templates from config
e. Logging Pipeline (a modular, asynchronous pipeline)
1. Log Collector (“log_collector.rs”) gathers raw interaction data
2. Log Batcher (“log_batcher.rs”) buffers events into batches
3. Log Compressor (“log_compressor.rs”) gzips or otherwise compresses batches
4. Log Uploader (“log_uploader.rs”) writes compressed batches to disk, cloud storage, or remote API
f. Application Entry Point
– “main.rs” ties everything together, initializes the async runtime, launches listeners, and spins up the logging pipeline
g. CI / Deployment
– GitHub Actions CI (ci.yml) runs linting, tests, and build
– Dockerfile for containerized deployment

##### Relationships and Data Flows
– Config Loader → Application Entry → Network Listener & Registry
– Incoming Connection → Handler → [Emulator Logic → optional ChatGPT API call] → Handler → Log Collector
– Log Collector → Log Batcher → Log Compressor → Log Uploader → Storage (local/remote)
– Handler ←→ ChatGPT API (external service)
– The async runtime (Tokio) underpins all concurrency, allowing many connections and log‐pipeline tasks to run in parallel

##### Architectural Patterns & Principles
– Modular separation of concerns: networking, protocol logic, AI integration, and logging are distinct modules
– Async pipeline pattern for efficient, backpressured logging
– Configuration-driven design (TOML) for maximum flexibility
– Externalized service integration (ChatGPT, storage) to keep core logic lean

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Configuration Layer
  subgraph "Configuration Layer"
    Config["Config Loader\n(Config.toml)"]:::config
    ConfigEx["Example Config\n(config.toml.example)"]:::config
    Manifest["Project Manifest\n(Cargo.toml)"]:::config
  end

  %% Application Entry
  Main["App Entry Point\n(main.rs)\n(Tokio Runtime)"]:::app

  %% Networking & Emulation Layer
  subgraph "Networking & Emulation Layer"
    Prelude["Common Imports\n(prelude.rs)"]:::net
    Registration["Service Registry\n(registration.rs)"]:::net
    Listener["Network Listener\n(Tokio)"]:::net
    Handler["Protocol Handler\n(handler.rs)"]:::net
  end

  %% AI Integration Layer
  subgraph "AI Integration Layer"
    ChatGPT["ChatGPT Client\n(chatgpt.rs)"]:::ai
    API["ChatGPT API"]:::external
  end

  %% Logging Pipeline Layer
  subgraph "Logging Pipeline Layer"
    Collector["Log Collector\n(log_collector.rs)"]:::log
    Batcher["Log Batcher\n(log_batcher.rs)"]:::log
    Compressor["Log Compressor\n(log_compressor.rs)"]:::log
    Uploader["Log Uploader\n(log_uploader.rs)"]:::log
    Storage["Storage (Disk/Cloud)"]:::external
  end

  %% Deployment / CI Layer
  subgraph "Deployment / CI Layer"
    CI["GitHub Actions CI\n(ci.yml)"]:::deploy
    Docker["Docker Deployment\n(Dockerfile)"]:::deploy
  end

  %% Connections
  ConfigEx --> Config
  Config --> Main
  Manifest --> Main
  Main --> Prelude
  Main --> Registration
  Registration --> Listener
  Listener -->|"TCP connection"| Handler
  Handler -->|"dispatch to emulator"| Handler
  Handler -->|"prompt & response"| ChatGPT
  ChatGPT -->|"API call"| API
  Handler -->|"emit log event"| Collector
  Collector -.->|"async batch"| Batcher
  Batcher -.->|"async compress"| Compressor
  Compressor -.->|"async upload"| Uploader
  Uploader -->|"store logs"| Storage
  CI -->|"build/test"| Main
  CI --> Docker
  Docker -->|"deploy container"| Main

  %% Click Events
  click Config "https://github.com/jamesbinford/rustbucket/blob/main/Config.toml"
  click ConfigEx "https://github.com/jamesbinford/rustbucket/blob/main/config.toml.example"
  click Manifest "https://github.com/jamesbinford/rustbucket/blob/main/Cargo.toml"
  click Main "https://github.com/jamesbinford/rustbucket/blob/main/src/main.rs"
  click Prelude "https://github.com/jamesbinford/rustbucket/blob/main/src/prelude.rs"
  click Registration "https://github.com/jamesbinford/rustbucket/blob/main/src/registration.rs"
  click Listener "https://github.com/jamesbinford/rustbucket/blob/main/src/registration.rs"
  click Handler "https://github.com/jamesbinford/rustbucket/blob/main/src/handler.rs"
  click ChatGPT "https://github.com/jamesbinford/rustbucket/blob/main/src/chatgpt.rs"
  click Collector "https://github.com/jamesbinford/rustbucket/blob/main/src/log_collector.rs"
  click Batcher "https://github.com/jamesbinford/rustbucket/blob/main/src/log_batcher.rs"
  click Compressor "https://github.com/jamesbinford/rustbucket/blob/main/src/log_compressor.rs"
  click Uploader "https://github.com/jamesbinford/rustbucket/blob/main/src/log_uploader.rs"
  click CI "https://github.com/jamesbinford/rustbucket/blob/main/.github/workflows/ci.yml"
  click Docker "https://github.com/jamesbinford/rustbucket/tree/main/Dockerfile"

  %% Styles
  classDef config fill:#FFF4C1,stroke:#D6B656
  classDef net fill:#C8E1FF,stroke:#70A4E8
  classDef ai fill:#D5FFD5,stroke:#5EBF5E
  classDef log fill:#E0FFFF,stroke:#55C4C4
  classDef deploy fill:#F0F0F0,stroke:#B0B0B0
  classDef external fill:#F3E6FF,stroke:#A367E6,stroke-dasharray: 5 5
  classDef app fill:#FFEFD5,stroke:#E8A14B,stroke-width:2px
```
