# d6falcon/gcphoneytrap architecture

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

- Interactive diagram: https://gitdiagram.com/d6falcon/gcphoneytrap
- Repository: https://github.com/d6falcon/gcphoneytrap

## Overview

##### Project Type & Purpose
- This is a specialized honeypot system that fakes a Linux environment over SSH. Its purpose is to deceive potential attackers by simulating a real server environment, capturing user inputs, generating convincing responses through an AI backend, and logging everything for forensic analysis.
- The README makes it clear the system’s “backend” drives the simulated environment based on a configurable prompt.

##### File Structure
- Top-Level Files: The repository includes configuration (LICENSE, .gitignore, requirements.txt, TODO.txt, README.md) and an SSH directory.
- SSH Directory: Contains key simulation files –
- ssh_server.py: The main script launching the honeypot’s SSH server.
- config.ini.TEMPLATE: A template for configuring the honeypot (LLM backend settings, user accounts).
- prompt.txt: Contains the system prompt that instructs the simulated environment.
- This clear separation shows that the core of the application is centered around the SSH module that integrates with the LLM backend, while the rest of the project provides configuration and documentation.

##### Main Components
a. SSH Server Component:
- SSH server (hosted via ssh_server.py) that listens for incoming connections.
- Authentication modules checking usernames and passwords (as set up in the config.ini file).
b. LLM Simulation Engine:
- An “AI/LLM Backend” component that receives the configured prompt (from prompt.txt) and generates simulated responses.
c. Logger/Session Manager:
- A logging component that captures session details like connection events, user inputs (base64 encoded), AI responses, and summary judgement.
- This component writes logs to a file (default: SSH/ssh_log.log) in JSON lines format.
d. Configuration & Customization:
- Configuration files (config.ini and prompt.txt) as setup and customization points that tailor system behavior.
e. Client (Attacker Simulation):
- SSH client side that connects to the honeypot to simulate interaction. This is the external point of entry generating the connection and command events.

##### Relationships and Interactions
- Log events (connections, user inputs, LLM responses, session summaries) from different parts flow into the Log/Session Manager component.

##### Architectural Patterns & Technologies
- The design follows a modular architecture where the SSH server, configuration management, LLM integration, and logging are separate concerns.
- That even though this is a proof-of-concept, proper separation of components (input handling, AI backend processing, and logging) not only makes it easier to test but also to upgrade or extend.
- That the system is implemented entirely in Python3 and leverages standard libraries along with AI modules (accessed via environment variables like OPENAI_API_KEY) for LLM responses.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend
    subgraph "Frontend"
        Client["SSH Client (Attacker)"]:::client
    end

    %% Configuration
    subgraph "Configuration Settings"
        Config1["config.ini.TEMPLATE"]:::config
        Config2["prompt.txt"]:::config
    end

    %% Backend Components
    subgraph "Backend Components"
        SSH_Server["SSH Server – Connection & Session Handler"]:::server
        LLM["LLM Simulation Engine"]:::llm
        Logger["Logging / Session Manager"]:::logger
        Env["OPENAI_API_KEY (Env Var)"]:::env
    end

    %% Connections
    Client -->|"connects"| SSH_Server
    Config1 -->|"configures"| SSH_Server
    Config2 -->|"providesPrompt"| LLM
    Env -->|"authenticates"| LLM
    SSH_Server -->|"forwardsCommand"| LLM
    LLM -->|"returnsResponse"| SSH_Server
    SSH_Server -->|"logsSession"| Logger

    %% Styles
    classDef client fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef server fill:#7FB3D5,stroke:#000,stroke-width:2px;
    classDef llm fill:#ABEBC6,stroke:#000,stroke-width:2px;
    classDef logger fill:#D2B4DE,stroke:#000,stroke-width:2px;
    classDef config fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef env fill:#D7DBDD,stroke:#000,stroke-width:2px;

    %% Click Events
    click SSH_Server "https://github.com/d6falcon/gcphoneytrap/blob/main/SSH/ssh_server.py"
    click Config1 "https://github.com/d6falcon/gcphoneytrap/blob/main/SSH/config.ini.TEMPLATE"
    click Config2 "https://github.com/d6falcon/gcphoneytrap/blob/main/SSH/prompt.txt"
```
