Skip to content

README.md

Latest commit

 

History

History
185 lines (150 loc) · 7.39 KB

README.md

File metadata and controls

185 lines (150 loc) · 7.39 KB

SoftRouter - Web-Based Software Router 🛡️🚀

A modern, high-performance web-based router management interface built with React (frontend) and Go (backend). Designed to turn any Debian or Ubuntu server into a powerful, security-hardened network appliance.

🌟 Key Features

🛡️ Integrated Security Stack

  • IDS/IPS (Suricata): Real-time network intrusion detection and prevention.
  • Threat Intelligence (CrowdSec): Community-driven IP reputation and automated blocking.
  • Firewall (NFTables): Full GUI for managing kernel-level network filtering with human-readable parsing.
  • Access Control: Zero Trust architecture with strict localhost binding and WAN/LAN zone management.
  • Ad-Blocking: Native support and management for AdGuard Home and Pi-hole.

🌐 Network & Interfaces

  • VLAN Management: Create and manage 802.1Q VLANs on physical interfaces.
  • L3 Configuration: Dynamic IP/CIDR assignment and interface state (Up/Down) control.
  • Smart Labeling: Organize ports as WAN, LAN, DMZ, or Trunk with custom descriptions.
  • Live Monitoring: Real-time traffic stats, interface status, and connection tracking.

⚙️ System Management

  • Service Governance: Unified dashboard to Start/Stop/Restart critical services (dnsmasq, WireGuard, OpenVPN, etc.).
  • Credential Security: SHA-256 password hashing and secure token-based session management.
  • Appliance Deployment: Single-script installation that converts a fresh OS into a router in minutes.

🔒 Phase 2 Security Features (NEW)

  • Audit Logging: Comprehensive audit trail for all security-sensitive operations
    • JSON line format with automatic daily rotation
    • Filter by date, action, user via web UI
    • Tracks: firewall changes, credential updates, settings, backups, sessions
  • Backup & Restore: Full system configuration snapshots
    • One-click backup creation and download
    • Upload and restore with automatic pre-restore backup
    • Includes: configs, credentials, metadata, DHCP, port forwarding
  • API Rate Limiting: Brute force attack prevention
    • Token bucket algorithm with per-IP tracking
    • Login: 10 req/min (configurable for other endpoints)
    • Standard rate limit headers (X-RateLimit-*)
  • Session Management: Track and control active sessions
    • View all active sessions (IP, device, timestamps)
    • Manual session revocation capability
    • 24-hour timeout with auto-renewal
  • Error Sanitization: Prevent information leakage
    • Error code system for debugging
    • Separate user-facing vs internal error messages
    • Structured logging with error codes

🔒 Access Control & Security (Latest)

  • Secure Binding: WebUI binds strictly to localhost (127.0.0.1), preventing accidental exposure.
  • Zone-Based Firewall:
    • LAN: Trusted access via secure DNAT proxies.
    • WAN: Blocked by default. Optionally enable access via custom, obscure ports (e.g., 980/9443).
  • Port Forwarding: Robust implementation with Hairpin NAT support, integrated directly into the NFTables pipeline.

🚀 Installation & Deployment

Master Installation (Recommended)

SoftRouter is optimized for headless servers. Run the comprehensive installer to set up the entire stack:

git clone -b Dev https://github.com/timmyd2434/SoftwareRouter.git
cd SoftwareRouter
sudo ./install.sh

What the installer handles:

  1. Core Toolchain: Installs Go, Node.js, NFTables, and network utilities.
  2. Security Setup: configures your admin account and API secrets.
  3. IDS/IPS Integration: Optional one-click setup for Suricata & CrowdSec.
  4. DNS Optimization: Automatically resolves Port 53 conflicts (disables systemd-resolved stub).
  5. AdGuard Home: Optional DNS ad-blocking with web UI (Port 3000).
  6. UniFi Controller: Optional network management for UniFi devices (requires AVX CPU).
  7. Production Build: Compiles the Go binary and builds the optimized React frontend.
  8. Persistence: Installs a softrouter.service for automated startup on boot.

Tested on:

  • Debian 12 (Bookworm) stable
  • Debian 13 (Trixie) testing
  • Ubuntu 22.04 LTS and 24.04 LTS

Accessing the Interface

  • URL: http://<YOUR_ROUTER_IP>
  • Admin Port: 80
  • Default Credentials: Set during installation (Step 2/10).

Post-Installation Configuration

After installation, access the Settings page to configure:

  • AdGuard Home Integration: Enter URL and credentials to enable real-time DNS analytics
  • Cloudflare Tunnel: Configure Zero Trust access
  • Administrative Credentials: Update username and password
  • Backup & Restore: Create system backups or restore from previous snapshots
  • Session Management: View and manage active sessions
  • Access Control: Configure WAN access rules and interface zones (LAN/WAN)

Access the Audit Logs page to:

  • View complete audit trail of all security operations
  • Filter logs by date range, action type, or user
  • Monitor system changes and administrative actions

💡 Professional Tips & Config

AdGuard Home DNS Analytics

The DNS Analytics page integrates with AdGuard Home to display:

  • Real-time DNS queries and blocked domains
  • Top queried and blocked domains
  • Ad-blocking statistics

Setup via Settings UI:

  1. Navigate to Settings → AdGuard Home Integration
  2. Enter AdGuard URL (e.g., http://localhost:3000)
  3. Enter username and password
  4. Click Save

No service restart required - changes take effect immediately!

Reclaiming Port 53

If you install AdGuard Home or Pi-hole, you must free up port 53 which Ubuntu occupies by default. The install.sh script handles this automatically (when you answer "y" to freeing port 53), but you can do it manually:

# Disable Ubuntu's internal listener
echo -e "[Resolve]\nDNSStubListener=no" | sudo tee /etc/systemd/resolved.conf.d/softrouter.conf
sudo ln -sf /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

Managing Security

Verify your security stance via CLI:

# View CrowdSec active bans
sudo cscli decisions list

# Check Suricata logs
tail -f /var/log/suricata/eve.json | jq

Using Phase 2 Features

Access security features via the web UI or API:

Audit Logs:

# View audit logs via API
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost/api/audit/logs?limit=50"

# Filter by action
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost/api/audit/logs?action=firewall.add"

Backup & Restore:

# Create backup
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/api/backup/create > backup.json

# List backups
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/api/backup/list

Session Management:

# List active sessions
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost/api/sessions

📂 Project Structure

  • backend/: Go API server (Port 80). Handles kernel interactions (IP, NFT, systemd).
  • frontend/: React + Vite SPA. Modern, glassmorphism-based UI.
  • install.sh: All-in-one installation script for full appliance deployment.
  • /etc/softrouter/: Secure persistent storage for credentials and configuration.

🛠️ Development

To run in development mode with live-reloading:

  1. Backend: cd backend && sudo go run main.go
  2. Frontend: cd frontend && npm install && npm run dev -- --host

Built with ❤️ for secure, open-source networking.