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.com/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"

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)

API Reference

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

Submit Threat Data

POST https://sain-firewall.com/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.com/api/threats/global-stats

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

Emergency Stop

sudo stop-sain-firewall