.\" Generated by scdoc 1.11.5
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "hussh" "1" "2026\-08\-24"
.PP
.SH NAME
.PP
hussh \- Memory\-safe SSH daemon for restricted TCP forwarding
.PP
.SH SYNOPSIS
.PP
\fBhussh\fR [\fIoptions\fR]
.PP
.SH DESCRIPTION
.PP
\fBhussh\fR is a minimal SSH server that only implements TCP forwarding
("direct\-tcpip").\& It is intended for use as a restricted SSH tunnel, proxy or
jump host where interactive login sessions and remote command execution are not
required or desired.\& Only public\-key authentication is supported, password
logins are never accepted.\& An optional low\-interaction honeypot mode can log or
report unsolicited password authentication attempts.\&
.PP
Interactive shell sessions, PTY allocation, and remote command execution are all
explicitly not supported.\&
.PP
By default, \fBhussh\fR binds to `[::]:2` and runs in the foreground.\&
.PP
.SH OPTIONS
.PP
\fB\-c\fR, \fB\-\-config\fR \fIPATH\fR
.RS 4
Path to the TOML configuration file.\& Required for daemon mode.\&
.PP
.RE
\fB\-B\fR, \fB\-\-bind\fR \fIADDRESS\fR
.RS 4
Address to bind to (socket address).\& Example: `[::]:22`
.PP
.RE
\fB\-K\fR, \fB\-\-keygen\fR
.RS 4
Generate an Ed25519 private key in OpenSSH format and print it to stdout,
then exit.\&
.PP
.RE
\fB\-v\fR, \fB\-\-verbose\fR
.RS 4
Increase log verbosity.\& Repeat to increase detail.\&
.PP
.RE
\fB\-\-help\fR
.RS 4
Show command help and exit.\&
.PP
.RE
\fB\-\-version\fR
.RS 4
Show version and exit.\&
.PP
.RE
.SH CONFIGURATION
.PP
The default configuration file location is \fB/etc/hussh.\&conf\fR.\& A minimal configuration would look like this:
.PP
.nf
.RS 4
[[rules]]
ssh_keys = [
    "ssh\-ed25519 AAAAC3Nyourkeyhere",
]
# Allowed destinations to connect to
permit = ["*"]
.fi
.RE
.PP
A more elaborate configuration could look like this:
.PP
.nf
.RS 4
[sshd]
# Change the ssh bind address (port 22 on ipv4 + ipv6)
bind_addr = "[::]:22"

[[rules]]
# Instead of allowing any username, require a specific value
username = "proxy"
ssh_keys = [
    "ssh\-ed25519 AAAAC3Nyourkeyhere",
    "ssh\-ed25519 AAAAC3Nanotherkey",
]
# Allowed destinations to connect to
permit = [
    # All ports on specific destinations
    "example\&.com:*",
    "127\&.0\&.0\&.1:*",
    # Filter by port
    "*:443",
]

# If the previous rule didn\&'t match, try this one next:
[[rules]]
ssh_keys = [
    "ssh\-ed25519 AAAAC3Nyourkeyhere",
]
permit = [
    # Allow specific locations only
    "127\&.0\&.0\&.1:8080",
    "[::1]:8080",
]
.fi
.RE
.PP
.SH RULES SYNTAX
.PP
The \fIpermit=\fR option allows both specific destinations and wildcard expressions.\& The following are valid:
.PP
\fIHOST:PORT\fR, \fIIP:PORT\fR
.PP
.RS 4
Exact match of IP address or hostname, and port number.\&
.PP
\fBExample:\fR \fIexample.\&com:443\fR, \fI127.\&0.\&0.\&1:22\fR, \fI[::1]:22\fR
.PP
.RE
\fIHOST:*\fR, \fIIP:*\fR
.PP
.RS 4
Exact match of IP address or hostname, and any port number.\&
.PP
\fBExample:\fR \fIexample.\&com:*\fR, \fI127.\&0.\&0.\&1:*\fR, \fI[::1]:*\fR
.PP
.RE
\fI*\fR:\fIPORT\fR
.PP
.RS 4
Any host or IP address, but exact match of port number.\&
.PP
\fBExample:\fR \fI*:443\fR
.PP
.RE
\fI*:*\fR, \fI*\fR
.PP
.RS 4
Any host or IP address, and any port number.\& Can also be abreviated as just \fI*\fR.\&
.PP
\fBExample:\fR \fI*:*\fR, \fI*\fR
.PP
.RE
.SH SSH CLIENT EXAMPLES
.PP
Set it up as a jump host for a 2nd, localhost\-only SSH daemon:
.PP
.nf
.RS 4
cat >> ~/\&.ssh/config <<EOF
Host example\&.com
Hostname 192\&.0\&.2\&.37
ProxyCommand ssh \-p 2 \-W 127\&.0\&.0\&.1:%p \-o ProxyCommand=none %h
EOF
.fi
.RE
.PP
Forward a TCP connection through ssh, connect it to stdin/stdout:
.PP
.RS 4
ssh \-p 2 \-W example.\&com:80 192.\&0.\&2.\&37
.PP
.RE
Start a socks5 proxy server on localhost:1080.\& All connections are forwarded through the ssh server:
.PP
.RS 4
ssh \-p 2 \-ND 1080 192.\&0.\&2.\&37
.PP
.RE
Listen for incoming connections on localhost:1337 and forward them to localhost:8080 of the ssh server:
.PP
.RS 4
ssh \-p 2 \-NL 127.\&0.\&0.\&1:1337:127.\&0.\&0.\&1:8080 192.\&0.\&2.\&37
.PP
.RE
.SH HONEYPOT MODE
.PP
In addition to operating as a network proxy, \fBhussh\fR can also be used as a
low\-interaction SSH honeypot, to passively build combolists from internet
noise.\& When enabled, it records unsolicited password authentication attempts,
including the username, password and source address.\& This information can
either be logged or forwarded as json to a remote HTTP endpoint:
.PP
.nf
.RS 4
# /etc/hussh\&.conf

[honeypot]
# Change the SSH server banner to a custom string
# Note that invalid values may confuse or break clients
spoof_server_id = "SSH\-2\&.0\-anything"
# Log unsolicited password authentication attempts (including the password) to stderr
log_bruteforce_passwords = true
# Report unsolicited password authentication attempts to a remote server via http json post:
# {"username":"root","password":"123456","src":"192\&.0\&.2\&.34:56789"}
report_url_bruteforce_passwords = "https://example\&.com/report"
# In addition to unsolicited password authentication attempts,
# advertise that password authentication is supported/enabled
bait_password_bruteforce = true
.fi
.RE
.PP
.SH AUTHORS
.PP
This program was originally written and is currently maintained by kpcyrd.\&
Bug reports and patches are welcome on Github:
.PP
.RS 4
\fIhttps://github.\&com/kpcyrd/hussh\fR
.RE