sshcatch 0.1.0__tar.gz → 0.2.0__tar.gz

sshcatch-0.2.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+All notable changes to **sshcatch** are documented here.
+This project follows [Keep a Changelog](https://keepachangelog.com/) and
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-07-19
+
+Large rewrite of the SFTP layer and the logging system.
+
+### Added
+
+- **Subdirectory support** for SCP/SFTP. `map_path()` is overridden to normalize
+  paths into the chroot, so `scp -r`, nested uploads/downloads and recursive
+  `sftp` listings now work. The old "root directory only" restriction
+  (`_require_flat`) is gone.
+- **Single-connection mode** (`-1` / `--single`). Accepts the first successful
+  authentication, closes the listener to free the port, and exits once that
+  connection ends. Implemented via an asyncio future resolved in
+  `auth_completed()`.
+- **Tiered, verbosity-controlled logging.** New mutually exclusive `-q`/`--quiet`
+  and `-v`/`--verbose` (repeatable) flags map to WARNING (default) / INFO (`-v`) /
+  DEBUG (`-vv`). Every log helper now takes a `level`. The `--output` logfile
+  always records everything (DEBUG) regardless of console verbosity.
+- **Recursive-upload plumbing.** `mkdir` is allowed during uploads and
+  `_ensure_parent()` auto-creates missing parent directories (logged as
+  `MKPARENT`), so uploading a tree lands intact.
+- **Directory listings** via `scandir` (download only), which also **hides
+  protected files and symlinks** from the listing.
+- **SCP log de-duplication**: identical SCP messages within a 1-second window are
+  collapsed to cut noise.
+- **Error-handling wrapper** `_execute_wrapped_log()` that reports
+  `NOTFOUND` (FileNotFoundError) and `ERROR` (OSError) cleanly instead of raising
+  raw tracebacks.
+- **`--single` and banner details in the startup summary**, plus a
+  `banner_preview()` helper that truncates long banners.
+
+### Changed
+
+- **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.
+  - 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.
+- **SFTP server implementation.** Replaced the metaprogramming approach
+  (`_SFTP_ALL_OPS` / `_SFTP_WHITELIST` / dynamic `setattr` of deny stubs) with
+  explicit, individually-commented methods for every allowed and denied
+  operation. Newly explicit denials: `open56`, `readlink`, `posix_rename`,
+  `statvfs`, `fstatvfs`, `fsync`, `lock`, `unlock` (in addition to
+  `remove`/`rename`/`rmdir`/`link`).
+- **Post-auth banner delivery** is now reliable: it wraps asyncssh's
+  `send_userauth_success` and fires exactly once, instead of being triggered from
+  inside password/key validation.
+- **Host key algorithm** changed from RSA-2048 to **ed25519**.
+- **Protected files** are now matched by their path relative to the SCP directory
+  (supports subdirectories) instead of just basename, and the **sshcatch script
+  itself** (`__file__`) is now protected alongside the host key, authorized_keys
+  and logfile.
+- **Startup summary** is now emitted through the logger (so it also lands in
+  `--output` and is suppressed by `-q`) rather than printed directly. The auth
+  line now shows counts, e.g. `restricted (2 users, 1 key)`.
+- **Connection-close logging** is level-aware: authenticated disconnects log at
+  WARNING, unauthenticated ones at DEBUG.
+- **Clean channel close.** `exit()` now calls `channel.exit(0)` so clients don't
+  hang waiting for a session that never opens.
+- Full offered public keys are now shown automatically at `-vv` (DEBUG) instead
+  of requiring a dedicated flag.
+- Help text / argument groups updated: "SCP / SFTP file transfer", refreshed
+  `--scp-*` descriptions (symlink behavior, no subdirectory restriction).
+
+### Removed
+
+- **`-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.
+
+### Security
+
+- Every SFTP operation is now explicitly allow-listed or denied, and symlink
+  traversal out of the chroot is blocked on every path-taking operation rather
+  than only checked once at startup.
+
+## [0.1.1]
+
+### Fixed
+
+- **Hardened the flat-directory (no-subdirectory) check.** The upload/download
+  path is now run through `posixpath.normpath()` before it is compared against
+  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]
+
+- Initial version published on GitHub.

{sshcatch-0.1.0 → sshcatch-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sshcatch
-Version: 0.1.0
+Version: 0.2.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,65 +21,95 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Security
 Classifier: Topic :: System :: Networking
 Requires-Python: >=3.10
-Requires-Dist: asyncssh>=2.15
+Requires-Dist: asyncssh<2.25.0,>=2.21.0
 Description-Content-Type: text/markdown
 
 # sshcatch
 
-A quick-deploy SSH server for tunneling (local/remote/dynamic) and simple SCP
-transfers - it NEVER opens a shell.
+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 what you need with the flags described below. Handy on an engagement
-when you want a controlled SSH endpoint without using a full `sshd`.
+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 
+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 
+to test.
+
 ## Install
 
+With `pipx` (recommended, installs into an isolated environment and puts
+`sshcatch` on your `PATH`):
+
+```
+pipx install sshcatch
+```
+
+With `pip`:
+
 ```
 pip install sshcatch
 ```
 
-Or from source:
+From source:
 
 ```
 git clone https://github.com/LorenzMap/sshcatch
 cd sshcatch
-pip install .
+pipx install .          # or: pip install .
 ```
 
 Needs Python 3.10+. A host key is auto-generated in the working directory on
 first run (or point `--host-key` at your own).
 
-## Usage
+## How it works
 
-Because no shell is created on the server **always** use the `-N` flag on 
-your tunnel connections or you get disconnected instantly! 
+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.
 
-The SCP directory does intentionally **NOT** support subdirectories! 
+Adjust the amount of logging using `-vv` and `-q`. Or put everything into a 
+logfile using `-o`.
 
-Log-only - just capture creds and full public keys:
+#### Tunnels
 
-```
-# Server
-sshcatch -K
+Because no shell is ever created, tunnel clients **must** pass `-N` (e.g.
+`ssh -NL ...`) or they get disconnected instantly.
 
-# Client
-ssh user@host
-```
+Turning tunneling on with `--open-auth` means **anyone** who connects can pivot
+through your host!
+
+#### 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. 
+
+The host key, `authorized_keys`, logfile and the sshcatch script itself are **protected** 
+and hidden when they live inside the SCP directory.
 
-Let one user pull files via SCP/SFTP:
+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 and Remove operations are denied.
+
+## Examples
+
+Let one user pull/put files from the current directory via SCP/SFTP:
 
 ```
 # Server
-sshcatch -u user:pass --scp-download
+sshcatch -u user:pass --scp-download --scp-upload
 
 # Client
 scp user@host:secret.txt .
+scp -r loot/ user@host:pete/pc/
+sftp user@host
 ```
 
-Let anyone tunnel through the server (local and dynamic forwards):
+Let anyone tunnel through the server (local and dynamic forwards): **Be careful with this one!**
 
 ```
 # Server
@@ -90,8 +120,21 @@ ssh -NL 8080:internal:80 user@host      # local forward
 ssh -ND 1080 user@host                  # dynamic (SOCKS)
 ```
 
-My favorite one - reverse tunnel and SCP uploads for the keys in
-`./authorized-keys`, while posing as a ubuntu SSH server on port 2222:
+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 \
+         --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:
 
 ```
 # Server
@@ -102,15 +145,16 @@ ssh -NR 9000:localhost:22 user@host -p 2222     # reverse tunnel
 scp -P 2222 loot.tar user@host:.                # upload
 ```
 
+
 ## Options
 
 ```
-usage: sshcatch [-h] [--version] [-p PORT] [-b BIND] [--host-key FILE]
-                [-u USER:PASS] [--open-auth] [--authorized-keys FILE] [-K]
+usage: sshcatch [-h] [--version] [-p PORT] [-b BIND] [--host-key FILE] [-1]
+                [-u USER:PASS] [--open-auth] [--authorized-keys FILE]
                 [--forward] [--reverse] [--scp-upload] [--scp-download]
                 [--scp-dir DIR] [--version-banner STRING]
                 [--pre-auth-banner STRING] [--post-auth-banner STRING]
-                [-o FILE] [-t] [--plain]
+                [-q | -v] [-o FILE] [-t] [--plain]
 
 options:
   -h, --help            show this help message and exit
@@ -118,6 +162,8 @@ options:
   -p PORT, --port PORT  listen port (default: 22)
   -b BIND, --bind BIND  bind address (default: all IPv4/v6 interfaces)
   --host-key FILE       server host key file (default: auto-generate)
+  -1, --single          close the listener after first successful
+                        authentication (and exit when that connection ends)
 
 authentication:
   -u USER:PASS, --user USER:PASS
@@ -126,21 +172,20 @@ authentication:
   --authorized-keys FILE
                         authorized_keys file for key auth (username
                         independent)
-  -K, --full-keys       log the full offered public key, not just its
-                        fingerprint
 
 tunneling:
   --forward             enable forward tunnels (client: ssh -NL / -ND)
   --reverse             enable reverse tunnels (client: ssh -NR)
 
-SCP / file transfer:
-  --scp-upload          enable file upload (SCP/SFTP write) - subdirectories
-                        are disabled - files get suffix instead of overwriting
-  --scp-download        enable file download (SCP/SFTP read) - subdirectories
-                        are disabled
-  --scp-dir DIR         directory for SCP/SFTP (default: cwd) - subdirectories
-                        are disabled - host-key (and optional authorized_keys
-                        and logfile) are protected
+SCP / SFTP file transfer:
+  --scp-upload          enable file upload (SCP/SFTP write) - files get suffix
+                        instead of overwriting - symlinks become placeholder
+                        files
+  --scp-download        enable file download (SCP/SFTP read) - symlinks are
+                        denied
+  --scp-dir DIR         directory for SCP/SFTP (default: cwd) - sensitive
+                        files (host-key, authorized_keys, logfile) are
+                        protected
 
 banners:
   --version-banner STRING
@@ -154,20 +199,15 @@ banners:
                         successfully
 
 logging:
+  -q, --quiet           print nothing on console
+  -v, --verbose         print additional information to the console
+                        (repeatable)
   -o FILE, --output FILE
                         append the log to FILE (plain with timestamps)
   -t, --timestamps      prefix console lines with a timestamp
   --plain               disable ANSI colors on the console
 ```
 
-## A word of warning
-
-- This is a pentesting tool. Only point it at systems and networks you are
-authorized to test. 
-
-- `--open-auth --forward` means ANYONE can tunnel through
-your host - know what you're exposing before you run it.
-
 ## License
 
 MIT

sshcatch-0.2.0/README.md

@@ -0,0 +1,187 @@
+# sshcatch
+
+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 
+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 
+to test.
+
+## Install
+
+With `pipx` (recommended, installs into an isolated environment and puts
+`sshcatch` on your `PATH`):
+
+```
+pipx install sshcatch
+```
+
+With `pip`:
+
+```
+pip install sshcatch
+```
+
+From source:
+
+```
+git clone https://github.com/LorenzMap/sshcatch
+cd sshcatch
+pipx install .          # or: pip install .
+```
+
+Needs Python 3.10+. A host key is auto-generated in the working directory on
+first run (or point `--host-key` at your own).
+
+## How it works
+
+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 
+logfile using `-o`.
+
+#### Tunnels
+
+Because no shell is ever created, tunnel clients **must** pass `-N` (e.g.
+`ssh -NL ...`) or they get disconnected instantly.
+
+Turning tunneling on with `--open-auth` means **anyone** who connects can pivot
+through your host!
+
+#### 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. 
+
+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 
+(`loot.tar` -> `loot_1.tar`). Non-existent parent folders are created.
+
+Renames and Remove operations are denied.
+
+## Examples
+
+Let one user pull/put files from the current directory via SCP/SFTP:
+
+```
+# Server
+sshcatch -u user:pass --scp-download --scp-upload
+
+# Client
+scp user@host:secret.txt .
+scp -r loot/ user@host:pete/pc/
+sftp user@host
+```
+
+Let anyone tunnel through the server (local and dynamic forwards): **Be careful with this one!**
+
+```
+# Server
+sshcatch --open-auth --forward
+
+# Client
+ssh -NL 8080:internal:80 user@host      # local forward
+ssh -ND 1080 user@host                  # dynamic (SOCKS)
+```
+
+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 \
+         --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:
+
+```
+# Server
+sshcatch --reverse --authorized-keys ./authorized-keys --scp-upload --version-banner ubuntu -p 2222
+
+# Client
+ssh -NR 9000:localhost:22 user@host -p 2222     # reverse tunnel
+scp -P 2222 loot.tar user@host:.                # upload
+```
+
+
+## Options
+
+```
+usage: sshcatch [-h] [--version] [-p PORT] [-b BIND] [--host-key FILE] [-1]
+                [-u USER:PASS] [--open-auth] [--authorized-keys FILE]
+                [--forward] [--reverse] [--scp-upload] [--scp-download]
+                [--scp-dir DIR] [--version-banner STRING]
+                [--pre-auth-banner STRING] [--post-auth-banner STRING]
+                [-q | -v] [-o FILE] [-t] [--plain]
+
+options:
+  -h, --help            show this help message and exit
+  --version             show program's version number and exit
+  -p PORT, --port PORT  listen port (default: 22)
+  -b BIND, --bind BIND  bind address (default: all IPv4/v6 interfaces)
+  --host-key FILE       server host key file (default: auto-generate)
+  -1, --single          close the listener after first successful
+                        authentication (and exit when that connection ends)
+
+authentication:
+  -u USER:PASS, --user USER:PASS
+                        allowed user:password (repeatable)
+  --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)
+
+SCP / SFTP file transfer:
+  --scp-upload          enable file upload (SCP/SFTP write) - files get suffix
+                        instead of overwriting - symlinks become placeholder
+                        files
+  --scp-download        enable file download (SCP/SFTP read) - symlinks are
+                        denied
+  --scp-dir DIR         directory for SCP/SFTP (default: cwd) - sensitive
+                        files (host-key, authorized_keys, logfile) are
+                        protected
+
+banners:
+  --version-banner STRING
+                        sent as 'SSH-2.0-STRING' version banner - presets
+                        (case-insensitive): ubuntu, debian, dropbear, windows,
+                        macos
+  --pre-auth-banner STRING
+                        banner shown to every client before login
+  --post-auth-banner STRING
+                        banner shown only to clients that authenticate
+                        successfully
+
+logging:
+  -q, --quiet           print nothing on console
+  -v, --verbose         print additional information to the console
+                        (repeatable)
+  -o FILE, --output FILE
+                        append the log to FILE (plain with timestamps)
+  -t, --timestamps      prefix console lines with a timestamp
+  --plain               disable ANSI colors on the console
+```
+
+## License
+
+MIT

{sshcatch-0.1.0 → sshcatch-0.2.0}/pyproject.toml

@@ -25,7 +25,7 @@ classifiers = [
     "Topic :: Security",
     "Topic :: System :: Networking",
 ]
-dependencies = ["asyncssh>=2.15"]
+dependencies = ["asyncssh>=2.21.0,<2.25.0"]
 
 [project.urls]
 Homepage = "https://github.com/LorenzMap/sshcatch"