Melissae

Melissae is a modular, containerized honeypot framework built to emulate real-world network services. It is designed for cybersecurity researchers, analysts, and SOC teams to detect, analyze, and better understand malicious activity on their infrastructure.

Each service module runs in its own container, allowing flexible deployment and isolated execution, while collected logs are centralized, parsed, and enriched via a dedicated processing pipeline.

The project includes a fully functional dashboard offering real-time visibility into attacker behavior, threat scoring, and IOC export, making Melissae not just a honeypot, but a lightweight threat intelligence platform.

Overview

Key Features

Modular Service Support: Configure Melissae to expose between 1 and 5 services simultaneously, allowing for flexible deployment scenarios tailored to your specific security needs. See contributing if you're interested in developing new modules.

Centralized Management Dashboard: Monitor and manage your honeypot through a web-based dashboard, which offers:

Statistical Analysis: Visualize attack patterns, trends, and frequency.
Advanced Log Search: Utilize the Melissae Query Language (MQL), a simple query language (that will be developed more in the future), to perform searches within the captured logs.
Data Export: Export logs or Indicators of Compromise (IOCs) in JSON format, filtered according to specific criteria such as time, service type, or threat verdict.
Threat Scoring: Assess attacker danger levels with a built-in scoring system, categorizing threats by severity. This helps prioritize responses and allocate resources effectively.

Infrastructure

Warning

Please use this tool with care, and remember to use it on a dedicated secure server that is properly isolated from your infrastructure.

The infrastructure is fully containerized with docker, and modules can be deployed on demand. The dashboard is always deployed locally and accessible via port forwarding.

Schema

Manager Mode Architecture

graph TD
    Operator[Dashboard / CLI]\n(Manager token)
    ManagerAPI[Manager API\n(FastAPI)]
    State[(manager/data\nstate.json)]
    Redis[(Redis queue\noptional)]
    subgraph Agents
        AgentA[Agent A\nmodules]
        AgentB[Agent B\nmodules]
    end

    Operator -->|HTTPS 8443| ManagerAPI
    AgentA -->|register + heartbeat\nBootstrap & Agent tokens| ManagerAPI
    AgentB -->|register + heartbeat\nBootstrap & Agent tokens| ManagerAPI
    ManagerAPI --> State
    ManagerAPI -.-> Redis

Topology and ports

Manager API: listens on 8443/tcp (configurable) and serves /api/agents, /api/overview, and command queues. Expose it only to trusted networks and front it with TLS.
Dashboard: still served locally on 127.0.0.1:9999 but the new Manager tab fetches live data from the Manager API using the operator token.
Optional Redis: shipped but disabled by default. When enabled (--profile manager) it offers a queue backend for future high-volume features.
Agents: initiate all communication outbound; no inbound firewall rules are required on agent nodes.

Registration & authentication

Operators start the manager stack with ./melissae.sh manager install and share the bootstrap token found in manager/config/manager.env.
Agents call ./melissae.sh agent register <envfile> which posts metadata and receives a per-agent token saved to the env file.
Agents send heartbeats and fetch commands with the agent token; operators manage the fleet with the manager API token via CLI or dashboard.
Audit trails for registrations, heartbeats, and commands are persisted in manager/data/audit.log.

The full Manager Mode playbook (operational flows, security guidance, troubleshooting) lives in docs/manager-mode.md.

File Tree

-- Melissae
    |-- README.md
    |-- dashboard
    |   |-- conf
    |   |   |-- dashboard.conf
    |   |-- css
    |   |   |-- styles.css
    |   |   |-- threat-intel.css
    |   |-- dashboard.html
    |   |-- img
    |   |   |-- favicon.ico
    |   |   |-- logo.png
    |   |-- js
    |   |   |-- backgroundDisplay.js
    |   |   |-- dashboardDisplay.js
    |   |   |-- main.js
    |   |   |-- searchDisplay.js
    |   |   |-- searchEngine.js
    |   |   |-- threatintelDisplay.js
    |   |-- json
    |   |   |-- logs.json
    |   |    -- threats.json
    |   |-- search.html
    |   |-- threat-intel.html
    |-- docker-compose.yml
    |-- melissae.sh
    |-- modules
    |   |-- ftp
    |   |   |-- logs
    |   |       |-- vsftpd.log
    |   |   |-- server
    |   |       |-- ftpuser
    |   |           |-- test.txt
    |   |-- ssh
    |   |   |-- Dockerfile
    |   |   |-- logs
    |   |       |-- commands.log
    |   |       |-- sshd.log
    |   |-- mqtt
    |   |   |-- logs
    |   |       |-- mosquitto.log
    |   |   |-- conf
    |   |       |-- mosquitto.conf
    |   |-- modbus
    |   |   |-- Dockerfile
    |   |   |-- server
    |   |       |-- server.py
    |   |   |-- logs
    |   |       |-- modbus.log
    |    -- web
    |       |-- Dockerfile
    |       |-- conf
    |       |   |-- web.conf
    |       |   |-- proxy.conf
    |       |-- logs
    |       |   |-- access.log
    |       |   |-- error.log
    |       |-- server
    |           |-- index.html
    |-- scripts
        |-- logParser.py
        |-- threatIntel.py

Workflow

The various module logs are processed by logParser.py, which parses and formats them. In turn, threatIntel.py processes these formatted logs to enrich Threat Intelligence.

Manager Mode

Manager Mode adds a fleet-wide control plane on top of the existing Melissae modules. It remains optional: if you never start the manager profile, the core honeypot experience behaves exactly as before.

Manager Mode Overview

Central command API built with FastAPI (manager/api/app.py). It exposes registration, heartbeat, overview, and command endpoints secured by signed tokens.
Persistent state stored in manager/data/state.json with an append-only audit log for accountability.
Frictionless onboarding via extended melissae.sh commands and ready-to-use env templates in manager/config/.
Dashboard updates including a dedicated Manager tab with fleet summaries, agent health cards, module synchronization matrix, and an aggregated threat timeline powered by dashboard/js/managerDisplay.js and dashboard/manager.html.
Documentation capturing the full workflow in docs/manager-mode.md.

CLI Quick Reference

Command	Description
`./melissae.sh manager install`	Build and start the Manager API (and optional Redis) using the docker-compose manager profile.
`./melissae.sh manager stop`	Gracefully stop Manager Mode containers without removing them.
`./melissae.sh manager destroy`	Stop and remove Manager Mode containers.
`./melissae.sh manager status`	Display running manager-related containers.
`./melissae.sh manager agents list`	List registered agents from the Manager API using the operator token.
`./melissae.sh manager agents remove <agent_id>`	Deregister an agent and revoke its token.
`./melissae.sh agent register [envfile]`	Register a node with the manager using the bootstrap token and persist the issued agent token.

Use the provided templates to bootstrap configuration:

cp manager/config/manager.env.example manager/config/manager.env
cp manager/config/agent.env.example /etc/melissae/agent.env

Dashboard Enhancements

The Manager tab mirrors the styling of the existing dashboard while surfacing fleet-wide telemetry:

Top-line cards showing total, online, degraded, and offline agents plus active alert counts.
Module synchronization heat bar to highlight drift across agents.
Agent cards with status badges, module health, telemetry counters, pending command counts, and inline module control forms.
Threat and alert timeline aggregating heartbeat events from every agent.
Operator settings drawer that stores API URL and tokens locally in the browser (no backend storage).

If the Manager API is unavailable the tab falls back to dashboard/json/manager-sample.json so the layout can be previewed offline.

Operational Flows

Manager operators: deploy the manager profile, distribute bootstrap tokens, approve fleet changes via CLI or dashboard, and monitor aggregated telemetry. All actions are auditable through manager/data/audit.log.
Agents: register once via ./melissae.sh agent register, ship heartbeats to /api/agents/<id>/heartbeat, poll /commands for tasks, and acknowledge completion. The helper script automatically writes the returned token back into the agent env file for automation tooling.

Detailed step-by-step guidance lives in the Manager Mode playbook.

Security & Reliability

Three distinct tokens separate operator, bootstrap, and per-agent privileges.
All manager endpoints are designed for HTTPS; place them behind your reverse proxy of choice for certificate management.
Heartbeat timeout (MANAGER_HEARTBEAT_TIMEOUT) determines the online/degraded/offline status progression and is configurable in manager/config/manager.env.
State is persisted on disk and can be backed up or shipped to a central log pipeline. Optional Redis support is scaffolded for future queue-backed workflows.

Manager Mode Troubleshooting

403 during registration: verify the bootstrap token and ensure system clocks are in sync.
Dashboard shows sample data: check MANAGER_ALLOWED_ORIGINS and that the operator token is saved via the Manager tab.
Agent remains offline: confirm the agent posts heartbeats with the stored MANAGER_AGENT_TOKEN and review timestamps in manager/data/state.json.
Command queue stuck: confirm the agent polls /commands and acknowledges with /commands/<id>/ack.

More scenarios—including FAQ responses—are documented in docs/manager-mode.md.

Modules

The choice of modular, containerized deployment means that contributors can easily develop new modules. There are currently 4 native modules:

Web

Type	Image	Container name
Proxy	nginx:latest	melissae_proxy
Web Server	httpd:2.4-alpine with apache2	melissae_apache1
Web Server	httpd:2.4-alpine with apache2	melissae_apache2

Logs format

[
  {
    "protocol": "http",
    "date": "2025-04-16",
    "hour": "11:47:08",
    "ip": "192.168.X.X",
    "action": "GET",
    "path": "/",
    "user-agent": "Mozilla/5.0"
  }
]

Usage
- By default, Melissae provides you a basic configuration for both proxy and web servers containers, those configurations are located in modules/web/conf
- Add the files you need for the website to be exposed via honeypot in modules/web/server

SSH

Type	Image	Container name
SSH Server	ubuntu:latest with openssh	melissae_ssh

Logs format

[
  {
    "protocol": "ssh",
    "date": "2025-04-16",
    "hour": "11:48:09",
    "ip": "192.168.X.X",
    "action": "Login failed with invalid user",
    "user": "test"
  }
]

Usage
- You need to modify your module credentials here : modules/ssh/Dockerfile (Default : user:admin)

FTP

Type	Image	Container name
FTP Server	fauria/vsftpd	melissae_ftp

Logs format

[
  {
    "protocol": "ftp",
    "date": "2025-04-16",
    "hour": "11:48:37",
    "ip": "192.168.X.X",
    "action": "Login failed",
    "user": "test"
  }
]

Usage
- The shared repository with the ftp container is modules/ftp/server
- You need to modify your module credentials here : docker-compose.yml (Default ftpuser:ftppass)

Modbus

Type	Image	Container name
Modbus TCP Server	python:3.11-slim with custom modbus server	melissae_modbus

Logs format

[
  {
    "protocol": "modbus",
    "date": "2025-05-30",
    "hour": "10:38:23",
    "ip": "192.168.X.X",
    "action": "Read request - Read Holding Registers"
  },
  {
    "protocol": "modbus",
    "date": "2025-05-30", 
    "hour": "10:41:22",
    "ip": "192.168.X.X",
    "action": "Write attempt - Write Multiple Registers"
  }
]

Features
- Industrial PLC Emulation: Simulates Siemens S7-1200 and Schneider Electric M340 PLCs
- Randomized Device Identifiers: Generates unique serial numbers and firmware versions on each startup
- Protocol Detection: Logs all Modbus function codes (read/write operations)
- Threat Escalation: Write attempts trigger high-severity threat alerts
Usage
- Default Profile: Siemens S7-1200 (modify in modules/modbus/Dockerfile to use schneider profile)
- Port: Standard Modbus TCP port 502
- Device Profiles:
  - Siemens: S7-xxxxxx serials, V3.x-V4.x firmware, 1000 registers
  - Schneider: M340-xxxxx-X serials, V2.x-V3.x firmware, 2000 registers

MQTT

Type	Image	Container name
Mosquitto Server	eclipse-mosquitto:latest	melissae_mqtt

Logs format

[
  {
    "protocol": "mqtt",
    "date": "2025-09-12",
    "hour": "08:56:25",
    "ip": "192.168.X.X",
    "action": "Client connected"
  },
  {
    "protocol": "mqtt",
    "date": "2025-09-12",
    "hour": "08:57:17",
    "ip": "192.168.X.X",
    "action": "Subscribe",
    "user": "auto-XX"
  }
]

Threat Intelligence

The Threat Intelligence section of the dashboard provides a simple visual overview of detected threats.
(Really) basic scoring rules have been implemented, but they are intended to be improved in the future. See contributing if you're interested in developing the threat intelligence.

There are 5 different verdicts:

Benign: Default verdict.
Suspicious: Threat requested the web module > 50 times OR requested the MQTT module > 30 times OR (Attempted to connect using SSH OR FTP) OR Performed Modbus read operations.
Malicious: Threat successfully connected via SSH OR FTP OR (Performed Modbus write operations AND Failed to connect to SSH OR FTP).
Nefarious: Threat connected via both SSH AND FTP OR (Performed Modbus write operations AND Successfuly connected via SSH OR FTP).

IoCs can be exported in json.

IoC Format

[
  {
    "type": "ip",
    "ip": "192.168.X.X",
    "protocol-score": 3,
    "verdict": "suspicious"
  }
]

Search Engine

Main Features

Search with logical operators: Use operators to combine multiple criteria in your search.
Field-specific filters: Search within specific fields like user, ip, protocol, date, hour, action, user-agent, or path using the syntax field:value
Global search: If no field is specified, the search applies to all log fields.
Export results: A button allows exporting the filtered logs.

Operators

AND / and OR / or NOT / not / !

Examples

user:root and protocol:ssh
ip:192.168.X.X or ip:192.168.X.Y or ip:192.168.X.Z
protocol:http and not action:success
protocol:modbus and action:write
user:admin or not path:/login
!ip:192.168.X.X and action:failed
protocol:modbus and action:read

Limitations

Currently, the search engine supports only a few operations at a time. See contributing if you're interested in developing the search engine.

Getting Started

Installation

Clone the repository : git clone https://github.com/ilostmypassword/Melissae.git

Give execution rights to the script :

cd Melissae/
chmod +x melissae.sh

Install Melissae :

Caution

Your SSH port will be modified and given to you at the end of the installation script. Note it carefully.

./melissae.sh install

Add your user in the docker group :

sudo su
usermod -aG docker your_username

Note

After adding the user to the docker group, you will likely need to reconnect via SSH using the generated port that was provided to you. You can connect directly with the command provided in "accessing the Dashboard"

Starting up the stack

Important

Before launching your stack, don't forget to check the modules usage here : Modules

Start your stack

./melissae.sh start [module 1] [module 2] [...]

Available modules: all, web, ssh, ftp, modbus, mqtt

Examples:

# Start all modules
./melissae.sh start all

# Start specific modules
./melissae.sh start web ssh modbus

# Start only Modbus honeypot
./melissae.sh start modbus

Your stack should now be deployed. If you are already connected with the port forwarding activated, your dashboard is accessible on :

http://localhost:8080

But if you didn't, and you want to access the dashboard, go to "Accessing the Dashboard"

Accessing the dashboard

Connect to your server with this command and the newly generated port. This command will allow you to forward the dashboard to your localhost.

ssh -L 8080:localhost:9999 user@server -p new_port

Then access the dasboard in your browser :

http://localhost:8080/

Destroying the stack

You can destroy your stack easily with :

./melissae.sh destroy

Contributing

This project is of course open to contributions, and there are a number of areas of work to be developed. For those who wish to contribute, you can join the discord server :

Discord : https://discord.gg/RXWn85cnYm

Priority Tasks :

Modbus Industrial Honeypot Module - Complete TCP honeypot with PLC emulation
MQTT module should be improved
New modules need to be developed (SNMP, etc.)
Improve the search engine
Threat Intelligence must be developed (enrichment from threat intel feeds for example)
Developing multi-instance capabilities

Credits

Thank you to all contributors for helping the project move forward.

summoningshells (https://github.com/summoningshells)

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
dashboard		dashboard
docs		docs
manager		manager
modules		modules
scripts		scripts
README.md		README.md
docker-compose.yml		docker-compose.yml
melissae.sh		melissae.sh

summoningshells/Melissae-Manager

Folders and files

Latest commit

History

Repository files navigation