Skip to main content

Common Concepts

This section covers shared concepts and features that apply to all NGINX client implementations.

JA4 Fingerprinting​

What is JA4?​

You can find more details here

JA4 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"';

JA4 Performance Impact​

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

Captcha Provider Configuration​

Arxignis supports multiple captcha providers for flexible integration. Each provider requires both a site key (for frontend) and a secret key (for backend verification).

Supported Providers​

ProviderFrontend JSFrontend KeyResponse Key
reCAPTCHAhttps://www.recaptcha.net/recaptcha/api.jsg-recaptchag-recaptcha-response
hCaptchahttps://js.hcaptcha.com/1/api.jsh-captchah-captcha-response
Cloudflare Turnstilehttps://challenges.cloudflare.com/turnstile/v0/api.jscf-turnstilecf-turnstile-response

Note: You can specify the captcha provider explicitly using the ARXIGNIS_CAPTCHA_PROVIDER environment variable, or let the system auto-detect it based on your API keys.

Getting API Keys​

reCAPTCHA​

  1. Visit Google reCAPTCHA Admin Console
  2. Click "Create" to add a new site
  3. Choose reCAPTCHA v2 "I'm not a robot" Checkbox
  4. Add your domain(s) to the list
  5. Copy the Site Key and Secret Key

hCaptcha​

  1. Go to hCaptcha Dashboard
  2. Click "Add Site" to create a new site
  3. Configure your domain and settings
  4. Copy the Site Key and Secret Key

Cloudflare Turnstile​

  1. Access Cloudflare Dashboard
  2. Navigate to Security > Turnstile
  3. Click "Add Site" to create a new widget
  4. Choose widget type (Managed, Non-Interactive, or Invisible)
  5. Copy the Site Key and Secret Key

Configuration Example​

# Set environment variables for your chosen provider
env ARXIGNIS_CAPTCHA_SITE_KEY=your_site_key_here;
env ARXIGNIS_CAPTCHA_SECRET_KEY=your_secret_key_here;
env ARXIGNIS_CAPTCHA_PROVIDER=recaptcha;  # or hcaptcha, turnstile
env ARXIGNIS_CAPTCHA_TEMPLATE_PATH=/etc/nginx/captcha_template.html;

# The captcha provider will be automatically detected based on your keys
# or you can specify it explicitly with ARXIGNIS_CAPTCHA_PROVIDER

Environment Variables​

VariableDescriptionRequiredDefault
ARXIGNIS_API_KEYYour Arxignis API keyYes-
ARXIGNIS_API_URLArxignis API endpointYeshttps://api.arxignis.com/v1
ARXIGNIS_CAPTCHA_SITE_KEYCaptcha site keyYes-
ARXIGNIS_CAPTCHA_SECRET_KEYCaptcha secret keyYes-
ARXIGNIS_CAPTCHA_PROVIDERCaptcha provider type (recaptcha, hcaptcha, turnstile)YesAuto-detected
ARXIGNIS_MODEOperation mode: monitor or blockNomonitor
JA4_ENABLEDEnable JA4 fingerprintingNotrue

Operation Modes​

Monitor Mode​

  • Analyzes all incoming traffic
  • Logs threat intelligence data
  • No blocking of requests
  • Perfect for initial deployment and testing

Block Mode​

  • Analyzes and blocks malicious traffic
  • Customizable blocking rules
  • Real-time threat response
  • Production-ready protection

Key Features​

🛡️ Advanced Threat Intelligence​

  • Real-time threat detection using Arxignis API
  • Comprehensive IP reputation analysis
  • Behavioral threat detection with JA4 fingerprinting
  • Custom threat scoring with configurable thresholds

🔍 JA4 Fingerprinting Support​

  • Native TLS client fingerprinting
  • TLS 1.3 protocol support
  • Behavioral analysis and pattern recognition
  • Advanced bot detection capabilities

📊 Complete Observability​

  • OpenTelemetry integration for comprehensive tracing
  • Real-time performance analytics
  • Custom metric collection and buffering
  • Comprehensive request logging

🔒 Flexible Protection Modes​

  • Monitor Mode: Traffic analysis without blocking
  • Block Mode: Active threat blocking with custom rules
  • Hybrid Mode: Selective blocking based on threat scores

🤖 Bot Protection​

  • Advanced bot detection using JA4 fingerprinting
  • Custom challenge configurations
  • Behavioral analysis for threat identification

Architecture​

Core Components​

  • Remediation Engine: Threat assessment and decision making
  • JA4 Fingerprinting: Advanced TLS client identification
  • Captcha Handler: Challenge integration and verification
  • Cache System: High-performance caching with mlcache
  • Worker Processes: Background task processing
  • OpenTelemetry: Comprehensive observability

Data Flow​

  1. Request Reception: Incoming requests are analyzed
  2. JA4 Fingerprinting: TLS client fingerprinting (if enabled)
  3. Threat Assessment: Arxignis API evaluates the request
  4. Decision Making: Choose between allow, block, or captcha
  5. Response Generation: Generate appropriate response
  6. Metrics Collection: Collect performance and security metrics

Performance Considerations​

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: 200MB shared cache recommended
  • CPU: Minimal impact on request processing
  • Storage: Log storage based on traffic volume

Security Best Practices​

JA4 Fingerprinting​

  • Enable JA4 logging for threat analysis
  • Monitor fingerprint patterns for anomalies
  • Use JA4 data for behavioral threat detection
  • Correlate fingerprints with threat intelligence

API Key Management​

  • Never commit API keys to version control
  • Use environment variables or secrets management
  • Regularly rotate API tokens

Access Control​

  • Review and update permissions regularly
  • Monitor access logs for suspicious activity
  • Implement least-privilege access

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

Getting Help​