Varnish

Bot protection for Varnish Cache 6.0 LTS using a VCL config and a small helper VMOD.

Overview

Centinel integrates with Varnish through VCL. Protected requests are routed to the Centinel validator as a normal Varnish backend fetch, so Varnish's backend connection pool keeps the connection warm. The decision comes back in x-centinel-* response headers, so VCL never parses JSON. A small helper module (libvmod_centinel) base64-decodes the block or challenge page for synth delivery and appends the validator's Set-Cookie without overwriting cookies from your origin. Requests are blocked, challenged, or restarted to your origin based on the decision.

If the validator is unreachable, times out, or returns an error, requests fail open to your origin.

Backend TLS required

Open-source Varnish has no native backend TLS, and the validator is HTTPS. You must run a small local TLS proxy (stunnel, hitch, or HAProxy) in front of validator.centinelanalytica.com and point the validator backend at it over plain HTTP on localhost. The install steps include an stunnel example. Varnish Enterprise users can use a native TLS backend and skip the proxy.

Prerequisites

Secret key from your dashboard
Varnish Cache 6.0 LTS (open source) or Varnish Enterprise 6, plus the matching varnish-dev headers
Build tools: autoconf, automake, libtool, pkg-config, python3-docutils
A TLS proxy (e.g. stunnel) for the HTTPS validator
A configured origin backend

Install

Download and extract the package

Download centinel-varnish.zip and extract it:

curl -O https://docs.centinelanalytica.com/downloads/centinel-varnish.zip
unzip centinel-varnish.zip -d centinel-varnish/
cd centinel-varnish/

The zip contains:

centinel.vcl — the VCL config template
src/ — the libvmod_centinel VMOD source (base64 decoding for block pages)
autogen.sh, configure.ac, Makefile.am — autotools build files

Build and install the VMOD

Install the build dependencies (Debian/Ubuntu example), then build:

sudo apt-get install -y varnish varnish-dev \
  build-essential automake autoconf libtool pkg-config python3-docutils

sh autogen.sh
./configure --disable-dependency-tracking
make
sudo make install

make install puts libvmod_centinel.so into Varnish's vmod directory.

Why --disable-dependency-tracking

The module includes the vmodtool-generated header, which doesn't exist when configure's dependency bootstrap runs. The flag defers that to the build step.

Run a TLS proxy to the validator

Open-source Varnish can't speak TLS to a backend. Point a local proxy at the HTTPS validator:

# /etc/stunnel/centinel.conf
foreground = no

[centinel]
client  = yes
accept  = 127.0.0.1:8443
connect = validator.centinelanalytica.com:443
sni     = validator.centinelanalytica.com

stunnel /etc/stunnel/centinel.conf

Configure centinel.vcl

Edit the bundled centinel.vcl:

Point the origin backend at your app.
Point the validator backend at the TLS proxy (127.0.0.1:8443).
Set your secret key in vcl_backend_fetch (set bereq.http.X-API-Key = "...";).

backend origin    { .host = "127.0.0.1"; .port = "8080"; }
backend validator { .host = "127.0.0.1"; .port = "8443"; .max_connections = 200; }

Load it

varnishd -f /etc/varnish/centinel.vcl -a :80 -s malloc,256m -p workspace_client=256k

Or on a running instance:

varnishadm vcl.load centinel /etc/varnish/centinel.vcl && varnishadm vcl.use centinel

Configure

How it works

On every request, the VCL:

Bypasses static assets (configurable regex in vcl_recv) and lets Varnish cache them normally.
Reads the decision from x-centinel-* response headers. centinel.b64decode() decodes the block or challenge page.
Applies the decision:
- allow / not_matched — restart to your origin
- block — 403 plus the block page
- redirect — 200 plus the verification page
Forwards the validator's Set-Cookie and a whitelisted set of response headers (Content-Type, Cache-Control, X-Content-Type-Options, X-Frame-Options, Content-Security-Policy, Referrer-Policy).

Configuration reference

Setting	Where	Default
Secret key	`vcl_backend_fetch` → `X-API-Key`	— (required)
Origin backend	`backend origin`	your app
Validator backend	`backend validator`	TLS proxy → validator
Protected paths	`vcl_recv` static-asset regex	static assets bypass
Block/challenge page	from the validator (`x-centinel-response-html-b64`)	served via `synth`

Changelog

v1.0.0 — Initial release