Cloudflare Sentinel

Pipeline-based security middleware for Cloudflare Workers

Protect your Workers with pluggable detectors, multi-level threat response, and configurable actions. Block SQL injection, XSS, brute force, and more.

✨ Features

• 🔄 Pipeline Architecture - Composable detection → scoring → resolution → handling
• 🛡️ Multi-Level Thresholds - Configurable actions per threat level
• 🔌 Pluggable Everything - Detectors, aggregators, resolvers, handlers
• ⚡ High Performance - Parallel detection, early exit, KV caching
• 🎯 Route-Based Config - Different protection per endpoint
• 💰 Cost-Effective - $0 for most websites

🚀 Quick Start

npm install cloudflare-sentinel

import { 
  SentinelPipeline,
  BlocklistDetector,
  ReputationDetector,
  RateLimitDetector,
  SQLInjectionRequestDetector,
  MaxScoreAggregator,
  MultiLevelResolver,
  LogHandler,
  ActionType,
} from 'cloudflare-sentinel';

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const pipeline = SentinelPipeline.sync([
      new BlocklistDetector({ kv: env.BLOCKLIST_KV }),
      new ReputationDetector({ kv: env.REPUTATION_KV }),
      new RateLimitDetector({ kv: env.RATE_LIMIT_KV, limit: 100, windowSeconds: 60 }),
      new SQLInjectionRequestDetector(),
    ])
      .score(new MaxScoreAggregator())
      .resolve(new MultiLevelResolver({
        levels: [
          { maxScore: 30, actions: [ActionType.LOG] },
          { maxScore: 60, actions: [ActionType.LOG, ActionType.UPDATE_REPUTATION] },
          { maxScore: 100, actions: [ActionType.BLOCK, ActionType.NOTIFY] },
        ],
      }))
      .on(ActionType.LOG, new LogHandler({ console: true }));

    const decision = await pipeline.process(request, { env, ctx });
    
    if (decision.has('block')) {
      return new Response('Blocked', { status: 403 });
    }
    
    return fetch(request);
  },
};

📖 Documentation

• Getting Started - Installation & setup
• Architecture - System design
• Notifications - Slack/email alerts

Component Guides

• Pipeline - Core orchestration
• Detector - Attack detection
• Scoring - Score aggregation
• Resolver - Action resolution
• Handler - Action execution

🎯 Built-in Components

Detectors

Type	Detectors
Security	BlocklistDetector, RateLimitDetector, ReputationDetector
Request	SQLInjectionRequestDetector, XSSRequestDetector, PathTraversalRequestDetector, CommandInjectionDetector, SSRFDetector, NoSQLInjectionDetector, XXEDetector, SSTIDetector, JWTDetector
Response	SQLInjectionResponseDetector, XSSResponseDetector, PathTraversalResponseDetector
Behavior	BruteForceDetector, EntropyDetector, FailureThresholdDetector
ML	MLDetector - Lightweight ML classifier for request pre-filtering

Aggregators

• MaxScoreAggregator - Use highest score (any high-severity = block)
• WeightedAggregator - Weighted average with detector weights

Resolvers

• DefaultResolver - Standard thresholds
• StrictResolver - Aggressive blocking
• LenientResolver - Permissive
• MultiLevelResolver - Configurable cascading actions

Handlers

• LogHandler - Console logging
• NotifyHandler - Webhook notifications (Slack, Discord, etc.)
• BlocklistHandler - Add to KV blocklist
• ReputationHandler - Update IP reputation score
• AnalyticsHandler - Cloudflare Analytics Engine logging

🤖 ML Detector

Lightweight binary classifier for suspicious request detection:

import { MLDetector } from 'cloudflare-sentinel';

const pipeline = SentinelPipeline.async([
  new MLDetector(),  // Uses bundled model (~224KB)
  // ... other detectors
]);

Custom Model Training

cd scripts/training

# 1. Download attack payloads
python3 download_datasets.py

# 2. Generate safe requests
python3 generate_safe_requests.py --count 50000

# 3. Prepare & train
python3 prepare_dataset.py
python3 train_classifier.py --data data/dataset.jsonl --output ../../models/classifier.json

See scripts/training/README.md for details.

📦 Sentinel Proxy Example

Ready-to-deploy security proxy for legacy websites:

cd examples/sentinel-proxy
npm install

# Create KV namespaces
wrangler kv:namespace create BLOCKLIST_KV
wrangler kv:namespace create RATE_LIMIT_KV
wrangler kv:namespace create REPUTATION_KV

# Configure wrangler.toml + sentinel.config.ts
# Deploy
wrangler deploy

See examples/sentinel-proxy/

🤝 Contributing

1. Fork the repo
2. Create feature branch
3. Add tests
4. Submit PR

See CONTRIBUTING.md

📜 License

Cloudflare Only License © 2025 lploc94

See LICENSE for details.

---

Made with ❤️ for Cloudflare Workers