# mrzkexe/melisis architecture

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

## Overview

Melisis is an SSH honeypot: network clients connect to a configurable listener, are handled according to one of four modes, and may be deceived, given a fake shell, or banned. The main runtime path is visible in the sampled Go sources. The README additionally documents systemd operation and Fail2Ban monitoring/configuration; source excerpts show Fail2Ban files being generated, but not the daemon’s runtime behavior. Shell command and ban logs are distinct outputs.

Main entry points: [`melisis/main.go`](https://github.com/mrzkexe/melisis/blob/main/melisis/main.go) (Mode router), [`melisis/honeypot.go`](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go) (SSH trap), [`melisis/writeban.go`](https://github.com/mrzkexe/melisis/blob/main/melisis/writeban.go) (Ban logger), [`melisis/highprotection.go`](https://github.com/mrzkexe/melisis/blob/main/melisis/highprotection.go) (High-protection mode)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_app["App startup<br/>[main.go]"]
  node_listener["TCP listener<br/>[main.go]"]
  node_router["Mode router<br/>[main.go]"]
  node_mode_domain["Modes and IPs<br/>[domain.go]"]
end

subgraph group_ssh["SSH deception"]
  node_ssh_trap["SSH trap<br/>[honeypot.go]"]
  node_auth["Login deception<br/>[honeypot.go]"]
  node_channels["Session channels<br/>[honeypot.go]"]
  node_terminal["Fake terminal<br/>[honeypot.go]"]
  node_commands["Command responses<br/>[honeypot.go]"]
end

subgraph group_protection["Blocking and bans"]
  node_shield["High-protection mode<br/>[highprotection.go]"]
  node_ban_logger["Ban logger<br/>[writeban.go]"]
  node_dependency_setup["Fail2Ban setup<br/>[fail2ban.go]"]
  node_fail2ban_configs["Fail2Ban rules<br/>[fail2ban.go]"]
end

subgraph group_operations["Configuration and monitoring"]
  node_config["Runtime config<br/>[main.go]"]
  node_command_log[("Command log<br/>[honeypot.go]")]
  node_ban_log[("Ban log<br/>[writeban.go]")]
end

node_client(("SSH client"))
node_fail2ban["Fail2Ban"]
node_systemd["systemd service"]

node_app -->|"checks dependencies"| node_dependency_setup
node_app -->|"loads settings"| node_config
node_app -->|"starts listener"| node_listener
node_listener -->|"routes connections"| node_router
node_client -.->|"connects to"| node_listener
node_router -->|"checks mode"| node_mode_domain
node_router -->|"dispatches mode 0"| node_shield
node_router -->|"dispatches other modes"| node_ssh_trap
node_ssh_trap -->|"checks password"| node_auth
node_ssh_trap -->|"processes channels"| node_channels
node_channels -->|"starts shell"| node_terminal
node_terminal -->|"generates replies"| node_commands
node_commands -->|"writes commands"| node_command_log
node_terminal -->|"bans on disconnect"| node_ban_logger
node_ssh_trap -->|"records failed sessions"| node_ban_logger
node_shield -->|"registers ban"| node_ban_logger
node_ban_logger -->|"writes record"| node_ban_log
node_dependency_setup -->|"creates rules and filters"| node_fail2ban_configs
node_fail2ban -->|"uses configured rules"| node_fail2ban_configs
node_fail2ban -->|"monitors ban log"| node_ban_log
node_systemd -->|"starts service"| node_app

click node_app "https://github.com/mrzkexe/melisis/blob/main/melisis/main.go"
click node_config "https://github.com/mrzkexe/melisis/blob/main/melisis/main.go"
click node_listener "https://github.com/mrzkexe/melisis/blob/main/melisis/main.go"
click node_router "https://github.com/mrzkexe/melisis/blob/main/melisis/main.go"
click node_mode_domain "https://github.com/mrzkexe/melisis/blob/main/melisis/domain.go"
click node_ssh_trap "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_auth "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_channels "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_terminal "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_commands "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_command_log "https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go"
click node_shield "https://github.com/mrzkexe/melisis/blob/main/melisis/highprotection.go"
click node_ban_logger "https://github.com/mrzkexe/melisis/blob/main/melisis/writeban.go"
click node_ban_log "https://github.com/mrzkexe/melisis/blob/main/melisis/writeban.go"
click node_dependency_setup "https://github.com/mrzkexe/melisis/blob/main/melisis/fail2ban.go"
click node_fail2ban_configs "https://github.com/mrzkexe/melisis/blob/main/melisis/fail2ban.go"

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_app,node_listener,node_router,node_mode_domain,node_client toneBlue
class node_ssh_trap,node_auth,node_channels,node_terminal,node_commands toneAmber
class node_shield,node_ban_logger,node_dependency_setup,node_fail2ban_configs toneMint
class node_config,node_command_log,node_ban_log toneRose
class node_fail2ban,node_systemd toneIndigo
```

## Components

### Server runtime

- [App startup](https://github.com/mrzkexe/melisis/blob/main/melisis/main.go): `melisis/main.go`
- [TCP listener](https://github.com/mrzkexe/melisis/blob/main/melisis/main.go): `melisis/main.go`
- [Mode router](https://github.com/mrzkexe/melisis/blob/main/melisis/main.go): `melisis/main.go`
- [Modes and IPs](https://github.com/mrzkexe/melisis/blob/main/melisis/domain.go): `melisis/domain.go`

### SSH deception

- [SSH trap](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`
- [Login deception](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`
- [Session channels](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`
- [Fake terminal](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`
- [Command responses](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`

### Blocking and bans

- [High-protection mode](https://github.com/mrzkexe/melisis/blob/main/melisis/highprotection.go): `melisis/highprotection.go`
- [Ban logger](https://github.com/mrzkexe/melisis/blob/main/melisis/writeban.go): `melisis/writeban.go`
- [Fail2Ban setup](https://github.com/mrzkexe/melisis/blob/main/melisis/fail2ban.go): `melisis/fail2ban.go`
- [Fail2Ban rules](https://github.com/mrzkexe/melisis/blob/main/melisis/fail2ban.go): `melisis/fail2ban.go`

### Configuration and monitoring

- [Runtime config](https://github.com/mrzkexe/melisis/blob/main/melisis/main.go): `melisis/main.go`
- [Command log](https://github.com/mrzkexe/melisis/blob/main/melisis/honeypot.go): `melisis/honeypot.go`
- [Ban log](https://github.com/mrzkexe/melisis/blob/main/melisis/writeban.go): `melisis/writeban.go`

### Other components

- **SSH client**
- **Fail2Ban**
- **systemd service**

## Connections

- App startup → Fail2Ban setup: checks dependencies (evidence: `melisis/main.go`)
- App startup → Runtime config: loads settings (evidence: `melisis/main.go`)
- App startup → TCP listener: starts listener (evidence: `melisis/main.go`)
- TCP listener → Mode router: routes connections (evidence: `melisis/main.go`)
- SSH client → TCP listener: connects to (evidence: `README.md`)
- Mode router → Modes and IPs: checks mode (evidence: `melisis/main.go`)
- Mode router → High-protection mode: dispatches mode 0 (evidence: `melisis/main.go`)
- Mode router → SSH trap: dispatches other modes (evidence: `melisis/main.go`)
- SSH trap → Login deception: checks password (evidence: `melisis/honeypot.go`)
- SSH trap → Session channels: processes channels (evidence: `melisis/honeypot.go`)
- Session channels → Fake terminal: starts shell (evidence: `melisis/honeypot.go`)
- Fake terminal → Command responses: generates replies (evidence: `melisis/honeypot.go`)
- Command responses → Command log: writes commands (evidence: `melisis/honeypot.go`)
- Fake terminal → Ban logger: bans on disconnect (evidence: `melisis/honeypot.go`)
- SSH trap → Ban logger: records failed sessions (evidence: `melisis/honeypot.go`)
- High-protection mode → Ban logger: registers ban (evidence: `melisis/highprotection.go`)
- Ban logger → Ban log: writes record (evidence: `melisis/writeban.go`)
- Fail2Ban setup → Fail2Ban rules: creates rules and filters (evidence: `melisis/fail2ban.go`)
- Fail2Ban → Fail2Ban rules: uses configured rules (evidence: `README.md`)
- Fail2Ban → Ban log: monitors ban log (evidence: `README.md`)
- systemd service → App startup: starts service (evidence: `README.md`)