# pointedsec/couragethehoneypot architecture

> Architecture diagram of the GitHub repository pointedsec/couragethehoneypot, 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/pointedsec/couragethehoneypot
- Repository: https://github.com/pointedsec/couragethehoneypot

## Overview

##### Project Type and Purpose
- The project is a security honeypot tool with two main parts:
- A Python-powered SSH honeypot component (located under the “honeypot” directory) that listens for SSH connections (default on port 2222, with options to change it to port 22) and captures attacker activity.
- A dashboard built with Next.js (located in the “web” directory) that provides a web interface where an administrator can log in, view attack statistics (using interactive charts), and manage settings (like changing the default admin password).
- It uses Docker for deployment (via docker-compose.yml) and integrates a lightweight SQLite database (accessed via Prisma, as seen by “web/prisma/schema.prisma”) to store recorded events.

##### Main Components and Their Roles
- External Actors:
- Attackers: These connect via SSH to the honeypot.
- Admin Users: They access the dashboard interface.
- Honeypot Service (Python):
- Contains Python scripts such as main.py for executing the honeypot logic.
- Has supporting files like create_database.py to setup or initialize the SQLite database and key files (server.key, server.pub) for SSH encryption.
- Uses Dockerfile and entrypoint.sh for container startup and configuration.
- Dashboard Service (Next.js):
- Provides the frontend UI and API endpoints. Files under “web/src/app”, “web/src/pages/api”, and various React components define the visual presentation and business logic.
- Contains middleware folders and utility modules that help manage session authentication and database checks.
- Contains configuration files (like next.config.ts, tailwind.config.ts, and tsconfig.json) which hint at the use of Tailwind CSS and TypeScript.
- Database:
- Implements a SQLite database (configured via Prisma as seen in “web/prisma/schema.prisma”) used to store and query honeypot logs.
- The README warns about SQLite’s simultaneous connection limitations and explains that a timeout has been implemented.
- Docker Infrastructure:
- docker-compose.yml orchestrates multiple containers (one for the honeypot and one for the dashboard).
- Both the “honeypot” and “web” directories include individual Dockerfiles, making them container-ready components.

##### Relationships and Interactions
- Incoming SSH connections (from attackers) hit the Honeypot Service. The honeypot processes authentication attempts, potentially using Groq-based AI responses as noted in the README.
- The Honeypot Service logs captured data (e.g., login attempts, session details) into the local SQLite database.
- The Dashboard Service, through its API endpoints, interacts with the SQLite database via Prisma. It queries, analyzes, and visualizes the stored data.
- Admin Users interact with the Dashboard Service (via a web browser) to view statistics, manage sessions, and even generate new password hashes using API endpoints like /api/generateNewHash.
- Docker ensures that both containers communicate within the same network environment, aligning with the project’s design for easy deployment.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is distinctly split into a security honeypot (backend service capturing data) and a dashboard (frontend service for data visualization and management).
- Containerization: Each service is built and deployed in its own Docker container, promoting isolation and scalability.
- API-Based Communication: The Next.js dashboard uses API routes (within “web/src/pages/api”) to fetch or modify data, indicating a RESTful or modular API structure.
- Use of Middleware: In the dashboard project, middleware files (e.g., withAuthMiddleware.ts, chain.ts) indicate that the application employs layered security and input validation strategies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    EX1["Attackers (SSH Clients)"]:::external
    EX2["Admin Users"]:::external

    %% Docker Compose Orchestration
    DC["Docker Compose Orchestration"]:::docker
    DC1["docker-compose.yml"]:::docker

    %% Honeypot Container
    subgraph "Honeypot Container"
        HP["SSH Honeypot (Python Service)"]:::backend
        HP1["main.py"]:::backend
        HP2["create_database.py"]:::backend
        HP7["server.key"]:::backend
        HP8["server.pub"]:::backend
        HP4["entrypoint.sh"]:::backend
        HP5["Dockerfile"]:::backend
        HP6["requirements.txt"]:::backend
    end

    %% Dashboard Container
    subgraph "Dashboard Container"
        DASH["Dashboard (Next.js)"]:::frontend
        subgraph "Dashboard Configuration"
            DCFG1["next.config.ts"]:::frontend
            DCFG2["package.json"]:::frontend
        end
        DASH2["Next.js Frontend (src/app)"]:::frontend
        DASH3["API Endpoints (src/pages/api)"]:::frontend
        DASH4["Middleware (src/middlewares)"]:::frontend
        DASH5["Prisma Setup (schema.prisma)"]:::frontend
    end

    %% Shared Database
    DB["SQLite Database (Prisma)"]:::db

    %% Relationships
    EX1 -->|"SSHConnection"| HP
    HP -->|"Logs"| DB
    DASH -->|"Queries/Updates"| DB
    EX2 -->|"BrowserAccess"| DASH
    DC --> HP
    DC --> DASH
    DC --> DC1

    %% Internal component associations inside Honeypot Container
    HP --- HP1
    HP --- HP2
    HP --- HP7
    HP --- HP8
    HP --- HP4
    HP --- HP5
    HP --- HP6

    %% Internal component associations inside Dashboard Container
    DASH --- DCFG1
    DASH --- DCFG2
    DASH --- DASH2
    DASH --- DASH3
    DASH --- DASH4
    DASH --- DASH5

    %% Click Events for Honeypot Service
    click HP1 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/main.py"
    click HP2 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/create_database.py"
    click HP7 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/server.key"
    click HP8 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/server.pub"
    click HP4 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/entrypoint.sh"
    click HP5 "https://github.com/pointedsec/couragethehoneypot/tree/main/honeypot/Dockerfile"
    click HP6 "https://github.com/pointedsec/couragethehoneypot/blob/main/honeypot/requirements.txt"

    %% Click Events for Dashboard Service
    click DCFG1 "https://github.com/pointedsec/couragethehoneypot/blob/main/web/next.config.ts"
    click DCFG2 "https://github.com/pointedsec/couragethehoneypot/blob/main/web/package.json"
    click DASH2 "https://github.com/pointedsec/couragethehoneypot/tree/main/web/src/app"
    click DASH3 "https://github.com/pointedsec/couragethehoneypot/tree/main/web/src/pages/api"
    click DASH4 "https://github.com/pointedsec/couragethehoneypot/tree/main/web/src/middlewares"
    click DASH5 "https://github.com/pointedsec/couragethehoneypot/blob/main/web/prisma/schema.prisma"

    %% Click Event for Docker Compose
    click DC1 "https://github.com/pointedsec/couragethehoneypot/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#ffccff,stroke:#ff66cc,stroke-width:2px;
    classDef backend fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#e6f9ff,stroke:#007acc,stroke-width:2px;
    classDef db fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef docker fill:#e6ffe6,stroke:#009933,stroke-width:2px;
```
