LF3551/ClawSec
LF3551/ClawSec has 70 GitHub stars and 0 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-17 15:04 UTC. Last push 2026-11-15.
What you can do
- Crypto - AES-256-GCM records with authenticated headers, X25519 ECDHE (forward secrecy), Argon2id password binding, HKDF directional keys, explicit key confirmation, 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, --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)
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Modern, secure, and minimalist encrypted network tool. Strong encryption , cross-platform, and easy to use.
SecurityREADME.md
Original
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, X25519 forward secrecy and an Argon2id-bound shared password, with 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 4444
Scope. 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 (notably: no PAKE yet, so use a long random password).
Features
| Area | What you get |
|---|---|
| Crypto | AES-256-GCM records with authenticated headers, X25519 ECDHE (forward secrecy), Argon2id password binding, HKDF directional keys, explicit key confirmation, 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, --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 SYN half-open as root, 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.
Security Features
- AES-256-GCM: Authenticated encryption; the frame header (sequence number, length, version) is authenticated too
- X25519 ECDHE: Perfect Forward Secrecy — each session has unique ephemeral keys
- Argon2id: Memory-hard password binding via libargon2 (identical keys on every platform and OpenSSL version)
- Directional keys: HKDF-SHA256 derives separate client→server and server→client keys (TCP and UDP), so frames cannot be reflected
- Key confirmation & version check: wrong passwords and incompatible peers are rejected 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 v3 (ClawSec 3.x); peers on a different version are rejected with a clear error
- Memory Safety: Key material wiped with
OPENSSL_cleanse; CI runs ASan/UBSan/LeakSanitizer,-Werrorand libFuzzer
Traffic shaping (anti-DPI) — what it does and does not do
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 |
Pads stream/chat/-L messages to 1400 bytes |
Not applied in --mux, --socks, -R, --tun or file-transfer modes |
--jitter N |
Random 0–N ms delay before each message | Adds latency; does not hide traffic volume |
Quick Start
Automatic Installation
# Clone repository
git clone https://github.com/LF3551/ClawSec.git
cd ClawSec
# Install build dependencies, build, optionally install to /usr/local/bin
./scripts/install.sh
Homebrew (macOS, Linux)
brew install lf3551/clawsec/clawsec
Prebuilt binaries
Every 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).
Manual Build
cd src
make linux # Linux with system OpenSSL
make macos # macOS with Homebrew OpenSSL
make alpine # Alpine Linux (Docker)
make freebsd # FreeBSD
make netbsd # NetBSD
Docker
# 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/clawsec
Basic Usage
ClawSec supports three main modes: Chat Mode, Reverse Shell Mode, and File Transfer Mode.
1. Chat Mode (Encrypted Communication)
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 8888
Features:
- 🔐 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
2. Reverse Shell Mode (Encrypted Remote Access)
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/bash
Client (your machine):
./clawsec -k "TestPass123" server-ip 8888
Features:
- 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.
3. File Transfer Mode (Secure File Transmission)
Transfer files with compression, progress bar, and SHA-256 verification.
Server (receiving machine):
./clawsec -v -l -p 8888 -k "FilePass123" > received_file.py
Client (sending machine):
./clawsec -v -k "FilePass123" server-ip 8888 < file_to_send.py
With 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.gz
Features:
-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
Requirements
- OpenSSL 3.x: AES-GCM, X25519, 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
Install dependencies
# 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-headers
Usage
Usage: 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)
--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)
--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 (X25519 + ML-KEM-768)
--fingerprint p Browser-like TLS ClientHello (chrome, firefox, safari)
--scan range Port scan, randomised order (1-1024, 22-443, all)
-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 packets to uniform 1400 bytes
--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)
Examples
Chat Mode
# 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 8888
Both 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
Reverse Shell Mode
# 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
File Transfer Mode
# 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.iso
Output:
[Sent] 42.3 MB (12.5 MB/s)
[Transfer complete] Sent 88000000→42300000 bytes (compressed)
[Verify] SHA-256 OK: ba7816bf8f01cfea...
Advanced Examples
# 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"
Port Scan
# 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
Banner Grabbing
# 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)
SOCKS5 Proxy (Encrypted Tunnel)
# 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 9999
Encrypted File Transfer (Resume + SHA-256)
# 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
Reverse Tunnel (-R)
# 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
Persistent Auto-Reconnect
# 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 outages
TUN VPN Mode (--tun)
Requirements:
- 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 (one client per server process)
# 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/24
Password Requirements
Strong passwords:
- Minimum 12 characters recommended
- Mix of uppercase, lowercase, numbers, symbols
- Example:
MyS3cur3Tr@nsf3r2025
Avoid:
- Default passwords
- Dictionary words
- Short passwords (less than 8 characters)
Passing the password
-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 1234
Precedence: -k > --key-file > CLAWSEC_PASSWORD > prompt.
Docker, docker-compose, Kubernetes and systemd examples in this repository
use the environment variable or a systemd credential.
Operational Security
- Use a long random password (
openssl rand -base64 24): there is no PAKE yet - 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 16and--handshake-timeout 15(or lower) so idle or slow clients cannot pile up
Cryptographic Specifications
| Component | Algorithm | Parameters |
|---|---|---|
| Cipher | AES-256 | 256-bit key |
| Mode | GCM | AEAD with authentication |
| Password binding | Argon2id (libargon2) | t=3, m=19 MiB, p=1 |
| 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 |
Protocol Format
[MAGIC:4][VERSION:2][FLAGS:2][SEQ:4][LENGTH:4][IV:12][TAG:16][CIPHERTEXT]
- Magic number:
0x434C4157("CLAW") - Version:
0x0003(protocol v3, ClawSec 3.x — not compatible with ClawSec ≤ 2.8.2) - 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
Session Handshake
Client ──TCP connect──▶ Server
Client ◀──hello "CS"+version (4B), X25519 pubkey (32B)── Server
Client ──hello "CS"+version (4B), X25519 pubkey (32B)──▶ Server
[Both: session = SHA256(ECDH_secret || Argon2id(password, SHA256(pubkeys)))]
[Both: k_c2s, k_s2c = HKDF-SHA256(session, "ClawSec v3 tcp c2s" / "... s2c")]
Client ◀──key confirmation HMAC (32B) each way──▶ Server
Client ◀──encrypted messages──▶ Server
A peer on another protocol version (e.g. ClawSec 2.x) is rejected at the hello; a wrong password is rejected at key confirmation, on both ends.
Password strength matters. The password is not protected by a PAKE yet: an active attacker who completes a handshake can test password guesses offline. Use a long random password (e.g.
openssl rand -base64 24).
Perfect Forward Secrecy: even if password is later compromised, previously recorded sessions cannot be decrypted.
See SECURITY.md for detailed cryptographic documentation.
Comparison
| 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 |
Testing
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-vpn
Test coverage:
- Encrypt/decrypt roundtrip
- Multi-message sequencing
- Random salt generation & uniqueness
- Different salts → different ciphertext
- Wrong password rejection
- Replay protection (duplicated packets rejected)
- Protocol v3 regressions: reflection, replay with edited sequence number, header tampering, version mismatch, forged frames, buffer bounds
- 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"
Troubleshooting
"Encryption not initialized"
Missing -k password option. Always provide password parameter.
"authentication failed - wrong password"
Key confirmation failed: the two endpoints use different passwords (or the handshake was tampered with). Both ends exit with status 1.
"does not speak ClawSec protocol v3" / "uses ClawSec protocol vN"
ClawSec 3.x speaks wire protocol 3 and does not interoperate with 2.x.
Upgrade both endpoints to the same major release; clawsec --version
prints the release and protocol version.
"Decryption/authentication failed"
A data frame failed authentication after the handshake: corrupted or tampered traffic.
"-e (execute program) is not built into this binary"
Since 3.0, -e is opt-in: make linux DFLAGS=-DGAPING_SECURITY_HOLE.
"Connection closed by peer"
Network error, or the peer closed the session.
OpenSSL / argon2 library errors
# 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)
Contributing
Contributions are welcome. Please:
- Review SECURITY.md before submitting security-related changes
- Test thoroughly
- Document all changes
- Follow existing code style
License
Based on Netcat and Cryptcat. See LICENSE for details.
Legal Notice
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
Credits
- Original Netcat: Hobbit
- Original Cryptcat: Farm9 team
- ClawSec Modernization: 2025 security enhancements
- OpenSSL Project: Cryptographic library
Documentation
- 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
Project Structure
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