Founding Industrial Partners cohort aperta — un anno di accesso gratuito per le aziende selezionate Candidati entro il 31 maggio →

Ward Quick Start

Deploy bot detection in one command. Zero config, zero cloud, zero rules. Multi-layer defense with neural anomaly detection.

1. Run Ward

Ward is a standalone Docker container. Build it from source in three commands (the prebuilt Docker Hub image is coming soon):

# 1. Get the source git clone https://github.com/luviner/ward.git cd ward # 2. Build the container (default engine: Vivi Focus 4) docker build -t luviner-ward . # 3. Run on port 9741 docker run -d -p 9741:9741 --name ward luviner-ward # Choose a specific engine via env var docker run -d -p 9741:9741 -e WARD_ENGINE=v4 --name ward luviner-ward
Need a license or production support? Contact us for the commercial build with priority updates and SLAs.

Ward starts in learning mode automatically. No configuration needed.

2. How it works

  1. Learning phase: Ward observes the first 500 requests and builds a behavioral model of normal human traffic. All requests are allowed during this phase.
  2. Training: After 500 requests, Ward auto-trains in the background (~2-5 seconds). Requests continue to be allowed.
  3. Detecting: Once trained, every request goes through multi-layer defense: rate limiting, burst detection, neural anomaly scoring, and session-level verdict aggregation.
Ward uses 5 defense layers: rate limiting, burst detection, neural anomaly scoring (18 behavioral features), session aggregation, and sticky blocking. No bot signatures, no rules to maintain.

3. Integrate with your app

Add a middleware to your web app that calls Ward's /check endpoint before processing each request:

// Express.js example app.use(async (req, res, next) => { const r = await fetch('http://ward:9741/check', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ session_id: req.cookies.session_id || req.ip, method: req.method, path: req.path, query_params: Object.keys(req.query).length, headers: req.headers, content_length: parseInt(req.headers['content-length'] || '0'), }) }); const verdict = await r.json(); if (verdict.action === 'block') return res.status(403).send('Blocked'); next(); });

4. API Reference

EndpointMethodDescription
/checkPOSTClassify a request. Returns action, score, is_bot, reason.
/trainPOSTUpload CSV of known-good traffic to train explicitly.
/healthGETHealth check with phase, engine, and session count.
/statsGETOperational statistics, config, and last training result.
/metricsGETPrometheus-compatible metrics for monitoring.
/sessionsGETList active sessions with per-session stats. Supports ?sort=score|rpm.
/resetPOSTReset model and return to learning mode.

POST /check — Request body

{ "session_id": "visitor-123", // required (max 256 chars) "method": "GET", // HTTP method "path": "/products/shoes", // URL path "headers": { // HTTP headers "User-Agent": "Mozilla/5.0...", "Referer": "https://example.com", "Cookie": "session=abc123", "Accept-Language": "en-US,en;q=0.9" }, "content_length": 0, // optional "query_params": 3, // optional "timestamp": 1711612800.0 // optional (defaults to now) }

Response

{ "action": "block", // "allow" or "block" "score": 0.8742, // anomaly score (higher = more suspicious) "is_bot": true, // boolean verdict "reason": "rate_limit_exceeded", // why blocked (or "allowed") "session_requests": 42, // requests in this session "session_anomalies": 15, // anomalous requests "session_avg_score": 0.6234, // rolling average score "session_rpm": 312.0, // requests per minute "latency_ms": 0.21, // processing time "phase": "detecting" // learning | training | detecting }

5. Configuration

Ward is configured via environment variables. All have sensible defaults:

VariableDefaultDescription
WARD_ENGINEfocusNeural engine (all 13 Luviner engines supported)
WARD_N_HIDDEN48Neurons per layer (smaller = faster)
WARD_N_LAYERS1Number of neural layers
WARD_LEARNING_SAMPLES500Requests collected before auto-training
WARD_TRAINING_EPOCHS50Training epochs
WARD_RATE_LIMIT_RPM120Rate limit (requests/minute per session)
WARD_BURST_MAX10Max requests in burst window
WARD_BURST_WINDOW2.0Burst detection window (seconds)
WARD_SESSION_TTL1800Session timeout in seconds (30 min)
WARD_MAX_SESSIONS100000Max concurrent sessions
WARD_LOG_LEVELINFOLogging level (DEBUG, INFO, WARNING)
WARD_PORT9741Server port

6. Detection Layers

Ward uses 5 defense layers for maximum accuracy:

  1. Rate limiting — blocks sessions exceeding RPM threshold
  2. Burst detection — blocks rapid-fire request bursts
  3. Neural anomaly detection — 18 behavioral features analyzed by liquid neural network
  4. Session aggregation — rolling anomaly rate + average score for session-level verdict
  5. Sticky blocking — once blocked, a session stays blocked

7. Performance

MetricValue
Bot detection rate100%
False positive rate0%
F1 Score1.00
Average latency0.23ms
P99 latency0.60ms
Behavioral features18
Bot profiles tested5 (scraper, headless, credential stuffer, API abuser, slow bot)
Memory per session~1KB

8. Monitoring

Ward exposes a Prometheus-compatible /metrics endpoint for integration with Grafana, Datadog, or any metrics platform:

curl http://localhost:9741/metrics # Output: ward_requests_total 12345 ward_bots_detected_total 42 ward_bot_rate 0.0034 ward_active_sessions 156 ward_avg_latency_ms 0.23

9. Dashboard

Ward includes a built-in dashboard in the Luviner SaaS platform. After logging in, navigate to Ward in the navigation bar to see real-time stats, active sessions, and detection metrics.

Need help? Contact us for integration support or a custom deployment.