# andy25x/ssh-honeypot architecture

> Architecture diagram of the GitHub repository andy25x/ssh-honeypot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andy25x/ssh-honeypot
- Repository: https://github.com/andy25x/ssh-honeypot

## Overview

This is an SSH honeypot with a live Flask dashboard and activity reporting. An SSH client connects to the listener, which dispatches a session handler; credential attempts are geolocated and logged, while the fake shell emulates a filesystem and captures commands. The dashboard and HTML report present persisted activity. Edges follow explicit imports, calls, or documented behavior in the supplied excerpts and SOURCE INDEX; the README is empty, so detector and threat-intelligence connections are not asserted where callers were not shown.

Main entry points: [`Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py) (SSH session handler), [`Documents/VScode-Projects/SSH-Honeypot/main.py`](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/main.py) (Application launcher), [`Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py) (Dashboard and API), [`Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py`](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py) (SSH listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["SSH capture"]
  node_main["Application launcher<br/>[main.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_server["SSH listener<br/>[server.py]"]
  node_handler["SSH session handler<br/>[handler.py]"]
  node_filesystem["Fake filesystem<br/>[filesystem.py]"]
end

subgraph group_enrichment["Session analysis"]
  node_geoip["IP geolocation<br/>[geoip.py]"]
  node_detector["Behavior detector<br/>[detector.py]"]
  node_threatintel["Threat intelligence<br/>[threat_intel.py]"]
end

subgraph group_persistence["Event storage"]
  node_logger["Structured event logger<br/>[logger.py]"]
  node_database_api["Persistence API<br/>[database.py]"]
  node_sqlite[("Activity database<br/>[honeypot.db]")]
  node_eventlog["JSONL event log<br/>[events.jsonl]"]
end

subgraph group_presentation["Monitoring and reports"]
  node_dashboard["Dashboard and API<br/>[app.py]"]
  node_template["Dashboard page<br/>[index.html]"]
  node_report["HTML activity report<br/>[report.py]"]
end

node_client(("SSH client"))
node_geo_service["ip-api.com"]
node_operator(("Dashboard user"))

node_main -->|"initializes"| node_database_api
node_main -->|"sets up"| node_logger
node_main -->|"starts"| node_server
node_main -->|"runs"| node_dashboard
node_main -->|"generates"| node_report
node_client -->|"connects to"| node_server
node_server -->|"dispatches sessions"| node_handler
node_handler -->|"looks up IP"| node_geoip
node_handler -->|"logs credentials"| node_logger
node_handler -->|"emulates shell"| node_filesystem
node_handler -.->|"records commands"| node_database_api
node_handler -.->|"logs commands"| node_logger
node_geoip -->|"queries"| node_geo_service
node_logger -->|"appends events"| node_eventlog
node_database_api -->|"reads and writes"| node_sqlite
node_dashboard -->|"queries activity"| node_database_api
node_dashboard -->|"renders"| node_template
node_operator -->|"views and exports"| node_dashboard
node_report -->|"queries activity"| node_sqlite
node_main -->|"overrides port"| node_config
node_server -->|"uses settings"| node_config
node_handler -.->|"uses settings"| node_config
node_dashboard -->|"uses settings"| node_config

click node_main "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/main.py"
click node_config "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/config.py"
click node_server "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py"
click node_handler "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py"
click node_filesystem "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/filesystem.py"
click node_geoip "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/geoip.py"
click node_detector "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/detector.py"
click node_threatintel "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/threat_intel.py"
click node_logger "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/logger.py"
click node_database_api "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/database.py"
click node_sqlite "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/data/honeypot.db"
click node_eventlog "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/data/events.jsonl"
click node_dashboard "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py"
click node_template "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/dashboard/templates/index.html"
click node_report "https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/report.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_config,node_server,node_handler,node_filesystem,node_client,node_operator toneBlue
class node_geoip,node_detector,node_threatintel toneAmber
class node_logger,node_database_api,node_sqlite,node_eventlog,node_geo_service toneMint
class node_dashboard,node_template,node_report toneRose
```

## Components

### SSH capture

- [Application launcher](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/main.py): `Documents/VScode-Projects/SSH-Honeypot/main.py`
- [Configuration](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/config.py): `Documents/VScode-Projects/SSH-Honeypot/config.py`
- [SSH listener](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py`
- [SSH session handler](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`
- [Fake filesystem](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/filesystem.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/filesystem.py`

### Session analysis

- [IP geolocation](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/geoip.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/geoip.py`
- [Behavior detector](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/detector.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/detector.py`
- [Threat intelligence](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/threat_intel.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/threat_intel.py`

### Event storage

- [Structured event logger](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/logger.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/logger.py`
- [Persistence API](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/database.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/database.py`
- [Activity database](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/data/honeypot.db): `Documents/VScode-Projects/SSH-Honeypot/data/honeypot.db`
- [JSONL event log](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/data/events.jsonl): `Documents/VScode-Projects/SSH-Honeypot/data/events.jsonl`

### Monitoring and reports

- [Dashboard and API](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py): `Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`
- [Dashboard page](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/dashboard/templates/index.html): `Documents/VScode-Projects/SSH-Honeypot/dashboard/templates/index.html`
- [HTML activity report](https://github.com/andy25x/ssh-honeypot/blob/main/Documents/VScode-Projects/SSH-Honeypot/honeypot/report.py): `Documents/VScode-Projects/SSH-Honeypot/honeypot/report.py`

### Other components

- **SSH client**
- **ip-api.com**
- **Dashboard user**

## Connections

- Application launcher → Persistence API: initializes (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- Application launcher → Structured event logger: sets up (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- Application launcher → SSH listener: starts (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- Application launcher → Dashboard and API: runs (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- Application launcher → HTML activity report: generates (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- SSH client → SSH listener: connects to (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py`)
- SSH listener → SSH session handler: dispatches sessions (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py`)
- SSH session handler → IP geolocation: looks up IP (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- SSH session handler → Structured event logger: logs credentials (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- SSH session handler → Fake filesystem: emulates shell (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- SSH session handler → Persistence API: records commands (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- SSH session handler → Structured event logger: logs commands (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- IP geolocation → ip-api.com: queries (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/geoip.py`)
- Structured event logger → JSONL event log: appends events (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/logger.py`)
- Persistence API → Activity database: reads and writes (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/database.py`)
- Dashboard and API → Persistence API: queries activity (evidence: `Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`)
- Dashboard and API → Dashboard page: renders (evidence: `Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`)
- Dashboard user → Dashboard and API: views and exports (evidence: `Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`)
- HTML activity report → Activity database: queries activity (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/report.py`)
- Application launcher → Configuration: overrides port (evidence: `Documents/VScode-Projects/SSH-Honeypot/main.py`)
- SSH listener → Configuration: uses settings (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/server.py`)
- SSH session handler → Configuration: uses settings (evidence: `Documents/VScode-Projects/SSH-Honeypot/honeypot/handler.py`)
- Dashboard and API → Configuration: uses settings (evidence: `Documents/VScode-Projects/SSH-Honeypot/dashboard/app.py`)