sshcatch 0.2.2__tar.gz → 0.4.0__tar.gz

{sshcatch-0.2.2 → sshcatch-0.4.0}/.gitignore

@@ -209,6 +209,8 @@ tempCodeRunnerFile.py
 # PyPI configuration file
 .pypirc
 
+CLAUDE.md
+
 # Marimo
 marimo/_static/
 marimo/_lsp/

{sshcatch-0.2.2 → sshcatch-0.4.0}/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to **sshcatch** are documented here.
 This project follows [Keep a Changelog](https://keepachangelog.com/) and
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.0] - 2026-09-14
+
+Route forwards through an upstream proxy, choose the reverse bind, passwordless users.
+
+### Added
+
+- **`--forward [SOCKS5]`** takes an optional SOCKS5 proxy (`--forward 127.0.0.1:1080`) and
+  routes every forwarded connection through it, transparent to the connecting client. The
+  new `socks5_forward()` helper connects with `rdns=True`, so hostnames (and their DNS) are
+  resolved by the proxy and never by the sshcatch host. Adds a dependency on `python-socks`.
+- **`--forward-socks-auth USER:PASSWORD`** for upstream proxies that require credentials.
+  Refused unless `--forward` actually names a proxy.
+- **`--reverse [BIND]`** takes an optional bind address (default `127.0.0.1`). sshcatch now
+  creates the reverse listener itself via `forward_local_port()` instead of handing the
+  request back to asyncssh, so the **client no longer decides which interface is exposed** -
+  `--reverse 0.0.0.0` is an explicit server-side choice.
+- **Passwordless users.** `-u name:` (empty password) now accepts the SSH `none` method for
+  that user, which allows non-interactive logins.
+- `parse_hostport()` validates `HOST:PORT` and `[IPv6]:PORT` arguments.
+- **A pytest suite in `tests/`** (106 tests) covering auth, tunnels, SCP/SFTP, banners,
+  host keys, logging, mimicry and OpenSSH-client interop.
+
+### Changed
+
+- `connection_requested()` and `server_requested()` are coroutines now. Both may have to
+  await an upstream connection or a listener before they can answer.
+- **SCP/SFTP filesystem errors are reported through a single `_log_fs_error()`.** The generic
+  `ERROR` category is now `FSERROR`, and failures while listing a directory or auto-creating
+  a parent directory are logged as well instead of only surfacing on the client.
+- `mimic-refs/capture.py` normalizes the local ssh client's own version lines, so a trace
+  stays comparable across client updates. The committed captures were re-normalized.
+
+### Fixed
+
+- A reverse listener that cannot bind (address in use, privileged port) is logged with the
+  address and the reason instead of failing silently.
+
+
+## [0.3.0] - 2026-08-02
+
+Pose as another SSH server.
+
+### Added
+
+- **`--mimic debian` / `--mimic dropbear`** poses as a real OpenSSH 8.4p1 (Debian 11) or
+  Dropbear 2024.86 server: version banner, KEXINIT/HASSH, offered host keys and auth
+  methods match a capture of the real server. After authentication `sshcatch` differs from a
+  real server anyway, so `--mimic` only works pre-auth. Every modification to asyncssh,
+  the reasoning and the captures are in
+  [`mimic-refs/mimic-notes.md`](https://github.com/LorenzMap/sshcatch/blob/main/mimic-refs/mimic-notes.md).
+- `select_host_keys()` offers only the host-key types the mimicked server has, in its order.
+
+### Changed
+
+- **asyncssh is pinned to 2.24.0 exactly** - `--mimic` patches library internals, so a
+  different version could break the disguise silently. If a patched internal is gone,
+  sshcatch refuses to start.
+- The sdist ships only what is needed to install the package (no `mimic-refs/`).
+- The startup summary shows the active mimic preset.
+
+### Removed
+
+- **`--version-banner` presets** (`ubuntu`, `debian`, `dropbear`, `windows`, `macos`)
+  are dropped and the flag now takes a literal string only, `--mimic` sets a fitting
+  banner itself.
+
+
 ## [0.2.2] - 2026-07-31
 
 Multiple host keys now used as default.
@@ -100,7 +167,7 @@ Large rewrite of the SFTP layer and the logging system.
 
 - **Symlink handling redesigned.**
   - On **download**, symlinks are denied (`_require_not_symlink`) and hidden from
-    listings — a transfer can never follow a link out of the chroot.
+    listings - a transfer can never follow a link out of the chroot.
   - On **upload**, a symlink is no longer rejected outright; instead a small
     placeholder file recording the target is written, so recursive uploads that
     contain a link still complete.
@@ -132,9 +199,9 @@ Large rewrite of the SFTP layer and the logging system.
 
 ### Removed
 
-- **`-K` / `--full-keys` flag** — superseded by `-vv` verbosity.
+- **`-K` / `--full-keys` flag** - superseded by `-vv` verbosity.
 - **Startup symlink scan** that refused to start if the SCP directory contained
-  any symlink — replaced by the per-operation symlink handling above.
+  any symlink - replaced by the per-operation symlink handling above.
 
 ### Security
 
@@ -142,7 +209,8 @@ Large rewrite of the SFTP layer and the logging system.
   traversal out of the chroot is blocked on every path-taking operation rather
   than only checked once at startup.
 
-## [0.1.1]
+
+## [0.1.1] - 2026-07-12
 
 ### Fixed
 
@@ -151,6 +219,7 @@ Large rewrite of the SFTP layer and the logging system.
   its basename, so `./`-prefixed and other non-canonical paths are collapsed
   first and can no longer slip past the "root directory only" restriction.
 
-## [0.1.0]
+
+## [0.1.0] - 2026-07-12
 
 - Initial version published on GitHub.

{sshcatch-0.2.2 → sshcatch-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sshcatch
-Version: 0.2.2
+Version: 0.4.0
 Summary: Quick-deploy SSH server for tunneling and simple SCP transfers - never opens a shell.
 Project-URL: Homepage, https://github.com/LorenzMap/sshcatch
 Project-URL: Repository, https://github.com/LorenzMap/sshcatch
@@ -21,22 +21,27 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.10
-Requires-Dist: asyncssh<2.25.0,>=2.21.0
+Requires-Dist: asyncssh==2.24.0
+Requires-Dist: python-socks>=3.0
 Description-Content-Type: text/markdown
 
 # sshcatch
 
+[![PyPI](https://img.shields.io/pypi/v/sshcatch)](https://pypi.org/project/sshcatch/)
+[![Python](https://img.shields.io/pypi/pyversions/sshcatch)](https://pypi.org/project/sshcatch/)
+[![License](https://img.shields.io/pypi/l/sshcatch)](https://github.com/LorenzMap/sshcatch/blob/main/LICENSE)
+
 A quick-deploy SSH server for tunneling (local/remote/dynamic) and simple SCP /
 SFTP transfers - it **never opens a shell**.
 
 By default all features are disabled: connections are logged and closed. Turn on
 only what you need with the flags described below. Handy on an engagement when
-you want a controlled SSH endpoint (a tunnel relay or a file drop) without 
+you want a controlled SSH endpoint (a tunnel relay or a file drop) without
 setting up a full `sshd`.
 
 Built on [asyncssh](https://github.com/ronf/asyncssh).
 
-This is a pentesting tool. Only point it at systems and networks you are authorized 
+This is a pentesting tool. Only point it at systems and networks you are authorized
 to test.
 
 ## Why this tool exists
@@ -48,15 +53,15 @@ to test.
 
 - `sshd` can be used, but:
   - configuring it through `sshd_configs` is a pain
-  - multiple use-cases require different configs (tunnel direction? sftp direction? different ports?) 
+  - multiple use cases require different configs (tunnel direction? sftp direction? different ports?)
   - logins are controlled by the OS so a user must be created (and secured)
-  - I want to restrict the shell so my host is safe
+  - ForceCommands need to be set up to restrict the shell
 
 - My solution: `sshcatch`
-  - Simply configure through clear flags and arguments on the commandline
+  - Simply configure through clear flags and arguments on the command line
     - restrictive defaults, every feature must be enabled consciously
   - Never allow shells (or commands)
-  - Forward/Reverse tunnels can be individually activated 
+  - Forward/Reverse tunnels can be individually activated
   - SCP/SFTP file uploads and downloads can be individually activated
     - restrictive upload handling to prevent overwriting
     - symlinks denied
@@ -90,11 +95,11 @@ at your own file).
 
 ## How it works
 
-Without any flags sshcatch is in **log-only** mode: It accepts the
+Without any flags sshcatch is in **log-only** mode: it accepts the
 connection, records the client version, username, offered passwords and public
 keys, then closes. Nothing else is enabled until you ask for it.
 
-Adjust the amount of logging using `-vv` and `-q`. Or put everything into a 
+Adjust the amount of logging using `-vv` and `-q`. Or put everything into a
 logfile using `-o`.
 
 #### Tunnels
@@ -109,31 +114,62 @@ Only plain **TCP** forwards are ever available. UNIX-domain-socket forwards
 (`ssh -L /sock:...` / `-R /sock:...`) and TUN/TAP tunnels (`ssh -w`) are always
 denied, even with `--forward` / `--reverse` set.
 
+`--forward` enables forward tunnels. A client connects with `ssh -L` / `ssh -D`
+and may then reach any destination through the network stack of the host
+sshcatch runs on. To chain all of those forwarded connections into an upstream
+SOCKS5 proxy, use `--forward 127.0.0.1:1080`. This is transparent to the
+connecting client. If the proxy needs credentials, pass them with
+`--forward-socks-auth`. If you want to further restrict what a client can do 
+via the network, check out my Project [`socksscope`](https://github.com/LorenzMap/socksscope)!
+
+`--reverse` enables reverse tunnels. A client connects with `ssh -R`, which
+opens a listening port on the host running sshcatch. Connections to that port
+are routed through the network stack of the client. Normal SSH servers let the
+client choose the interface that port is bound to. sshcatch overrides this and
+always binds to localhost. Pass a BIND address (`--reverse 0.0.0.0`) to listen
+somewhere else.
+
 #### SCP / SFTP
 
 **Symlinks** are handled very restrictively: On upload they create a placeholder file
-that contains the original target. On download they are outright denied. 
+that contains the original target. On download they are outright denied.
 
-The host key, `authorized_keys`, logfile and the sshcatch script itself are **protected** 
+The host key, `authorized_keys`, logfile and the sshcatch script itself are **protected**
 and hidden when they live inside the SCP directory.
 
-Uploads **never overwrite** an existing file. The new file gets a numeric suffix 
+Uploads **never overwrite** an existing file. The new file gets a numeric suffix
 (`loot.tar` -> `loot_1.tar`). Non-existent parent folders are created.
 
 Renames, deletes and directory removal are denied.
 
+#### Authentication
+
+`-u name:pass` is a normal password login (repeatable). Leave the password empty
+(`-u name:`) to make that user passwordless, which allows easy non-interactive
+logins. Because passwordless users are inherently insecure, it is best to
+combine them with `-1`, which closes the listener after the first successful
+login (the server stays up until that one connection closes).
+
+You can also enable key-based authentication by pointing `--authorized-keys FILE`
+at an "authorized_keys" file.
+
+Or use `--open-auth` to disable authentication entirely. That is obviously
+insecure, but it is there if you have a valid use case for it.
+
 ## Word of Warning
 
-Only using `--version-banner` obviously isn't enough deception because the KEXINIT
-that is transferred cleartext on the wire is a clear tell. This differing HASSH
-can be easily detected by a sufficiently sophisticated observer.
+Only using `--version-banner` obviously isn't enough deception against a sufficiently
+sophisticated observer because some of the data transferred in cleartext on the wire
+during connection establishment is a clear tell. Use `--mimic` if that's something you
+want to try and dodge in an engagement. Check out
+[`mimic-refs/mimic-notes.md`](https://github.com/LorenzMap/sshcatch/blob/main/mimic-refs/mimic-notes.md)
+for details about `--mimic`.
 
-Also: `sshcatch` is **NOT** designed to be a **honeypot**. Advanced deception, long-term logging 
+Also: `sshcatch` is **NOT** designed to be a **honeypot**. Advanced deception, long-term logging
 and everything else a real honeypot needs are deliberately out of scope. There are other
 projects that can be used: [Cowrie](https://github.com/cowrie/cowrie),
 [cyanide-framework](https://github.com/tanhiowyatt/cyanide-framework) and probably a lot more!
 
-
 ## Examples
 
 Let one user pull/put files from the current directory via SCP/SFTP:
@@ -148,6 +184,17 @@ scp -r loot/ user@host:pete/pc/
 sftp user@host
 ```
 
+Passwordless single-use forward. The username is the only "auth". The server
+keeps serving the first connection but accepts no new ones:
+
+```
+# Server
+sshcatch -1 -u agent: --forward
+
+# Client
+ssh -NL 8080:internal:80 agent@host      # no password, no key
+```
+
 Let anyone tunnel through the server (local and dynamic forwards): **Be careful with this one!**
 
 ```
@@ -159,47 +206,64 @@ ssh -NL 8080:internal:80 user@host      # local forward
 ssh -ND 1080 user@host                  # dynamic (SOCKS)
 ```
 
+Expose a reverse listener on all interfaces (default is only localhost):
+
+```
+# Server
+sshcatch --open-auth --reverse 0.0.0.0
+```
+
+Forward directly to an upstream SOCKS pivot with plain SSH. A teammate uses a normal dynamic
+forward and their traffic (and DNS) egresses through the proxy:
+
+```
+# Server (chains every forward into the SOCKS5 pivot on :1080)
+sshcatch -u arthur:42 --forward 127.0.0.1:1080
+
+# Client
+ssh -ND 1080 user@host
+```
+
 Using single-mode to return something to the first successful authentication
 by closing the server afterwards, while printing timestamped logs to the console
 and saving them into a file:
 
 ```
 # Server
-sshcatch -1 -u arthur:42 --version-banner debian \
+sshcatch -1 -u arthur:42 --version-banner 'heart_of_gold' \
          --pre-auth-banner "What is the answer to life the universe and everything" \
          --post-auth-banner "flag{So_Long_and_Thanks_for_All_the_Fish}" \
          -o sshcatch.log -t
 ```
 
-
 My favorite one: Reverse tunnel and SCP uploads for the keys in
-`./authorized-keys` while posing as an Ubuntu SSH server on port 2222:
+`./authorized_keys` on port 2222:
 
 ```
 # Server
-sshcatch --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+sshcatch --reverse --authorized-keys ./authorized_keys --scp-upload -p 2222
 
 # Client
 ssh -NR 9000:localhost:22 user@host -p 2222     # reverse tunnel
 scp -P 2222 loot.tar user@host:.                # upload
 ```
 
-
 ## Options
 
 `sshcatch -h` prints a short summary with just the flags you need to get going.
 The full reference below is `sshcatch --help`:
 
 ```
-usage: sshcatch [-h] [--help] [-p PORT] [-b BIND] [-1] [--host-key FILE]
-                [--version] [-u USER:PASS] [--open-auth]
-                [--authorized-keys FILE] [--forward] [--reverse]
+usage: sshcatch [-h] [--help] [-p PORT] [-b BIND] [-1] [--mimic PRESET]
+                [--host-key FILE] [--version] [-u USER:PASS] [--open-auth]
+                [--authorized-keys FILE] [--forward [SOCKS5]]
+                [--forward-socks-auth USER:PASSWORD] [--reverse [BIND]]
                 [--scp-upload] [--scp-download] [--scp-dir DIR]
                 [--version-banner STRING] [--pre-auth-banner STRING]
                 [--post-auth-banner STRING] [-q | -v] [-o FILE] [-t] [--plain]
 
 sshcatch - a quick-deploy SSH server for tunneling (local/remote/dynamic)
-and simple SCP transfers (NEVER opens a shell!).
+and simple SCP/SFTP transfers (NEVER opens a shell!)
 By default all features are disabled. Use flags to enable features.
 
 options:
@@ -209,6 +273,11 @@ options:
   -b BIND, --bind BIND  bind address (default: all IPv4/v6 interfaces)
   -1, --single          close the listener after first successful auth (and
                         exit when that connection ends)
+  --mimic PRESET        pose as another SSH server - presets (case-
+                        insensitive): debian, dropbear, none - match the
+                        preset's pre-auth (banner, KEXINIT, server-sig-algs,
+                        ...) exactly - banner can be overridden by --version-
+                        banner - check Github repository for details
   --host-key FILE       server host key file, may hold several keys - auto-
                         generated if missing - uses ./sshcatch_host_key by
                         default
@@ -216,15 +285,22 @@ options:
 
 authentication:
   -u USER:PASS, --user USER:PASS
-                        allowed user:password (repeatable)
+                        allowed user:password (repeatable) - an empty password
+                        (user:) allows login by username only
   --open-auth           accept any credentials (open mode)
   --authorized-keys FILE
                         authorized_keys file for key auth (username
                         independent)
 
 tunneling:
-  --forward             enable forward tunnels (client: ssh -NL / -ND)
-  --reverse             enable reverse tunnels (client: ssh -NR)
+  --forward [SOCKS5]    enable forward tunnels (client: ssh -NL / -ND) -
+                        optional SOCKS5 proxy HOST:PORT to route every
+                        forwarded connection through (e.g. 127.0.0.1:1080; the
+                        proxy resolves DNS)
+  --forward-socks-auth USER:PASSWORD
+                        username:password for the --forward SOCKS5 proxy
+  --reverse [BIND]      enable reverse tunnels (client: ssh -NR) - optional
+                        BIND address to listen on (default: 127.0.0.1)
 
 SCP / SFTP file transfer:
   --scp-upload          enable file upload (SCP/SFTP write) - files get suffix
@@ -237,10 +313,7 @@ SCP / SFTP file transfer:
 
 banners:
   --version-banner STRING
-                        sent as 'SSH-2.0-STRING' version banner - only first-
-                        glance deception, it can still be identified as
-                        asyncssh - presets (case-insensitive): ubuntu, debian,
-                        dropbear, windows, macos
+                        manually set 'SSH-2.0-STRING' version banner
   --pre-auth-banner STRING
                         banner shown to every client before login
   --post-auth-banner STRING
@@ -262,10 +335,18 @@ examples: (also check README on Github)
   sshcatch --open-auth --forward             Allow ANYONE! to tunnel through this SSH server
   # My favorite one
   #   Allows reverse tunnels and uploads via SCP for the keys in ./authorized_keys
-  #   while posing shallowly as an Ubuntu SSH server on port 2222
-  sshcatch --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+  sshcatch --reverse --authorized-keys ./authorized_keys --scp-upload -p 2222
 ```
 
+## Testing
+
+- the test suite lives in `tests/` (pytest)
+- run it from a virtualenv with the runtime and dev dependencies installed
+  (`asyncssh`, `python-socks`, `pytest`, `coverage`)
+- the interop tests also need the OpenSSH client tools and `sshpass` on `PATH`
+- run via `python -m pytest` or `tests/test.sh`
+- to get the coverage of the tests, run `tests/test.sh cov`
+
 ## License
 
 MIT

{sshcatch-0.2.2 → sshcatch-0.4.0}/README.md

@@ -1,16 +1,20 @@
 # sshcatch
 
+[![PyPI](https://img.shields.io/pypi/v/sshcatch)](https://pypi.org/project/sshcatch/)
+[![Python](https://img.shields.io/pypi/pyversions/sshcatch)](https://pypi.org/project/sshcatch/)
+[![License](https://img.shields.io/pypi/l/sshcatch)](https://github.com/LorenzMap/sshcatch/blob/main/LICENSE)
+
 A quick-deploy SSH server for tunneling (local/remote/dynamic) and simple SCP /
 SFTP transfers - it **never opens a shell**.
 
 By default all features are disabled: connections are logged and closed. Turn on
 only what you need with the flags described below. Handy on an engagement when
-you want a controlled SSH endpoint (a tunnel relay or a file drop) without 
+you want a controlled SSH endpoint (a tunnel relay or a file drop) without
 setting up a full `sshd`.
 
 Built on [asyncssh](https://github.com/ronf/asyncssh).
 
-This is a pentesting tool. Only point it at systems and networks you are authorized 
+This is a pentesting tool. Only point it at systems and networks you are authorized
 to test.
 
 ## Why this tool exists
@@ -22,15 +26,15 @@ to test.
 
 - `sshd` can be used, but:
   - configuring it through `sshd_configs` is a pain
-  - multiple use-cases require different configs (tunnel direction? sftp direction? different ports?) 
+  - multiple use cases require different configs (tunnel direction? sftp direction? different ports?)
   - logins are controlled by the OS so a user must be created (and secured)
-  - I want to restrict the shell so my host is safe
+  - ForceCommands need to be set up to restrict the shell
 
 - My solution: `sshcatch`
-  - Simply configure through clear flags and arguments on the commandline
+  - Simply configure through clear flags and arguments on the command line
     - restrictive defaults, every feature must be enabled consciously
   - Never allow shells (or commands)
-  - Forward/Reverse tunnels can be individually activated 
+  - Forward/Reverse tunnels can be individually activated
   - SCP/SFTP file uploads and downloads can be individually activated
     - restrictive upload handling to prevent overwriting
     - symlinks denied
@@ -64,11 +68,11 @@ at your own file).
 
 ## How it works
 
-Without any flags sshcatch is in **log-only** mode: It accepts the
+Without any flags sshcatch is in **log-only** mode: it accepts the
 connection, records the client version, username, offered passwords and public
 keys, then closes. Nothing else is enabled until you ask for it.
 
-Adjust the amount of logging using `-vv` and `-q`. Or put everything into a 
+Adjust the amount of logging using `-vv` and `-q`. Or put everything into a
 logfile using `-o`.
 
 #### Tunnels
@@ -83,31 +87,62 @@ Only plain **TCP** forwards are ever available. UNIX-domain-socket forwards
 (`ssh -L /sock:...` / `-R /sock:...`) and TUN/TAP tunnels (`ssh -w`) are always
 denied, even with `--forward` / `--reverse` set.
 
+`--forward` enables forward tunnels. A client connects with `ssh -L` / `ssh -D`
+and may then reach any destination through the network stack of the host
+sshcatch runs on. To chain all of those forwarded connections into an upstream
+SOCKS5 proxy, use `--forward 127.0.0.1:1080`. This is transparent to the
+connecting client. If the proxy needs credentials, pass them with
+`--forward-socks-auth`. If you want to further restrict what a client can do 
+via the network, check out my Project [`socksscope`](https://github.com/LorenzMap/socksscope)!
+
+`--reverse` enables reverse tunnels. A client connects with `ssh -R`, which
+opens a listening port on the host running sshcatch. Connections to that port
+are routed through the network stack of the client. Normal SSH servers let the
+client choose the interface that port is bound to. sshcatch overrides this and
+always binds to localhost. Pass a BIND address (`--reverse 0.0.0.0`) to listen
+somewhere else.
+
 #### SCP / SFTP
 
 **Symlinks** are handled very restrictively: On upload they create a placeholder file
-that contains the original target. On download they are outright denied. 
+that contains the original target. On download they are outright denied.
 
-The host key, `authorized_keys`, logfile and the sshcatch script itself are **protected** 
+The host key, `authorized_keys`, logfile and the sshcatch script itself are **protected**
 and hidden when they live inside the SCP directory.
 
-Uploads **never overwrite** an existing file. The new file gets a numeric suffix 
+Uploads **never overwrite** an existing file. The new file gets a numeric suffix
 (`loot.tar` -> `loot_1.tar`). Non-existent parent folders are created.
 
 Renames, deletes and directory removal are denied.
 
+#### Authentication
+
+`-u name:pass` is a normal password login (repeatable). Leave the password empty
+(`-u name:`) to make that user passwordless, which allows easy non-interactive
+logins. Because passwordless users are inherently insecure, it is best to
+combine them with `-1`, which closes the listener after the first successful
+login (the server stays up until that one connection closes).
+
+You can also enable key-based authentication by pointing `--authorized-keys FILE`
+at an "authorized_keys" file.
+
+Or use `--open-auth` to disable authentication entirely. That is obviously
+insecure, but it is there if you have a valid use case for it.
+
 ## Word of Warning
 
-Only using `--version-banner` obviously isn't enough deception because the KEXINIT
-that is transferred cleartext on the wire is a clear tell. This differing HASSH
-can be easily detected by a sufficiently sophisticated observer.
+Only using `--version-banner` obviously isn't enough deception against a sufficiently
+sophisticated observer because some of the data transferred in cleartext on the wire
+during connection establishment is a clear tell. Use `--mimic` if that's something you
+want to try and dodge in an engagement. Check out
+[`mimic-refs/mimic-notes.md`](https://github.com/LorenzMap/sshcatch/blob/main/mimic-refs/mimic-notes.md)
+for details about `--mimic`.
 
-Also: `sshcatch` is **NOT** designed to be a **honeypot**. Advanced deception, long-term logging 
+Also: `sshcatch` is **NOT** designed to be a **honeypot**. Advanced deception, long-term logging
 and everything else a real honeypot needs are deliberately out of scope. There are other
 projects that can be used: [Cowrie](https://github.com/cowrie/cowrie),
 [cyanide-framework](https://github.com/tanhiowyatt/cyanide-framework) and probably a lot more!
 
-
 ## Examples
 
 Let one user pull/put files from the current directory via SCP/SFTP:
@@ -122,6 +157,17 @@ scp -r loot/ user@host:pete/pc/
 sftp user@host
 ```
 
+Passwordless single-use forward. The username is the only "auth". The server
+keeps serving the first connection but accepts no new ones:
+
+```
+# Server
+sshcatch -1 -u agent: --forward
+
+# Client
+ssh -NL 8080:internal:80 agent@host      # no password, no key
+```
+
 Let anyone tunnel through the server (local and dynamic forwards): **Be careful with this one!**
 
 ```
@@ -133,47 +179,64 @@ ssh -NL 8080:internal:80 user@host      # local forward
 ssh -ND 1080 user@host                  # dynamic (SOCKS)
 ```
 
+Expose a reverse listener on all interfaces (default is only localhost):
+
+```
+# Server
+sshcatch --open-auth --reverse 0.0.0.0
+```
+
+Forward directly to an upstream SOCKS pivot with plain SSH. A teammate uses a normal dynamic
+forward and their traffic (and DNS) egresses through the proxy:
+
+```
+# Server (chains every forward into the SOCKS5 pivot on :1080)
+sshcatch -u arthur:42 --forward 127.0.0.1:1080
+
+# Client
+ssh -ND 1080 user@host
+```
+
 Using single-mode to return something to the first successful authentication
 by closing the server afterwards, while printing timestamped logs to the console
 and saving them into a file:
 
 ```
 # Server
-sshcatch -1 -u arthur:42 --version-banner debian \
+sshcatch -1 -u arthur:42 --version-banner 'heart_of_gold' \
          --pre-auth-banner "What is the answer to life the universe and everything" \
          --post-auth-banner "flag{So_Long_and_Thanks_for_All_the_Fish}" \
          -o sshcatch.log -t
 ```
 
-
 My favorite one: Reverse tunnel and SCP uploads for the keys in
-`./authorized-keys` while posing as an Ubuntu SSH server on port 2222:
+`./authorized_keys` on port 2222:
 
 ```
 # Server
-sshcatch --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+sshcatch --reverse --authorized-keys ./authorized_keys --scp-upload -p 2222
 
 # Client
 ssh -NR 9000:localhost:22 user@host -p 2222     # reverse tunnel
 scp -P 2222 loot.tar user@host:.                # upload
 ```
 
-
 ## Options
 
 `sshcatch -h` prints a short summary with just the flags you need to get going.
 The full reference below is `sshcatch --help`:
 
 ```
-usage: sshcatch [-h] [--help] [-p PORT] [-b BIND] [-1] [--host-key FILE]
-                [--version] [-u USER:PASS] [--open-auth]
-                [--authorized-keys FILE] [--forward] [--reverse]
+usage: sshcatch [-h] [--help] [-p PORT] [-b BIND] [-1] [--mimic PRESET]
+                [--host-key FILE] [--version] [-u USER:PASS] [--open-auth]
+                [--authorized-keys FILE] [--forward [SOCKS5]]
+                [--forward-socks-auth USER:PASSWORD] [--reverse [BIND]]
                 [--scp-upload] [--scp-download] [--scp-dir DIR]
                 [--version-banner STRING] [--pre-auth-banner STRING]
                 [--post-auth-banner STRING] [-q | -v] [-o FILE] [-t] [--plain]
 
 sshcatch - a quick-deploy SSH server for tunneling (local/remote/dynamic)
-and simple SCP transfers (NEVER opens a shell!).
+and simple SCP/SFTP transfers (NEVER opens a shell!)
 By default all features are disabled. Use flags to enable features.
 
 options:
@@ -183,6 +246,11 @@ options:
   -b BIND, --bind BIND  bind address (default: all IPv4/v6 interfaces)
   -1, --single          close the listener after first successful auth (and
                         exit when that connection ends)
+  --mimic PRESET        pose as another SSH server - presets (case-
+                        insensitive): debian, dropbear, none - match the
+                        preset's pre-auth (banner, KEXINIT, server-sig-algs,
+                        ...) exactly - banner can be overridden by --version-
+                        banner - check Github repository for details
   --host-key FILE       server host key file, may hold several keys - auto-
                         generated if missing - uses ./sshcatch_host_key by
                         default
@@ -190,15 +258,22 @@ options:
 
 authentication:
   -u USER:PASS, --user USER:PASS
-                        allowed user:password (repeatable)
+                        allowed user:password (repeatable) - an empty password
+                        (user:) allows login by username only
   --open-auth           accept any credentials (open mode)
   --authorized-keys FILE
                         authorized_keys file for key auth (username
                         independent)
 
 tunneling:
-  --forward             enable forward tunnels (client: ssh -NL / -ND)
-  --reverse             enable reverse tunnels (client: ssh -NR)
+  --forward [SOCKS5]    enable forward tunnels (client: ssh -NL / -ND) -
+                        optional SOCKS5 proxy HOST:PORT to route every
+                        forwarded connection through (e.g. 127.0.0.1:1080; the
+                        proxy resolves DNS)
+  --forward-socks-auth USER:PASSWORD
+                        username:password for the --forward SOCKS5 proxy
+  --reverse [BIND]      enable reverse tunnels (client: ssh -NR) - optional
+                        BIND address to listen on (default: 127.0.0.1)
 
 SCP / SFTP file transfer:
   --scp-upload          enable file upload (SCP/SFTP write) - files get suffix
@@ -211,10 +286,7 @@ SCP / SFTP file transfer:
 
 banners:
   --version-banner STRING
-                        sent as 'SSH-2.0-STRING' version banner - only first-
-                        glance deception, it can still be identified as
-                        asyncssh - presets (case-insensitive): ubuntu, debian,
-                        dropbear, windows, macos
+                        manually set 'SSH-2.0-STRING' version banner
   --pre-auth-banner STRING
                         banner shown to every client before login
   --post-auth-banner STRING
@@ -236,10 +308,18 @@ examples: (also check README on Github)
   sshcatch --open-auth --forward             Allow ANYONE! to tunnel through this SSH server
   # My favorite one
   #   Allows reverse tunnels and uploads via SCP for the keys in ./authorized_keys
-  #   while posing shallowly as an Ubuntu SSH server on port 2222
-  sshcatch --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+  sshcatch --reverse --authorized-keys ./authorized_keys --scp-upload -p 2222
 ```
 
+## Testing
+
+- the test suite lives in `tests/` (pytest)
+- run it from a virtualenv with the runtime and dev dependencies installed
+  (`asyncssh`, `python-socks`, `pytest`, `coverage`)
+- the interop tests also need the OpenSSH client tools and `sshpass` on `PATH`
+- run via `python -m pytest` or `tests/test.sh`
+- to get the coverage of the tests, run `tests/test.sh cov`
+
 ## License
 
 MIT

{sshcatch-0.2.2 → sshcatch-0.4.0}/pyproject.toml

@@ -25,7 +25,21 @@ classifiers = [
     "Topic :: Security",
     "Topic :: System :: Networking",
 ]
-dependencies = ["asyncssh>=2.21.0,<2.25.0"]
+# asyncssh pinned exactly due to mimic monkey-patches on its internals (see mimic-refs/mimic-notes.md)
+dependencies = ["asyncssh==2.24.0", "python-socks>=3.0"]
+
+[dependency-groups]
+dev = ["pytest>=8", "coverage>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.coverage.run]
+source = ["sshcatch"]
+parallel = true
+sigterm = true
+branch = true
 
 [project.urls]
 Homepage = "https://github.com/LorenzMap/sshcatch"
@@ -40,3 +54,6 @@ path = "sshcatch.py"
 
 [tool.hatch.build.targets.wheel]
 only-include = ["sshcatch.py"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["sshcatch.py", "README.md", "CHANGELOG.md", "LICENSE"]

{sshcatch-0.2.2 → sshcatch-0.4.0}/sshcatch.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 """
 sshcatch - a quick-deploy SSH server for tunneling (local/remote/dynamic)
-and simple SCP transfers (NEVER opens a shell!).
+and simple SCP/SFTP transfers (NEVER opens a shell!).
 """
 
 import argparse
 import asyncio
+import functools
 import logging
 import os
 import posixpath
@@ -16,8 +17,10 @@ from pathlib import Path
 from itertools import count
 
 import asyncssh
+from python_socks import ProxyError, ProxyType
+from python_socks.async_.asyncio import Proxy
 
-__version__ = "0.2.2"
+__version__ = "0.4.0"
 
 # ── Logging ───────────────────────────────────────────────────────────
 
@@ -114,13 +117,16 @@ class SFTPCatchServer(asyncssh.SFTPServer):
         self._log_scp(f"DENIED {detail} ({reason})", level)
         raise asyncssh.SFTPPermissionDenied("Permission denied")
 
+    def _log_fs_error(self, path, error):
+        if isinstance(error, FileNotFoundError):
+            self._log_scp(f"NOTFOUND {self._local_path(path)}", logging.WARNING)
+        else:
+            self._log_scp(f"FSERROR {self._local_path(path)} ({error.strerror or error})", logging.WARNING)
+
     def _execute_wrapped_log(self, path, fn, *args):
         try: return fn(*args)
-        except FileNotFoundError:
-            self._log_scp(f"NOTFOUND {self._local_path(path)}", logging.WARNING)
-            raise
-        except OSError as e:
-            self._log_scp(f"ERROR {self._local_path(path)} ({e.strerror or e})", logging.WARNING)
+        except OSError as error:
+            self._log_fs_error(path, error)
             raise
 
     # ── path checks ───────────────────────────────────────────────
@@ -161,7 +167,7 @@ class SFTPCatchServer(asyncssh.SFTPServer):
     def _ensure_parent(self, path):
         parent = Path(os.fsdecode(self.map_path(path))).parent
         if not parent.is_dir():
-            parent.mkdir(parents=True, exist_ok=True)
+            self._execute_wrapped_log(path, lambda: parent.mkdir(parents=True, exist_ok=True))
             self._log_scp(f"MKPARENT {self._local_path(path)}", logging.INFO)
 
     def _local_path(self, path):
@@ -252,8 +258,7 @@ class SFTPCatchServer(asyncssh.SFTPServer):
         self._ensure_parent(new)
         target = old.decode(errors="replace")
         Path(os.fsdecode(self.map_path(new))).write_text(f"symlink -> {target}\n")
-        self._log_scp(f"SYMLINK {self._local_path(new)} -> {target} (placeholder)",
-                      logging.WARNING)
+        self._log_scp(f"SYMLINK {self._local_path(new)} -> {target} (placeholder)", logging.WARNING)
 
     def setstat(self, path, attrs):
         # Allow (upload only): perms/timestamps on uploaded files
@@ -289,16 +294,20 @@ class SFTPCatchServer(asyncssh.SFTPServer):
         self._require_not_symlink(path)
         self._log_scp(f"LISTDIR {self._local_path_log(path)}", logging.DEBUG)
         # hide protected files and symlinks
-        async for name in super().scandir(path):
-            if name.filename not in (b".", b".."):
-                mapped = self.map_path(posixpath.join(path, name.filename))
-                relative = self.reverse_map_path(mapped).decode(errors="replace").lstrip("/")
-                if relative in self._protected_files:
-                    continue
-                if os.path.islink(os.fsdecode(mapped)):
-                    self._log_scp(f"SKIP symlink {relative}", logging.DEBUG)
-                    continue
-            yield name
+        try:
+            async for name in super().scandir(path):
+                if name.filename not in (b".", b".."):
+                    mapped = self.map_path(posixpath.join(path, name.filename))
+                    relative = self.reverse_map_path(mapped).decode(errors="replace").lstrip("/")
+                    if relative in self._protected_files:
+                        continue
+                    if os.path.islink(os.fsdecode(mapped)):
+                        self._log_scp(f"SKIP symlink {relative}", logging.DEBUG)
+                        continue
+                yield name
+        except OSError as error:
+            self._log_fs_error(path, error)
+            raise
     
     # read      - file download after open
 
@@ -353,6 +362,21 @@ class SFTPCatchServer(asyncssh.SFTPServer):
         self._deny_sftp("UNLOCK")
 
 
+# ── SOCKS5 upstream ───────────────────────────────────────────────────
+
+async def socks5_forward(loop, proxy, dest_host, dest_port, auth):
+    # Connect to dest through the SOCKS5 proxy; returns the channel-side
+    #   SSHForwarder to hand back from connection_requested
+    proxy_host, proxy_port = proxy
+    user, password = auth if auth else (None, None)
+    # rdns=True so the destination name is resolved by the proxy, not by us
+    socks = Proxy(proxy_type=ProxyType.SOCKS5, host=proxy_host, port=proxy_port,
+                  username=user, password=password, rdns=True, loop=loop)
+    sock = await socks.connect(dest_host=dest_host, dest_port=dest_port)
+    _, peer = await loop.create_connection(asyncssh.forward.SSHForwarder, sock=sock)
+    return asyncssh.forward.SSHForwarder(peer)
+
+
 # ── SSH server factory ────────────────────────────────────────────────
 
 def make_server_factory(args, single_future=None):
@@ -435,6 +459,9 @@ def make_server_factory(args, single_future=None):
             self._log_client_version()
             if args.pre_auth_banner:
                 self._send_banner(args.pre_auth_banner)
+            if users.get(username) == "":
+                log_auth("Login accepted (passwordless user)", success=True, addr=self._addr, user=username)
+                return False
             return True
 
         def _post_auth(self):
@@ -470,6 +497,11 @@ def make_server_factory(args, single_future=None):
             # always accept passwords so we can log them
             return True
 
+        def kbdint_auth_supported(self):
+            # force  publickey,password auth for mimic (drop keyboard-interactive)
+            if not args.mimic == "none": return False
+            return super().kbdint_auth_supported()
+            
         def validate_password(self, username, password):
             accepted = accept_password(username, password)
             if accepted:
@@ -497,29 +529,52 @@ def make_server_factory(args, single_future=None):
 
         # ── ALLOWED (gated) ──────────────────────────────────────────
 
-        def connection_requested(self, dest_host, dest_port, orig_host, orig_port):
+        async def connection_requested(self, dest_host, dest_port, orig_host, orig_port):
             # Allow (--forward): direct TCP forward (client: ssh -NL / -ND)
             route = f"{addr_str(orig_host, orig_port)} -> {addr_str(dest_host, dest_port)}"
             if not args.forward:
                 return self._deny_tunnel(f"forward {route}", "Forwarding is disabled")
             user = self._conn.get_extra_info("username")
+            # --forward SOCKS: egress through the SOCKS5 proxy instead of a direct socket
+            if args.forward is not True:
+                proxy = addr_str(*args.forward)
+                try: fwd = await socks5_forward(asyncio.get_running_loop(), args.forward,
+                                                dest_host, dest_port, args.forward_socks_auth)
+                except (OSError, ProxyError) as e:
+                    log_tunnel(f"Forward {route} via socks {proxy} failed ({e})",
+                               addr=self._addr, user=user, level=logging.WARNING)
+                    # This forward failes, SSH connection stays open
+                    raise asyncssh.ChannelOpenError(
+                        asyncssh.OPEN_CONNECT_FAILED, f"SOCKS proxy: {e}") from None
+                log_tunnel(f"Forward {route} via socks {proxy}", addr=self._addr, user=user)
+                return fwd
             log_tunnel(f"Forward {route}", addr=self._addr, user=user)
-            return True
+            return await self._conn.forward_connection(dest_host, dest_port)
 
-        def server_requested(self, listen_host, listen_port):
+        async def server_requested(self, listen_host, listen_port):
             # Allow (--reverse): remote TCP listen (client: ssh -NR)
             if not args.reverse:
                 return self._deny_tunnel(f"reverse {addr_str(listen_host, listen_port)}", "Reverse is disabled")
             user = self._conn.get_extra_info("username")
-            log_tunnel(f"Reverse listen on {addr_str(listen_host, listen_port)}", addr=self._addr, user=user)
 
             def accept(orig_host, orig_port):
                 # Log the connection - real target is requested/resolved on the
                 #   client so we can't show it (decided against packet inspection)
                 log_tunnel(f"Reverse {addr_str(orig_host, orig_port)} on "
-                           f"{addr_str(listen_host, listen_port)}", addr=self._addr, user=user)
+                           f"{addr_str(args.reverse, listener.get_port())}", addr=self._addr, user=user)
                 return True
-            return accept
+
+            # Create a listener so we control the bind address
+            try:
+                listener = await self._conn.forward_local_port(
+                    args.reverse, listen_port, args.reverse, listen_port, accept)
+            except OSError as e:
+                log_tunnel(f"Reverse bind {addr_str(args.reverse, listen_port)} failed "
+                           f"({e.strerror or e})", addr=self._addr, user=user, level=logging.WARNING)
+                raise
+            log_tunnel(f"Reverse listen on {addr_str(args.reverse, listener.get_port())}",
+                       addr=self._addr, user=user)
+            return listener
 
         # ── DENIED forwarding/tunneling ──────────────────────────────
         # asyncssh rejects these by default, override to deny anyway and log them
@@ -540,14 +595,13 @@ def make_server_factory(args, single_future=None):
             # Deny: layer-2 TAP tunnel
             return self._deny_tunnel(f"tap unit={unit}")
 
-    return SSHCatchServer, len(users), len(auth_keys_fps)
+    return SSHCatchServer, users, len(auth_keys_fps)
 
 
 # ── Server start ──────────────────────────────────────────────────────
 
-HOST_KEY_ALGS = ("ssh-ed25519", "ssh-rsa", "ecdsa-sha2-nistp256")
-HOST_KEY_OPTS = {"ssh-rsa": {"key_size": 3072}}
-
+GENERATE_KEYS = ("ssh-ed25519", "ssh-rsa", "ecdsa-sha2-nistp256")
+GENERATE_OPTS = {"ssh-rsa": {"key_size": 3072}}
 
 async def start_server(args):
     # Handle Host keys
@@ -563,27 +617,32 @@ async def start_server(args):
         if not host_keys: raise ValueError(f"No usable host key in {key_path}")
         log_info(f"Read host key: {key_path} ({len(host_keys)} key{'s'*(len(host_keys)!=1)})")
     else:
-        host_keys = [asyncssh.generate_private_key(a, **HOST_KEY_OPTS.get(a, {}))
-                     for a in HOST_KEY_ALGS]
+        host_keys = [asyncssh.generate_private_key(a, **GENERATE_OPTS.get(a, {})) for a in GENERATE_KEYS]
         key_path.write_bytes(b"".join(k.export_private_key() for k in host_keys))
         log_info(f"Generated host keys file: {key_path}")
         if os.name == "posix": key_path.chmod(0o600)
         else: log_info("Please make sure the permissions on the host key are securely set!", level=logging.WARNING)
-    fingerprints = [(k.get_algorithm(), k.get_fingerprint()) for k in host_keys]
+
+    # Choose which keys to expose and what host-key algorithms to advertise
+    exposed_keys, host_key_algs = select_host_keys(host_keys, args.mimic)
+    fingerprints = [(k.get_algorithm(), k.get_fingerprint()) for k in exposed_keys]
 
     # for single-connection mode - resolving releases the bind on the listen port
     single_future = asyncio.get_running_loop().create_future() if args.single else None
 
     # Build the connection options for the ssh server
-    server_factory, n_users, n_keys = make_server_factory(args, single_future)
+    server_factory, users, n_keys = make_server_factory(args, single_future)
     opts = {
         "server_factory": server_factory,
-        "server_host_keys": host_keys,
+        "server_host_keys": exposed_keys,
         # SFTPv3 only so all transfers use open() and not open56()
         "sftp_version": 3,
     }
-    if args.version_banner: 
+    if args.version_banner:
         opts["server_version"] = args.version_banner
+    if args.mimic != "none":
+        opts.update(MIMIC_PRESETS[args.mimic][1])
+        apply_mimic_patches(args.mimic, host_key_algs)
 
     has_scp = args.scp_upload or args.scp_download
     if has_scp:
@@ -624,13 +683,21 @@ async def start_server(args):
     if args.open_auth: auth_mode = "open (accept any)"
     elif args.user or args.authorized_keys:
         parts = []
-        if args.user: parts.append(f"{n_users} user{'s'*(n_users!=1)}")
+        if args.user: parts.append(f"{len(users)} user{'s'*(len(users)!=1)}")
         if args.authorized_keys: parts.append(f"{n_keys} key{'s'*(n_keys!=1)}")
         auth_mode = f"restricted ({', '.join(parts)})"
+        pw_users = sorted(u for u, p in users.items() if p != "")
+        pwless_users = sorted(u for u, p in users.items() if p == "")
+        if pw_users: auth_mode += f"\n  Users ................ {', '.join(pw_users)}"
+        if pwless_users: auth_mode += f"\n  Users (no password) .. {', '.join(pwless_users)}"
     else: auth_mode = "reject all (no auth configured)"
     features = []
-    if args.forward: features.append("forward-tunnel")
-    if args.reverse: features.append("reverse-tunnel")
+    if args.forward:
+        if args.forward is True: features.append("forward-tunnel")
+        else:
+            via = f"forward-tunnel (via socks {addr_str(*args.forward)}"
+            features.append(via + (", auth)" if args.forward_socks_auth else ")"))
+    if args.reverse: features.append(f"reverse-tunnel ({args.reverse})")
     if args.scp_upload: features.append("scp-upload")
     if args.scp_download: features.append("scp-download")
     if not features: features.append("log-only (connect & close)")
@@ -643,10 +710,12 @@ async def start_server(args):
     if args.single: summary.append("Mode .......... single-connection")
     if has_scp: summary.append(f"SCP dir ....... {args.scp_dir.resolve()}")
     summary.append(f"Version ....... SSH-2.0-{options.version.decode()}")
+    summary.append(f"Mimic ......... {args.mimic}")
     if args.pre_auth_banner: summary.append(f"Pre-auth ...... {banner_preview(args.pre_auth_banner)}")
     if args.post_auth_banner: summary.append(f"Post-auth ..... {banner_preview(args.post_auth_banner)}")
     summary.append(f"Key file ...... {key_path}")
     for algo, fp in fingerprints: summary.append(f"Host key ...... {fp} ({algo})")
+    summary.append(f"\n")
     log_info("sshcatch\n" + "\n".join(f"  {line}" for line in summary), level=logging.WARNING)
 
     acceptor = await asyncssh.listen(host=args.bind, port=args.port, options=options)
@@ -665,18 +734,137 @@ async def start_server(args):
 
 # ── Main ──────────────────────────────────────────────────────────────
 
-# Quick --version-banner presets: keyword -> realistic 'SSH-2.0-<value>' banner.
-VERSION_PRESETS = {
-    "ubuntu":   "OpenSSH_9.6p1 Ubuntu-3ubuntu13.5",
-    "debian":   "OpenSSH_9.2p1 Debian-2+deb12u3",
-    "dropbear": "dropbear_2022.83",
-    "windows":  "OpenSSH_for_Windows_9.5",
-    "macos":    "OpenSSH_9.8",
+# ── Mimic presets ─────────────────────────────────────────────────────
+# - algorithm lists below shape the cleartext KEXINIT
+# - apply_mimic_patches() handles the monkey-patches of asyncssh
+# - for full reasoning see 'mimic-refs/mimic-notes.md'
+
+DEBIAN_ALGS = {
+    "kex_algs": ["curve25519-sha256", "curve25519-sha256@libssh.org",
+                 "ecdh-sha2-nistp256", "ecdh-sha2-nistp384", "ecdh-sha2-nistp521",
+                 "diffie-hellman-group-exchange-sha256", "diffie-hellman-group16-sha512",
+                 "diffie-hellman-group18-sha512", "diffie-hellman-group14-sha256"],
+    "encryption_algs": ["chacha20-poly1305@openssh.com", "aes128-ctr", "aes192-ctr",
+                        "aes256-ctr", "aes128-gcm@openssh.com", "aes256-gcm@openssh.com"],
+    "mac_algs": ["umac-64-etm@openssh.com", "umac-128-etm@openssh.com",
+                 "hmac-sha2-256-etm@openssh.com", "hmac-sha2-512-etm@openssh.com",
+                 "hmac-sha1-etm@openssh.com", "umac-64@openssh.com", "umac-128@openssh.com",
+                 "hmac-sha2-256", "hmac-sha2-512", "hmac-sha1"],
+    "compression_algs": ["none", "zlib@openssh.com"],
+    "signature_algs": ["ssh-ed25519", "sk-ssh-ed25519@openssh.com", "ssh-rsa",
+                       "rsa-sha2-256", "rsa-sha2-512", "ssh-dss",
+                       "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521",
+                       "sk-ecdsa-sha2-nistp256@openssh.com",
+                       "webauthn-sk-ecdsa-sha2-nistp256@openssh.com"],
 }
 
+DROPBEAR_ALGS = {
+    "kex_algs": ["curve25519-sha256", "curve25519-sha256@libssh.org",
+                 "ecdh-sha2-nistp521", "ecdh-sha2-nistp384", "ecdh-sha2-nistp256",
+                 "diffie-hellman-group14-sha256", "diffie-hellman-group14-sha1"],
+    "encryption_algs": ["chacha20-poly1305@openssh.com", "aes128-ctr", "aes256-ctr"],
+    "mac_algs": ["hmac-sha1", "hmac-sha2-256"],
+    "compression_algs": ["zlib@openssh.com", "none"],
+    "signature_algs": ["ssh-ed25519", "sk-ssh-ed25519@openssh.com",
+                       "ecdsa-sha2-nistp256", "ecdsa-sha2-nistp384", "ecdsa-sha2-nistp521",
+                       "sk-ecdsa-sha2-nistp256@openssh.com", "rsa-sha2-256", "ssh-rsa"],
+}
+
+MIMIC_PRESETS = {
+    "debian":   ("OpenSSH_8.4p1 Debian-5+deb11u7", DEBIAN_ALGS),   # Debian 11 (bullseye)
+    "dropbear": ("dropbear_2024.86", DROPBEAR_ALGS),               # Dropbear 2024.86
+    "none":     None                                               # asyncssh defaults
+}
+
+ADVERTISED_HOSTKEY_ALGS = {
+    "ssh-ed25519":         [b"ssh-ed25519"],
+    "ecdsa-sha2-nistp256": [b"ecdsa-sha2-nistp256"],
+    "ssh-rsa":             [b"rsa-sha2-512", b"rsa-sha2-256", b"ssh-rsa"],
+}
+
+MIMIC_HOSTKEYS = {
+    "debian":   ["ssh-rsa", "ecdsa-sha2-nistp256", "ssh-ed25519"],      # debian: rsa+ecdsa+ed25519
+    "dropbear": ["ssh-ed25519"],                                        # dropbear: ed25519 only
+}
+
+
+def select_host_keys(host_keys, mimic):
+    # Select fitting host keys for the mimicked server and order them in the default way
+    keys_by_algo = {k.get_algorithm(): k for k in host_keys}
+    wanted = MIMIC_HOSTKEYS.get(mimic, [])
+    missing = [a for a in wanted if a not in keys_by_algo]
+    if missing:
+        log_info(f"Host-keys missing: {missing} - a real {mimic} server provides "
+                 f"those (delete the host-key file to auto-generate all types)",
+                 level=logging.WARNING)
+    order = [a for a in wanted if a in keys_by_algo]
+    # return (keys_to_expose, advertised_algs)
+    if not order: return host_keys, None
+    return ([keys_by_algo[a] for a in order],
+            [alg for a in order for alg in ADVERTISED_HOSTKEY_ALGS[a]])
+
+
+def apply_mimic_patches(mimic, host_key_algs=None):
+    # Monkey-patch asyncssh internals so the cleartext/pre-auth transport matches the mimicked server
+    from asyncssh.connection import SSHConnection, SSHServerConnection
+    from asyncssh.constants import MSG_IGNORE
+
+    def wrap(cls, name, fn):
+        orig = getattr(cls, name, None)
+        if orig is None:
+            raise RuntimeError(
+                f"Cannot apply --mimic {mimic}: asyncssh internal '{name}' changed. "
+                f"Refusing to run a fingerprintable disguise (use '--mimic none' to bypass)")
+        setattr(cls, name, functools.partialmethod(fn, orig))
+
+    def kex(self, orig):
+        # 1. Modify KEXINIT to match mimicked server
+        algs = [a for a in orig(self) if a != b"ext-info-s"]
+        if self.is_server() and mimic == "dropbear":
+            algs = [b"kexguess2@matt.ucc.asn.au"] + algs
+        return algs
+    wrap(SSHConnection, "_get_extra_kex_algs", kex)
+
+    def ext_info(self, orig):
+        # 2. Strip asyncssh 'global-requests-ok' from EXT_INFO
+        self._extensions_to_send.pop(b"global-requests-ok", None)
+        return orig(self)
+    wrap(SSHConnection, "_send_ext_info", ext_info)
+
+    def send_packet(self, orig, pkttype, *a, **kw):
+        # 3. Suppress asyncssh's SSH_MSG_IGNORE traffic-analysis chaff (added with
+        #   OpenSSH 9.5). Safe to drop all because asyncssh only sends MSG_IGNORE
+        #   as this chaff using self.send_packet() before each real packet
+        if pkttype != MSG_IGNORE:
+            return orig(self, pkttype, *a, **kw)
+    wrap(SSHConnection, "send_packet", send_packet)
+
+    if host_key_algs is not None:
+        # 4. Pin the advertised server host-key algorithms
+        algs = list(host_key_algs)
+        def init(self, orig, *a, **kw):
+            orig(self, *a, **kw)
+            self._server_host_key_algs = [x for x in algs if x in self._server_host_keys]
+        wrap(SSHServerConnection, "__init__", init)
+
+# ── Startup and arguments ─────────────────────────────────────────────
+
+def parse_hostport(spec):
+    # return (host, port); raises ValueError on bad input
+    if spec.startswith("["):
+        host, sep, port = spec[1:].partition("]:")
+        if not sep: raise ValueError(f"'{spec}' - expected [IPv6]:PORT")
+    else:
+        host, sep, port = spec.rpartition(":")
+        if not sep: raise ValueError(f"'{spec}' - expected HOST:PORT")
+    if not host: raise ValueError(f"'{spec}' - missing host")
+    if not port.isdigit() or not (0 < int(port) < 65536):
+        raise ValueError(f"'{spec}' - invalid port")
+    return host, int(port)
+
 _description="""\
 sshcatch - a quick-deploy SSH server for tunneling (local/remote/dynamic)
-and simple SCP transfers (NEVER opens a shell!).
+and simple SCP/SFTP transfers (NEVER opens a shell!)
 By default all features are disabled. Use flags to enable features.
 """
 
@@ -691,8 +879,7 @@ examples: (also check README on Github)
   %(prog)s --open-auth --forward             Allow ANYONE! to tunnel through this SSH server
   # My favorite one
   #   Allows reverse tunnels and uploads via SCP for the keys in ./authorized_keys
-  #   while posing shallowly as an Ubuntu SSH server on port 2222
-  %(prog)s --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+  %(prog)s --reverse --authorized-keys ./authorized_keys --scp-upload -p 2222
 """
 
 def build_parser(full=False):
@@ -718,6 +905,13 @@ def build_parser(full=False):
     parser.add_argument("-1", "--single", action="store_true",
                         help=help_text(short_help="close the listener after first successful auth",
                                        long_help="(and exit when that connection ends)"))
+    parser.add_argument("--mimic", metavar="PRESET", type=str.lower,
+                         choices=list(MIMIC_PRESETS), default="none",
+                         help=help_text(long_help="pose as another SSH server "
+                                        f"- presets (case-insensitive): {', '.join(list(MIMIC_PRESETS))} "
+                                        "- match the preset's pre-auth (banner, KEXINIT, server-sig-algs, ...) "
+                                        "exactly - banner can be overridden by --version-banner "
+                                        "- check Github repository for details"))
     parser.add_argument("--host-key", metavar="FILE", type=Path,
                         help=help_text(long_help="server host key file, may hold several keys "
                                        "- auto-generated if missing - uses ./sshcatch_host_key by default"))
@@ -727,17 +921,23 @@ def build_parser(full=False):
 
     auth = parser.add_argument_group("authentication")
     auth.add_argument("-u", "--user", action="append", metavar="USER:PASS",
-                      help="allowed user:password (repeatable)")
+                      help=help_text(short_help="allowed user:password (repeatable)",
+                                     long_help="- an empty password (user:) allows login by username only"))
     auth.add_argument("--open-auth", action="store_true",
                       help="accept any credentials (open mode)")
     auth.add_argument("--authorized-keys", metavar="FILE", type=Path,
                       help="authorized_keys file for key auth (username independent)")
 
     tunnel = parser.add_argument_group("tunneling")
-    tunnel.add_argument("--forward", action="store_true",
-                        help="enable forward tunnels (client: ssh -NL / -ND)")
-    tunnel.add_argument("--reverse", action="store_true",
-                        help="enable reverse tunnels (client: ssh -NR)")
+    tunnel.add_argument("--forward", nargs="?", const=True, default=None, metavar="SOCKS5",
+                         help=help_text(short_help="enable forward tunnels (client: ssh -NL / -ND)",
+                                        long_help="- optional SOCKS5 proxy HOST:PORT to route every forwarded connection "
+                                        "through (e.g. 127.0.0.1:1080; the proxy resolves DNS)"))
+    tunnel.add_argument("--forward-socks-auth", metavar="USER:PASSWORD",
+                         help=help_text(long_help="username:password for the --forward SOCKS5 proxy"))
+    tunnel.add_argument("--reverse", nargs="?", const="127.0.0.1", default=None, metavar="BIND",
+                         help=help_text(short_help="enable reverse tunnels (client: ssh -NR)",
+                                        long_help="- optional BIND address to listen on (default: 127.0.0.1)"))
 
     scp = parser.add_argument_group("SCP / SFTP file transfer")
     scp.add_argument("--scp-upload", action="store_true",
@@ -752,9 +952,7 @@ def build_parser(full=False):
 
     banners = parser.add_argument_group("banners")
     banners.add_argument("--version-banner", metavar="STRING",
-                         help=help_text(long_help="sent as 'SSH-2.0-STRING' version banner - "
-                             "only first-glance deception, it can still be identified as asyncssh - "
-                             f"presets (case-insensitive): {', '.join(VERSION_PRESETS)}"))
+                         help=help_text(long_help="manually set 'SSH-2.0-STRING' version banner"))
     banners.add_argument("--pre-auth-banner", metavar="STRING",
                          help=help_text(long_help="banner shown to every client before login"))
     banners.add_argument("--post-auth-banner", metavar="STRING",
@@ -791,10 +989,23 @@ def main():
     configure_logging(output=args.output, timestamps=args.timestamps,
                       plain=args.plain, console_level=console_level)
 
-    # Handle version-banner presets
-    if args.version_banner:
-        args.version_banner = VERSION_PRESETS.get(
-            args.version_banner.lower(), args.version_banner)
+    # Handle --mimic version-banner
+    if args.mimic != "none" and not args.version_banner:
+        args.version_banner = MIMIC_PRESETS[args.mimic][0]
+
+    # Validate optional --forward SOCKS
+    if isinstance(args.forward, str):
+        try: args.forward = parse_hostport(args.forward)
+        except ValueError as e: parser.error(f"Invalid --forward SOCKS proxy: {e}")
+
+    # Handle --forward-socks-auth
+    if args.forward_socks_auth is not None:
+        if not isinstance(args.forward, tuple):
+            parser.error("--forward-socks-auth requires --forward with a SOCKS proxy (HOST:PORT)")
+        user, sep, password = args.forward_socks_auth.partition(":")
+        if not sep or not user or not password:
+            parser.error("Invalid --forward-socks-auth, expected USER:PASSWORD")
+        args.forward_socks_auth = (user, password)
 
     # Validate user format
     if args.user:
@@ -813,10 +1024,9 @@ def main():
         parser.error(f"Authorized-keys file not found: {args.authorized_keys}")
 
     try: asyncio.run(start_server(args))
-    except (OSError, ValueError) as e:
-        parser.error(f"Could not start server: {e}")
-    except KeyboardInterrupt:
-        print()
+    except (OSError, ValueError) as e: parser.error(f"Could not start server: {e}")
+    except RuntimeError as e: parser.error(str(e))
+    except KeyboardInterrupt: print()
 
 
 if __name__ == "__main__":