Skip to main content

OpenResty integration

A lightweight Lua module that can be integrated with any OpenResty/NGINX installation, providing core Arxignis security features without requiring a custom NGINX build.

Overview​

lua-resty-arxignis is designed for existing OpenResty deployments and development environments where you need Arxignis security features without the overhead of a custom NGINX build. It provides all core functionality through Lua modules that integrate seamlessly with your existing setup.

Best For​

  • Existing OpenResty deployments
  • Lightweight client implementations
  • Development environments
  • Environments where custom NGINX builds are not feasible

Features​

  • Captcha integration with Arxignis challenges
  • Comprehensive logging and monitoring
  • Performance and security metrics collection
  • Automated threat response and blocking
  • Background worker processes
  • High-performance caching with mlcache

Requirements​

System Requirements​

  • Lua: Version 5.1 or higher
  • OpenResty: Any version with lua-resty-core support
  • Dependencies: lua-resty-http, lua-resty-mlcache, lua-resty-jwt

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​

Using LuaRocks​

luarocks install lua-resty-arxignis

Manual Installation​

git clone https://github.com/arxignis/lua-resty-arxignis.git
cd lua-resty-arxignis
cp -r lib/resty/arxignis /usr/local/openresty/lualib/resty/

Configuration​

Environment Variables​

# Environment variables
env ARXIGNIS_CAPTCHA_SITE_KEY;
env ARXIGNIS_CAPTCHA_SECRET_KEY;
env ARXIGNIS_API_KEY;
env ARXIGNIS_API_URL;

Shared Memory Configuration​

# Shared memory
lua_shared_dict arxignis_cache 200m;
lua_shared_dict arxignis_queue 50m;

# SSL configuration
lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;

Complete NGINX Configuration Example​

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

    # 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;
        server_name  _;

        # 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!")
                ngx.exit(ngx.HTTP_OK)
            }
        }
    }
}

Usage​

Basic Integration​

  1. Install the module using LuaRocks or manual installation
  2. Configure environment variables for your Arxignis API credentials
  3. Set up shared memory for caching and queuing
  4. Add the remediation block to your server configuration
  5. Configure captcha templates if using challenge responses

Advanced Configuration​

Custom Cache Settings​

init_by_lua_block {
    local mlcache = require "resty.mlcache"
    local arxignis_cache, err = mlcache.new("arxignis_cache", "arxignis_cache", {
        lru_size = 100000,  # Increase cache size
        ttl = 1200,         # Longer TTL
        neg_ttl = 30,       # Longer negative TTL
    })
    _G.arxignis_cache = arxignis_cache
}

Custom Worker Configuration​

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"),
        FLUSH_INTERVAL = 5,  # Custom flush interval
        BATCH_SIZE = 100     # Custom batch size
    })
}

Monitoring and Analytics​

Logs​

  • View detailed logs in NGINX access/error logs
  • Real-time request/response analysis
  • Threat intelligence data logging

Metrics​

  • OpenTelemetry metrics export
  • Comprehensive tracing and metrics collection
  • Custom performance analytics
  • Real-time dashboard integration

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

Troubleshooting​

Common Issues​

Dependencies​

  • Missing Dependencies: Verify all Lua dependencies are installed
  • Version Compatibility: Check OpenResty and Lua version compatibility

Memory Issues​

  • Shared Memory: Check shared memory configuration
  • Cache Size: Adjust cache size based on traffic volume

SSL Issues​

  • Certificates: Ensure SSL certificates are properly configured
  • Trust Chain: Verify certificate trust chain

Debug Mode​

Enable debug logging for troubleshooting:

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

# In your lua block
local arxignis = require "resty.arxignis"
arxignis.set_debug(true)

Development​

Local Development​

# Run tests
cd t
prove *.t

# Development setup
docker-compose up -d

Testing​

The module includes comprehensive testing:

  • Unit tests for core functionality
  • Integration tests for API interactions
  • NGINX configuration validation

FAQ​

lua-resty-arxignis is designed to work with any OpenResty/NGINX installation that supports lua-resty-core, making it ideal for existing deployments without requiring custom builds.
The Lua module adds minimal overhead (<2ms latency) and uses efficient caching mechanisms. Performance impact is negligible while providing comprehensive security features.
Use 'luarocks upgrade lua-resty-arxignis' for LuaRocks installations, or replace the files manually for manual installations. Always test updates in a development environment first.
Yes, you can configure cache size, TTL values, and eviction policies through the mlcache configuration in your init_by_lua_block.
Yes, lua-resty-arxignis supports reCAPTCHA, hCaptcha, and Cloudflare Turnstile with automatic provider detection based on your API keys.
Use OpenTelemetry integration for comprehensive metrics, check NGINX access logs for request patterns, and monitor shared memory usage for cache performance.

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.