Cloudflare

A Cloudflare Workers-based proxy that provides advanced threat intelligence and protection for your web applications, offering full control over your security data and observability.

Overview

The Arxignis Cloudflare client delivers enterprise-grade threat intelligence directly at the edge, providing real-time protection while maintaining complete control over your security data and observability.

Cloudflare Plan Requirements

Important: This client requires a paid Cloudflare plan for production use. The Free plan has severe limitations that make it unsuitable for production workloads:

Workers Plan Limits

Feature	Workers Free	Workers Paid
Subrequests	50/request	1000/request
Simultaneous outgoing connections/request	6	6
Environment variables	64/Worker	128/Worker
Environment variable size	5 KB	5 KB
Worker size	3 MB	10 MB
Worker startup time	400 ms	400 ms
Number of Workers	100	500
Number of Cron Triggers per account	5	250
Number of Static Asset files per Worker version	20,000	20,000
Individual Static Asset file size	25 MiB	25 MiB

Additional Limitations on Free Plan

KV Storage: Limited to 100,000 operations/day
Durable Objects: Available but with significant limitations

Durable Objects Plan Limits

Feature	Workers Free	Workers Paid
Maximum Durable Object classes	100	500
Storage per account	5 GB	Unlimited
Storage per class	Unlimited	Unlimited
Storage per Durable Object	10 GB	10 GB
Key + Value size limit	2 MB	2 MB
WebSocket message size	1 MiB	1 MiB
CPU per request	30 seconds	30 seconds (configurable to 5 minutes)
Number of Objects	Unlimited	Unlimited

For production deployments, we strongly recommend using a paid Cloudflare plan to ensure reliable operation and full feature availability.

Key Features

🛡️ Advanced Threat Intelligence

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

📊 Complete Observability

OpenTelemetry integration for comprehensive tracing
Durable Objects for efficient log and metrics buffering
KV storage for caching and performance optimization
Prometheus-compatible metrics export via Axiom

🔒 Flexible Protection Modes

Monitor Mode: Traffic analysis without blocking
Block Mode: Active threat blocking with custom rules

🤖 Bot Protection

Cloudflare Turnstile integration with JWT-based authentication
Advanced bot detection and challenge systems
Custom challenge configurations and response handling

📈 Performance Monitoring

Optional OpenTelemetry metrics export to any compatible provider
Real-time performance analytics with OpenTelemetry
Custom metric collection and buffering

Why Choose Arxignis Over Cloudflare WAF?

Limitations of Cloudflare WAF/Firewall

Free Plan Restrictions: Cloudflare Free plan severely limits Workers, KV storage, and Durable Objects
Rate Limiting: Cloudflare WAF has strict rate limits that can cause data loss
Limited Observability: Restricted access to detailed traffic information
No Full Control: Limited customization of security rules and responses
Data Ownership: Limited control over your security data
Cost Scaling: Expensive at scale with limited features

Arxignis Advantages

No Rate Limits: Unlimited threat intelligence queries
Complete Observability: Full access to all traffic data and logs
Full Control: Customize every aspect of your security rules
Data Ownership: Complete control over your security data
Cost Effective: Predictable pricing with enterprise features
No Plan Restrictions: Works with any Cloudflare plan, including Free (though not recommended for production)

Requirements

System Requirements

Node.js: Version 16 or higher
pnpm: For package management (recommended)
npx: For Wrangler commands
jq: For JSON parsing (automatically installed if missing)
Bash: For running the installation script

Cloudflare Requirements

Cloudflare Account: Active Cloudflare account
Cloudflare Plan: Paid plan required (Free plan is very limited and not recommended for production workloads)
API Token: Cloudflare API token with the following permissions:
- Account Settings (Read)
- Challenge Widgets (Edit)
- User Details (Read)
- Workers KV Storage (Edit)
- Workers Routes (Edit)
- Workers Scripts (Edit)
- Zone (Read)
- DNS (Read)

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 (Axiom, Prometheus, Jaeger, etc.)

Quick Installation

Automated Setup

Clone the repository:

git clone https://github.com/arxignis/cf-integration
cd cf-integration

Run the installation script:
```
./install.sh
```
Follow the interactive prompts to configure your settings

Deploy to Cloudflare Workers:

pnpm install
npx wrangler deploy -e production

Manual Configuration

If you prefer manual setup:

Install dependencies:
```
pnpm install
```

Configure wrangler.jsonc with your settings:

{
  "name": "ax-proxy",
  "main": "src/index.ts",
  "compatibility_date": "2025-06-17",
  "workers_dev": false,
  "logpush": false,
  "upload_source_maps": true,
  "compatibility_flags": ["nodejs_compat"],
  "observability": { "enabled": true },
  "kv_namespaces": [
    {
      "binding": "AX_CACHE",
      "id": "<AX_CACHE_ID>"
    }
  ],
  "durable_objects": {
    "bindings": [
      {
        "name": "LOG_BUFFER",
        "class_name": "LogBufferDO"
      },
      {
        "name": "METRICS_BUFFER",
        "class_name": "MetricsBufferDO"
      }
    ]
  },
  "migrations": [
    {
      "tag": "v1",
      "new_classes": ["LogBufferDO", "MetricsBufferDO"]
    }
  ],
  "vars": {
    "MODE": "block",
    "ARXIGNIS_API_KEY": "your-arxignis-api-key",
    "ARXIGNIS_API_URL": "https://api.arxignis.com/v1",
    "TURNSTILE_SITE_KEY": "your-turnstile-site-key",
    "TURNSTILE_SECRET_KEY": "your-turnstile-secret-key",
    "PERFORMANCE_METRICS": "false",
    "PROMETHEUS_URL": "https://your-otel-provider.com/v1/traces",
    "PROMETHEUS_HEADERS": {
      "Authorization": "Bearer YOUR_PROVIDER_TOKEN",
      "X-Custom-Header": "YOUR_CUSTOM_VALUE"
    }
  }
}

Deploy:
```
npx wrangler deploy -e production
```

Configuration

Environment Variables

Variable	Description	Required	Default
`MODE`	Operation mode: `monitor` or `block`	Yes	`block`
`ARXIGNIS_API_KEY`	Your Arxignis API key	Yes	-
`ARXIGNIS_API_URL`	Arxignis API endpoint	Yes	`https://api.arxignis.com/v1`
`TURNSTILE_SITE_KEY`	Cloudflare Turnstile site key	Yes	-
`TURNSTILE_SECRET_KEY`	Cloudflare Turnstile secret key	Yes	-
`PERFORMANCE_METRICS`	Enable metrics: `true` or `false`	No	`false`
`PROMETHEUS_URL`	OpenTelemetry traces endpoint for metrics	No	-
`PROMETHEUS_HEADERS`	Authorization headers for metrics	No	-
`BUFFER_FLUSH_INTERVAL`	Buffer flush interval in milliseconds	No	-
`BUFFER_MAX_RETRIES`	Maximum retry attempts for buffer operations	No	-

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

Turnstile Configuration

The installation script can automatically create Turnstile widgets or use existing ones:

Automatic Creation: Answer "no" when asked about existing Turnstile keys
Manual Configuration: Provide your existing site key and secret key

Caching and Performance

KV Storage: L1 and L2 caching for remediation decisions
Durable Objects: Efficient buffering for logs and metrics
Smart Placement: Cloudflare's intelligent edge placement

DNS Configuration

After deployment, configure your domain's DNS:

Add a CNAME record pointing to your Cloudflare Workers domain
Or use Cloudflare's proxy for additional benefits

Example DNS configuration:

Type: CNAME
Name: @
Target: your-worker.your-subdomain.workers.dev
Proxy: Enabled (recommended)

Monitoring and Analytics

Logs

View detailed logs in Cloudflare Workers dashboard
Real-time request/response analysis
Threat intelligence data logging
Comprehensive request body and header capture

Metrics (Optional)

OpenTelemetry metrics export to any compatible provider
Comprehensive tracing and metrics collection
Custom performance analytics
Real-time dashboard integration

Analytics

Traffic pattern analysis
Threat detection statistics
Performance monitoring
Buffer status monitoring

Architecture

Core Components

Remediation Engine: Threat assessment and decision making with caching
Captcha Handler: Turnstile integration with JWT-based authentication
Log Buffer: Efficient logging with Durable Objects
Metrics Buffer: Performance metrics collection and buffering
Cache System: KV-based caching for improved performance
OpenTelemetry: Comprehensive observability and tracing

Data Flow

Request Reception: Incoming requests are analyzed
Threat Assessment: Arxignis API evaluates the request
Decision Making: Choose between allow, block, or captcha
Response Generation: Generate appropriate response
Metrics Collection: Collect performance and security metrics
Buffering: Efficient log and metrics buffering

Troubleshooting

Common Issues

Installation Failures

Node.js Version: Ensure Node.js 16+ is installed
API Token Permissions: Verify Cloudflare API token has all required permissions
Arxignis API Key: Confirm your API key is valid and active

Turnstile Issues

API Token: Ensure "Challenge Widgets (Edit)" permission is granted
Domain Configuration: Verify domain is properly configured in Cloudflare
Key Validation: Check that site key and secret key match

Deployment Problems

Wrangler Login: Ensure you're logged in: npx wrangler login
Configuration: Verify wrangler.jsonc settings are correct
Account ID: Confirm Cloudflare Account ID is accurate
Use Production Flag: Deploy with npx wrangler deploy -e production

Getting Help

Documentation: Visit docs.arxignis.com
Support: Contact support through the Arxignis platform
Community: Join our Discord community

Security Best Practices

API Key Management

Never commit API keys to version control
Use Cloudflare Workers secrets for sensitive data
Regularly rotate API tokens

Access Control

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

Monitoring

Enable comprehensive logging
Monitor security events in real-time
Set up alerts for critical security events

Development

Local Development

pnpm dev          # Development with live reload
pnpm start        # Basic development server
pnpm test         # Run tests
pnpm cf-typegen   # Generate Cloudflare types

Testing

The client includes comprehensive testing with Vitest:

Unit tests for core functionality
Client tests for API interactions
Cloudflare Workers testing environment

FAQ

Cloudflare WAF has significant limitations including free plan restrictions that severely limit Workers, KV storage, and Durable Objects, strict rate limiting that causes data loss, limited observability with restricted access to detailed traffic information, no full control over security rules and responses, limited data ownership, and expensive scaling costs. Arxignis provides unlimited threat intelligence queries, complete observability with full access to all traffic data, full customization control, complete data ownership, and cost-effective enterprise features.

Clone the repository with `git clone https://github.com/arxignis/cf-integration`, navigate to the directory, run `./install.sh` for automated setup, or manually configure `wrangler.jsonc` and deploy with `npx wrangler deploy -e production`.

Monitor mode analyzes traffic without blocking, perfect for initial deployment and testing. Block mode actively blocks malicious traffic with customizable rules, ideal for production environments.

The client is available for deployment and use, with comprehensive documentation and community support through our Discord channel.

Unlike Cloudflare WAF's strict rate limits that cause data loss, Arxignis provides unlimited threat intelligence queries with no rate limiting, ensuring you never lose critical security data.

Arxignis provides complete observability including OpenTelemetry integration, Durable Objects for efficient buffering, KV storage for caching, comprehensive request logging, and optional metrics export to any OpenTelemetry-compatible provider.

The client uses a two-level caching system with Cloudflare KV storage for L1 and L2 caching of remediation decisions, improving performance and reducing API calls to Arxignis.

Cloudflare Turnstile is a privacy-focused, user-friendly alternative to traditional CAPTHAs. It uses advanced bot detection and only shows challenges when necessary, providing better user experience while maintaining security.

While technically possible, it's not recommended for production use. Cloudflare's Free plan severely limits Workers (50 subrequests/request vs 1000, 3MB Worker size vs 10MB), KV storage (100,000 operations/day), and Durable Objects (5GB total storage vs unlimited, 100 classes vs 500), which can cause the integration to fail under normal traffic loads. For production workloads, a paid Cloudflare plan is strongly recommended.

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.

Overview​

Workers Plan Limits​

Additional Limitations on Free Plan​

Durable Objects Plan Limits​

Key Features​

🛡️ Advanced Threat Intelligence​

📊 Complete Observability​

🔒 Flexible Protection Modes​

🤖 Bot Protection​

📈 Performance Monitoring​

Why Choose Arxignis Over Cloudflare WAF?​

Limitations of Cloudflare WAF/Firewall​

Arxignis Advantages​

Requirements​

System Requirements​

Cloudflare Requirements​

External Services​

Quick Installation​

Automated Setup​

Manual Configuration​

Configuration​

Environment Variables​

Operation Modes​

Monitor Mode​

Block Mode​

Turnstile Configuration​

Caching and Performance​

DNS Configuration​

Monitoring and Analytics​

Logs​

Metrics (Optional)​

Analytics​

Architecture​

Core Components​

Data Flow​

Troubleshooting​

Common Issues​

Installation Failures​

Turnstile Issues​

Deployment Problems​

Getting Help​

Security Best Practices​

API Key Management​

Access Control​

Monitoring​

Development​

Local Development​

Testing​

FAQ​

License​

Contributing​