Documentation

Quick Start

Get SAIN FIREWALL up and running in under 5 minutes with these simple steps.

Prerequisites

• Linux server (Ubuntu 20.04+ or Debian 11+)
• Root or sudo access
• Node.js 18+ (auto-installed if missing)
• 1GB RAM minimum, 2GB recommended

One-Line Installation

curl -sSL https://sain-firewall-site.saincraft.co.tz/install.sh | sudo bash

Start Monitoring

sudo sain-firewall monitor

Launch Dashboard

sudo sain-firewall dashboard

Installation

System Requirements

Automatic Installation (Recommended)

curl -sSL https://sain-firewall-site.saincraft.co.tz/install.sh | sudo bash

Manual Installation

git clone https://github.com/saincraft/sain-firewall.git
cd sain-firewall
sudo ./install.sh

Docker Installation

docker run -d --name sain-firewall \
  --cap-add NET_ADMIN \
  --cap-add NET_RAW \
  -v /var/log/sain-firewall:/var/log/sain-firewall \
  saincraft/sain-firewall:latest

Configuration

The configuration file is located at /etc/sain-firewall/config.yaml. Edit it with:

sudo sain-firewall config

Basic Configuration

# Network interface to monitor
interface: "eth0"

# Operating mode (monitor_only for safe mode)
mode: "monitor_only"

# Resource limits
resource_limits:
  max_cpu_percent: 30
  max_memory_mb: 384

# Email notifications
email:
  enabled: true
  smtp:
    host: "smtp.gmail.com"
    port: 587
    auth:
      user: "your-email@gmail.com"
      pass: "your-app-password"
  recipients:
    admin: "admin@example.com"
    author: "gsainyeye@saincraft.co.tz"

VPN Tunnel (WireGuard)

SAIN FIREWALL provides a paid-gated WireGuard VPN feature for secure remote admin access with a single peer profile. This allows authorized administrators to securely access the server remotely.

Prerequisites

• Valid SAIN FIREWALL paid license
• Root or sudo access
• WireGuard installed on the server (auto-installed if missing)
• Port 51820/udp open in your firewall (if using external access)

Configuration

Add the following blocks to your /etc/sain-firewall/config.yaml:

# Licensing configuration for paid features
licensing:
  enabled: true
  api_url: "https://api.sain-firewall-site.saincraft.co.tz/v1/entitlement"
  cache_file: "/var/lib/sain-firewall/license.cache"
  grace_period_hours: 72
  retry_interval_minutes: 60

# VPN configuration
vpn:
  enabled: true
  interface: "wg0"
  port: 51820
  server_address: "10.0.0.1/24"
  peer_address: "10.0.0.2/32"
  dns: "8.8.8.8"
  persistent_keepalive: 25
  config_dir: "/etc/wireguard"
  peer_name: "admin-laptop"

VPN Commands

Available commands for managing the VPN tunnel:

Quick Setup for Paid Customers

1. Configure Licensing and VPN

Edit /etc/sain-firewall/config.yaml with your license key and VPN settings as shown above.

2. Provision Configurations

sudo sain-firewall vpn init

This generates server and peer WireGuard configurations, including keys.

3. Start the VPN Tunnel

sudo sain-firewall vpn up

4. Check Status

sudo sain-firewall vpn status

5. Export Peer Configuration

The peer configuration file is located at /etc/wireguard/clients/<peer_name>.conf. Transfer this file to your admin client machine and import it into your WireGuard client.

sudo cat /etc/wireguard/clients/admin-laptop.conf

Licensing and Entitlement

The VPN feature uses an online entitlement check system:

• Online Check: POST request to your licensing API endpoint
• Offline Grace Period: Cached entitlement file allows continued operation (default 72 hours)
• Graceful Degradation: If entitlement check fails with no valid cached license, VPN commands exit with code 2 and indicate it's a paid feature

Security Notes

• WireGuard uses modern cryptography (ChaCha20, Poly1305, Curve25519)
• Each peer gets a unique private/public key pair
• Keep peer configuration files secure - they contain private keys
• Use firewall rules to restrict VPN access to authorized IP ranges
• Regularly rotate VPN keys for high-security environments

User Integrity & Lockout Rescue

SAIN FIREWALL can watch local UNIX accounts and SSH authorized_keys against a saved baseline. If someone adds users, changes passwords (detected via /etc/shadow hash changes), alters uid/gid/shell, or changes monitored SSH keys, the daemon can email you and attach a reviewed-then-run bash script plus new random passwords for baseline accounts that still exist on the system.

Requirements

• The firewall process must run as root (it reads /etc/shadow)
• Email must be configured and working (email section in config.yaml, SMTP env vars if you use them)
• A baseline file must be created while the system is in a known-good state

Quick Setup

1. Create or Refresh Baseline

sudo node /opt/sain-firewall/index.js --init-user-baseline

This writes a root-only JSON file (default: /var/lib/sain-firewall/user-baseline.json, mode 0600) containing user records from /etc/passwd, password hashes from /etc/shadow, and optional fingerprints of authorized_keys for users listed under ssh_watch_users.

2. Enable Monitoring in config.yaml

user_integrity:
  enabled: true
  interval_seconds: 300
  state_dir: "/var/lib/sain-firewall"
  baseline_filename: "user-baseline.json"
  auto_create_baseline: false
  alert_cooldown_seconds: 3600
  ssh_authorized_keys: true
  ssh_watch_users:
    - root

3. Restart Service

sudo systemctl restart sain-firewall

What is Detected

What You Receive by Email

• A short summary of the drift
• New random passwords for each baseline user that still exists on the machine (for use with the recovery script's chpasswd lines). If no baseline users remain, the email explains that no passwords were generated
• A bash script (in the message body) that typically:
  • Removes accounts not in the baseline (userdel -r — destructive for those usernames)
  • Runs usermod to restore uid, gid, and shell from the baseline where they diverged
  • Runs chpasswd to set the new passwords for surviving baseline users

Configuration Reference (user_integrity)

Security Notes

• The baseline file contains password hashes and is highly sensitive; keep ownership root and mode 0600
• Recovery emails contain plaintext passwords; protect SMTP (TLS), the mailbox, and delete the message after use
• An attacker with root could disable the daemon, delete the baseline, or alter the binary — plan for out-of-band recovery
• userdel -r deletes home directories of flagged usernames; confirm they are truly rogue before running the script

Commands Reference

Monitor Mode (Safe Mode)

Monitor mode is the safest way to run SAIN FIREWALL on production servers. It:

• ✅ Captures and analyzes network packets
• ✅ Detects attacks and anomalies
• ✅ Logs everything to files
• ✅ Sends email alerts
• ❌ Does NOT add any iptables rules
• ❌ Does NOT block any traffic

Start Monitor Mode

sudo sain-firewall monitor

Verify Monitor Mode

grep "mode:" /etc/sain-firewall/config.yaml
# Should output: mode: "monitor_only"

sudo iptables -L -n | grep sain
# Should output: (nothing - no rules)

Dashboard

The terminal dashboard provides real-time visualization of attacks and system status.

Launch Dashboard

sudo sain-firewall dashboard

Dashboard Controls

• q - Quit dashboard
• r - Reset counters
• h - Show help

Real-time Metrics Display

• 🔴 Critical attacks (severity >70%)
• 🟡 Medium attacks (severity 30-70%)
• 🟢 Low severity alerts (severity <30%)
• 📊 Real-time severity graphs
• 📝 Live attack logs

Email Alerts

Configure email notifications to stay informed about threats.

Gmail Setup

1. Enable 2-Step Verification in your Google Account
2. Generate an App Password (Security → App Passwords)
3. Copy the 16-character password
4. Update config with your email and app password

email:
  enabled: true
  smtp:
    host: "smtp.gmail.com"
    port: 587
    auth:
      user: "your-email@gmail.com"
      pass: "your-16-char-app-password"
  recipients:
    admin: "admin@example.com"
    author: "gsainyeye@saincraft.co.tz"

Alert Types

• Immediate Alerts - High severity attacks (real-time)
• Batch Alerts - Multiple low severity attacks (every 5 min)
• Daily Reports - Summary of all activities (8 AM)
• Weekly Reports - Weekly statistics (Monday 9 AM)
• User Integrity Alerts - Account drift detection
• License Expiry Alerts - VPN license expiration warnings

API Reference

SAIN FIREWALL provides a REST API for integration with other systems.

Submit Threat Data

POST https://sain-firewall-site.saincraft.co.tz/api/benchmark/submit
Content-Type: application/json

{
  "instanceId": "your-instance-id",
  "hostname": "server01",
  "threats": [{
    "type": "SYN_FLOOD",
    "severity": 0.95,
    "timestamp": "2024-01-15T10:30:00Z"
  }]
}

Get Global Threat Statistics

GET https://sain-firewall-site.saincraft.co.tz/api/threats/global-stats

License Entitlement Check

POST https://sain-firewall-site.saincraft.co.tz/api/license/entitlemen 
Content-Type: application/json

{
  "license_key": "your-license-key",
  "feature": "vpn",
  "version": "1.0.0"
}

Troubleshooting

Service Won't Start

sudo journalctl -u sain-firewall-monitor -n 50

No Packets Captured

# List interfaces
ip link show

# Test packet capture
sudo tcpdump -i eth0 -c 10

High CPU Usage

# Edit config
sudo sain-firewall config

# Reduce these values:
resource_limits:
  max_cpu_percent: 20
  max_memory_mb: 256

# Restart
sudo sain-firewall restart

VPN Issues

License Entitlement Failed

# Check license cache
sudo cat /var/lib/sain-firewall/license.cache

# Check license validation logs
sudo journalctl -u sain-firewall | grep -i license

VPN Won't Start

# Check WireGuard service status
sudo systemctl status wg-quick@wg0

# Check WireGuard logs
sudo journalctl -u wg-quick@wg0 -n 50

WireGuard Not Installed

sudo apt install wireguard wireguard-tools -y

User Integrity Baseline Issues

# Check baseline file exists and permissions
sudo ls -la /var/lib/sain-firewall/user-baseline.json

# Validate baseline contents
sudo cat /var/lib/sain-firewall/user-baseline.json | jq .

Emergency Stop

sudo stop-sain-firewall