• Overview
• Documentation
• Architecture
• Core Features

• Technical Specifications
• Quick Start
• Installation

• Configuration
• API Reference
• Performance Benchmarks
• Security Considerations
• Development
• License

┌────────────────────────────────────────────────────────────────┐
│                        nginx-defender                          │
├────────────────────────────────────────────────────────────────┤
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────────┐  │
│  │  Log Monitor  │  │ Threat Intel │  │   Web Dashboard     │  │
│  │   (Async)     │  │  (Real-time) │  │    (WebSocket)      │  │
│  └───────┬───────┘  └──────┬───────┘  └─────────┬───────────┘  │
│          │                 │                    │              │
│  ┌───────▼─────────────────▼────────────────────▼───────────┐  │
│  │                Threat Detection Engine                   │  │
│  │  ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐    │  │
│  │  │   Pattern   │ │  ML Anomaly  │ │  Rate Limiting  │    │  │
│  │  │   Matcher   │ │  Detection   │ │     Engine      │    │  │
│  │  └─────────────┘ └──────────────┘ └─────────────────┘    │  │
│  └─────────────────────────┬────────────────────────────────┘  │
│                            │                                   │
│  ┌─────────────────────────▼────────────────────────────────┐  │
│  │                  Firewall Manager                        │  │
│  │  ┌─────────────┐ ┌──────────────┐ ┌─────────────────┐    │  │
│  │  │  iptables   │ │   nftables   │ │      pf         │    │  │
│  │  │   Backend   │ │   Backend    │ │   Backend       │    │  │
│  │  └─────────────┘ └──────────────┘ └─────────────────┘    │  │
│  └─────────────────────────┬────────────────────────────────┘  │
│                            │                                   │
│  ┌─────────────────────────▼────────────────────────────────┐  │
│  │            Multi-Channel Notification System             │  │
│  │    Telegram │ Slack │ Email │ Webhook │ Discord          │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────────┘

Machine Learning Integration

• Behavioral Analysis: Statistical anomaly detection using sliding windows
• Attack Vectorization: Feature extraction from HTTP requests
• Model Training: Continuous learning from threat patterns
• False Positive Reduction: Adaptive threshold adjustment

Pattern Matching Engine

# Example threat patterns
patterns:
  sql_injection:
    regex: "(?i)(union|select|insert|update|delete|drop|exec|script)"
    severity: 9
    categories: ["injection", "database"]
    
  xss_detection:
    regex: "(?i)(<script||vbscript:|onload=|onerror=)"
    severity: 8
    categories: ["xss", "injection"]
    
  directory_traversal:
    regex: "(?i)(\\.\\.[\\/\\\\]|%2e%2e%2f|%252e%252e%252f)"
    severity: 7
    categories: ["pathtraversal", "fileaccess"]

Rate Limiting Algorithm

type RateLimiter struct {
    Window    time.Duration
    Threshold int
    Algorithm string // "slidingwindow", "tokenbucket", "leaky_bucket"
}

Supported Backends

| Backend | Platform | Features | Performance | |---------|----------|----------|-------------| | iptables | Linux | Legacy compatibility, wide support | ~10k rules/sec | | nftables | Linux | Modern netfilter, better performance | ~50k rules/sec | | pf | FreeBSD/macOS | Advanced filtering, built-in NAT | ~30k rules/sec | | Windows Firewall | Windows | Native Windows integration | ~5k rules/sec | | Mock | All | Testing and development | Unlimited |

Rule Management

type Rule struct {
    ID          string            json:"id"
    IP          string            json:"ip"
    Action      Action            json:"action"
    Duration    time.Duration     json:"duration"
    CreatedAt   time.Time         json:"created_at"
    ExpiresAt   time.Time         json:"expires_at"
    Reason      string            json:"reason"
    ThreatLevel string            json:"threat_level"
    Metadata    map[string]string json:"metadata"
}

Action Types

• BLOCK: Complete traffic blocking
• DROP: Silent packet dropping
• REJECT: Explicit connection rejection
• RATE_LIMIT: Bandwidth throttling
• TARPIT: Connection delay injection
• ALLOW: Whitelist override

Web Dashboard Features

• Real-time Threat Map: Geographic visualization of attacks
• Performance Metrics: Request processing and response times
• Rule Management: Interactive firewall rule configuration
• Log Analysis: Filtering and search capabilities
• Alert Management: Notification configuration and history

Prometheus Metrics

# HELP nginxdefenderrequests_total Total number of requests processed
TYPE nginxdefenderrequests_total counter
nginxdefenderrequeststotal{status="blocked",reason="sqlinjection"} 1234
HELP nginxdefenderresponsedurationseconds Request processing duration
TYPE nginxdefenderresponsedurationseconds histogram
nginxdefenderresponsedurationseconds_bucket{le="0.1"} 8932

WebSocket API

const ws = new WebSocket('ws://localhost:8080/ws');
ws.onmessage = function(event) {
    const data = JSON.parse(event.data);
    console.log('New threat detected:', data);
};

Supported Channels

| Channel | Features | Configuration | |---------|----------|---------------| | Telegram | Rich formatting, bot integration | Bot token, chat ID | | Slack | Channel posting, thread replies | Webhook URL, channel | | Email | HTML templates, attachments | SMTP configuration | | Webhook | Custom integrations, JSON payload | Endpoint URL, headers | | Discord | Server notifications, embeds | Webhook URL | | PagerDuty | Incident management, escalation | Integration key |

Alert Severity Levels

severity_mapping:
  critical: 9-10    # Immediate response required
  high: 7-8         # Urgent attention needed
  medium: 4-6       # Standard monitoring
  low: 1-3          # Informational only

Namespace and ConfigMap

apiVersion: v1
kind: Namespace
metadata:
  name: nginx-defender

apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-defender-config
  namespace: nginx-defender
data:
  config.yaml: |
    firewall:
      backend: "iptables"
      whitelist:
        - "10.0.0.0/8"
        - "172.16.0.0/12"
        - "192.168.0.0/16"
    
    detection:
      enabled: true
      patterns_file: "pkg/patterns/common.yaml"
      rate_limiting:
        enabled: true
        window: "1m"
        max_requests: 100
    
    server:
      host: "0.0.0.0"
      port: 8080
    
    metrics:
      enabled: true
      prometheus:
        enabled: true
        host: "0.0.0.0"
        port: 9090

DaemonSet Deployment

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: nginx-defender
  namespace: nginx-defender
spec:
  selector:
    matchLabels:
      app: nginx-defender
  template:
    metadata:
      labels:
        app: nginx-defender
    spec:
      hostNetwork: true
      hostPID: true
      containers:
      - name: nginx-defender
        image: ghcr.io/anipaleja/nginx-defender:latest
        imagePullPolicy: Always
        securityContext:
          privileged: true
          capabilities:
            add:
              - NET_ADMIN
              - NET_RAW
              - SYS_ADMIN
        ports:
        - containerPort: 8080
          name: web
        - containerPort: 9090
          name: metrics
        volumeMounts:
        - name: config
          mountPath: /app/config.yaml
          subPath: config.yaml
        - name: log-files
          mountPath: /var/log/nginx
          readOnly: true
        - name: proc
          mountPath: /host/proc
          readOnly: true
        - name: sys
          mountPath: /host/sys
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: nginx-defender-config
      - name: log-files
        hostPath:
          path: /var/log/nginx
      - name: proc
        hostPath:
          path: /proc
      - name: sys
        hostPath:
          path: /sys
      tolerations:
      - operator: Exists
        effect: NoSchedule

Service and Ingress

apiVersion: v1
kind: Service
metadata:
  name: nginx-defender-service
  namespace: nginx-defender
spec:
  selector:
    app: nginx-defender
  ports:
  - name: web
    port: 8080
    targetPort: 8080
  - name: metrics
    port: 9090
    targetPort: 9090
  type: ClusterIP

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-defender-ingress
  namespace: nginx-defender
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: nginx-defender.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-defender-service
            port:
              number: 8080

# nginx-defender configuration file
Version: 2.0
Firewall configuration
firewall:
  # Backend type: iptables, nftables, pf, mock
  backend: "iptables"
  
  # Whitelisted IP addresses and ranges
  whitelist:
    - "127.0.0.1"
    - "::1"
    - "192.168.0.0/16"
    - "10.0.0.0/8"
    - "172.16.0.0/12"
  
  # Default action for threats
  default_action: "BLOCK"
  
  # Rule cleanup interval
  cleanup_interval: "5m"
  
  # Maximum number of rules
  max_rules: 10000
Threat detection configuration
detection:
  enabled: true
  
  # Machine learning model file (optional)
  mlmodel: "/app/models/threatdetection.model"
  
  # Threat patterns file
  patterns_file: "pkg/patterns/common.yaml"
  
  # Rate limiting configuration
  rate_limiting:
    enabled: true
    window: "1m"
    max_requests: 100
    algorithm: "sliding_window"
  
  # Geographic blocking
  geo_blocking:
    enabled: true
    blocked_countries: ["CN", "RU", "KP"]
    allowed_countries: []
    geoip_database: "/app/data/GeoLite2-City.mmdb"
  
  # Honeypot integration
  honeypot:
    enabled: false
    boost_factor: 2.0
    services: ["ssh", "http", "ftp"]
Log monitoring configuration
logs:
  level: "info"
  format: "json"
  output: "stdout"
  
  # Log sources to monitor
  sources:
    - path: "/var/log/nginx/access.log"
      format: "combined"
      follow: true
    - path: "/var/log/nginx/error.log"
      format: "error"
      follow: true
    - path: "/var/log/apache2/access.log"
      format: "combined"
      follow: false
Web server configuration
server:
  host: "0.0.0.0"
  port: 8080
  
  # TLS configuration
  tls:
    enabled: false
    cert_file: "/app/certs/server.crt"
    key_file: "/app/certs/server.key"
  
  # CORS configuration
  cors:
    enabled: true
    allowed_origins: ["*"]
    allowed_methods: ["GET", "POST", "PUT", "DELETE"]
Metrics and monitoring
metrics:
  enabled: true
  
  # Prometheus configuration
  prometheus:
    enabled: true
    host: "0.0.0.0"
    port: 9090
    path: "/metrics"
  
  # Performance monitoring
  performance:
    enabled: true
    interval: "30s"
Notification configuration
notifications:
  enabled: true
  
  # Notification channels
  channels:
    console:
      enabled: true
      level: "info"
    
    email:
      enabled: false
      smtp_host: "smtp.example.com"
      smtp_port: 587
      username: "alerts@example.com"
      password: "password"
      to: ["admin@example.com"]
      subject_prefix: "[nginx-defender]"
    
    telegram:
      enabled: false
      bottoken: "BOTTOKEN"
      chatid: "CHATID"
    
    slack:
      enabled: false
      webhookurl: "WEBHOOKURL"
      channel: "#security"
      username: "nginx-defender"
    
    webhook:
      enabled: false
      url: "https://api.example.com/webhooks/security"
      headers:
        Authorization: "Bearer TOKEN"
        Content-Type: "application/json"
Clustering configuration (Enterprise)
clustering:
  enabled: false
  node_id: "node-1"
  discovery:
    method: "static"
    endpoints: ["node-2:8081", "node-3:8081"]
  
  # Distributed rule synchronization
  sync:
    enabled: true
    interval: "10s"

System Information

GET /api/v1/status

{
  "status": "healthy",
  "version": "2.0.0",
  "uptime": "2h30m15s",
  "build_info": {
    "version": "v2.0.0",
    "commit": "abc123",
    "build_time": "2025-07-27T10:00:00Z"
  }
}

Firewall Rules Management

GET /api/v1/rules
POST /api/v1/rules
DELETE /api/v1/rules/{id}

Create Rule:

{   "ip": "192.168.1.100",   "action": "BLOCK",   "duration": "1h",   "reason": "SQL injection attempt",   "metadata": {     "threat_level": "high",     "pattern": "sql_injection"   } }

Statistics and Metrics

GET /api/v1/stats
GET /api/v1/metrics

Statistics Response:

{   "firewall": {     "backend": "iptables",     "total_rules": 1234,     "active_rules": 987,     "expired_rules": 247   },   "detection": {     "total_requests": 50000,     "blocked_requests": 1234,     "threat_detections": {       "sql_injection": 456,       "xss": 234,       "brute_force": 344     }   },   "performance": {     "avgresponsetime": "0.5ms",     "memory_usage": "89MB",     "cpu_usage": "3.2%"   } }

Configuration Management

GET /api/v1/config
PUT /api/v1/config
POST /api/v1/config/reload

Log Analysis

GET /api/v1/logs?limit=100&level=error
GET /api/v1/threats?since=1h&severity=high

Connection

const ws = new WebSocket('ws://localhost:8080/ws');

Event Types

// Threat detection event
{
  "type": "threat_detected",
  "timestamp": "2025-07-27T12:00:00Z",
  "data": {
    "ip": "192.168.1.100",
    "threattype": "sqlinjection",
    "severity": 9,
    "blocked": true
  }
}
// Rule creation event {   "type": "rule_created",   "timestamp": "2025-07-27T12:00:01Z",   "data": {     "rule_id": "rule-123",     "ip": "192.168.1.100",     "action": "BLOCK",     "expires_at": "2025-07-27T13:00:01Z"   } }
// System metrics update {   "type": "metrics_update",   "timestamp": "2025-07-27T12:00:00Z",   "data": {     "cpu_usage": 3.2,     "memory_usage": 89,     "active_connections": 1234   } }

Test Environment

• Hardware: Intel Xeon E5-2686v4 (4 cores), 16GB RAM
• OS: Ubuntu 22.04 LTS
• Network: 10Gbps Ethernet
• Backend: nftables

Results

| Test Scenario | Throughput | Latency (p95) | CPU Usage | Memory Usage | |---------------|------------|---------------|-----------|--------------| | Log Processing | 150k entries/sec | 2ms | 15% | 120MB | | Pattern Matching | 100k requests/sec | 1ms | 25% | 95MB | | Rule Application | 75k rules/sec | 0.5ms | 10% | 85MB | | API Requests | 50k requests/sec | 5ms | 20% | 100MB | | WebSocket Events | 25k events/sec | 3ms | 12% | 90MB |

Scaling Characteristics

Log Processing Rate vs CPU Cores:
  1 core:  50k entries/sec
  2 cores: 95k entries/sec
  4 cores: 150k entries/sec
  8 cores: 180k entries/sec (diminishing returns)

| Component | Base Memory | Per Rule | Per Connection | |-----------|-------------|----------|----------------| | Core Engine | 45MB | 64 bytes | 2KB | | Pattern Matcher | 25MB | - | 512 bytes | | Web Server | 15MB | - | 4KB | | Metrics Collector | 10MB | 128 bytes | 1KB | | Total Baseline | 95MB | 192 bytes | 7.5KB |

Memory Growth Projections

• 10k rules: ~97MB
• 100k rules: ~114MB
• 1M rules: ~287MB
• 10k concurrent connections: ~170MB

Defense in Depth

• Input Validation: All user inputs are validated and sanitized
• Principle of Least Privilege: Minimal required permissions
• Fail-Safe Defaults: Secure defaults for all configurations
• Complete Mediation: All access attempts are checked
• Open Design: Security through design, not obscurity

Threat Model

graph LR
    A[External Attacker] -->|HTTP Requests| B[nginx-defender]
    C[Malicious Insider] -->|Config Changes| B
    D[Compromised System] -->|Local Access| B
    
    B -->|Validated Traffic| E[Protected Services]
    B -->|Blocked Traffic| F[Firewall Drop]
    B -->|Alerts| G[Security Team]

Security Controls

| Layer | Control | Implementation | |-------|---------|----------------| | Network | Traffic filtering | iptables/nftables rules | | Application | Input validation | Regex patterns, ML detection | | Authentication | API access control | JWT tokens, API keys | | Authorization | Role-based access | RBAC system | | Audit | Activity logging | Structured logging, SIEM integration | | Encryption | Data protection | TLS 1.3, AES-256 |

Regular Security Assessments

• Static Analysis: Weekly automated scans
• Dynamic Testing: Monthly penetration testing
• Dependency Scanning: Daily vulnerability checks
• Configuration Audits: Quarterly security reviews

Incident Response

• Detection: Automated threat detection and alerting
• Analysis: Log correlation and forensic analysis
• Containment: Automatic rule application and isolation
• Recovery: System restoration and patch application
• Lessons Learned: Post-incident review and improvements

Compliance Standards

• OWASP Top 10: Protection against common web vulnerabilities
• NIST Cybersecurity Framework: Risk management alignment
• ISO 27001: Information security management
• PCI DSS: Payment card industry compliance (where applicable)

Prerequisites

# Install Go 1.21+
curl -L https://go.dev/dl/go1.21.linux-amd64.tar.gz | sudo tar -C /usr/local -xz
export PATH=$PATH:/usr/local/go/bin
Install development tools
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
go install github.com/securecodewarrior/sast-scan@latest

Build Process

# Clone repository
git clone https://github.com/anipaleja/nginx-defender.git
cd nginx-defender
Install dependencies
go mod download
Run tests
go test -v ./...
Build binary
go build -o nginx-defender ./cmd/nginx-defender
Build for multiple platforms
make build-all

Development Workflow

# Run with hot reload
air -c .air.toml
Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
Lint code
golangci-lint run
Security scan
gosec ./...

Code Standards

• Go Style: Follow effective Go guidelines
• Documentation: Comprehensive godoc comments
• Testing: Minimum 80% test coverage
• Performance: Benchmark critical paths
• Security: Static analysis and vulnerability scanning

Pull Request Process

• Fork the repository
• Create feature branch (git checkout -b feature/amazing-feature)
• Commit changes (git commit -m 'Add amazing feature')
• Push to branch (git push origin feature/amazing-feature)
• Open Pull Request with detailed description

Issue Reporting

## Bug Report Template
Environment: 
OS: [e.g., Ubuntu 22.04]
 
Version: [e.g., v2.0.0]
 
Backend: [e.g., iptables]
 
 Steps to Reproduce: 
Configuration used
 
Command executed
 
Expected vs actual behavior
 
 Logs:

Additional Context: [Any other relevant information]

| Dependency | License | Usage | |------------|---------|-------| | gorilla/mux | BSD-3-Clause | HTTP routing | | gorilla/websocket | BSD-2-Clause | WebSocket support | | sirupsen/logrus | MIT | Structured logging | | prometheus/client_golang | Apache-2.0 | Metrics collection | | oschwald/geoip2-golang | ISC | Geographic lookup | | go-telegram-bot-api/telegram-bot-api | MIT | Telegram integration | | slack-go/slack | BSD-2-Clause | Slack integration |