NullSec ClusterGuard

Distributed Intrusion Detection System written in Erlang

Part of the NullSec offensive security toolkit
Twitter: x.com/AnonAntics
Portal: bad-antics.github.io

Overview

ClusterGuard is a distributed intrusion detection system that leverages Erlang's actor model for highly concurrent, fault-tolerant network security monitoring. The tool demonstrates Erlang's unique strengths: message passing, pattern matching, and the "let it crash" philosophy.

Erlang Features Showcased

• Actor Model: Independent processes for event handling
• Message Passing: Zero-shared-state communication
• Pattern Matching: Elegant attack signature detection
• Records: Type-safe structured data
• Fault Tolerance: Supervisor trees and crash recovery
• Hot Code Reloading: Update detection rules without downtime
• OTP Behaviors: Industry-standard design patterns

Attack Detection

Attack Type	MITRE ID	Severity
SQL Injection	T1190	CRITICAL
Command Injection	T1059	CRITICAL
Malware C2	T1204	CRITICAL
Data Exfiltration	T1048	HIGH
Lateral Movement	T1021	HIGH
Brute Force	T1110	HIGH
Port Scanning	T1046	MEDIUM
XSS	T1189	MEDIUM
DDoS	T1498	MEDIUM

Installation

# Clone
git clone https://github.com/bad-antics/nullsec-clusterguard.git
cd nullsec-clusterguard

# Compile
erlc clusterguard.erl

Usage

Command Line

# Run demo mode
erl -noshell -s clusterguard start -s init stop

# Interactive shell
erl
1> c(clusterguard).
2> clusterguard:demo().

Options

USAGE:
    clusterguard [OPTIONS]

OPTIONS:
    -h, --help       Show help
    -n, --nodes      Cluster nodes to connect
    -i, --interface  Network interface to monitor
    -r, --rules      Custom rules file

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    ClusterGuard Architecture                  │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    │
│    │   Node 1    │    │   Node 2    │    │   Node 3    │    │
│    │ ┌─────────┐ │    │ ┌─────────┐ │    │ ┌─────────┐ │    │
│    │ │Analyzer │ │    │ │Analyzer │ │    │ │Analyzer │ │    │
│    │ └────┬────┘ │    │ └────┬────┘ │    │ └────┬────┘ │    │
│    └──────│──────┘    └──────│──────┘    └──────│──────┘    │
│           │                  │                  │            │
│           └──────────────────┼──────────────────┘            │
│                              ▼                               │
│                    ┌─────────────────┐                       │
│                    │   Aggregator    │                       │
│                    │   (Leader)      │                       │
│                    └────────┬────────┘                       │
│                             ▼                                │
│                    ┌─────────────────┐                       │
│                    │  Alert Manager  │                       │
│                    └─────────────────┘                       │
│                                                               │
└──────────────────────────────────────────────────────────────┘

Sample Output

╔══════════════════════════════════════════════════════════════════╗
║          NullSec ClusterGuard - Distributed IDS                  ║
╚══════════════════════════════════════════════════════════════════╝

[Demo Mode]

Analyzing sample network events...

  [CRITICAL] command_injection
    Source:     185.220.101.1
    Target:     10.0.0.5:80
    Node:       node3@localhost
    Confidence: 85.0%
    MITRE:      T1059
    Desc:       Command injection attempt

  [CRITICAL] sql_injection
    Source:     192.168.1.100
    Target:     10.0.0.5:80
    Node:       node1@localhost
    Confidence: 90.0%
    MITRE:      T1190
    Desc:       SQL injection attack attempt

  [HIGH] brute_force
    Source:     192.168.1.50
    Target:     10.0.0.20:22
    Node:       node2@localhost
    Confidence: 70.0%
    MITRE:      T1110
    Desc:       Brute force authentication attempt

  Summary:
    Events Processed: 6
    Alerts Generated: 5
    Critical:         2
    High:             1
    Medium:           2

Code Highlights

Pattern Matching for Attack Detection

%% Check for HTTP-based attacks
check_http_attack(Payload) ->
    Checks = [
        {<<"SELECT ">>, sql_injection},
        {<<"UNION ">>, sql_injection},
        {<<"<script>">>, xss},
        {<<"; cat ">>, command_injection}
    ],
    check_patterns(Payload, Checks).

Record Types for Events

-record(event, {
    id :: integer(),
    timestamp :: erlang:timestamp(),
    source_ip :: string(),
    dest_ip :: string(),
    dest_port :: integer(),
    protocol :: atom(),
    payload :: binary(),
    node :: atom()
}).

Message Passing Architecture

%% Distributed event analysis
analyze_distributed(Event) ->
    Nodes = [node() | nodes()],
    [Node ! {analyze, Event} || Node <- Nodes].

Why Erlang?

Requirement	Erlang Advantage
High Concurrency	Lightweight processes (2KB each)
Fault Tolerance	Supervisor trees, "let it crash"
Distributed Systems	Built-in distribution protocol
Real-time Processing	Soft real-time guarantees
Hot Upgrades	Update code without stopping
Pattern Matching	Elegant signature detection

License

MIT License - See LICENSE for details.

Related Tools

• nullsec-beaconhunt - C2 beacon detector (Elixir)
• nullsec-flowtrace - Network flow analyzer (Haskell)
• nullsec-cryptoaudit - Crypto analyzer (Scala)