TNT/docs/SECURITY_QUICKREF.md

Security Quick Reference

Quick Start

Default (Open Access)

./tnt
# No password required
# Anyone can connect

Protected Mode

TNT_ACCESS_TOKEN="YourSecretPassword" ./tnt

Connect: sshpass -p "YourSecretPassword" ssh -p 2222 localhost

---

Environment Variables

Variable	Default	Description	Example
TNT_ACCESS_TOKEN	(none)	Require password	TNT_ACCESS_TOKEN="secret"
TNT_BIND_ADDR	0.0.0.0	Bind address	TNT_BIND_ADDR="127.0.0.1"
TNT_SSH_LOG_LEVEL	1	SSH logging (0-4)	TNT_SSH_LOG_LEVEL=3
TNT_RATE_LIMIT	1	Rate limiting on/off	TNT_RATE_LIMIT=0
TNT_MAX_CONNECTIONS	64	Total connection limit	TNT_MAX_CONNECTIONS=100
TNT_MAX_CONN_PER_IP	5	Per-IP limit	TNT_MAX_CONN_PER_IP=3

---

Security Levels

Level 1: Default (Open)

./tnt

• No authentication
• Rate limiting enabled
• 64 max connections
• 5 per IP

Level 2: Local Only

TNT_BIND_ADDR=127.0.0.1 ./tnt

• Localhost access only
• Good for development
• No external access

Level 3: Password Protected

TNT_ACCESS_TOKEN="MyPassword123" ./tnt

• Requires password
• Rate limiting blocks brute force (5 failures → 5 min block)
• 3 auth attempts per session

Level 4: Maximum Security

TNT_ACCESS_TOKEN="StrongPass123" \
TNT_BIND_ADDR=127.0.0.1 \
TNT_MAX_CONNECTIONS=10 \
TNT_MAX_CONN_PER_IP=2 \
./tnt

• Password required
• Localhost only
• Strict limits
• Rate limiting enabled

---

Rate Limiting

Defaults

• Connection Rate: 10 connections per IP per 60 seconds
• Auth Failures: 5 failures → 5 minute IP block
• Window: 60 second rolling window

Block Behavior

After 5 failed auth attempts:

IP 192.168.1.100 blocked due to 5 auth failures
Blocked IP 192.168.1.100 (blocked until 1234567890)

Auto-unblock after 5 minutes.

Disable (Testing Only)

TNT_RATE_LIMIT=0 ./tnt

⚠️ Warning: No protection against brute force!

---

Connection Limits

Global Limit

TNT_MAX_CONNECTIONS=50 ./tnt

Rejects new connections when 50 total clients connected.

Per-IP Limit

TNT_MAX_CONN_PER_IP=3 ./tnt

Each IP can have max 3 concurrent connections.

Combined Example

TNT_MAX_CONNECTIONS=100 TNT_MAX_CONN_PER_IP=10 ./tnt

• Total: 100 connections
• Each IP: max 10 connections

---

Key Management

Key Generation

First run automatically generates 4096-bit RSA key:

Generating new RSA 4096-bit host key...

Key File

• Location: ./host_key
• Permissions: 0600 (owner read/write only)
• Size: 4096 bits RSA

Regenerate Key

rm host_key
./tnt  # Generates new key

Verify Key

ssh-keygen -l -f host_key
# Output: 4096 SHA256:... (RSA)

---

Testing

Run Security Tests

./test_security_features.sh

Expected output: ✓ All security features verified!

Manual Tests

Test 1: Check Key Size

./tnt &
sleep 8
ssh-keygen -l -f host_key
# Should show: 4096
kill %1

Test 2: Test Access Token

TNT_ACCESS_TOKEN="test123" ./tnt &
sleep 5
sshpass -p "test123" ssh -p 2222 localhost  # Success
sshpass -p "wrong" ssh -p 2222 localhost     # Fails
kill %1

Test 3: Test Rate Limiting

./tnt &
sleep 5
for i in {1..15}; do ssh -p 2222 localhost & done
# After 10 connections, should see rate limit blocks
kill %1

---

Troubleshooting

Server Won't Start

# Check if port is in use
lsof -i :2222

# Kill existing instance
pkill -f tnt

# Check logs
./tnt 2>&1 | tee debug.log

Can't Connect

# Check server is listening
lsof -i :2222 | grep tnt

# Check bind address
# If TNT_BIND_ADDR=127.0.0.1, only localhost works
# Use 0.0.0.0 for all interfaces

# Test connection
ssh -v -p 2222 localhost

Authentication Fails

# Check if token is set
env | grep TNT_ACCESS_TOKEN

# If token is set, password is required
# Use: sshpass -p "YourToken" ssh -p 2222 localhost

# If no token, any password works (or none)

Rate Limited / Blocked

# Wait 5 minutes for auto-unblock
# Or restart server to clear blocks
pkill -f tnt
./tnt

---

Migration Guide

Upgrading from Previous Version

Before:

./tnt  # Open access

After (Same Behavior):

./tnt  # Still open access, backward compatible!

New: Add Protection

TNT_ACCESS_TOKEN="secret" ./tnt  # Now protected

No Breaking Changes

• Default behavior unchanged
• All new features opt-in via environment variables
• Existing scripts/deployments work as-is

---

Production Deployment

Recommended Configuration

#!/bin/bash
# /usr/local/bin/tnt-secure.sh

export TNT_ACCESS_TOKEN="$(cat /etc/tnt/access_token)"
export TNT_BIND_ADDR="0.0.0.0"
export TNT_MAX_CONNECTIONS=200
export TNT_MAX_CONN_PER_IP=10
export TNT_SSH_LOG_LEVEL=1

cd /opt/tnt
exec ./tnt

systemd Service

[Unit]
Description=TNT Chat Server
After=network.target

[Service]
Type=simple
User=tnt
WorkingDirectory=/opt/tnt
EnvironmentFile=/etc/tnt/config
ExecStart=/opt/tnt/tnt
Restart=on-failure

[Install]
WantedBy=multi-user.target

Config File (/etc/tnt/config)

TNT_ACCESS_TOKEN=YourProductionPassword
TNT_BIND_ADDR=0.0.0.0
TNT_MAX_CONNECTIONS=500
TNT_MAX_CONN_PER_IP=20
TNT_RATE_LIMIT=1
TNT_SSH_LOG_LEVEL=1

---

Security Best Practices

✅ DO:

• Use TNT_ACCESS_TOKEN in production
• Set TNT_BIND_ADDR=127.0.0.1 if local-only
• Keep rate limiting enabled (TNT_RATE_LIMIT=1)
• Monitor messages.log for suspicious activity
• Rotate access tokens periodically
• Use strong passwords (12+ chars, mixed case, numbers, symbols)

❌ DON'T:

• Disable rate limiting in production (TNT_RATE_LIMIT=0)
• Use weak passwords (e.g., "password", "123456")
• Expose to internet without access token
• Run as root (use dedicated user)
• Share access tokens in plain text

---

Performance Impact

Feature	Impact	Notes
4096-bit RSA	First startup: +3s	Cached after generation
Rate Limiting	Minimal	Hash table lookup
Access Token	Minimal	Simple string compare
UTF-8 Validation	Minimal	Per-character check
Message Snapshot	Low	Only during render

Expected overhead: <5% in normal usage

---

Support

• Documentation: README.md, CHANGELOG.md
• Test Results: TEST_RESULTS.md
• Test Suite: ./test_security_features.sh
• Issues: https://github.com/m1ngsama/TNT/issues