knock-gui/rust-knocker

Rust Knocker 🦀

Port knocking utility written in Rust, compatible with Go knocker. Can be used standalone or as a helper for Electron applications.

Features

• TCP/UDP Support: Knock on both TCP and UDP ports
• Gateway Routing: Route packets through specific interfaces or IPs (bypass VPNs)
• SO_BINDTODEVICE: ✅ Linux-specific interface binding for reliable VPN bypass
• YAML Configuration: Human-readable configuration files
• Encrypted Configs: AES-GCM encryption for sensitive configurations
• Electron Compatible: JSON API for integration with Electron apps
• Cross-platform: Works on Linux, macOS, Windows (with limitations)

Installation

From Source

git clone <repository>
cd rust-knocker
cargo build --release

Binaries

• rust-knocker - Standalone CLI tool
• knock-local - Electron helper (JSON API)

Usage

CLI Mode

# Single target
rust-knocker --target tcp:192.168.1.1:22 --verbose

# With gateway
rust-knocker --target tcp:192.168.1.1:22 --gateway eth0 --delay 2s

# From config file
rust-knocker --config config.yaml --verbose

# With encrypted config
rust-knocker --config encrypted.yaml --key secret.key --verbose

Configuration File

targets:
  - host: 192.168.1.1
    ports: [22, 80, 443]
    protocol: tcp
    delay: 1s
    wait_connection: false
    gateway: eth0  # optional

Electron Integration

The knock-local binary provides the same JSON API as the Go helper:

# Input JSON to stdin
echo '{"targets":["tcp:192.168.1.1:22"],"delay":"1s","verbose":false,"gateway":"eth0"}' | ./knock-local

# Output JSON to stdout
{"success":true,"message":"ok"}

Gateway Support

Interface Binding

# Route through specific interface
rust-knocker --target tcp:192.168.1.1:22 --gateway enp1s0

IP Binding

# Route from specific local IP
rust-knocker --target tcp:192.168.1.1:22 --gateway 192.168.1.100

VPN Bypass

The gateway feature is particularly useful for bypassing VPNs:

# Bypass WireGuard by routing through physical interface
rust-knocker --target tcp:192.168.89.1:2655 --gateway enp1s0

Examples

Basic Port Knocking

# Knock SSH port
rust-knocker --target tcp:192.168.1.1:22 --verbose

# Knock multiple ports
rust-knocker --config examples/config.yaml --verbose

Network Diagnostics

# Test connectivity through specific interface
rust-knocker --target tcp:8.8.8.8:53 --gateway wlan0 --verbose

# UDP DNS query through gateway
rust-knocker --target udp:8.8.8.8:53 --gateway 192.168.1.100 --verbose

Encrypted Configuration

# Create encrypted config
rust-knocker --config config.yaml --key secret.key --encrypt

# Use encrypted config
rust-knocker --config encrypted.yaml --key secret.key --verbose

API Reference

KnockRequest (JSON)

{
  "targets": ["tcp:192.168.1.1:22", "udp:10.0.0.1:53"],
  "delay": "1s",
  "verbose": false,
  "gateway": "eth0"
}

KnockResponse (JSON)

{
  "success": true,
  "message": "ok"
}

or

{
  "success": false,
  "error": "Connection failed"
}

Error Handling

Critical Errors (Exit Code 1)

• Interface binding errors: If the specified network interface doesn't exist:

  {
    "success": false,
    "error": "Port knocking failed: Ошибка при knock'е цели 1"
  }
  

• Invalid configuration: Malformed targets, unsupported protocols, etc.

Warning Mode (Exit Code 0)

• Connection timeouts: When wait_connection: false, connection failures are treated as warnings
• Network unreachability: Temporary network issues are logged but don't fail the operation

Building

Development

cargo build

Release

cargo build --release

Cross-compilation

# Linux x64
cargo build --release --target x86_64-unknown-linux-gnu

# Windows
cargo build --release --target x86_64-pc-windows-gnu

Testing

# Run tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Test specific functionality
cargo test test_parse_duration

Performance

Rust Knocker is significantly faster than the Go version:

• Startup time: ~10ms vs ~50ms (Go)
• Memory usage: ~2MB vs ~8MB (Go)
• Binary size: ~3MB vs ~12MB (Go)

Compatibility

Go Knocker Compatibility

Rust Knocker is fully compatible with Go knocker:

• Same configuration format
• Same JSON API
• Same command-line interface
• Drop-in replacement

Platform Support

Platform	TCP	UDP	Gateway	SO_BINDTODEVICE
Linux	✅	✅	✅	✅
macOS	✅	✅	✅	❌
Windows	✅	✅	✅	❌

Troubleshooting

Common Issues

1. Permission denied: Run with sudo for interface binding
2. Interface not found: Check interface name with ip link show
3. Gateway not working: Verify interface has the specified IP

Debug Mode

# Enable verbose output
rust-knocker --target tcp:192.168.1.1:22 --verbose

# Check interface binding
rust-knocker --target tcp:192.168.1.1:22 --gateway eth0 --verbose

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by Go knocker
• Compatible with Electron port knocking applications
• Uses Rust's excellent networking libraries