How pointedsec/couragethehoneypot works
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.