ClawSec is an encrypted netcat alternative (a modern descendant of Cryptcat) for secure tunnels without certificates: pipe data, transfer files with resume and SHA-256 verification, forward ports, run a SOCKS5 proxy or a point-to-point TUN VPN — all protected by AES-256-GCM and a SPAKE2 password-authenticated key exchange (RFC 9382): forward secrecy, no offline password guessing, optional post-quantum ML-KEM-768.
brew install lf3551/clawsec/clawsec # or a static binary / Docker, see below
clawsec -l -p 4444 --key-file key --recv ./in # receiver
clawsec --key-file key --send backup.tgz host 4444Scope. ClawSec is a community project that has not been externally audited. For production remote access prefer OpenSSH or WireGuard; see SECURITY.md for the threat model and known limitations.
| Area | What you get |
|---|---|
| Crypto | SPAKE2 PAKE (RFC 9382) with transcript-bound mutual key confirmation and forward secrecy, Argon2id, AES-256-GCM records with authenticated headers, HKDF directional keys, optional --pq hybrid with ML-KEM-768 (OpenSSL ≥ 3.5), optional --tofu server identity (Ed25519, known_hosts) |
| Modes | stdin/stdout stream, chat (-c), file transfer with resume + SHA-256 (--send/--recv), port forwarding (-L, --mux), reverse tunnel (-R), SOCKS5 (--socks), TUN VPN (--tun, --tun-udp, --default-route, --masquerade), opt-in remote program (-e), UDP (-u) |
| Operations | -K multi-client with --max-clients, --max-per-ip, --auth-fail-limit, --handshake-timeout, --persistent reconnect, -z compression, -P progress, -V verification, IPv4/IPv6, shell completions, man page |
| Traffic shaping | --obfs http|tls, --fingerprint, --ech, --fallback, --pad, --jitter (see their limits below) |
| Recon | --scan (Linux, as root: pipelined SYN half-open scan for IPv4/IPv6 at --scan-rate probes/s with open/closed/filtered detection; otherwise parallel connect scan; randomised order), -b banner grabbing |
| Footprint | ~135 KB dynamically linked; release binaries for Linux are fully static (~5.6 MB, no runtime dependencies); Docker image ~18 MB |
Unlike ncat --ssl or socat openssl, which use TLS certificates, ClawSec
authenticates both ends with a shared password.
- AES-256-GCM: Authenticated encryption; the frame header (sequence number, length, version) is authenticated too
- SPAKE2 (RFC 9382): password-authenticated key exchange — an eavesdropper or man-in-the-middle cannot test password guesses offline; every attempt costs a connection. Forward secrecy from fresh scalars per session; verified against the RFC test vectors
- Transcript binding: both confirmation MACs (and the
--tofusignature) cover the whole handshake — versions, options, identity key, ML-KEM data - Argon2id: memory-hard password scalar via libargon2, computed once per process
- Key updates (
--rekey 30m|2h|100000r): each direction ratchets its stream key (HKDF, like TLS 1.3 KeyUpdate) and wipes the old one: a key that leaks later does not decrypt earlier traffic, and long sessions have no record limit - Guessing limits: with
-K,--auth-fail-limitblocks an address after repeated wrong passwords,--max-per-ipcaps concurrent handlers per address - Directional keys: HKDF-SHA256 derives separate client→server and server→client keys (TCP and UDP), so frames cannot be reflected
- Version and option check: wrong passwords, incompatible versions and different
--tofu/--pqsettings are reported during the handshake, with a clear error and exit status 1 - Replay Protection: Strict sequence numbers on TCP; sliding anti-replay windows for UDP (
-u: 64,--tun-udp: 256) - Bounded decryption: Plaintext is released only after tag verification and never beyond the caller's buffer
- Protocol Versioning: Wire protocol v4 (ClawSec 4.x); peers on a different version are rejected with a clear error on both ends
- Memory Safety: Key material wiped with
OPENSSL_cleanse; CI runs ASan/UBSan/LeakSanitizer,-Werrorand libFuzzer
These options change how the traffic looks; none of them adds secrecy beyond the inner encryption, and none makes ClawSec undetectable.
| Flag | What it does | Limits |
|---|---|---|
--obfs tls |
Runs the session inside a real TLS 1.3 connection | The server presents a self-signed certificate with a made-up CDN name; anyone who connects can see that it is not that site |
--obfs http |
Wraps every message in an HTTP POST | Trivially recognisable by a protocol-aware observer |
--fingerprint chrome|firefox|safari |
Sets cipher suites, groups, signature algorithms, ALPN (and ALPS for Chrome) like the browser | OpenSSL cannot reproduce extension order, GREASE or other details: the ClientHello approximates a browser, it does not match its JA3/JA4 exactly |
--ech |
Adds a GREASE Encrypted Client Hello extension | The visible SNI (a fake CDN name) is still sent in clear; nothing is actually hidden by it |
--fallback host:port |
After the TLS handshake, clients that do not send the ClawSec knock are proxied to another service | Probers still see ClawSec's self-signed certificate; unlike REALITY it does not borrow a real site's TLS identity |
--pad |
Every encrypted record is padded to a multiple of 1400 bytes (in every mode: stream, -L, --mux, --socks, -R, -u, --tun, --tun-udp, file transfer); stream-like modes send 1400-byte records |
Hides message sizes, not timing or total volume; both ends need --pad and 4.2+ (negotiated, mismatch is an explicit error); with --tun the interface MTU becomes 1392 |
--jitter N |
Random 0–N ms delay before each message | Adds latency; does not hide traffic volume |
# Clone repository
git clone https://github.com/LF3551/ClawSec.git
cd ClawSec
# Install build dependencies, build, optionally install to /usr/local/bin
./scripts/install.shbrew install lf3551/clawsec/clawsecEvery release has tested binaries
(clawsec-<version>-<os>-<arch>.tar.gz, verify with SHA256SUMS):
Linux x86_64 and arm64 are fully static (no runtime dependencies, any
distribution); macOS arm64 and x86_64 use Homebrew's openssl@3 and argon2
(brew install openssl@3 argon2, or use the tap above).
Verifying a download (releases from 4.3.0 on are signed in CI with Sigstore; nothing to trust but GitHub's OIDC identity of the release workflow):
# checksums, signed keylessly by the release workflow
cosign verify-blob SHA256SUMS --bundle SHA256SUMS.sigstore.json \
--certificate-identity-regexp '^https://github.com/LF3551/ClawSec/\.github/workflows/release\.yml@' \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
sha256sum --ignore-missing -c SHA256SUMS
# SLSA build provenance of an archive (which workflow and commit built it)
gh attestation verify clawsec-<version>-linux-x86_64.tar.gz -R LF3551/ClawSec
# Docker image signature (SBOM and provenance are attached to the image)
cosign verify ghcr.io/lf3551/clawsec:<version> \
--certificate-identity-regexp '^https://github.com/LF3551/ClawSec/\.github/workflows/docker-publish\.yml@' \
--certificate-oidc-issuer https://token.actions.githubusercontent.comcd src
make linux # Linux with system OpenSSL
make macos # macOS with Homebrew OpenSSL
make alpine # Alpine Linux (Docker)
make freebsd # FreeBSD
make netbsd # NetBSD# Build image
docker build -t clawsec .
# Run server (the image has no default password; pass it via the environment)
docker run -e CLAWSEC_PASSWORD="$(openssl rand -base64 24)" -p 8888:8888 clawsec
# Or use docker compose
CLAWSEC_PASSWORD="$(openssl rand -base64 24)" docker compose up
# Prebuilt multi-arch images: ghcr.io/lf3551/clawsec, lf3551/clawsecClawSec supports three main modes: Chat Mode, Reverse Shell Mode, and File Transfer Mode.
Secure encrypted chat with session fingerprints, read receipts, inline file sharing, and slash commands.
Server:
./clawsec -l -p 8888 -k "TestPass123" -c -n "Alice"Client:
./clawsec -k "TestPass123" -c -n "Bob" server-ip 8888Features:
- 🔐 Session fingerprint: emoji + hex fingerprint shown at connect — verify both sides match to confirm no MITM
- 📛 Custom nicknames (
-n): display names instead of Server/Client - ✓✓ Read receipts: automatic delivery confirmations
- 📎 Inline file sharing:
/file pathsends small files (up to ~8 KB) through the chat; use--send/--recvfor larger files - 🏓 Encrypted ping:
/pingmeasures RTT through the encrypted tunnel - Slash commands:
/file,/ping,/clear,/whoami,/help - Colored timestamps: green for local, cyan for remote
- Session duration shown on disconnect
- All communication encrypted with AES-256-GCM + PFS
Get encrypted command-line access to a remote machine.
-ehands a program (here a shell) to anyone who knows the password, so it is not built by default since 3.0. Build it in explicitly:make linux DFLAGS=-DGAPING_SECURITY_HOLE(ormacos,freebsd, ...).
Server (target machine):
cd ~/ClawSec/src
make linux DFLAGS=-DGAPING_SECURITY_HOLE
./clawsec -l -p 8888 -k "TestPass123" -e /bin/bashClient (your machine):
./clawsec -k "TestPass123" server-ip 8888Features:
- Full encrypted shell access to target
- Run commands:
ls,cd,cat,ps,whoami,pwd, etc. - All traffic encrypted end-to-end
- Clean output without formatting
Note: Interactive programs (nano, vim, top) are now supported with PTY (pseudo-terminal). Use Ctrl+C to terminate programs, and exit or Ctrl+D to close the shell.
Transfer files with compression, progress bar, and SHA-256 verification.
Server (receiving machine):
./clawsec -v -l -p 8888 -k "FilePass123" > received_file.pyClient (sending machine):
./clawsec -v -k "FilePass123" server-ip 8888 < file_to_send.pyWith compression, progress & verification:
# Server
./clawsec -l -p 8888 -k "FilePass123" -z -P -V > received.tar.gz
# Client
./clawsec -k "FilePass123" -z -P -V server-ip 8888 < archive.tar.gzFeatures:
-zzlib compression: reduces bandwidth 3-5x for text files-Pbuilt-in progress bar with speed and bytes (no externalpvneeded)-VSHA-256 end-to-end verification: hash sent after transfer, receiver verifies- Automatic connection close after transfer
- Transfer statistics:
[Transfer complete] Sent/Received X bytes - Files transferred with full AES-256-GCM encryption
- Supports any file type (text, binary, archives)
Advanced Examples:
# Transfer archive
tar -czf - /path/to/directory | ./clawsec -k "pass" server 9999
./clawsec -l -p 9999 -k "pass" | tar -xzf -
# Transfer with progress (requires pv)
pv largefile.iso | ./clawsec -k "pass" server 7777
./clawsec -l -p 7777 -k "pass" > largefile.iso- OpenSSL 3.x: AES-GCM, P-256 (SPAKE2), HKDF, TLS camouflage (
--pqneeds OpenSSL ≥ 3.5) - libargon2: Argon2id password hashing (same result on every platform)
- zlib:
-zcompression - GCC/G++ or Clang: C11 / C++11
- POSIX System: Linux, BSD, macOS
# macOS
brew install openssl@3 argon2
# Debian/Ubuntu
sudo apt-get install libssl-dev libargon2-dev zlib1g-dev build-essential
# Fedora/RHEL (EPEL)
sudo dnf install openssl-devel libargon2-devel zlib-devel gcc gcc-c++ make
# Arch
sudo pacman -S openssl argon2 zlib
# Alpine
apk add openssl-dev argon2-dev zlib-dev gcc g++ make musl-dev linux-headersUsage: clawsec [options] hostname port
clawsec -l -p port [options]
Password (one of; precedence top to bottom):
-k password On the command line (visible in ps/history; discouraged)
--key-file file First line of a file (mode 0600)
CLAWSEC_PASSWORD Environment variable
(none) Prompt on the terminal, no echo
Connection:
-l Listen mode for inbound connections
-p port Local port number
-K Keep-open: one handler process per client
--max-clients n With -K: concurrent handlers (default 16)
--control path With -K: status socket (read with clawsec --status path)
--config file Read options from a file (key = value)
--max-per-ip n With -K: concurrent handlers per address, IPv6 per /64
(default 8, 0 = unlimited)
--users file Server: per-user passwords instead of one shared password
--add-user name With --users: add a user or change its password
--set-user name With --users: change a user's options (--user-option)
--del-user name With --users: remove a user
--user-option o ip=A.B.C.D | socks-allow=CIDR;CIDR | disabled | none
--user name Client: log in as name (server runs --users)
--rekey when Update the stream keys every 30m, 2h or 100000r records
(both ends, 4.3+; not with -u)
--auth-fail-limit n With -K: refuse an address for 10 min after n wrong
passwords within 10 min (default 5, 0 = off)
--handshake-timeout s Abort session setup after s seconds (default 15, 0 = off)
Options:
-c Chat mode with timestamps and colors
-v Verbose mode
-z Compress data with zlib before encryption
-P Show transfer progress bar
-V SHA-256 end-to-end file verification
-n name Chat nickname (default: Server/Client)
-L host:port Port forwarding (encrypted tunnel)
--obfs http Traffic obfuscation (anti-DPI)
--obfs tls Run inside TLS 1.3 (self-signed certificate)
--ech Add a GREASE Encrypted Client Hello extension
--mux Multiplex streams over one tunnel (with -L): up to 255
concurrent streams, flow control, half-close
--fallback h:p Proxy clients without the ClawSec knock to h:p
--tofu Trust On First Use (SSH-like server identity)
--pq Post-quantum hybrid (SPAKE2 + ML-KEM-768)
--fingerprint p Browser-like TLS ClientHello (chrome, firefox, safari)
--scan range Port scan, randomised order (1-1024, 22-443, all)
--scan-rate pps SYN scan probes per second (default 1000)
-b Banner grab (show service version on open ports)
--socks [h:]port SOCKS5 proxy through encrypted tunnel (client listens on
127.0.0.1 unless an address is given; no proxy auth)
--socks-allow l SOCKS server: allow only destinations in CIDR list l
(default: all except loopback, link-local/metadata, multicast)
--pad Pad every record to 1400-byte units (all modes; both ends)
--jitter ms Random delay 0-N ms between packets
-w secs Timeout for connects
--version Print version and wire protocol
-e prog Execute program per connection (only in builds made with
DFLAGS=-DGAPING_SECURITY_HOLE)
# Server: Listen for encrypted chat
./clawsec -l -p 8888 -k "TestPass123" -c -n "Alice"
# Client: Connect to server for chat
./clawsec -k "TestPass123" -c -n "Bob" server-ip 8888Both sides see:
╔══════════════════════════════════════╗
║ 🔐 ClawSec Encrypted Chat ║
╚══════════════════════════════════════╝
🔐 Session: a3f2-81bc-44de-9f71 🔒🌟💎🚀🍀🌸
Verify this matches on both sides to confirm no MITM.
Type /help for commands
📛 Peer identified as: Bob
[10:30:15 Alice] Hello!
✓✓ delivered
[10:30:18 Bob] Hi! Check /ping
✓✓ delivered
🏓 Pong: 12 ms RTT
# Server: Provide encrypted shell access (binary built with DFLAGS=-DGAPING_SECURITY_HOLE)
./clawsec -l -p 8888 -k "TestPass123" -e /bin/bash
# Client: Connect and execute commands
./clawsec -k "TestPass123" server-ip 8888
ls
pwd
whoami# Server: Receive file with statistics
./clawsec -v -l -p 8888 -k "FilePass123" > received.py
# Client: Send file
./clawsec -v -k "FilePass123" server-ip 8888 < file.py
# With compression + progress + verification
./clawsec -z -P -V -l -p 8888 -k "FilePass123" > received.iso
./clawsec -z -P -V -k "FilePass123" server-ip 8888 < file.isoOutput:
[Sent] 42.3 MB (12.5 MB/s)
[Transfer complete] Sent 88000000→42300000 bytes (compressed)
[Verify] SHA-256 OK: ba7816bf8f01cfea...
# Transfer directory as archive
tar -czf - /data | ./clawsec -k "pass" server 9999
./clawsec -l -p 9999 -k "pass" | tar -xzf -
# Verbose debug mode
./clawsec -vv -l -p 8080 -k "debug"# Scan common ports (1-1024)
./clawsec --scan 1-1024 target.com
# Scan ALL ports (65535) — takes ~2 seconds on localhost, ~60s remote
./clawsec --scan all target.com
# Custom range, slower and randomised (--jitter between probes)
./clawsec --scan 1-65535 --jitter 50 target.com
# Force IPv4/IPv6
./clawsec --scan 1-1024 -4 target.com
./clawsec --scan 1-1024 -6 target.com
# Verbose — shows scan method
./clawsec --scan 22-443 -v target.com# Scan with service version detection
./clawsec --scan 1-1024 -b target.com
# Example output:
# 22/tcp open
# └─ SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.6
# 80/tcp open
# └─ HTTP/1.1 200 OK
# 443/tcp open
# └─ (TLS — no plaintext banner)# Server: accept connections and proxy outbound
./clawsec -l -k "strongpass" -p 9999 --socks 0
# Client: open local SOCKS5 proxy on 127.0.0.1:1080
./clawsec -k "strongpass" --socks 1080 server.com 9999
# The proxy has no authentication, so it listens on loopback by default.
# Share it with your LAN only deliberately: --socks 0.0.0.0:1080
# Server-side destination policy: by default every destination is allowed
# EXCEPT the server itself (127.0.0.0/8, ::1), link-local / cloud metadata
# (169.254.169.254, fd00:ec2::254, ...), multicast and reserved ranges.
# Restrict it to an explicit list (replaces the defaults):
./clawsec -l -k "strongpass" -p 9999 --socks 0 --socks-allow 10.0.0.0/8,192.168.1.0/24
# Now use any SOCKS5-aware application:
curl --proxy socks5://127.0.0.1:1080 https://ifconfig.me
# Firefox: Settings → Network → SOCKS5 → 127.0.0.1:1080
# ssh: ssh -o ProxyCommand='nc -x 127.0.0.1:1080 %h %p' user@target
# Combine with other features:
./clawsec -k "pass" --socks 1080 --pq --tofu --obfs tls server.com 9999Since 4.1 every SOCKS connection is a separate multiplexed stream: a browser can load a page over dozens of parallel connections, a slow download does not hold up other connections, and half-closed connections work. Both ends need 4.1 or later; with an older server the client falls back to one connection at a time and prints a warning.
# Receiver: listen and save files to ./incoming/
./clawsec -l -k "secretkey" -p 4444 --recv ./incoming
# Sender: encrypt and transfer a file
./clawsec -k "secretkey" --send backup.tar.gz remote.host 4444
# Features:
# - AES-256-GCM encrypted transfer
# - SHA-256 end-to-end verification
# - Automatic resume on interrupted transfers (data is kept in
# <name>.clawsec-part and moved into place only after SHA-256 matches)
# - Progress bar with speed display
# - Receiver never writes through symlinks/hard links, never creates hidden
# files or paths outside the target directory
# Combine with post-quantum crypto and obfuscation:
./clawsec -k "pass" --send secret.pdf --pq --obfs tls server.com 4444# Expose internal service (e.g. web app on :3000) to remote server
# Server: listen on 9999, open port 8080 for reverse connections.
# The server listens exactly on the given address: 0.0.0.0 = public,
# 127.0.0.1 = only reachable from the server itself.
./clawsec -l -k "strongpass" -p 9999 -R 0.0.0.0:8080 -v
# Client (behind NAT/firewall): connect and forward to local :3000
./clawsec -k "strongpass" -R 127.0.0.1:3000 -v server.com 9999
# Now anyone can access server.com:8080 → tunneled to client's localhost:3000
# Works like SSH -R but with AES-256-GCM encryption, no certificates needed
# Combine with traffic shaping:
./clawsec -k "pass" -R 127.0.0.1:22 --pq --obfs tls --persistent server.com 443# Client auto-reconnects on disconnect (exponential backoff 1s→60s)
./clawsec -k "pass" --persistent -R 127.0.0.1:22 server.com 9999
# Keeps tunnel alive through network interruptions
# Works with any mode: -L, -R, --socks, chat, etc.
./clawsec -k "pass" --persistent --socks 1080 server.com 443
# Ideal for:
# - Unstable networks (mobile, satellite)
# - Long-running tunnels that must survive reboots
# - Unattended links that must come back after outagesRequirements:
- Root/sudo (for TUN device creation)
- Server must have a public (white) IP or a forwarded port on the router. Behind CGNAT/double NAT the server cannot accept incoming connections — use a VPS ($3/mo) as relay or ask your ISP for a public IP.
- Dynamic public IP works fine — consider DDNS (e.g. noip.com) so clients can connect by hostname instead of a changing address.
# Point-to-point encrypted VPN with one command
# Server (public IP or port-forwarded):
sudo ./clawsec -l -k "VpnSecret123" -p 9000 --tun 10.0.0.1/24 --masquerade
# Client — ALL traffic through VPN (like a real VPN service):
sudo ./clawsec -k "VpnSecret123" server.com 9000 --tun 10.0.0.2/24 --default-route
# UDP data channel — avoids TCP-over-TCP meltdown, lower latency:
sudo ./clawsec -l -k "VpnSecret123" -p 9000 --tun 10.0.0.1/24 --masquerade --tun-udp
sudo ./clawsec -k "VpnSecret123" server.com 9000 --tun 10.0.0.2/24 --default-route --tun-udp
# That's it! Your entire internet now goes through the server.
# curl ifconfig.me will show the server's IP, not yours.
# With --masquerade, server NATs client traffic to internet (exit node)
# Without --default-route, only VPN subnet traffic goes through tunnel
# With --default-route, ALL traffic goes through VPN (full tunnel mode)
# Combine with PQ crypto for quantum-resistant VPN:
sudo ./clawsec -k "pass" --tun 10.0.0.2/24 --default-route --pq --persistent server.com 9000
# Dynamic IP? Use DDNS hostname:
sudo ./clawsec -k "pass" --tun 10.0.0.2/24 --persistent myvpn.ddns.net 9000
# No public IP at all? Use a $3 VPS as relay:
# VPS: ./clawsec -l -k "pass" -p 9000 --tun 10.0.0.1/24 --masquerade
# Client: sudo ./clawsec -k "pass" vps.example.com 9000 --tun 10.0.0.2/24Many clients, IPv6 (4.2+). With -K the server becomes a hub: one TUN
device, one process per client, addresses handed out by the server:
# Server: IPv4 /24 and an IPv6 ULA prefix, NAT for both, per-user passwords
sudo clawsec -l -p 9000 -K --tun 10.8.0.1/24 --tun6 fd00:c1a5::1/64 --masquerade \
--users /etc/clawsec/users
# Clients: ask the server for an address (10.8.0.2 + fd00:c1a5::2, ...)
sudo clawsec --user alice --tun auto --default-route vpn.example.com 9000
sudo clawsec --user bob --tun 10.8.0.20/24 vpn.example.com 9000 # fixed address- Each client may only send from its own addresses (anything else is dropped and logged); packets are routed to clients by destination address.
- Client-to-client traffic passes the server's kernel: it works when IP
forwarding is on (
--masqueradeenables it) and can be filtered there. --default-routewith IPv6 adds::/1and8000::/1through the tunnel; removed again on exit.- ClawSec 4.1 clients still work (the hub learns their address from the first packet).
--tun-udpworks with-Ktoo (4.3+): the hub runs every client's UDP data channel on the server port, with its own replay window per client; clients that cannot use UDP stay on the TCP channel.
SPAKE2 rules out offline guessing, but each connection is still one online
guess. Use a random password (openssl rand -base64 24, ≥ 128 bits) or a long
passphrase; never default, example or dictionary passwords.
-k <password> works, but anything on the command line is visible to other
local users (ps, /proc/<pid>/cmdline) and ends up in shell history.
ClawSec overwrites it in its own argv right away, but prefer:
# 1. A key file (first line; keep it mode 0600)
openssl rand -base64 24 > ~/.clawsec-key && chmod 600 ~/.clawsec-key
clawsec -l -p 1234 --key-file ~/.clawsec-key
# 2. The CLAWSEC_PASSWORD environment variable (removed from the environment
# after reading, so -e programs and child processes do not inherit it)
CLAWSEC_PASSWORD="$(cat ~/.clawsec-key)" clawsec server.example.com 1234
# 3. No password option at all: ClawSec prompts on the terminal (no echo)
clawsec server.example.com 1234Precedence: -k > --key-file > CLAWSEC_PASSWORD > prompt.
Docker, docker-compose, Kubernetes and systemd examples in this repository
use the environment variable or a systemd credential.
Instead of one shared password, a server can give every user their own:
# Server admin: add users (asks for the password twice; file mode 0600)
clawsec --users /etc/clawsec/users --add-user alice
clawsec --users /etc/clawsec/users --add-user bob
# Server: no shared password needed
clawsec -l -p 9000 -K --users /etc/clawsec/users
# Client
clawsec --user alice server.example.com 9000 # password prompt / --key-file / CLAWSEC_PASSWORD-
The users file stores
w = Argon2id(password, user-specific salt), not passwords; equal passwords give different lines. SPAKE2 is a balanced PAKE, so a line still lets someone log in as that user: protect the file like a private key. -
The file is read on every connection: add, change or delete users without a restart.
-
Per-user options: a fixed VPN address, the user's own SOCKS destinations, or a disabled account:
clawsec --users /etc/clawsec/users --add-user carol --user-option ip=10.8.0.10 clawsec --users /etc/clawsec/users --set-user bob --user-option socks-allow=10.0.0.0/8 clawsec --users /etc/clawsec/users --set-user bob --user-option disabled # lock clawsec --users /etc/clawsec/users --set-user bob --user-option none # clear clawsec --users /etc/clawsec/users --del-user bob
-
An unknown user fails exactly like a wrong password (no user enumeration).
-
The server logs
user 'alice' logged in;-eprograms getCLAWSEC_USER. -
Not available with
-u.
Long server command lines can live in a file; options given on the command
line come after it and win. A password cannot be put there (use key-file).
# /etc/clawsec/server.conf
listen
port = 9000
keep-open
tun = 10.8.0.1/24
tun6 = fd00:c1a5::1/64
masquerade
users = /etc/clawsec/users
max-clients = 64
control = /run/clawsec.socksudo clawsec --config /etc/clawsec/server.conf
sudo clawsec --status /run/clawsec.sock
# ClawSec 4.3.0, pid 1234, up 2h05m, 2 of 64 sessions
# PID PEER USER AGE
# 4321 203.0.113.7 alice 1h12m
# VPN SLOT PID USER IPV4 IPV6 RX (pkts/B) TX (pkts/B)
# 0 4321 alice 10.8.0.10 fd00:c1a5::a 48211/31M 52940/58MKeys are the long option names (tun, users, max-per-ip, …) or listen,
port, keep-open, udp, ipv4, ipv6, verbose, timeout, forward,
reverse, … for the short ones; flags are key or key = yes|no. The status
socket is created with mode 0600 and only reports sessions (no secrets).
- Use a random password (
openssl rand -base64 24) - Never put passwords in scripts or command lines; use
--key-fileorCLAWSEC_PASSWORD - Share passwords through secure channels only
- Expose servers with
-Kand keep the defaults--max-clients 16,--max-per-ip 8,--auth-fail-limit 5and--handshake-timeout 15(or lower): idle clients cannot pile up and password guessing is throttled (authentication failure from <address>is logged; a block is always logged)
| Component | Algorithm | Parameters |
|---|---|---|
| Cipher | AES-256 | 256-bit key |
| Mode | GCM | AEAD with authentication |
| Key exchange | SPAKE2, RFC 9382 | P-256, SHA-256, HKDF, HMAC; fresh scalars per session |
| Password scalar | Argon2id (libargon2) | t=3, m=19 MiB, p=1 |
Post-quantum (--pq) |
ML-KEM-768 (FIPS 203) | hybrid with SPAKE2 |
| Traffic keys | HKDF-SHA256 | separate keys per direction, per channel (TCP / UDP) |
| IV | CSPRNG | 96 bits (12 bytes) |
| Auth Tag | GMAC | 128 bits (16 bytes), covers header (AAD) + ciphertext |
[MAGIC:4][VERSION:2][FLAGS:2][SEQ:4][LENGTH:4][IV:12][TAG:16][CIPHERTEXT]
- Magic number:
0x434C4157("CLAW") - Version:
0x0004(protocol v4, ClawSec 4.x — not compatible with ClawSec ≤ 3.1.0) - Sequence number: strictly consecutive per direction; a session never reuses one
- The 16-byte header is GCM associated data: altering sequence, length, version or flags invalidates the tag
Client ──TCP connect──▶ Server
Client ◀── hello "CS"+v4+flags, pB = y·P + w·N [, identity key] [, ML-KEM pk] ── Server
Client ── hello "CS"+v4+flags, pA = x·P + w·M [, ML-KEM ciphertext] ──▶ Server
[Both: K, TT, Ke as in RFC 9382; AAD = SHA-256(message 1 ‖ message 2)]
Client ◀── cB = HMAC(KcB, TT) [, Ed25519 signature over TT and AAD] ── Server
Client ── cA = HMAC(KcA, TT) ──▶ Server
[Both: session = HKDF(Ke [‖ ML-KEM secret], "ClawSec v4 session" ‖ AAD)]
Client ◀──encrypted messages──▶ Server
w = Argon2id(password). A peer on another protocol version or with other
--tofu/--pq settings is reported at the hello; a wrong password or any
change to the handshake fails the confirmation, on both ends. A failed attempt
gives an attacker nothing to test further password guesses against offline.
Perfect Forward Secrecy: even if the password is later compromised, previously recorded sessions cannot be decrypted.
See SECURITY.md for detailed cryptographic documentation.
| Feature | ClawSec | Original Cryptcat | Netcat |
|---|---|---|---|
| Encryption | AES-256-GCM | Twofish (deprecated) | None |
| Authentication | GCM Tag | None | None |
| Key Derivation | Argon2id + HKDF | Direct key | N/A |
| Memory Safety | Secure wiping | No | N/A |
| Protocol Version | Yes | No | N/A |
cd src
# Unit/integration tests (140 tests)
make linux && make test # macOS: make macos && make test-macos
# Same tests under AddressSanitizer + UndefinedBehaviorSanitizer
make test-asan
# End-to-end tests of the real binary (Linux): stream modes, --mux, --socks,
# -R, --send/--recv, wrong password, control-byte payloads
make e2e
# VPN end-to-end tests in network namespaces (Linux, root): --tun, --tun-udp
sudo make e2e-vpnTest coverage:
- Encrypt/decrypt roundtrip
- Multi-message sequencing
- Random salt generation & uniqueness
- Different salts → different ciphertext
- Wrong password rejection
- Replay protection (duplicated packets rejected)
- SPAKE2 against all RFC 9382 test vectors; invalid points rejected
- Protocol v4 handshake: v3 peers rejected without hanging, option mismatch, wrong password reported on both ends, man-in-the-middle tampering detected
- Record layer: reflection, replay with edited sequence number, header tampering, version mismatch, forged frames, buffer bounds
-Kper-address limits and authentication lockout (IPv6 per /64)- Large messages (8KB)
- Input validation (NULL/empty password, invalid salt)
- Protocol magic validation
- Full handshake simulation
- Bidirectional communication
- Obfuscation (HTTP mode send/recv, multi-message, large payload)
- Host:port parsing (IPv4, IPv6, hostname, invalid)
- Zlib compress/decompress roundtrip
- SHA-256 known vector and incremental hashing
- Session fingerprint determinism
- Control message protocol format
- farm9crypt_initialized state tracking
- Raw 32-byte key initialization
- Fingerprint error when uninitialized
- write_all full buffer correctness
- TLS camouflage accept/connect roundtrip
- Packet padding/unpadding roundtrip
- Padding uniform size across different inputs
- Padding rejects oversized input
- Timing jitter applies delay
- Timing jitter(0) is no-op
# Manual connection test (two terminals)
# Terminal 1:
./clawsec -l -p 12345 -k "TestPassword" -v
# Terminal 2:
echo "Test message" | ./clawsec localhost 12345 -k "TestPassword"Missing -k password option. Always provide password parameter.
Key confirmation failed: the two endpoints use different passwords (or the
handshake was tampered with). Both ends exit with status 1. With -K, the
server counts the failure against the client address (--auth-fail-limit).
ClawSec 4.x speaks wire protocol 4 and does not interoperate with 3.x or 2.x.
Upgrade both endpoints to the same major release; clawsec --version
prints the release and protocol version.
--tofu and --pq change the handshake and must be set identically on both ends.
The address is temporarily blocked after repeated wrong passwords (the server
logs blocking it for 600 s), or it already has --max-per-ip sessions.
A data frame failed authentication after the handshake: corrupted or tampered traffic.
Since 3.0, -e is opt-in: make linux DFLAGS=-DGAPING_SECURITY_HOLE.
Network error, or the peer closed the session.
# macOS (Homebrew): the macos target already uses /opt/homebrew/opt/{openssl@3,argon2}
brew install openssl@3 argon2
cd src && make clean && make macos
# Linux: "argon2.h: No such file" -> install libargon2-dev (Debian/Ubuntu),
# libargon2-devel (Fedora/RHEL), argon2 (Arch), argon2-dev (Alpine)Contributions are welcome. Please:
- Review SECURITY.md before submitting security-related changes
- Test thoroughly
- Document all changes
- Follow existing code style
Based on Netcat and Cryptcat. See LICENSE for details.
This tool is for authorized testing and legitimate use only.
- Obtain permission before testing networks
- Comply with all applicable laws and regulations
- Authors not responsible for misuse or unauthorized access
- Use at your own risk
- Original Netcat: Hobbit
- Original Cryptcat: Farm9 team
- ClawSec Modernization: 2025 security enhancements
- OpenSSL Project: Cryptographic library
- SECURITY.md - Detailed security documentation
- docs/EXAMPLE_USAGE.md - Usage examples
- docs/FAQ.md - Frequently asked questions
- CHANGELOG.md - Version history
- CONTRIBUTING.md - Development guide
- OpenSSL GCM Documentation
- NIST SP 800-38D - GCM Specification
- Argon2 RFC 9106
ClawSec/
├── src/ # Source code (C/C++)
├── tests/ # Unit tests (140) + end-to-end scripts
├── docs/ # Documentation (FAQ, examples, man page)
├── scripts/ # Build, install, quickstart scripts
├── deploy/ # Deployment configs (systemd, k8s, Homebrew)
├── completions/ # Shell completions (bash, fish, zsh)
├── releases/ # Release archives
├── .github/workflows # CI/CD (build, CodeQL, Docker)
├── Dockerfile # Docker build
└── docker-compose.yml
