SSH

Synopsis

Creates an emulated SSH server that logs every authentication attempt, including the cleartext password, without exposing a real system. A credential that matches the credentials list opens a fake interactive shell that returns canned responses to a fixed set of commands; nothing is ever executed on the host.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: ssh
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    hostname: <string>
    banner: <string>
    banner_text: <string>
    motd: <string>
    server_version: <string>
    host_key: <string>
    max_auth_tries: <numeric>
    timeout: <numeric>
    credentials:
      - username: <string>
        password: <string>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
id	Y		Unique identifier
name	Y		Device name
description	N	-	Optional description
type	Y		Must be ssh
tags	N	-	Optional tags
pipelines	N	-	Optional pre-processor pipelines
status	N	true	Enable/disable the device

Connection

Field	Required	Default	Description
address	N	"0.0.0.0"	Listen address
port	Y		Listen port
max_auth_tries	N	6	Failed authentications per connection before disconnect
timeout	N	15	Handshake / idle timeout in seconds

Appearance

Field	Required	Default	Description
hostname	N	"server"	Host name shown in the shell prompt and canned command output
banner	N	"ubuntu"	Distro preset selecting the pre-auth banner, post-login MOTD, and SSH identification string
banner_text	N	-	Overrides the preset's pre-auth banner
motd	N	-	Overrides the preset's post-login message
server_version	N	-	Overrides the preset's SSH identification string

banner selects one of five presets — ubuntu, debian, centos, rhel, or alpine. An unrecognized or empty value falls back to ubuntu.

Authentication

The credentials property is the list of username/password pairs the honeypot accepts. Every login attempt is logged regardless of the outcome — the list only decides whether the attacker is granted a session afterwards.

Field	Required	Default	Description
credentials	N	-	Accepted username/password pairs. Omit to reject every login.
credentials[].username	Y		Username to accept. An entry with an empty username is discarded.
credentials[].password	N	-	Password to accept. An empty value accepts any password for that username.

Matching rules:

• Omitted or empty list: no login ever succeeds. Attempts are still logged, so the honeypot keeps collecting credentials without ever handing out a session.
• Empty password: any password is accepted for that username — useful for emulating a service that permits anonymous or unauthenticated access.
• Failed attempts are counted per connection, and the client is disconnected once max_auth_tries is reached.

Both fields accept plain text, ${ENV_VAR} environment references, and $secret{...} vault tokens.

warning

Credentials configured here are decoys, not access control. Anything an attacker types is written to the event stream in cleartext, including the password. Never reuse a real credential as a honeypot credential.

Host Key

Field	Required	Default	Description
host_key	N	-	Host key name resolved from the certificate store

note

host_key is resolved against the service root directory. When it is set but cannot be resolved, the device fails to start with a host key error. When it is left empty, a fresh ephemeral key is generated on every start, so the server's fingerprint changes each restart.

Details

Emulated Shell

A successful authentication opens a fake interactive shell: the MOTD, then a user@hostname:~$ prompt (# when the authenticated user is root). Canned responses exist for whoami, id, uname (and uname -a), hostname, pwd, ls/dir, ps, and echo. cat, less, more, head, and tail respond that the file does not exist. sudo and su return a not-allowed message. cd, export, set, umask, and history are silent no-ops. Any other command returns -bash: <command>: command not found. Exec requests complete immediately with an exit status of 0. Nothing is ever executed on the host, and no file system is touched.

Logged Events

Every connection generates one or more of the following event types:

event_type	Emitted when
auth_attempt	An authentication attempt is made, using either the password or keyboard-interactive method
session_open	A session channel opens after a successful authentication
session_command	A command is entered at the emulated shell prompt
session_close	The session channel closes

Event Fields

Every event carries timestamp, event_type, source_ip, source_port, and local_addr. The remaining fields depend on the event type:

Field	Description
username	Username submitted in the attempt
password	Password submitted in the attempt, in cleartext
auth_method	Authentication method used: password or keyboard-interactive
success	Whether the attempt or session matched an accepted credential
client_version	SSH client identification string reported by the connecting client
session_id	Hex-encoded SSH session ID
command	Command entered at the emulated shell prompt
args	Arguments parsed from the command
distro	Configured banner preset for the session

Examples

The following are commonly used configuration types.

Basic

Creating a minimal SSH honeypot on a non-privileged port...

devices: - id: 1 name: basic_ssh type: ssh properties: port: 2222

Accepted Credentials

Accepting one fixed credential and any password for a second username...

devices: - id: 2 name: ssh_credentials type: ssh properties: port: 2222 credentials: - username: admin password: admin123 - username: root password: ""

Custom Appearance

Presenting the honeypot as a CentOS host with a custom MOTD...

devices: - id: 3 name: ssh_appearance type: ssh properties: port: 22 hostname: prod-db01 banner: centos motd: "Welcome to CentOS Linux 7 (Core)\n"

With Pre-Processing

Routing captured attempts through a pre-processing pipeline before ingestion...	devices: - id: 4 name: ssh_preprocessed type: ssh pipelines: - decoy-honeypot-enrich properties: port: 2222
A failed login is logged with the cleartext credential before pipeline processing...	{ "timestamp": "2026-08-03T09:14:22.481937204Z", "event_type": "auth_attempt", "source_ip": "203.0.113.44", "source_port": "51422", "local_addr": "10.0.4.12:2222", "username": "admin", "password": "admin123", "auth_method": "password", "success": false, "client_version": "SSH-2.0-OpenSSH_9.6" }