Skip to main content

Arxignis NGINX

A custom NGINX distribution built with OpenResty and enhanced security modules, including native JA4 fingerprinting support for advanced TLS client identification.

Overview​

Arxignis NGINX is a production-ready, custom-built NGINX distribution that includes native JA4 fingerprinting support and advanced security features. It's designed for environments where maximum security capabilities are required and where JA4 fingerprinting is critical for threat detection.

Best For​

  • Production deployments requiring maximum security features
  • Environments where JA4 fingerprinting is critical
  • High-traffic applications needing optimized performance
  • Deployments requiring ModSecurity WAF integration

Features​

  • JA4 Fingerprinting: Native TLS client fingerprinting support
  • OpenResty 1.27.1.2 with NGINX 1.27.1
  • ModSecurity 3.0.14 WAF integration
  • Advanced SSL/TLS features with OpenSSL 3.4.1
  • Brotli compression and performance optimizations
  • OpenTelemetry integration for observability

Requirements​

System Requirements​

  • Base OS: Alpine Linux 3.22 or compatible
  • Memory: Minimum 512MB RAM
  • Storage: 1GB available disk space
  • Docker: For containerized deployment

External Services​

  • Arxignis API Key: Get your API key from arxignis.com
  • Domain: A domain you control and can configure DNS for
  • OpenTelemetry Provider (Optional): For metrics collection

Installation​

Docker Deployment​

Build the Image​

docker build -t ghcr.io/arxignis/nginx:local .

Run the Container​

docker run -d -p 80:80 -p 443:443 \
  -e ARXIGNIS_API_KEY=your-api-key \
  -e ARXIGNIS_API_URL=https://api.arxignis.com/v1 \
  ghcr.io/arxignis/nginx:local

Docker Compose​

services:
  nginx:
    image: ghcr.io/arxignis/nginx:1.0
    ports:
      - "80:80"
      - "443:443"
    environment:
      - ARXIGNIS_API_KEY=<ARXIGNIS_API_KEY>
      - ARXIGNIS_API_URL=<ARXIGNIS_API_URL>
      - ARXIGNIS_CAPTCHA_SITE_KEY=<ARXIGNIS_CAPTCHA_SITE_KEY>
      - ARXIGNIS_CAPTCHA_SECRET_KEY=<ARXIGNIS_CAPTCHA_SECRET_KEY>
      - ARXIGNIS_CAPTCHA_PROVIDER=<ARXIGNIS_CAPTCHA_PROVIDER>
      - ARXIGNIS_MODE=block
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro

Check our example in the repository

Configuration​

JA4 Fingerprinting Configuration​

Enable JA4 Support​

# In your nginx configuration
load_module modules/ngx_http_ja4_module.so;

http {
    # JA4 configuration
    ja4_enabled on;
    ja4_log_level info;
    ja4_log_format detailed;
}

JA4 Logging​

# Custom log format with JA4 data
log_format ja4 '$remote_addr - $remote_user [$time_local] '
               '"$request" $status $body_bytes_sent '
               '"$http_referer" "$http_user_agent" '
               'ja4="$ja4_hash" ja4s="$ja4s_hash"';

ModSecurity WAF Configuration​

http {
    # Load ModSecurity module
    load_module modules/ngx_http_modsecurity_module.so;

    # ModSecurity configuration
    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec/main.conf;

    server {
        # Enable ModSecurity for this server
        modsecurity on;

        location / {
            # Your application configuration
        }
    }
}

Complete Configuration Example​

# Main configuration
http {
    include       mime.types;
    default_type  application/octet-stream;

    # Load security modules
    load_module modules/ngx_http_ja4_module.so;
    load_module modules/ngx_http_modsecurity_module.so;

    # JA4 configuration
    ja4_enabled on;
    ja4_log_level info;
    ja4_log_format detailed;

    # ModSecurity configuration
    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec/main.conf;

    # Arxignis configuration
    lua_shared_dict arxignis_cache 200m;
    lua_shared_dict arxignis_queue 50m;

    # Initialize cache
    init_by_lua_block {
        local mlcache = require "resty.mlcache"
        local arxignis_cache, err = mlcache.new("arxignis_cache", "arxignis_cache", {
            lru_size = 50000,
            ttl = 800,
            neg_ttl = 10,
        })
        _G.arxignis_cache = arxignis_cache
    }

    # Start worker processes
    init_worker_by_lua_block {
        local worker = require "resty.arxignis.worker"
        worker.start_flush_timers({
            ARXIGNIS_API_URL = os.getenv("ARXIGNIS_API_URL"),
            ARXIGNIS_API_KEY = os.getenv("ARXIGNIS_API_KEY")
        })
    }

    server {
        listen       80;
        listen       443 ssl http2;
        server_name  _;

        # SSL configuration
        ssl_certificate     /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;
        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;

        # Enable ModSecurity
        modsecurity on;

        # Apply Arxignis remediation
        access_by_lua_block {
            local arxignis = require "resty.arxignis"
            arxignis.remediate(ngx.var.remote_addr)
        }

        location / {
            content_by_lua_block {
                ngx.header.content_type = "text/html"
                ngx.say("Protected by Arxignis NGINX!")
                ngx.exit(ngx.HTTP_OK)
            }
        }
    }
}

Advanced Features​

JA4 Fingerprinting​

Selective JA4 Enablement​

server {
    # Enable JA4 for specific locations
    location /api/ {
        ja4_enabled on;
        # Your API configuration
    }

    location /static/ {
        ja4_enabled off;  # Disable for static content
        # Static file serving
    }
}

Custom JA4 Logging​

# Detailed JA4 logging
log_format ja4_detailed '$remote_addr - $remote_user [$time_local] '
                       '"$request" $status $body_bytes_sent '
                       '"$http_referer" "$http_user_agent" '
                       'ja4="$ja4_hash" ja4s="$ja4s_hash" '
                       'ja4_raw="$ja4_raw" ja4s_raw="$ja4s_raw"';

# Use in server block
access_log /var/log/nginx/ja4.log ja4_detailed;

ModSecurity Integration​

Custom Rules​

# Custom ModSecurity rules
modsecurity_rules '
    SecRule REQUEST_HEADERS:User-Agent "@contains bot" \
        "id:1001,phase:1,block,msg:\'Bot detected\',logdata:\'User-Agent: %{MATCHED_VAR}\'"
';

Rule Sets​

# Load OWASP Core Rule Set
modsecurity_rules_file /etc/nginx/modsec/owasp-crs/crs-setup.conf;
modsecurity_rules_file /etc/nginx/modsec/owasp-crs/rules/*.conf;

Performance Optimization​

JA4 Performance​

  • Minimal Overhead: JA4 fingerprinting adds <1ms latency
  • Efficient Processing: Optimized C implementation
  • Selective Enablement: Can be enabled per location

Caching Strategy​

  • L1 Cache: In-memory caching for fast access
  • L2 Cache: Shared memory for cross-worker access
  • TTL Optimization: Configurable cache expiration

Resource Requirements​

  • Memory: 512MB minimum, 1GB recommended
  • CPU: Optimized for high-throughput processing
  • Storage: Log storage based on traffic volume

Monitoring and Analytics​

JA4 Analytics​

  • Client fingerprint analysis
  • Behavioral pattern recognition
  • Threat correlation with fingerprints
  • Historical fingerprint tracking

ModSecurity Logs​

  • Detailed WAF event logging
  • Attack pattern analysis
  • Rule violation tracking
  • Performance impact monitoring

OpenTelemetry Integration​

  • Comprehensive tracing and metrics
  • Real-time performance analytics
  • Custom metric collection
  • Dashboard integration

Development​

Local Development​

# Build development image
docker build -t ghcr.io/arxignis/nginx:1.0.0:dev .

# Run with development configuration
docker run -it -p 8080:80 ghcr.io/arxignis/nginx:1.0.0:dev

Testing​

The distribution includes comprehensive testing:

  • Unit tests for core functionality
  • Integration tests for API interactions
  • NGINX configuration validation
  • JA4 fingerprinting verification
  • ModSecurity rule testing

Troubleshooting​

Common Issues​

JA4 Fingerprinting​

  • Module Loading: Ensure JA4 module is properly loaded
  • TLS Configuration: Verify TLS settings support fingerprinting
  • Log Level: Check JA4 logging configuration

ModSecurity​

  • Rule Loading: Verify ModSecurity rules are properly loaded
  • Performance: Monitor ModSecurity performance impact
  • False Positives: Tune rules to reduce false positives

Debug Mode​

Enable debug logging for troubleshooting:

error_log /var/log/nginx/error.log debug;

# JA4 debug logging
ja4_log_level debug;

# ModSecurity debug logging
SecDebugLog /var/log/nginx/modsec_debug.log
SecDebugLogLevel 9

FAQ​

Arxignis NGINX includes native JA4 fingerprinting support, ModSecurity WAF integration, enhanced SSL/TLS features, OpenTelemetry integration, and is specifically optimized for security and threat detection.
JA4 fingerprinting adds minimal overhead (&lt;1ms latency) and uses an optimized C implementation. The performance impact is negligible while providing significant security benefits.
Yes, JA4 fingerprinting can be enabled per location block in your NGINX configuration, allowing you to apply it only where needed for optimal performance.
ModSecurity rules can be configured through rule files, inline rules, or by loading the OWASP Core Rule Set. Rules are applied at the server or location level.
Arxignis NGINX provides OpenTelemetry integration, comprehensive logging, real-time metrics collection, custom analytics, and JA4 fingerprinting data for advanced threat correlation.
Yes, Arxignis NGINX is specifically designed for production deployments with enterprise-grade security features, performance optimizations, and comprehensive monitoring capabilities.

License​

This project is licensed under the terms specified in the LICENSE file.

Contributing​

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.

For more information, visit arxignis.com or join our Discord community.