Guarder

A high-performance network connection tracking tool based on eBPF/XDP technology that monitors TCP/UDP connections and ICMP traffic, with intelligent AI-powered filter generation capabilities.

🚀 Features

High Performance: Zero-copy data processing with eBPF/XDP technology
Comprehensive Monitoring: TCP/UDP connection tracking and ICMP traffic analysis
Intelligent Filtering: AI-powered filter rule generation and management
Real-time Statistics: Detailed network performance statistics and analysis
HTTP API: Complete RESTful API interface
Precise Matching: Multi-dimensional filtering based on IP, port, protocol, and more

🏗️ Architecture


┌─────────────────────┐      ┌─────────────────────────────────┐
│                     │      │                                 │
│    Network Packets  │──────▶  eBPF/XDP Program              │
│                     │      │  (conn_tracker.c)              │
└─────────────────────┘      └───────────────┬─────────────────┘
                                             │
                                             │ BPF Maps
                                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│                         User Space Program                      │
│                                                                 │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────┐    │
│  │   BPF Loader  │    │  Map Reader   │    │  API Server   │    │
│  │  (main.go)    │    │  (main.go)    │    │  (api.go)     │    │
│  └───────────────┘    └───────────────┘    └───────────────┘    │
│                                                    │            │
│                       ┌─────────────────────────────────────┐   │
│                       │         AI Analysis Module          │   │
│                       │       (ai_filter.go)               │   │
│                       └─────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                                     │
                                                     ▼
                                           ┌───────────────────────┐
                                           │   HTTP Clients/AI     │
                                           └───────────────────────┘

📁 Project Structure


conn-tracker/
├── bpf/                    # eBPF kernel programs
│   └── conn_tracker.c      # Main XDP program
├── cmd/conn-tracker/       # User space application
│   ├── main.go            # Main program entry
│   ├── api.go             # HTTP API server
│   ├── ai_filter.go       # AI filter generation
│   ├── filter.go          # Filter management
│   └── common.go          # Common utilities
├── pkg/                   # Go packages
└── docs/                  # Documentation (this README)

🔧 Installation

Prerequisites

Linux kernel 5.4+ (with eBPF/XDP support)
Go 1.19+
libbpf development libraries
clang compiler
OpenAI API key (optional, for AI functionality)

Build


# Clone the repository
git clone <repository-url>
cd conn-tracker
 
# Build the project
make
 
# Run the application
sudo ./conn-tracker -iface eth0 -interval 5 -api :8080

Command Line Options

-iface: Network interface to monitor (required)
-interval: Console output interval in seconds (default: 10)
-api: API server listen address (default: :8080)

📊 Connection Tracking

Real-time Monitoring

The system provides comprehensive network connection tracking with detailed information:

TCP/UDP Connections: Source/destination IPs, ports, packet counts, byte counts
Connection States: TCP flags, sequence numbers, acknowledgment numbers
Timing Information: First seen, last seen timestamps
Performance Metrics: Retransmissions, window sizes, packet loss

API Endpoints

Get Connections


curl http://localhost:8080/api/connections

Response Example:


[
  {
    "key": "192.168.1.100:12345 -> 8.8.8.8:53 (UDP)",
    "info": "Packets: 1, Bytes: 64, IP ID: 1234, Last Seen: 2023-05-01T12:34:56Z"
  },
  {
    "key": "192.168.1.100:56789 -> 93.184.216.34:443 (TCP)",
    "info": "Packets: 42, Bytes: 8192, TCP Flags: 24, Seq: 1234567890, Ack: 987654321"
  }
]

Get ICMP Traffic


curl http://localhost:8080/api/icmp

Get Performance Statistics


curl http://localhost:8080/api/stats

🛡️ Filter Management

Overview

The filter system provides kernel-space packet filtering with support for fine-grained filtering across different protocols:

Basic Filtering: IP addresses, ports, protocols
ICMP Filtering: ICMP types, codes, and error message inspection
TCP Filtering: TCP flag-based filtering
UDP Filtering: Port-based filtering

Filter API

Get All Filters


curl http://localhost:8080/api/filters

Built-in Security Filter Examples

1. Block All ICMP Ping Requests:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 8,
    "icmp_code": 0,
    "action": "drop",
    "enabled": false,
    "comment": "Block all ICMP ping requests (Echo Request)"
  }'

2. Block ICMP Destination Unreachable and Source Quench:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 3,
    "action": "drop",
    "enabled": true,
    "comment": "Block ICMP Destination Unreachable messages"
  }'


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 4,
    "action": "drop",
    "enabled": true,
    "comment": "Block ICMP Source Quench messages"
  }'

8. Block ICMP Error Messages Containing UDP Traffic:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 3,
    "inner_protocol": "udp",
    "action": "drop",
    "enabled": true,
    "comment": "Block ICMP Destination Unreachable with inner UDP packets"
  }'

9. Advanced ICMP Filtering - Block Specific Inner UDP Ports:


# Block ICMP errors containing DNS traffic (inner UDP port 53)
curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 3,
    "inner_protocol": "udp",
    "inner_dst_ip": "",
    "comment": "Block ICMP errors exposing DNS queries"
  }'
 
# Block ICMP Time Exceeded with inner UDP (traceroute detection)
curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 11,
    "inner_protocol": "udp",
    "action": "drop",
    "enabled": true,
    "comment": "Block UDP traceroute attempts (ICMP Time Exceeded)"
  }'

10. Block All ICMP Echo Requests (Comprehensive Ping Block):


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "protocol": "icmp",
    "icmp_type": 8,
    "action": "drop",
    "enabled": true,
    "comment": "Block all ICMP Echo Requests (comprehensive ping block)"
  }'

4. Block Dangerous Ports - Remote Access:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 23,
    "action": "drop",
    "enabled": true,
    "comment": "Block Telnet (insecure remote access)"
  }'


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 135,
    "action": "drop",
    "enabled": true,
    "comment": "Block RPC Endpoint Mapper (Windows vulnerability)"
  }'

5. Block Dangerous Ports - File Sharing:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 445,
    "action": "drop",
    "enabled": true,
    "comment": "Block SMB/CIFS (ransomware vector)"
  }'


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 139,
    "action": "drop",
    "enabled": true,
    "comment": "Block NetBIOS Session Service"
  }'

6. Block Dangerous Ports - Database Services:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 1433,
    "action": "drop",
    "enabled": true,
    "comment": "Block MS SQL Server (external access)"
  }'


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 3306,
    "action": "drop",
    "enabled": true,
    "comment": "Block MySQL (external access)"
  }'

7. Block Dangerous Ports - Remote Desktop:


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 3389,
    "action": "drop",
    "enabled": true,
    "comment": "Block RDP (brute force target)"
  }'


curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "tcp",
    "protocol": "tcp",
    "dst_port": 5900,
    "action": "drop",
    "enabled": true,
    "comment": "Block VNC (insecure remote access)"
  }'

Update Filter


curl -X PUT http://localhost:8080/api/filters/0 \
  -H "Content-Type: application/json" \
  -d '{
    "id": 0,
    "action": "drop",
    "enabled": false,
    "comment": "Temporarily disabled"
  }'

Delete Filter


curl -X DELETE http://localhost:8080/api/filters/0

Enable/Disable Filter


# Enable
curl -X POST http://localhost:8080/api/filters/0/enable
 
# Disable
curl -X POST http://localhost:8080/api/filters/0/disable

Filter Rule Types

Wildcard Values

When creating filter rules, you can omit certain fields and the system will automatically set them to wildcard values:

IP addresses: Empty or omitted fields are set to "any" (matches any IP)
Ports: Default value 0 matches any port
Protocol: Automatically set based on rule_type if not specified
ICMP type/code: Use 255 for wildcard matching in BPF program

Testing and Debugging Filters

To verify that your filters are working correctly:

Monitor BPF trace output (shows detailed filter matching):


sudo cat /sys/kernel/debug/tracing/trace_pipe

Check if filter was added successfully:


curl http://localhost:8080/api/filters

Test ICMP filter with ping:


# Add ICMP filter
curl -X POST http://localhost:8080/api/filters \
  -H "Content-Type: application/json" \
  -d '{
    "rule_type": "icmp",
    "icmp_type": 8,
    "icmp_code": 0,
    "action": "drop",
    "enabled": true,
    "comment": "Block ICMP ping requests"
  }'
 
# Test with ping (should be blocked)
ping -c 1 target_ip

Basic Rules

Fields: src_ip, dst_ip, src_port, dst_port, protocol

TCP Rules

Additional fields: tcp_flags, tcp_flags_mask

UDP Rules

Fields: src_port, dst_port

ICMP Rules

Additional fields: icmp_type, icmp_code, inner_src_ip, inner_dst_ip, inner_protocol

TCP Flags Reference

Flag	Value	Description
FIN	1	Connection termination
SYN	2	Synchronize, establish connection
RST	4	Reset connection
PSH	8	Push data
ACK	16	Acknowledgment
URG	32	Urgent data

Common Combinations:

SYN (2): Connection request
SYN+ACK (18): Connection response
ACK (16): Data transmission
FIN+ACK (17): Normal close
RST (4): Force close

🤖 AI-Powered Filter Generation

Overview

The AI intelligent filter generation feature utilizes large language models (like OpenAI GPT series) to analyze network connection data and automatically generate appropriate eBPF filter rules.

Core Features

Intelligent Analysis: Automatic analysis of TCP/UDP connections, ICMP traffic, and performance statistics
Multiple Strategies: Security-oriented, performance-oriented, and balanced modes
Custom Prompts: User-provided custom analysis instructions
Detailed Comments: Generated rules include detailed explanations and suggestions
Flexible Configuration: Support for custom OpenAI endpoints and model parameters

AI Configuration

Get Current Configuration


curl http://localhost:8080/api/ai/config

Update AI Configuration


curl -X POST http://localhost:8080/api/ai/config \
  -H "Content-Type: application/json" \
  -d '{
    "openai_endpoint": "https://api.openai.com/v1/chat/completions",
    "api_key": "sk-your-openai-api-key",
    "model": "gpt-4",
    "temperature": 0.7,
    "timeout": 120,
    "debug": true
  }'

AI Filter Generation

Security-Oriented Analysis


curl -X POST http://localhost:8080/api/ai/generate \
  -H "Content-Type: application/json" \
  -d '{
    "analyze_type": "security",
    "include_tcp": true,
    "include_icmp": true,
    "include_stats": true
  }'

Performance-Oriented Analysis


curl -X POST http://localhost:8080/api/ai/generate \
  -H "Content-Type: application/json" \
  -d '{
    "analyze_type": "performance",
    "include_tcp": true,
    "include_icmp": false,
    "include_stats": true
  }'

Custom Analysis


curl -X POST http://localhost:8080/api/ai/generate \
  -H "Content-Type: application/json" \
  -d '{
    "analyze_type": "custom",
    "custom_prompt": "Focus on SSH and HTTP service security, identify brute force attacks",
    "include_tcp": true,
    "include_icmp": true,
    "include_stats": true
  }'

Network Analysis Only (No Filter Generation)


curl -X POST http://localhost:8080/api/ai/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "include_tcp": true,
    "include_icmp": true,
    "include_stats": true,
    "custom_prompt": "Analyze traffic patterns for anomalies"
  }'

Supported Endpoints

OpenAI Compatible Endpoints


# OpenAI Official
"https://api.openai.com/v1/chat/completions"
 
# Azure OpenAI
"https://your-resource.openai.azure.com/openai/deployments/your-deployment/chat/completions?api-version=2023-05-15"
 
# DeepSeek AI
"https://api.deepseek.com/v1/chat/completions"

Local Deployed Models


# Ollama
"http://localhost:11434/v1/chat/completions"
 
# vLLM
"http://localhost:8000/v1/chat/completions"
 
# LocalAI
"http://localhost:8080/v1/chat/completions"

Response Format

Success Response


{
  "success": true,
  "analysis": "Network traffic analysis shows potential brute force attack on SSH service...",
  "suggestions": [
    "Implement rate limiting for SSH connections",
    "Block suspicious IP addresses",
    "Monitor for port scanning activities"
  ],
  "filters": [
    {
      "rule_type": "tcp",
      "protocol": "tcp",
      "tcp_flags": 2,
      "tcp_flags_mask": 2,
      "action": "drop",
      "enabled": true,
      "comment": "Block TCP SYN scanning attacks"
    }
  ],
  "tokens_used": 250
}

Debug Mode

Enable Debug Mode


curl -X POST http://localhost:8080/api/ai/config \
  -H "Content-Type: application/json" \
  -d '{
    "debug": true,
    "timeout": 120
  }'

When debug mode is enabled, detailed information is printed to the server console:

Request parameters
Connection data summary
Generated system prompts
OpenAI API requests/responses
HTTP request/response details
JSON parsing process
Final results

🎯 Use Cases

Network Security Monitoring

Real-time monitoring of network connection states
Detection of anomalous traffic and potential threats
Automatic generation of security protection rules

Performance Optimization

Analysis of network bottlenecks and performance issues
Optimization of network configuration and traffic distribution
Intelligent generation of performance optimization rules

Compliance Auditing

Network access control and auditing
Configuration checks for security standard compliance
Automated compliance report generation

Incident Response

Rapid response to network security incidents
Automatic generation of emergency protection rules
Traffic pattern analysis for threat hunting

🛠️ Advanced Configuration

Environment Variables


export OPENAI_API_KEY="your-api-key"
export OPENAI_ENDPOINT="https://api.openai.com/v1/chat/completions"
export AI_DEBUG="true"

Automation Script Example


#!/bin/bash
 
# Configure AI service
curl -X POST http://localhost:8080/api/ai/config \
  -H "Content-Type: application/json" \
  -d '{
    "openai_endpoint": "'$OPENAI_ENDPOINT'",
    "api_key": "'$OPENAI_API_KEY'",
    "model": "gpt-4",
    "temperature": 0.5,
    "timeout": 120
  }'
 
# Generate security filter rules
RESPONSE=$(curl -s -X POST http://localhost:8080/api/ai/generate \
  -H "Content-Type: application/json" \
  -d '{
    "analyze_type": "security",
    "include_tcp": true,
    "include_icmp": true,
    "include_stats": true
  }')
 
# Check if successful
if echo "$RESPONSE" | jq -e '.success' > /dev/null; then
  echo "AI analysis completed successfully"
  echo "$RESPONSE" | jq '.analysis'
  
  # Auto-apply generated rules (optional)
  echo "$RESPONSE" | jq '.filters[]' | while IFS= read -r filter; do
    curl -X POST http://localhost:8080/api/filters \
      -H "Content-Type: application/json" \
      -d "$filter"
  done
else
  echo "AI analysis failed:"
  echo "$RESPONSE" | jq '.error'
fi

🔍 Troubleshooting

Common Issues

Compilation Errors

Ensure Linux kernel headers are installed
Verify clang and libbpf development packages
Check Go version (1.19+ required)

API Connection Issues


# Check if service is running
curl http://localhost:8080/api/stats
 
# Verify network interface
ip link show

AI Generation Failures

Verify API key and endpoint configuration
Check network connectivity to AI service
Enable debug mode for detailed error information
Increase timeout for slow AI responses

Permission Errors


# Run with sudo for eBPF operations
sudo ./conn-tracker -iface eth0

📋 Technical Specifications

Kernel Requirements: Linux 5.4+
Memory Usage: < 50MB typical
CPU Overhead: < 1% on modern systems
Network Protocols: IPv4, TCP, UDP, ICMP
Maximum Connections: 1M+ concurrent tracking
Filter Rules: 1000+ rules supported

🌟 Acknowledgments

eBPF/XDP technology from the Linux kernel community
OpenAI for AI-powered analysis capabilities
Go eBPF libraries and tools

Guarder

🚀 Features

🏗️ Architecture

📁 Project Structure

🔧 Installation

Prerequisites

Build

Command Line Options

📊 Connection Tracking

Real-time Monitoring

API Endpoints

Get Connections

Get ICMP Traffic

Get Performance Statistics

🛡️ Filter Management

Overview

Filter API

Get All Filters

Built-in Security Filter Examples

Update Filter

Delete Filter

Enable/Disable Filter

Filter Rule Types

Wildcard Values

Testing and Debugging Filters

Basic Rules

TCP Rules

UDP Rules

ICMP Rules

TCP Flags Reference

🤖 AI-Powered Filter Generation

Overview

Core Features

AI Configuration

Get Current Configuration

Update AI Configuration

AI Filter Generation

Security-Oriented Analysis

Performance-Oriented Analysis

Custom Analysis

Network Analysis Only (No Filter Generation)

Supported Endpoints

OpenAI Compatible Endpoints

Local Deployed Models

Response Format

Success Response

Debug Mode

Enable Debug Mode

🎯 Use Cases

Network Security Monitoring

Performance Optimization

Compliance Auditing

Incident Response

🛠️ Advanced Configuration

Environment Variables

Automation Script Example

🔍 Troubleshooting

Common Issues

Compilation Errors

API Connection Issues

AI Generation Failures

Permission Errors

📋 Technical Specifications

🌟 Acknowledgments

📚 Additional Resources