Skip to content

cynthiaschomp/NetGuardAI

BranchesTags

Repository files navigation

NetGuard AI

AI-Powered Network Monitoring System - A free, open-source security monitoring solution for Ubuntu with Docker.

Features

  • Real-time Traffic Analysis - Zeek captures and analyzes all network traffic
  • Intrusion Detection - Suricata IDS with automatic rule updates
  • AI-Powered Anomaly Detection - Machine learning models detect unusual behavior
  • Beacon Detection - Identifies C2 communication patterns
  • DNS Tunneling Detection - Detects data exfiltration via DNS
  • Port Scan Detection - Identifies reconnaissance activities
  • Threat Intelligence - Automatic updates from free threat feeds
  • Beautiful Dashboards - Grafana and OpenSearch visualizations
  • Alerting - Configurable alerts via Alertmanager
  • GUI Setup Wizard - Easy web-based installation and configuration

Note: This is a passive monitoring system. It detects and alerts but does not block traffic.

Requirements

  • Ubuntu 20.04+ (22.04 recommended)
  • 8GB RAM minimum (16GB recommended)
  • 4 CPU cores minimum
  • 100GB disk space
  • Network interface for monitoring

Quick Start

Option 1: GUI Setup Wizard (Recommended)

# Extract the package
tar -xzvf netguard-ai.tar.gz
cd netguard-ai

# Launch the setup wizard
./setup-wizard.sh

# Open http://localhost:5000 in your browser

The wizard will guide you through:

  1. Welcome - System check and feature overview
  2. Network Setup - Select monitoring interface and internal networks
  3. Alert Configuration - Set up Slack, Email, Discord, or PagerDuty notifications
  4. Storage Settings - Configure memory allocation and log retention
  5. Security - Set Grafana admin password
  6. Review - Confirm all settings
  7. Installation - Automated Docker build and deployment
  8. Complete - Access your dashboards

Option 2: Command Line Installation

# Extract the package
tar -xzvf netguard-ai.tar.gz
cd netguard-ai

# Run the installer
sudo ./install.sh

# Or specify your network interface
sudo ./install.sh --interface eth0

Installation Options

sudo ./install.sh [OPTIONS]

Options:
  --interface IFACE   Network interface to monitor (default: auto-detect)
  --skip-docker       Skip Docker installation (if already installed)
  --minimal           Minimal installation (fewer resources)
  --help              Show help message

Access Points

After installation, access the following services:

Service URL Credentials
OpenSearch Dashboards http://localhost:5601 None
Grafana http://localhost:3000 admin / netguard
AI Detection API http://localhost:8080 None
AI Firewall http://localhost:8888 None
Alertmanager http://localhost:9093 None

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         Network Traffic                              │
└─────────────────────────────────────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    ▼                             ▼
            ┌──────────────┐              ┌──────────────┐
            │     Zeek     │              │   Suricata   │
            │   (Traffic   │              │    (IDS)     │
            │   Analysis)  │              │              │
            └──────┬───────┘              └──────┬───────┘
                   │                             │
                   └──────────────┬──────────────┘
                                  ▼
                          ┌──────────────┐
                          │   Filebeat   │
                          │ (Log Shipper)│
                          └──────┬───────┘
                                 │
                                 ▼
                          ┌──────────────┐
                          │  OpenSearch  │
                          │  (Storage)   │
                          └──────┬───────┘
                                 │
       ┌─────────────────────────┼─────────────────────────┐
       │                         │                         │
       ▼                         ▼                         ▼
┌──────────────┐          ┌──────────────┐          ┌──────────────┐
│   Grafana    │          │   AI Engine  │          │    RITA      │
│ (Dashboards) │          │  (ML Detect) │          │(Threat Hunt) │
└──────────────┘          └──────┬───────┘          └──────────────┘
                                 │
                                 ▼
                          ┌──────────────┐
                          │ Alertmanager │
                          │  (Alerts)    │
                          └──────────────┘

Components

Zeek (Network Analysis)

  • Generates rich metadata from network traffic
  • Logs connections, DNS, HTTP, SSL, files, and more
  • JSON output for easy processing

Suricata (IDS/IPS)

  • Signature-based intrusion detection
  • Automatic rule updates from Emerging Threats
  • EVE JSON logging

AI Detection Engine

  • Baseline Anomaly Detection - Isolation Forest algorithm
  • Beacon Detection - Identifies regular callback patterns (C2)
  • DNS Tunneling - High-entropy subdomain detection
  • Port Scanning - Multiple ports in short timeframe
  • Online Learning - Adapts to your network over time

AI Firewall

The AI Firewall is a companion service that actively blocks threats based on AI detections:

Operating Modes:

Mode Description
monitor Logs actions but doesn't block (safe for testing)
enforce Actively blocks threats using nftables/iptables
learning Builds baseline without taking action

Features:

  • Auto-blocking - Automatically blocks IPs based on AI threat scores
  • Rate Limiting - Throttles suspicious sources
  • Whitelist - Protect critical IPs from being blocked
  • Threat Scoring - Cumulative scoring based on multiple detections
  • Web Dashboard - Visual management at http://localhost:8888
  • REST API - Full programmatic control

Firewall API Endpoints:

# Get firewall status
curl http://localhost:8888/status

# Get blocked IPs
curl http://localhost:8888/blocked

# Block an IP manually
curl -X POST http://localhost:8888/block \
  -H "Content-Type: application/json" \
  -d '{"ip": "1.2.3.4", "reason": "Manual block", "duration_minutes": 60}'

# Unblock an IP
curl -X DELETE http://localhost:8888/block/1.2.3.4

# Whitelist an IP
curl -X POST http://localhost:8888/whitelist/10.0.0.1

# Get threat scores
curl http://localhost:8888/threats

# Change firewall mode
curl -X POST http://localhost:8888/mode/enforce

⚠️ Important: To enable active blocking, set FIREWALL_MODE=enforce in your .env file and ensure the firewall container has network_mode: host.

RITA (Threat Hunting)

  • Long connection detection
  • Beacon analysis
  • DNS analysis
  • Blacklist checking

Threat Intelligence

Auto-updates from free feeds:

  • abuse.ch (Feodo, URLhaus, SSL Blacklist)
  • Emerging Threats
  • blocklist.de
  • Phishing Army
  • OpenPhish

API Endpoints

The AI Detection Engine exposes a REST API:

# Health check
curl http://localhost:8080/health

# Get statistics
curl http://localhost:8080/stats

# Get recent alerts
curl http://localhost:8080/alerts

# Get alerts by severity
curl http://localhost:8080/alerts?severity=high

# Trigger manual detection
curl -X POST http://localhost:8080/detect

Management Commands

# View all logs
cd /opt/netguard-ai && docker compose logs -f

# View specific service logs
docker compose logs -f ai-detector
docker compose logs -f zeek
docker compose logs -f suricata

# Check service status
docker compose ps

# Restart a service
docker compose restart ai-detector

# Stop everything
sudo systemctl stop netguard-ai

# Start everything
sudo systemctl start netguard-ai

# Update threat intelligence manually
docker compose exec threat-intel python threat_intel_updater.py

Configuration

Environment Variables

Edit /opt/netguard-ai/.env:

# Network interface to monitor
MONITOR_INTERFACE=eth0

# Detection cycle interval (seconds)
DETECTION_INTERVAL=300

# Anomaly threshold (contamination rate)
ANOMALY_THRESHOLD=0.01

# Threat intel update interval (seconds)
THREAT_INTEL_INTERVAL=86400

# AI Firewall Settings
FIREWALL_MODE=monitor           # monitor, enforce, or learning
AUTO_BLOCK_THRESHOLD=3          # Threat score to trigger auto-block
BLOCK_DURATION_MINUTES=60       # Default block duration
RATE_LIMIT_THRESHOLD=100        # Connections before rate limiting
SYNC_INTERVAL=30                # Seconds between AI sync

Customize AI Detection

Edit /opt/netguard-ai/scripts/ai_detector.py to adjust:

  • Detection thresholds
  • Feature extraction
  • Alert severity levels
  • Custom detection rules

Add Custom Suricata Rules

Add rules to /opt/netguard-ai/rules/local.rules:

alert tcp any any -> any any (msg:"Custom Rule"; content:"pattern"; sid:1000001; rev:1;)

Alerting

Configure Slack Notifications

Edit /opt/netguard-ai/configs/alertmanager.yml:

receivers:
  - name: 'slack-notifications'
    slack_configs:
      - api_url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
        channel: '#security-alerts'

Configure Email Notifications

receivers:
  - name: 'email-alerts'
    email_configs:
      - to: 'security@example.com'
        from: 'netguard@example.com'
        smarthost: 'smtp.example.com:587'
        auth_username: 'user'
        auth_password: 'password'

Troubleshooting

Services not starting

# Check Docker status
sudo systemctl status docker

# Check container logs
docker compose logs

# Verify system requirements
free -h
df -h

No traffic being captured

# Verify interface
ip link show

# Check Zeek status
docker compose logs zeek

# Verify promiscuous mode
ip link show eth0 | grep PROMISC

High memory usage

# Reduce OpenSearch heap
# Edit docker-compose.yml: OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m

# Restart services
docker compose down && docker compose up -d

Performance Tuning

For high-traffic networks:

  1. Increase Resources

    # docker-compose.yml
opensearch:
  environment:
    - "OPENSEARCH_JAVA_OPTS=-Xms4g -Xmx4g"

  2. Add Zeek Workers

    # configs/zeek/node.cfg
[worker-1]
type=worker
host=localhost
interface=eth0

  3. Tune Detection Interval

    # .env
DETECTION_INTERVAL=600  # 10 minutes

Maintenance & Updates

NetGuard AI requires regular updates to stay secure and effective.

Quick Update

cd /opt/netguard-ai
sudo ./update.sh --all

Update Options

Command What It Does
./update.sh --all Full update (system, images, rules, feeds)
./update.sh --rules Update Suricata rules only
./update.sh --threat-intel Refresh threat intelligence
./update.sh --check Check for updates without applying

Maintenance Schedule

Frequency Tasks
Weekly Check dashboard for alerts, verify services running
Monthly Run ./update.sh --all, review false positives
Quarterly Review detection thresholds, test alerting

See docs/MAINTENANCE_GUIDE.md for complete procedures.

Security Considerations

  • Keep Docker and all components updated
  • Use firewall to restrict dashboard access
  • Change default Grafana password
  • Consider VPN for remote access
  • Review and tune detection rules regularly

License

MIT License - Free for personal and commercial use.

Contributing

Contributions welcome! Please submit issues and pull requests.

Support

  • GitHub Issues: Report bugs and request features
  • Documentation: See /docs folder for detailed guides

About

Guard Networks With AI

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages