# Introduction

> How to deploy Centinel Analytica on your site and customize protection settings.

Source: https://docs.centinelanalytica.com/

## Before you begin

* Create your account in the [Centinel Analytica dashboard](https://dash.centinelanalytica.com).
* You'll need:
  * your **site key** (public, used by the browser script)
  * your **secret key** (server-only, used for `/validate`)

## How it works

Centinel has three parts:

* **Server validation** (required): your backend, or a platform integration, calls the validation API for each protected request and acts on the decision (`allow`, `block`, or `redirect`). The validator issues the `_centinel` session cookie, and your response sets it.
* **Policy rules**: rules select bot detection and actions for matching requests. The dashboard's default rule enforces nothing, because the validator skips it. Add and verify an explicit matching rule before you rely on a policy action.
* **Browser script** (optional): collects browser and network signals that server-side data alone cannot see, and mirrors the `_centinel` cookie. Detection works without it, with a smaller signal set.

## Next steps

1. Copy your keys from the dashboard. Review the default policy. Add and order path-specific rules where you need different behavior.

   Go to: [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md) and [Policy Rules](https://docs.centinelanalytica.com/admin/policy.md)

2. Wire up validation: use a platform integration, or call `/validate` from your backend.

   Go to: [Platform integrations](https://docs.centinelanalytica.com/platforms.md) or [Validation](https://docs.centinelanalytica.com/install/validation.md)

3. Add the browser script for stronger detection on pages visitors load.

   Go to: [Scripts](https://docs.centinelanalytica.com/install/scripts.md)

New to the decisions and block reasons in the dashboard? The [Glossary](https://docs.centinelanalytica.com/concepts/glossary.md)
defines them.

## Getting help

Contact support with:

* the URL you're protecting
* a sample `/validate` request payload (redact secrets)
* the decision you received and any `crawler` metadata (if enabled)

---

# Interstitial Challenge

> How Centinel verifies uncertain visitors with a brief in-browser challenge before granting access.

Source: https://docs.centinelanalytica.com/concepts/interstitial-challenge

## Overview

The interstitial is for traffic the validator cannot confidently allow or block from request data alone. It gives an uncertain visitor a way to prove that they are human.

When `/validate` returns `decision: "redirect"` with a Centinel interstitial, your backend must serve the returned HTML. If you use a platform integration, verify that it applies the validator's `status_code`, `headers`, and `cookies`. The page runs a challenge in the visitor's browser. If the visitor clears it, they can continue to the protected content. If not, the session remains unverified.

A `redirect` does not always mean an interstitial. A custom block page can also use that decision. Do not infer challenge intent from `decision` alone. Serve the response HTML and status that the validator returns.

On rare occasions a `redirect` arrives with no `response_html` at all, because rendering or session encryption failed. Deny those requests rather than passing them through: the validator picked that visitor for a challenge, so an allow hands them the protected content.

## What a visitor sees

By default, a blank page titled "Please wait" with nothing to read and nothing to do. The
challenge is entirely non-interactive: there is no CAPTCHA and no puzzle. When it finishes, the
browser reloads the same URL and your backend serves the real content. You can author your own
challenge page in the dashboard and select it per policy rule.

### If the challenge can't run

Two screens can appear. While the browser is retrying a failed upload, the visitor sees **Still
verifying** with a spinner and "We're having trouble reaching our servers. Retrying
automatically." After the retry budget is spent, or when session storage is unavailable, they see
**Still unable to verify** with "We couldn't verify your connection after several attempts. Please
refresh the page or try again in a few minutes." and a reference code for support.

There is no fallback for clients that never run JavaScript. They keep receiving the interstitial
with whatever status your backend applies, which is why serving it with a 200 is a mistake.

## End-to-end flow

```mermaid
sequenceDiagram
    participant B as Browser
    participant A as Your backend
    participant C as Centinel

    B->>A: GET protected page
    A->>C: POST /validate
    C-->>A: Serve interstitial
    A-->>B: Execute script
    B->>C: Send telemetry
    B->>A: Reload page in client
    A->>C: POST /validate
    C-->>A: Allow or block
    A-->>B: Enforce decision
```

1. The visitor requests a protected URL. Your backend calls `POST /validate`.

2. The validator cannot confidently allow or block from request data alone. For an interstitial, it returns `decision: "redirect"` with base64 HTML in `response_html`.

3. Your backend returns the decoded interstitial HTML with `status_code` as the HTTP status, which is 403 by default. Apply the returned `cookies` and `headers` as well. The `Content-Security-Policy` header carries the nonce the challenge script needs, so dropping it stops the challenge from running.

4. The browser renders the interstitial and runs Centinel's challenge logic. The visitor does nothing.

5. Centinel runs the full validation pipeline after completion. The signals and fatal signals determine the result. A failed upload or retry can leave the session unverified.

6. The script reloads the same URL. Centinel never returns a redirect target, and `redirect_url` is never populated.

## See also

* [Validation API](https://docs.centinelanalytica.com/api/validation.md): Where the \`redirect\` decision originates.
* [Wire the validation API](https://docs.centinelanalytica.com/install/validation.md): Backend handling for redirect (and other decisions).
* [Scripts](https://docs.centinelanalytica.com/install/scripts.md): The browser collector script and the signals it adds.
* [Preserve the Referrer](https://docs.centinelanalytica.com/install/preserve-referrer.md): Keep the original traffic source across the interstitial reload.

---

# Glossary

> Plain-English definitions for the terms you'll see in the dashboard, decisions, and block reasons.

Source: https://docs.centinelanalytica.com/concepts/glossary

Terms used in the dashboard and in `/validate` responses. Linked pages cover anything that needs more than a paragraph.

## Decisions

### Allow

An `allow` normally lets your backend serve the original content. It can also contain validator-owned
`response_html`, such as managed `robots.txt`. In that case, serve the returned body, status, and
headers.

A request with no policy action continues to configured bot detection. When monitor mode applies,
a would-be block returns as `allow` with `block_reasons`. A `redirect` remains a `redirect`.

### Block

The validator denied the request. Serve Centinel's block page from `response_html` with the
returned `status_code`, which is 403 unless a policy rule or a tenant setting changed it.

### Redirect

The validator can't decide from request data alone, so it returns an [interstitial challenge](https://docs.centinelanalytica.com/concepts/interstitial-challenge.md). Serve `response_html` with the returned `status_code`, which is 403 by default. The browser runs the challenge and the next request continues. The dashboard labels this decision **Challenged**.

A `redirect` does not always mean a challenge. If you have configured a custom block page, a real
block arrives as `redirect` carrying that page. Read `status_code` rather than inferring intent
from the decision string.

### Monitor

A rule setting, shown in the dashboard as **Detect & log only**. `monitor: true` applies to the
whole request. Terminal blocks return as `allow`, but challenges still return as `redirect`.
`monitor: false` does not disable monitor mode. See [Policy Rules](https://docs.centinelanalytica.com/admin/policy.md#what-monitor-really-covers).

### Rate limit

A rule setting that caps requests per scope. Over-budget requests are blocked with a
`rate_limit_exceeded` reason and a `retry_after` value, delivered in-band on a 200 rather than as
an HTTP 429.

## Visitors

### Crawler (identified)

Request's User-Agent matches a known crawler signature, like Googlebot or GPTBot. Identification alone does not prove the request really came from that crawler. See the [crawler object](https://docs.centinelanalytica.com/api/crawlers.md) for the full schema.

### Crawler (verified)

An identified crawler whose source IP falls inside the operator's published IP ranges, which
Centinel ingests and refreshes. A crawler whose operator publishes no ranges can only ever be
identified by name, never verified.

### Crawler (allowed)

A crawler you've placed on your allowlist. It passes through without scoring. The allowlist is a built-in [policy rule](https://docs.centinelanalytica.com/admin/policy.md#crawler-allowlist-priority) that runs last, so any rule you write can override it. An identified crawler that is not on your allowlist is blocked by a matching built-in rule.

### Stealth crawler

A bot that tries to look like an ordinary browser. The validator catches it by collecting browser signals and spotting inconsistencies. For real browsers controlled by automation tools (Selenium, Playwright, Puppeteer), see [Automated browser](#automated-browser).

## How a check works

### Challenge

A short, non-interactive test that the browser runs in the background. There is no CAPTCHA and nothing for the visitor to solve. After it completes, Centinel runs the full validation pipeline. A failed or absent upload can leave the session unverified.

### Interstitial

The HTML page Centinel returns for a challenge. The browser runs the challenge and reloads the same URL. A custom block page can also use `decision: "redirect"`, so do not identify an interstitial from the decision alone. See [Interstitial Challenge](https://docs.centinelanalytica.com/concepts/interstitial-challenge.md).

### Session

A run of requests associated with the same `_centinel` cookie. While the server-side session and cached verdict remain available, later validations reuse that verdict. If either item is missing or expired, Centinel can evaluate and challenge the visitor again.

### Fingerprint

A composite signature of how the browser behaves at the network and JavaScript level. The validator compares it against what the User-Agent claims.

## Block-reason categories

### Header anomaly

HTTP headers are missing, contradictory, or shaped like a script rather than a browser. Real browsers send a consistent set of headers; bots and minimal HTTP libraries often don't.

### Fingerprint mismatch

The request doesn't match what its User-Agent claims. This covers the TLS, TCP, and HTTP/2 layers, header order and client hints, and disagreements between the page and a Web Worker. For example, a request says it's Chrome but the network signature looks like Python or Go.

### Bot identity

The request's User-Agent identifies it as a known bot or scraper HTTP client (such as `python-requests` or `curl`), and is not on your allowlist. An identified crawler that isn't on your allowlist also lands here, as `crawler_blocked`. See [Crawler (allowed)](#crawler-allowed). Browser-automation frameworks like Selenium or Puppeteer fall under [Automated browser](#automated-browser) instead.

### Automated browser

A real Chrome or Firefox driven by Selenium, Playwright, Puppeteer, or a similar tool. They run JavaScript fine, but leave traces in the browser environment that the validator picks up.

### Crawler impersonator

A request claims to be a well-known crawler like Googlebot, but its IP doesn't belong to that crawler's operator. Common in scrapers trying to bypass crawler-allow rules.

### Suspicious network

Traffic came from a network type associated with abuse. Common sub-types you'll see in analytics:

* **VPN** — commercial VPN service. Legitimate users do use VPNs, so this is a signal weighed with the others, not an automatic block.
* **Datacenter (DC)** — IP belongs to a cloud or hosting provider. Most consumer traffic doesn't originate from datacenters; bots often do.
* **Proxy** — open or commercial HTTP proxy. Frequently used to mask the origin of automated traffic.
* **Tor** — a Tor exit node. Anonymity network with mixed legitimate and abusive use.
* **IP reputation** — the address is a known anonymizer, hosting range, abuser, or is blacklisted.
* **Rate limit** — the request exceeded a rate-limit rule. Filed here even though it isn't a network signal.

### Challenge failure

The session got an interstitial and never cleared it. Several things produce this: the challenge failed, the verification was invalid, or the visitor abandoned the page. There are timeout and payload variants too.

One case is on your side. If your backend serves the interstitial but drops the `cookies` from the
`/validate` response, the challenge cannot be won and the request fails closed with
`interstitial_no_session`.

### Unknown

A block reason Centinel hasn't grouped into a category yet. Rare. Read the raw `block_reasons`
value to see what actually fired.

## See also

* [Interstitial Challenge](https://docs.centinelanalytica.com/concepts/interstitial-challenge.md): How redirect decisions are enforced and what visitors see.
* [Validation API](https://docs.centinelanalytica.com/api/validation.md): POST /validate endpoint spec: schemas, decisions, errors.
* [Policy Rules](https://docs.centinelanalytica.com/admin/policy.md): Allow, block, rate-limit, or scrutinize requests with custom rules.

---

# Dashboard

> Find your keys, and see what a /validate response can include.

Source: https://docs.centinelanalytica.com/install/dashboard

## What you'll do here

1. Find and copy your integration keys (site key + secret key). Centinel normally generates both when it creates your organisation; check the Organisation page and regenerate either key if it is missing.

2. Review your policy rules. Add and order path-specific rules where you need different behavior. See [Policy Rules](https://docs.centinelanalytica.com/admin/policy.md).

> **Warning:** Keys authenticate `/validate`; they do not enforce traffic. Before relying on blocks, add and
> verify a matching policy rule. Then have your backend or platform integration act on the
> `/validate` response.

The dashboard opens on **Insights**. **Analytics** has an endpoint tree showing which paths
actually receive traffic, which is the quickest way to decide what to protect first. **Crawlers**
holds the allowlist. Source-IP verification and allowlist membership determine `access_allowed`.
**Threats** shows what Centinel blocked and why. Press `⌘``K` (or
`Ctrl``K`) to jump to any of them.

## API keys

Centinel issues two kinds of key, on two different pages under **Organisation**.

### Integration keys

On the [Organisation](https://dash.centinelanalytica.com/organisation) page, under **Integration
keys**:

* **Site key (public)**: used in the browser script URL. Safe to expose.
* **Secret key (sensitive)**: used as `x-api-key` when your backend calls `/validate`. Keep this server-side only—store it in environment variables or a secret manager.

> **Never expose the secret key:** The `x-api-key` is server-only. Don't put it in client-side code, HTML, or public repositories.

### Analytics keys

The **API keys** page at
[Organisation → API keys](https://dash.centinelanalytica.com/organisation/tokens) issues the
`sk_api_ro_` keys that the [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md) and the
[MCP server](https://docs.centinelanalytica.com/api/mcp.md) accept as a bearer token. These are separate from your integration keys
and cannot call `/validate`. Create one key per integration so you can revoke it on its own.

## Crawler metadata

`/validate` responses can carry a `crawler` object identifying which crawler made the request. It
holds `id`, `name`, and `access_allowed`, plus `category` and `rsl_category` when the catalog entry
resolves. See [Crawlers](https://docs.centinelanalytica.com/api/crawlers.md) for the full schema.

`/validate` includes this object only when the `validate_response_include_crawler` feature flag is
enabled for your organisation. Crawler detection is always active, and you manage the allowlist on
the **Crawlers** page either way.

Once you have both integration keys, continue to:

* [Add scripts](https://docs.centinelanalytica.com/install/scripts.md): Install the browser script using your site key, and make sure it loads wherever protected actions can be triggered.
* [Validate requests](https://docs.centinelanalytica.com/install/validation.md): Call /validate from your backend using your secret key, then enforce the returned decision.

---

# Scripts

> Optional browser script that adds browser-side signals and establishes a session up front.

Source: https://docs.centinelanalytica.com/install/scripts

## Overview

The Centinel collector script is an **optional** addition to your site. It runs in the browser, sets the `_centinel` cookie, and feeds browser-side signals back to the validator.

Server-only validation works without it, on a smaller signal set. The script adds the browser and network signals that no amount of server-side data can reveal, which is what catches automation driving a real browser. The `_centinel` cookie it sets gives the validator a session key before the first challenge.

The interstitial challenge does not need this script. The validator injects its own copy into the
interstitial it serves, so challenges work on a server-only install too.

## Add the script

Drop this in your page `<head>` and replace `SITE_KEY` with your site key (from the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md)).

```html
<html>
  <head>
    <script src="https://collector.centinelanalytica.com/script.js?site_key=SITE_KEY" defer></script>
    <!-- Rest of the head -->
  </head>
  <body>
    <!-- Page content -->
  </body>
</html>
```

Keep the `defer`. Several signals read the DOM, so a script that runs before `<body>` exists
collects less and weakens detection. `defer` also keeps the parser from blocking on the download.

## Where to install it

Add the script to any page where a protected action can be triggered:

* Login forms (or any page hosting a login modal)
* Signup and password-reset flows
* Checkout and payment pages
* Gated content: premium articles, paid downloads, members-only areas
* Comment, review, and other user-generated-content submission

> **Single-page apps:** Install the script once in the global layout, not per route, to avoid double-loading. It collects once per full document load and deliberately does not hook client-side navigation, so a route change does not re-run collection. That is fine: the session it established on first load carries across routes.

## Verify

Load a page and check three things in your browser's dev tools:

* The request to `collector.centinelanalytica.com/script.js` returns `200`. A `401` means the `site_key` is missing or wrong, and no signals are collected.
* A `POST` to the collector origin carries the payload.
* A first-party `_centinel` cookie is set.

In code, check `window.cen.initialized` to confirm the script finished. If it is not ready yet, wait
for the `CentinelInitialized` event.

> **Warning:** The event fires only after the payload upload succeeds, and a failed upload is not retried. Always
> pair the wait with a timeout, or a visitor on a flaky network can never complete the action you
> gated behind it.

```javascript
function whenCentinelReady(cb, timeoutMs = 2000) {
  if (window.cen && window.cen.initialized) {
    cb();
    return;
  }

  let done = false;
  const run = () => {
    if (done) return;
    done = true;
    window.removeEventListener('CentinelInitialized', run);
    cb();
  };

  window.addEventListener('CentinelInitialized', run);
  setTimeout(run, timeoutMs); // never block the action on the script
}

whenCentinelReady(() => {
  login();
});
```

## Next steps

Whether you added the script or chose to skip it, your backend needs to call `/validate` on every protected request.

* [Validation](https://docs.centinelanalytica.com/install/validation.md): Wire the /validate API into your backend.

---

# Validation

> Wire the /validate API into your backend when no platform integration covers your stack.

Source: https://docs.centinelanalytica.com/install/validation

## Overview

If a [platform integration](https://docs.centinelanalytica.com/platforms.md) covers your stack, use it. This page is for custom backends and platforms not yet supported. You will call `POST /validate` for every protected request and act on the response.

A `block` or `allow` can come straight from a [policy rule](https://docs.centinelanalytica.com/admin/policy.md), including the crawler allowlist, before any bot scoring runs. Either way, your backend handles the decision the same.

## When to call /validate

* On the server, after you have parsed the request.
* Once per request, before your application handles it.
* Skip locally for paths you do not want to protect. The validator returns `allow` for those anyway, but skipping saves a round trip.

Send the request to `POST https://validator.centinelanalytica.com/validate` with
`content-type: application/json` and your secret key in the `x-api-key` header. Only `url` and
`ip` are required. `ip` must be a single parseable IP address, and `cookie` must be the bare
`_centinel` UUID rather than the whole `Cookie` header.

Use a timeout of 300ms to 500ms. The validator's own budget is 500ms, so a longer client
timeout turns a slow validator into a stall your visitors feel.

## Handle each decision

1. Call `POST /validate` with the request URL, method, client IP, all headers, and the `_centinel` cookie.

2. Apply every entry from `response.headers` to your outgoing response, and every entry from `response.cookies` as a Set-Cookie.

3. Send `response.status_code` as the HTTP status, falling back to `403` if it is missing.

4. For `block` or `redirect`, base64-decode `response.response_html` and return it as the response body.

5. For `allow`, return validator-owned HTML when `response_html` is present. Otherwise, pass the request to your application.

### Failing safely

> **Warning:** Fail open on a 5xx or a transport error, and fail closed on a 4xx. A 400, 401, or 409 is a
> deterministic rejection, not an outage. Treating one as a reason to allow the request is how
> bots get through: a crafted `ip` value makes the validator answer 400, so a backend that
> allows on 400 hands every attacker a bypass.

Do not infer challenge intent from the decision string alone. A custom block page can arrive as `decision: "redirect"`. Serve the response HTML and status that the validator returns.

```ts
type ValidateDecision = 'allow' | 'block' | 'redirect';

async function enforce(req, res, next) {
  let result;
  try {
    result = await callValidate({
      url: req.url,
      method: req.method,
      ip: clientIpFrom(req),
      referrer: req.headers.referer,
      cookie: req.cookies['_centinel'],
      headers: req.headers,
    }); // 300-500ms timeout
  } catch {
    return next(); // transport error or timeout: fail open
  }

  if (result.status >= 500) return next(); // validator outage: fail open
  if (result.status >= 400) return res.status(403).send('Forbidden'); // rejected: fail closed
  if (result.body.success === false) return next();

  const data = result.body;
  for (const [name, value] of Object.entries(data.headers ?? {})) res.setHeader(name, value);
  for (const c of data.cookies ?? []) {
    res.cookie(c.name, c.value, {
      path: c.path,
      domain: c.domain || undefined,
      secure: c.secure,
      sameSite: c.same_site,
      maxAge: c.max_age * 1000,
    });
  }
  if (data.rate_limited) res.setHeader('Retry-After', String(data.retry_after));

  const status = data.status_code || 403;
  const html = data.response_html
    ? Buffer.from(data.response_html, 'base64').toString('utf8')
    : null;

  if (data.decision === 'allow' && html !== null) {
    return res.status(status).send(html); // validator-owned response, such as robots.txt
  }

  switch (data.decision) {
    case 'allow':
      return next();
    case 'block':
    case 'redirect':
      // Missing HTML can result from a rendering or session-encryption failure.
      return res.status(status).send(html ?? 'Access Denied');
    default:
      return res.status(403).send('Access Denied');
  }
}
```

Preserve every cookie attribute the validator sends. Dropping `max_age` demotes `_centinel` to
a session cookie, which breaks continuity across the interstitial challenge.

## Decoding `response_html`

Both `block` and `redirect` carry `response_html` as base64-encoded UTF-8. Decode and return it as
the body, with `response.status_code` as the HTTP status. That field defaults to `403` for both
decisions, and a policy rule or a tenant setting can change it to any of `200`, `302`, `401`,
`403`, `404`, `418`, `429`, `451`, `460`, or `503`. Hardcoding a status throws away whatever was
configured in the dashboard.

A `redirect` can also arrive with no `response_html` at all, which happens when interstitial
rendering or session encryption failed. Deny those requests with `status_code` and a short body of
your own. The validator picked that visitor for a challenge, so an allow hands them the protected
content. The shipped gateway integration substitutes a block page whenever the HTML is missing.

```js
// Node.js
const html = Buffer.from(response.response_html, 'base64').toString('utf8');
```

```js
// Web platforms (Cloudflare Workers, Deno, browsers)
const html = new TextDecoder().decode(
  Uint8Array.from(atob(response.response_html), c => c.charCodeAt(0))
);
```

## Applying headers

A response can carry a `headers` object on any decision. Set each entry on your outgoing response. A `block` can contain `Content-Type`, `X-Content-Type-Options`, and `X-Frame-Options`. An interstitial can contain `Content-Type`, `X-Content-Type-Options`, and a `Content-Security-Policy` whose nonce the challenge script needs. An `allow` can carry a validator-owned response, such as managed `robots.txt`, with its own headers. Always guard for a missing `headers` key.

```js
// Express
for (const [name, value] of Object.entries(response.headers ?? {})) {
  res.setHeader(name, value);
}
```

```js
// Cloudflare Worker
const headers = new Headers();
for (const [name, value] of Object.entries(response.headers ?? {})) {
  headers.set(name, value);
}
return new Response(body, { status, headers });
```

## Common pitfalls

* **Failing open on a 4xx.** A 400, 401, or 409 means the validator rejected your request, not that it is down. Allowing those requests opens a bypass.
* **Calling `/validate` from the browser.** The `x-api-key` is server-only. Anyone with the key has full tenant access.
* **Hardcoding the HTTP status.** Send `response.status_code`. Hardcoding `200` on `redirect` answers real blocks with a success status, which caches may then store.
* **Assuming `headers` is always present.** It can be absent on any decision. Reading it without a guard can throw.
* **Trusting `X-Forwarded-For` blindly.** Pass the real client IP, but take it from a hop you control. The header is attacker-controlled, and a non-IP value makes the validator answer 400.
* **Ignoring `cookies` on `allow`.** The `cookies` array can be non-empty on any decision (session cookies on a happy-path response, challenge cookies on `redirect`). Apply them all, with their attributes.
* **Dropping the `_centinel` cookie.** Without it, session tracking across interstitial challenges fails, and the visitor is challenged again on every request.
* **Expecting an HTTP 429.** Rate limits arrive in-band as a 200 with `rate_limited` and `retry_after` in the body. `/validate` never answers 429.

## See also

* [Validation API reference](https://docs.centinelanalytica.com/api/validation.md): POST /validate endpoint spec: schemas, decisions, errors.
* [Platform integrations](https://docs.centinelanalytica.com/platforms.md): Drop-in modules for Cloudflare, Fastly, Nginx, Next.js, and more.
* [Policy Rules](https://docs.centinelanalytica.com/admin/policy.md): Allow, block, rate-limit, or watch requests, and set the crawler allowlist priority.

---

# Preserve the Referrer

> Carry the original visitor source across the interstitial so your analytics still sees where traffic came from.

Source: https://docs.centinelanalytica.com/install/preserve-referrer

## Overview

When an uncertain visitor passes through the [interstitial challenge](https://docs.centinelanalytica.com/concepts/interstitial-challenge.md), the browser reloads into your protected page. That reload erases the original referrer, so analytics on the page attributes the visit to your own site instead of the real source (Google, a newsletter, a partner link).

Centinel preserves the original source in a session-scoped value named `_centinel_ref`, kept in the browser's `sessionStorage`. This page explains why the loss happens and how to hand the saved value to your analytics.

## Why the referrer is lost

The interstitial is a real page load. To send the visitor on to your content, it calls `location.reload()`. A reload (like a redirect) does not carry the previous page's referrer forward: after it, both `document.referrer` and the `Referer` request header become the interstitial's own URL. The visit looks like a self-referral from your own domain.

JavaScript cannot fix this on its own. `document.referrer` is read-only, and `Referer` is a [forbidden header](https://developer.mozilla.org/en-US/docs/Glossary/Forbidden_request_header) that scripts may not set on a top-level navigation. The only document that still holds the true upstream referrer is the interstitial itself, before it reloads.

## The `_centinel_ref` value

While it is still running, the collector script the interstitial loads captures the upstream referrer and writes it to `sessionStorage` so it survives the reload. `sessionStorage` is scoped to the tab and origin, so the value is there when your page loads but never travels to your server the way a cookie would.

The entry is keyed `_centinel_ref`. Four properties decide how you read it:

* **Origin only.** The entry holds the referrer's origin (`https://www.google.com`), never the full path or query. That is all an analytics tool needs for source attribution, and it stays free of personal data regardless of the referring site's `Referrer-Policy`.
* **Cross-origin only.** It is written only when the visitor arrived from a different origin. A same-origin visit leaves nothing behind, so your own URL is never stored as a source.
* **Readable on one origin.** Only the origin that served the interstitial can read the entry, so a page on `www.example.com` will not find a value written on `example.com`.
* **Cleared on every run.** Each interstitial run removes the entry before deciding whether to store a fresh one. A second interstitial in the same tab therefore discards an origin saved earlier, so read the value on the first page view after the challenge.

> **Warning:** The value is absent when there was no cross-origin referrer. Always treat it as optional: if it is missing, fall back to the browser's normal behavior.

## Restore the referrer

One snippet covers every tool. Most trackers read `document.referrer` themselves and give you no way to override it, so instead of wiring each one, redefine `document.referrer` before any of them loads.

```html
<script>
(function () {
  try {
    var ref = sessionStorage.getItem('_centinel_ref');
    if (!ref) return;
    sessionStorage.removeItem('_centinel_ref');
    Object.defineProperty(document, 'referrer', {
      get: function () { return ref; },
      configurable: true
    });
  } catch (e) {}
})();
</script>
```

`document.referrer` is a getter on `Document.prototype`. Defining an own property on `document` shadows that getter for the rest of the page view, so anything reading the referrer gets the original source instead of your own URL.

Nothing else changes. With no stored value the snippet returns early and every tool sees the browser's own referrer, exactly as it would without this code. That is what makes it safe on the page views that never meet an interstitial, and in browsers that block `sessionStorage`.

> **Warning:** Placement decides whether this works. The snippet has to run before your tag manager and before every analytics loader in `<head>`. A tracker that has already read the referrer keeps the old value.

If your tags live in Google Tag Manager, the snippet can go in a Custom HTML tag on the **Initialization - All Pages** trigger, which runs before the container's other tags. That orders only what GTM fires. A tracker installed as its own `<script>` in the page, as Chartbeat often is, still needs the snippet above it in the markup.

The patch applies to scripts on the page, nothing else. The HTTP `Referer` header still carries the interstitial URL, so CDN logs and server-side tagging are unaffected. Reporting fed by a server-side export never sees `sessionStorage` either: forward the origin yourself as a field on an event your page already posts to that pipeline.

## When you cannot control load order

A consent manager or a CMS that injects analytics ahead of your own markup leaves nowhere to put the snippet first. Where the tracker exposes a referrer field, read the value and pass it there instead of patching the document. That route does not depend on load order, because you are setting a value rather than racing to shadow a getter.

```javascript
function centinelReferrer() {
  const ref = sessionStorage.getItem('_centinel_ref');
  if (ref) sessionStorage.removeItem('_centinel_ref');
  return ref || undefined;
}
```

This is the same read and clear the patch performs, so use one route or the other on a page. Whichever runs first takes the value, and the second finds nothing.

Google Analytics 4 accepts the origin as [`page_referrer`](https://developers.google.com/analytics/devguides/collection/ga4/reference/config) on the `config` call or in the GA4 tag's **Fields to set**. Not every tool has such a field. Chartbeat exposes no referrer key in `_sf_async_config`, so there the document patch is the only route.

## Verify

Load a page through the interstitial from an external source, then check what your tracker sends.

For Chartbeat, filter the Network tab on `ping?` and open a request to `ping.chartbeat.net`. Two query parameters carry the source:

| Parameter | Carries                                                  |
| --------- | -------------------------------------------------------- |
| `r`       | The referring URL when the referrer is an external site. |
| `v`       | The referring URL when the referrer is your own site.    |

When the restore works, `r` holds the saved origin and `v` is absent. Without it the reverse is true: `v` holds your own URL, because the reload made the visit look like a self-referral.

For Google Analytics 4, open DebugView and read the page referrer on the `page_view` event, or look for `dr=` on the request to `/g/collect`.

Trackers that post JSON rather than a query string carry the value under their own name. A Snowplow collector, for one, sends it as `refr` in the `pv` event body.

## See also

* [Interstitial Challenge](https://docs.centinelanalytica.com/concepts/interstitial-challenge.md): Why a reload happens and what the visitor sees.
* [Scripts](https://docs.centinelanalytica.com/install/scripts.md): The browser script and the signals it adds.

---

# Platform Integrations

> Drop-in Centinel integrations for CDNs, web servers, application frameworks, and content management systems.

Source: https://docs.centinelanalytica.com/platforms

## Overview

Each integration calls the validation API for you and enforces the decision it returns. Pick the
one that matches where you want protection to run. If nothing here covers your stack, wire the
API up yourself with [Validation](https://docs.centinelanalytica.com/install/validation.md).

Enforcement runs wherever you install it. An edge integration stops unwanted traffic before it
reaches your origin, while an application integration sees the request after your platform has
already served it from cache.

## CDN and edge

* [Cloudflare Workers](https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-standalone.md): Paste a single worker file in the Cloudflare dashboard.
* [Cloudflare Workers (npm)](https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-npm.md): Add Centinel to an existing worker project.
* [Fastly VCL](https://docs.centinelanalytica.com/platforms/cdn-edge/fastly.md): Attach to an existing Fastly VCL service.
* [Fastly Compute (Rust)](https://docs.centinelanalytica.com/platforms/cdn-edge/fastly-compute-rust.md): Validate at the edge with the Rust SDK.
* [Akamai EdgeWorkers](https://docs.centinelanalytica.com/platforms/cdn-edge/akamai-edgeworkers.md): Deploy on an Akamai property.
* [AWS CloudFront](https://docs.centinelanalytica.com/platforms/cdn-edge/aws-cloudfront.md): Install as a Lambda\@Edge viewer-request function.
* [F5 BIG-IP iRules](https://docs.centinelanalytica.com/platforms/cdn-edge/f5-bigip.md): iRules for F5 load balancers.

## Web server and proxy

* [Nginx / OpenResty](https://docs.centinelanalytica.com/platforms/web-server/nginx.md): Lua module running in the access phase.
* [Apache HTTP Server](https://docs.centinelanalytica.com/platforms/web-server/apache.md): Lua module loaded through mod\_lua.
* [HAProxy](https://docs.centinelanalytica.com/platforms/web-server/haproxy.md): SPOE filter plus Lua hooks.
* [Varnish](https://docs.centinelanalytica.com/platforms/web-server/varnish.md): VCL config with a small helper VMOD.

## Application

* [Next.js](https://docs.centinelanalytica.com/platforms/application/nextjs.md): Middleware plus the client script component.
* [ASP.NET Core](https://docs.centinelanalytica.com/platforms/application/aspnet-core.md): Middleware for the ASP.NET request pipeline.
* [Azure Functions](https://docs.centinelanalytica.com/platforms/application/azure-functions.md): Validate requests from an Azure Function.

## Content management

* [WordPress](https://docs.centinelanalytica.com/platforms/cms/wordpress.md): Plugin covering pages, REST API, login, and uploads.
* [Drupal 8+](https://docs.centinelanalytica.com/platforms/cms/drupal-8.md): Module for Drupal 8 through 11.
* [Drupal 7](https://docs.centinelanalytica.com/platforms/cms/drupal-7.md): Module for Drupal 7.

---

# Cloudflare Workers

> Deploy Centinel Analytica on your website via the Cloudflare Workers dashboard.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-standalone

## Overview

This guide covers the console workflow for installing the Centinel Worker as a standalone file.
The worker deploys globally in 2-3 minutes.

> **Have an existing worker?:** If you already have a Cloudflare Worker and want to add Centinel to it, use the [npm package](https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-npm.md) instead.

## Prerequisites

* Centinel secret key (for validator API)
* Cloudflare account with a website added
* Access to the Cloudflare dashboard

## Install

1. **Prepare the script**

   1. Download or copy [`centinel-worker.js`](https://docs.centinelanalytica.com/downloads/centinel-worker.js).
   2. Keep your **CENTINEL\_SECRET\_KEY** ready (you'll add it as an environment variable later).

2. **Create the worker**

   1. Log into your Cloudflare dashboard.
   2. Go to **Workers & Pages → Create application → Create Worker**.
   3. Name your worker (e.g. `centinel-protection`).
   4. Click **Deploy** to create the worker with default code.

3. **Upload the script**

   1. In the worker overview, click **Quick Edit** (or go to **Edit code**).
   2. Delete all the default code.
   3. Paste the entire contents of `centinel-worker.js`.
   4. Click **Save and Deploy**.

## Configure

1. **Configure environment variables**

   1. Go to **Settings → Variables and Secrets**.
   2. Click **Add variable** and enter:
      * Variable name: `CENTINEL_SECRET_KEY`
      * Value: `your-secret-key`
      * Type: **Secret**. Do not use a plaintext variable for this.
   3. Optionally add `CENTINEL_VALIDATOR_URL`, `CENTINEL_TIMEOUT`, or `CENTINEL_ENABLE_DEBUGGING`.
   4. Click **Save and Deploy**.

   | Variable                    | Type   | Default                                            | Purpose                                                           |
   | --------------------------- | ------ | -------------------------------------------------- | ----------------------------------------------------------------- |
   | `CENTINEL_SECRET_KEY`       | secret | —                                                  | Required. Without it the worker forwards all traffic unvalidated. |
   | `CENTINEL_VALIDATOR_URL`    | text   | `https://validator.centinelanalytica.com/validate` | Alternate validator endpoint.                                     |
   | `CENTINEL_TIMEOUT`          | text   | `10000`                                            | Validator timeout in ms.                                          |
   | `CENTINEL_ENABLE_DEBUGGING` | text   | `false`                                            | Set to `true` for verbose logs.                                   |

   > **Use a Worker secret, not a Secrets Store binding:** The worker reads this value as a plain string. A Secrets Store binding arrives as an object, which fails silently and leaves traffic unvalidated.

2. **Add a route to your domain**

   1. Go to **Settings → Domains & Routes** and click **Add**.
   2. Choose **Route**, then enter your pattern (e.g. `'example.com/*'` or `'*.example.com/*'`). A **Custom Domain** works too if the worker owns the hostname.
   3. Select your zone/domain from the dropdown.
   4. Click **Add route**.

### Advanced configuration

Edit the `activateCentinel()` call at the bottom of the script. Keep it at the top level of the
module, exactly as shipped.

```javascript
export default activateCentinel(undefined, {
    // Protect only specific paths (optional; default is every path)
    protectedPathsInclusion: /\/(api|admin|checkout)\//,

    // Exclude static assets (a default exclusion list is already applied)
    protectedPathsExclusion: /\.(js|css|png|jpg|svg)$/,

    // Alternate validator endpoint (optional)
    validatorURL: 'https://custom-validator.example.com/validate',

    // Validator timeout in milliseconds (default: 10000)
    timeout: 10000,

    // Verbose logging (default: false)
    enableDebugging: false,
});
```

> **Call activateCentinel() once, at the top level:** The handler holds the failure-backoff state. Calling `activateCentinel()` inside `fetch` resets that state for each request. The worker still calls the validator, but repeated failures can cause more validator traffic.

Path matching uses `url.pathname`, not the full URL. A query string cannot bypass an exclusion. Use the options above for supported configuration. Editing a bundled constant can change the worker behavior, but the change does not update the integration source or a later download.

```bash
# Install Wrangler 4 (needs Node.js 20+)
npm install -D wrangler@4

# Authenticate
npx wrangler login

# Set secret
npx wrangler secret put CENTINEL_SECRET_KEY

# Deploy
npx wrangler deploy
```

Routes are declarative in Wrangler 4. Add them to `wrangler.toml` rather than on the command line,
then deploy:

```toml
name = "centinel-protection"
main = "centinel-worker.js"
compatibility_date = "2025-03-25"

routes = [
  { pattern = "example.com/*", zone_name = "example.com" }
]
```

## Verify

* Visit your site to confirm traffic flows normally.
* Test that requests to protected paths are validated by the Centinel API.
* Confirm a protected response carries a `Server-Timing: validator;dur=...` header. That is the zero-config signal that the validator was actually called.
* For log output, set `CENTINEL_ENABLE_DEBUGGING` to `true`, then open **Logs → Begin log stream** and reload a protected path. Entries carry `"service": "CentinelAnalytics"`. Unset it when you are done.
* A healthy worker logs nothing by default, so silence in the log stream does not mean it is working. Watch instead for `CENTINEL_SECRET_KEY not set` or a 401 from the validator: either one means traffic is passing through unvalidated.

Per-worker traffic charts are under **Workers dashboard → Your worker → Analytics**.

## Changelog

* **v1.2.1** — Edge case fixes
* **v1.2.0** — Security and edge fixes
* **v1.1.3** — Timeout handling
* **v1.1.0** — Error handling

---

# Cloudflare Workers (npm)

> Add Centinel bot detection to an existing Cloudflare Worker using the npm package.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-npm

## Overview

This guide covers adding Centinel to an existing Cloudflare Worker project via the npm package.
Requests flow through the Centinel validator before reaching your worker, blocking bots while letting legitimate traffic through.

> **Looking for the standalone version?:** If you don't have an existing worker and want to paste a single file into the Cloudflare dashboard, see the [Cloudflare Workers (standalone)](https://docs.centinelanalytica.com/platforms/cdn-edge/cloudflare-worker-standalone.md) guide instead.

## Prerequisites

* Secret key from your [dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
* An existing Cloudflare Worker project using Wrangler

## Install

```bash
npm install @centinel/cloudflare-worker
```

## Configure

1. **Set your secret key**

   Use a Wrangler secret. Do not add `CENTINEL_SECRET_KEY` to `[vars]`. A committed
   `wrangler.toml` can expose the key.

   ```bash
   npx wrangler secret put CENTINEL_SECRET_KEY
   ```

2. **Wrap your worker**

   Import `activateCentinel` and wrap your existing worker:

   ```javascript
   import { activateCentinel } from '@centinel/cloudflare-worker';

   const myWorker = {
       async fetch(request, env, ctx) {
           // Your existing worker code
           return new Response('Hello from my app');
       },
   };

   export default activateCentinel(myWorker);
   ```

   Requests now go through the Centinel validator before reaching your worker. Bots are blocked; legitimate traffic passes through.

### Options

Pass a second argument to `activateCentinel`:

```javascript
export default activateCentinel(myWorker, {
    // Only validate paths matching this pattern (tested against pathname)
    protectedPathsInclusion: /\/api(\/|$)/,

    // Skip paths matching this pattern (default: static assets like .css, .js, .png)
    protectedPathsExclusion: /\.(css|js|png|jpg|woff2)$/i,

    // Validator API timeout in milliseconds (default: 10000)
    timeout: 5000,

    // Structured JSON debug logging (default: false)
    enableDebugging: true,
});
```

> **Path matching:** `protectedPathsInclusion` and `protectedPathsExclusion` are tested against the URL pathname (e.g. `/api/users`), not the full URL. Query strings and hostname are ignored.

### Environment variables

Options can be overridden per-request via environment variables. Set in `wrangler.toml`, the dashboard, or `.dev.vars`:

| Variable                    | What it does                   | Default                                            |
| --------------------------- | ------------------------------ | -------------------------------------------------- |
| `CENTINEL_SECRET_KEY`       | API key sent to the validator  | (none, required)                                   |
| `CENTINEL_VALIDATOR_URL`    | Validator API endpoint         | `https://validator.centinelanalytica.com/validate` |
| `CENTINEL_TIMEOUT`          | Request timeout in ms          | `10000`                                            |
| `CENTINEL_ENABLE_DEBUGGING` | Set to `"true"` for debug logs | `false`                                            |

Env vars take precedence over options passed to `activateCentinel()`, so you can use different settings per environment without changing code.

### How requests flow

1. Request arrives at your Cloudflare Worker
2. `activateCentinel` checks the path against inclusion/exclusion patterns
3. If protected, it POSTs request metadata (URL, method, IP, headers, `_centinel` cookie) to the validator API
4. The validator returns a decision:

**allow**

Request is forwarded to your worker. If the validator set cookies, they're added to the response.

```text
Client → Centinel → Validator (allow) → Your Worker → Client
```

**block**

Your worker is not called. The client receives an HTML error page with the status code from the validator (default 403).

```text
Client → Centinel → Validator (block) → 403 HTML page
```

**redirect**

Your worker is not called. The client receives a base64-decoded challenge page from the validator.

```text
Client → Centinel → Validator (redirect) → Challenge page
```

**not\_matched**

The URL didn't match any protected endpoint on the validator side. Request is forwarded to your worker normally.

```text
Client → Centinel → Validator (not_matched) → Your Worker → Client
```

### Fail-open behavior

If the validator is down, slow, or returns an error, the worker forwards the request without validation. This keeps the site available.

A bad secret key, an authentication failure, or a validator response error can also forward a protected request to your origin without validation.

After repeated failures, the worker uses exponential backoff (1s, 2s, 4s, ... up to 5 minutes). This prevents repeated calls to a broken endpoint.

### Standalone mode

If you don't have an existing worker, the default export works on its own:

```javascript
import centinelWorker from '@centinel/cloudflare-worker';
export default centinelWorker;
```

### TypeScript

Type definitions are included:

```typescript
import { activateCentinel, CentinelOptions, CentinelHandler } from '@centinel/cloudflare-worker';

const options: CentinelOptions = {
    protectedPathsInclusion: /\/api\//,
    timeout: 5000,
};

export default activateCentinel(myWorker, options);
```

## Verify

Visit your site and confirm normal traffic works. A response includes
`Server-Timing: validator;dur=<ms>` when the worker gets a validator duration; a network error has
no timing header.

For log output, open **Workers dashboard → Your worker → Logs → Begin log stream** and look for
`"service": "CentinelAnalytics"` entries. Set `CENTINEL_ENABLE_DEBUGGING = "true"` for a JSON line
at each step.

## Changelog

* **v1.2.1** — Edge case fixes

---

# Fastly VCL

> Attach Centinel Analytica to your existing Fastly VCL service via the attach script, Fastly Web UI, or Terraform.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/fastly

## Overview

Centinel attaches to your **existing** Fastly VCL service. The integration adds exactly three things to your service and modifies nothing else. Your domains, origins, custom VCL, and other snippets stay untouched:

1. A backend named `centinel` pointing at the validator (1s connect / 3s first-byte timeouts, so an outage adds at most a bounded delay before failing open)
2. A Private Edge Dictionary named `centinel_config` (API key, debug flag, kill-switch)
3. Seven VCL snippets named `centinel_*`

On every request the snippets check the path filter, validate the request against the Centinel `/validate` API, and block, challenge, or forward to your origin based on the decision. Every validator failure mode fails open. Changes take 2-3 minutes to roll out across Fastly's edge.

Installation aborts up front if any of those names already exist on your service, and uninstalling removes only those names.

## Prerequisites

* An existing Fastly VCL service with at least one domain and origin
* Centinel API key (for validator authentication)
* Fastly account with API token (Account → Personal API Tokens, full-service access)
* `curl` and `jq` (attach script path only)

## Install

Download [centinel-fastly.zip](https://docs.centinelanalytica.com/downloads/centinel-fastly.zip) and extract.

**Attach script (recommended)**

### Attach script

The script clones your service's active version, adds the backend + dictionary + snippets, validates the VCL, and activates.

```bash
cd install

export FASTLY_API_KEY="your-fastly-api-token"
export CENTINEL_API_KEY="your-centinel-api-key"

./attach.sh install <SERVICE_ID>
```

Your service ID is on the service overview page in the Fastly dashboard (or `fastly service list`).

Useful variations:

```bash
./attach.sh install <SERVICE_ID> --no-activate   # review the new version in the UI before activating
./attach.sh install <SERVICE_ID> --debug         # echo x-centinel-* headers (turn off in production)
./attach.sh status  <SERVICE_ID>                 # list installed Centinel components
./attach.sh uninstall <SERVICE_ID>               # remove only the centinel_* components
```

**Fastly Web UI (manual)**

### Manual installation via Fastly Web UI

#### Step 1: Clone the active version

Log into your Fastly dashboard, select your service, and click **Clone version** to create an editable draft (you can't edit active versions).

#### Step 2: Create the `centinel` backend

In **Origins → Hosts**, add a backend alongside your existing origin:

* **Name**: `centinel`
* **Address**: `validator.centinelanalytica.com`
* **Port**: `443`
* **Use SSL**: yes
* **SSL hostname**: `validator.centinelanalytica.com`
* **SSL SNI hostname**: `validator.centinelanalytica.com`
* **Override host**: `validator.centinelanalytica.com`
* **Connect timeout**: `1000` ms
* **First byte timeout**: `3000` ms
* **Between bytes timeout**: `2000` ms

#### Step 3: Create the Edge Dictionary

In **Edge Dictionaries → Create**:

* **Name**: `centinel_config`
* Mark as **Private**
* Add items:
  * `secret_key` → `<your-centinel-api-key>`
  * `debug` → `false`
  * `enabled` → `true`
* Save.

#### Step 4: Upload the seven VCL snippets

In **VCL Snippets → Create snippet**, repeat for each file in the `snippets/` directory from the downloaded zip. The priorities matter. Fastly runs lower numbers first, so these make Centinel run before your own recv/fetch snippets and after your own deliver snippets:

| File          | Snippet type | Name               | Priority |
| ------------- | ------------ | ------------------ | -------- |
| `init.vcl`    | `init`       | `centinel_init`    | `10`     |
| `recv.vcl`    | `recv`       | `centinel_recv`    | `10`     |
| `pass.vcl`    | `pass`       | `centinel_pass`    | `10`     |
| `miss.vcl`    | `miss`       | `centinel_miss`    | `10`     |
| `fetch.vcl`   | `fetch`      | `centinel_fetch`   | `10`     |
| `error.vcl`   | `error`      | `centinel_error`   | `10`     |
| `deliver.vcl` | `deliver`    | `centinel_deliver` | `150`    |

Paste each file's contents verbatim. You don't need to substitute an API key in the VCL; the snippets read it from the dictionary at runtime.

#### Step 5: Activate

1. Review the new backend, dictionary, and snippets.
2. Click **Activate** on the new version.
3. Wait 2-3 minutes for the new VCL to propagate globally.

**Terraform**

### Terraform (service managed by Terraform)

If your service is already managed by an existing `fastly_service_vcl` resource, paste these blocks into it (the Fastly provider is monolithic, so snippets must live inside the service resource):

```hcl
resource "fastly_service_vcl" "your_service" {
  # ... your existing domains, backends, settings ...

  # --- Centinel bot protection ---
  backend {
    name                  = "centinel"
    address               = "validator.centinelanalytica.com"
    port                  = 443
    use_ssl               = true
    ssl_cert_hostname     = "validator.centinelanalytica.com"
    ssl_sni_hostname      = "validator.centinelanalytica.com"
    override_host         = "validator.centinelanalytica.com"
    connect_timeout       = 1000
    first_byte_timeout    = 3000
    between_bytes_timeout = 2000
    max_conn              = 200
  }

  dictionary {
    name       = "centinel_config"
    write_only = true
  }

  dynamic "snippet" {
    for_each = {
      init = 10, recv = 10, pass = 10, miss = 10, fetch = 10, error = 10, deliver = 150
    }
    content {
      type     = snippet.key
      name     = "centinel_${snippet.key}"
      content  = file("${path.module}/centinel-snippets/${snippet.key}.vcl")
      priority = snippet.value
    }
  }
  # --- end Centinel ---
}
```

Copy the seven `.vcl` files from the zip's `snippets/` directory into `centinel-snippets/` next to your Terraform config, and populate the dictionary items (`secret_key`, `debug`, `enabled`) via a `fastly_service_dictionary_items` resource or the Fastly API.

> **write\_only dictionaries and Terraform:** The Fastly provider cannot read back `write_only = true` dictionary items. Either set `write_only = false` while managing items in Terraform, or keep it `true` and populate items via the Fastly API after `terraform apply`.

## Configure

### Edge Dictionary items (`centinel_config`)

| Key                 | Required | Description                                                                                                                |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `secret_key`        | yes      | Centinel validator API key.                                                                                                |
| `enabled`           | no       | Kill-switch. Set to `"false"` to bypass validation instantly, with no version activation or redeploy. Defaults to enabled. |
| `debug`             | no       | `"true"` or `"false"` (string). When `"true"`, debug headers are echoed on client responses. Keep `"false"` in production. |
| `cookie_attributes` | no       | Override the `_centinel` Set-Cookie attributes. Default: `Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=86400`.          |

### Path filtering

Static assets (images, fonts, CSS, JS, media) are excluded by default. The exclusion regex lives in `recv.vcl` as a literal (a Fastly VCL constraint: regex patterns can't come from variables). To customize, edit the regex in `recv.vcl` and re-upload that one snippet.

### Coexisting with your existing VCL

The integration is additive, but two interactions are inherent to pure-VCL bot protection. Audit your existing VCL for these before activating:

**Snippet ordering.** Fastly runs **lower priority numbers first**, and customer snippets default to **100**. Centinel's recv/fetch snippets run at priority 10 (before yours); its deliver snippet runs at priority 150 (after your default-priority deliver snippets, so its cleanup and validator-header application win). Don't `return()` out of `vcl_recv` or `vcl_fetch` from a snippet whose priority is below 10 (it would run before `centinel_recv` and silently bypass protection). If you need a deliver snippet to run after Centinel's cleanup, give it priority above 150.

**Restarts.** Validation consumes exactly one restart per protected request, and origin-bound requests carry the marker header `req.http.X-CN-Done == "1"`. If your VCL branches on `req.restarts`, adapt it:

```text
# run-once logic — was: if (req.restarts == 0)
if (req.restarts == 0 || (req.http.X-CN-Done && req.restarts == 1)) { ... }

# restart-based origin failover — was: if (req.restarts > 0)
if (req.restarts > 1 || (req.restarts == 1 && !req.http.X-CN-Done)) { ... }
```

**Next-Gen WAF (NGWAF / Signal Sciences).** If your service runs Fastly's edge WAF, Centinel's snippets (priority 10) run before NGWAF's (priority 9000) and mark the internal validator leg with `x-sigsci-no-inspection: true`, so the WAF skips the bodyless `POST /validate` hop. Without it, the WAF blocks the validator subrequest with HTTP 406 and logs its response as a spurious security event. The header is a no-op on services without NGWAF, so you don't need a manual allow-rule. Keep your own NGWAF snippets at their default priority (9000); a snippet below 10 runs before Centinel and breaks the bypass.

**Reserved names.** Backend `centinel`, dictionary `centinel_config`, snippets `centinel_*`, request headers `X-CN-*` / `X-Centinel-*` / `x-sigsci-no-inspection` (validator leg only), and synthetic codes `760`/`761` in `vcl_error`.

Requests that are automatically skipped (fail-open): static assets, `FASTLYPURGE`, WebSocket upgrades, ESI subrequests, background fetches, shield-node passes, and everything while the kill-switch is off.

## Verify

```bash
curl -i https://www.example.com/some-page
```

Expect: your origin's normal response, plus `Set-Cookie: _centinel=...; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=86400` and `Server-Timing: centinel;dur=<ms>`. That timing is the validator round-trip only (typically well under 100 ms), appended to any existing Server-Timing.

For temporary debugging, set `debug` → `true` in the dictionary; responses then include `x-centinel-decision`, `x-centinel-request-id`, and crawler info. Turn it back off in production.

## Uninstall

* **Pause instantly:** set the `enabled` dictionary item to `false`. Takes effect within seconds; set back to `true` to resume.
* **Remove completely:** `./attach.sh uninstall <SERVICE_ID>`, or in the UI clone the active version, delete the seven `centinel_*` snippets, the `centinel_config` dictionary, and the `centinel` backend, then activate.

## Changelog

* **v2.3.0** — Next-Gen WAF coexistence
* **v2.2.0** — Attach script and kill-switch
* **v2.1.0** — Dedicated `X-Centinel-Client` gate header
* **v2.0.0** — Header-mode validator contract
* **v1.0.0** — Initial release

---

# Fastly Compute (Rust)

> Add Centinel Analytica bot protection to your Fastly Compute service using the Rust SDK.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/fastly-compute-rust

## Overview

The Centinel Rust crate integrates with Fastly Compute to validate requests at the edge before they reach your origin. Suspicious requests are blocked or redirected; legitimate traffic and browser script injection are handled automatically. If the API is unavailable, requests pass through to keep your service online.

## Prerequisites

* Fastly account with Compute enabled
* Centinel secret key (server-side validation)
* Centinel site key (browser script)
* Rust 1.74 or later
* Fastly CLI installed

## Install

Add the Centinel crate to your Fastly Compute project:

```toml
[dependencies]
centinel-analytica-fastly = "0.2"
fastly = "0.12"
```

Both lines matter. The 0.2 crate requires `fastly` 0.12 or newer, and pinning `fastly = "0.11"`
alongside it puts two incompatible versions of the SDK in your dependency graph, which fails to
compile.

## Configure

1. **Update your main function**

   Replace `src/main.rs`:

   ```rust
   use centinel_analytica_fastly::Centinel;
   use fastly::{Error, Request, Response};

   #[fastly::main]
   fn main(req: Request) -> Result<Response, Error> {
       match Centinel::new() {
           Ok(centinel) => centinel.handle_request(req, |r| r.send("origin")),
           Err(_) => Ok(req.send("origin")?), // misconfigured: fail open
       }
   }
   ```

   > **Use handle\_request for normal integrations:** `handle_request` applies validator cookies and response headers. It adds `Server-Timing` after
   > validation. When a site key is configured, it injects the browser script into HTML responses.
   > `check_request` is deprecated since v0.2.4. It returns only a block or challenge response. On
   > `allow`, it discards the cookies and headers that establish the session, so every request starts
   > a new one. Move the code that followed it into the `handle_request` closure.

   Handling the `Centinel::new()` error matters too. Using `?` there turns a missing config store or a
   missing `centinel_secret_key` into a 500 for every request, which fails closed on a
   misconfiguration rather than open.

2. **Configure backends**

   Add to `fastly.toml`:

   ```toml
   [setup.backends]
   [setup.backends.origin]
   address = "your-origin.com"
   port = 443

   [setup.backends.centinel]
   address = "validator.centinelanalytica.com"
   port = 443
   override_host = "validator.centinelanalytica.com"
   use_ssl = true
   max_connections = 500

   [setup.config_stores]
   [setup.config_stores.centinel]
   ```

3. **Create config store**

   ```bash
   # Create the config store
   fastly config-store create --name=centinel

   # Add your secret key
   fastly config-store-entry create \
     --store-id=YOUR_STORE_ID \
     --key=centinel_secret_key \
     --value=YOUR_SECRET_KEY

   # Add your site key (for browser script)
   fastly config-store-entry create \
     --store-id=YOUR_STORE_ID \
     --key=centinel_site_key \
     --value=YOUR_SITE_KEY
   ```

4. **Link config store to service**

   ```bash
   fastly resource-link create \
     --version=latest \
     --autoclone \
     --service-id=YOUR_SERVICE_ID \
     --resource-id=YOUR_STORE_ID
   ```

### Configuration options

All configuration lives in the Fastly Config Store named `centinel`:

| Name                           | Type      | Default | Description                                                                    |
| ------------------------------ | --------- | ------- | ------------------------------------------------------------------------------ |
| `centinel_secret_key`          | `string`  |         | Server-side secret key (required)                                              |
| `centinel_site_key`            | `string`  |         | Browser script key (recommended)                                               |
| `centinel_url_exclusion`       | `string`  |         | Regex pattern for URLs to exclude                                              |
| `centinel_url_inclusion`       | `string`  |         | Regex pattern for URLs to include                                              |
| `centinel_timeout_ms`          | `number`  |         | API timeout in milliseconds (default: 300)                                     |
| `centinel_origin_backend_name` | `string`  |         | Origin backend name (default: origin)                                          |
| `centinel_backend_name`        | `string`  |         | Centinel validator backend name (default: centinel)                            |
| `centinel_api_endpoint`        | `string`  |         | Override validator API URL (default: https\://validator.centinelanalytica.com) |
| `centinel_debug`               | `boolean` |         | Enable debug logging (default: false)                                          |

### Advanced configuration

#### Custom routing

Route different paths through `Centinel::protect`. It applies validator cookies and response
headers, adds `Server-Timing` after validation, and injects the browser script into HTML responses
when a site key is configured:

```rust
use centinel_analytica_fastly::Centinel;
use fastly::{Error, Request, Response};

#[fastly::main]
fn main(req: Request) -> Result<Response, Error> {
    Centinel::protect(req, |req| {
        let backend = if req.get_path().starts_with("/api/") {
            "api_backend"
        } else {
            "origin"
        };

        Ok(req.send(backend)?)
    })
}
```

#### Health check bypass

Skip Centinel for health checks:

```rust
use centinel_analytica_fastly::Centinel;
use fastly::{Error, Request, Response};

#[fastly::main]
fn main(req: Request) -> Result<Response, Error> {
    if req.get_path() == "/health" {
        return Ok(Response::from_status(200)
            .with_body_text_plain("OK\n"));
    }

    Centinel::protect(req, |req| Ok(req.send("origin")?))
}
```

#### URL exclusions

Exclude static assets from bot protection:

```bash
fastly config-store-entry create \
  --store-id=YOUR_STORE_ID \
  --key=centinel_url_exclusion \
  --value='\.(css|js|png|jpg|svg|woff2?)$'
```

#### Protect specific paths

Only protect API routes:

```bash
fastly config-store-entry create \
  --store-id=YOUR_STORE_ID \
  --key=centinel_url_inclusion \
  --value='^/api/'
```

#### Custom timeout

`centinel_timeout_ms` applies only when the SDK builds a dynamic backend. If you declared a
`centinel` backend in `fastly.toml`, as the setup above does, requests go through that backend and
this key is ignored. Tune the backend's own connect and first-byte timeouts instead.

```bash
fastly config-store-entry create \
  --store-id=YOUR_STORE_ID \
  --key=centinel_timeout_ms \
  --value=2000
```

## Verify

1. **Deploy**

   ```bash
   # Build the WASM package
   fastly compute build

   # Deploy to Fastly
   fastly compute deploy
   ```

### Local testing

**Local server**

Configure local testing in `fastly.toml`:

```toml
[local_server.config_stores]
[local_server.config_stores.centinel]
format = "inline-toml"
[local_server.config_stores.centinel.contents]
centinel_secret_key = "test-secret-key"
centinel_site_key = "test-site-key"
```

Run locally:

```bash
# Start local development server
fastly compute serve

# Service available at http://127.0.0.1:7676
```

**Unit tests**

Install testing tools:

```bash
cargo install viceroy cargo-nextest
rustup target add wasm32-wasip1
```

Create `.cargo/config.toml`:

```toml
[build]
target = "wasm32-wasip1"

[target.wasm32-wasip1]
runner = "viceroy run -C fastly.toml -- "
```

Run tests:

```bash
cargo nextest run --release
```

## Troubleshooting

**Config Store not found**

Link the config store to your service:

```bash
fastly resource-link create \
  --version=latest \
  --autoclone \
  --service-id=YOUR_SERVICE_ID \
  --resource-id=YOUR_STORE_ID
```

**All requests being allowed**

Check your logs for errors:

```bash
fastly log-tail --service-id=YOUR_SERVICE_ID | grep -i centinel
```

Verify your secret key is correct and increase timeout if needed.

**Script not injecting**

Make sure `centinel_site_key` is set in your config store and responses have `Content-Type: text/html`.

### Resources

* **Package**: [crates.io/crates/centinel-analytica-fastly](https://crates.io/crates/centinel-analytica-fastly)

## Changelog

* **v0.2.4** — Session cookie kept; `check_request` deprecated
* **v0.2.3** — Relaxed `fastly` dependency to 0.12+
* **v0.2.1** — Non-UTF-8 header panic fix
* **v0.2.0** — Breaking: Server-Timing, full headers
* **v0.1.11** — Hardened validator client
* **v0.1.6** — Response header passthrough

---

# Akamai EdgeWorkers

> Deploy Centinel Analytica on your Akamai property using EdgeWorkers.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/akamai-edgeworkers

## Overview

This guide walks through deploying Centinel Analytica server-side validation on Akamai using EdgeWorkers.
Property Manager changes take 15-30 minutes to propagate across the Akamai network.

> **Have an existing EdgeWorker?:** If your property already runs an EdgeWorker on the requests you want to protect, follow [Run alongside an existing EdgeWorker](#run-alongside-an-existing-edgeworker) instead of attaching a second one.

## Prerequisites

* Centinel secret key
* Akamai Control Center access, with the EdgeWorkers add-on enabled
* Property Manager read-write access for the property you want to protect
* The Advanced Metadata privilege (open a support ticket if your account lacks it)

## Install

1. **Download the package**

   1. Download [`centinel-akamai-edgeworker.tgz`](https://docs.centinelanalytica.com/downloads/centinel-akamai-edgeworker.tgz).
   2. Extract the archive to get `main.js` and `bundle.json`.

2. **Create the EdgeWorker**

   1. Log into **Akamai Control Center**.
   2. Go to **CDN → EdgeWorkers**.
   3. Click **Create EdgeWorker ID**.
   4. Enter a name (e.g. `centinel-protection`).
   5. Select your **Group**, and choose **Dynamic Compute** (Tier 200) as the resource tier.
   6. Click **Create EdgeWorker ID**.

3. **Upload and activate the code**

   1. Select the EdgeWorker you just created.
   2. Click **Create Version**.
   3. Upload the `main.js` and `bundle.json` files.
   4. Click **Create Version**.
   5. Activate the new version on the staging and production networks.

## Configure

> **Rule order:** Keep the Centinel rules at the bottom of your rule tree. When two rules set the same behavior, the bottom-most match wins, so a later origin or caching rule would override them.

1. **Configure the validator route**

   Route `/centinel-validate` to the Centinel API.

   1. Go to **CDN → Properties** and select your property.
   2. Click **Edit New Version** to create a draft.
   3. Under **Property Configuration**, click **Add Rule**.
   4. Name the rule `Centinel Validator`.
   5. Add a **Criteria**:
      * **Match Type**: Path
      * **Match Operator**: matches one of
      * **Value**: `/centinel-validate`
   6. Add a **Behavior** → **Origin Server**:
      * **Origin Server Hostname**: `validator.centinelanalytica.com`
      * **Forward Host Header**: Origin Hostname
      * **Origin SSL Certificate Verification**: Yes
   7. Add a **Behavior** → **Allow POST**:
      * **Behavior**: Allow
      * **Allow POST without Content-Length header**: No
   8. Add a **Behavior** → **Modify Outgoing Request Path**:
      * **Action**: Replace Entire Path
      * **Replace With**: `/validate`
   9. Add a **Behavior** → **Caching**:
      * **Caching Option**: No Store
   10. Click **Save**.

   > **Watch out:** Do **not** apply the EdgeWorker behavior to the `/centinel-validate` rule.

2. **Set Property Manager variables**

   1. In your property configuration, go to **Property Variables**.
   2. Add:

   | Variable                        | Value                    |
   | ------------------------------- | ------------------------ |
   | `PMUSER_EW_CENTINEL_SECRET_KEY` | Your Centinel secret key |
   | `PMUSER_EW_CENTINEL_FLOW`       | Leave empty              |

   3. (Optional) Add additional variables from the configuration reference below.
   4. Click **Save**.

   > **Variable visibility:** Set variables to **Hidden** (not Sensitive) in Property Manager.

3. **Attach the EdgeWorker**

   1. Under **Property Configuration**, click **Add Rule** and name it
      `Centinel Protection`.
   2. Add a **Criteria**:
      * **Match Type**: File Extension
      * **Match Operator**: is not one of
      * **Case Sensitive**: Off
      * **Value**: the file types Centinel skips:

   ```text
   avi avif bmp css eot flac flv gif gz ico jpeg jpg js json
   less map mka mkv mov mp3 mp4 mpeg mpg ogg ogm opus otf png
   svg svgz swf ttf wav webm webp woff woff2 xml zip
   ```

   3. Add a **Behavior** → **EdgeWorkers** and select your
      `centinel-protection` EdgeWorker ID.
   4. Add a **Behavior** → **Advanced** with this metadata:

   ```xml
   <edgeservices:cookie.pass-set-cookie-policy>ALWAYS</edgeservices:cookie.pass-set-cookie-policy>
   ```

   5. Click **Save**.

   Your pages stay cacheable. The EdgeWorker checks every request before the cache lookup and adds
   the `_centinel` cookie to each response after it, so the cookie is never stored in
   the cache.

   > **Scope:** To protect only part of your site, add a **Path** criterion to this rule.

4. **Activate the property**

   1. Click **Activate** in Property Manager.
   2. Select **Staging** for initial testing, or **Production** when ready.
   3. Add activation notes and click **Activate**.
   4. Wait for activation to complete (15-30 minutes).

### Run alongside an existing EdgeWorker

Akamai runs one EdgeWorker per request. To add Centinel to rules that already run your own
EdgeWorker, use Akamai
[flexible composition](https://techdocs.akamai.com/edgeworkers/docs/flexible-composition):
your EdgeWorker imports Centinel as a module.

1. **Activate Centinel without attaching it**

   1. Create, upload, and activate the Centinel EdgeWorker as described in
      [Install](#install).
   2. Complete the Configure steps above, but leave the **EdgeWorkers** behavior out
      of the `Centinel Protection` rule. Your EdgeWorker stays on its own rule. If that
      rule covers only part of the property, add its criteria to `Centinel Protection`.

2. **Add Centinel as a dependency**

   In your EdgeWorker's `bundle.json`, add a `dependencies` entry, keep your
   existing fields, and bump `edgeworker-version` as usual. Replace `12345`
   with the Centinel EdgeWorker ID. The key
   `centinel` is the module name you import in the next step.

   ```json
   {
     "edgeworker-version": "2.0.0",
     "dependencies": {
       "centinel": {
         "edgeWorkerId": 12345,
         "version": "active"
       }
     }
   }
   ```

3. **Call Centinel from your handlers**

   In your EdgeWorker's `main.js`, call Centinel before your own code, so blocked requests
   never reach it:

   ```js
   import * as centinel from "centinel";

   export async function onClientRequest(request) {
     await centinel.onClientRequest(request);
     // Centinel responded: return, or a later respondWith() replaces it.
     if (request.wasTerminated()) return;

     // Your existing onClientRequest code.
   }

   export async function onClientResponse(request, response) {
     centinel.onClientResponse(request, response);

     // Your existing onClientResponse code, if any.
   }
   ```

   Centinel uses only these two handlers. Leave your other handlers as they are.

4. **Activate your EdgeWorker**

   1. Upload the updated bundle as a new version of your EdgeWorker.
   2. Activate it on staging and check it with the steps in [Verify](#verify).
   3. Activate it on production.

Before you activate, check:

* **Resource tier**: use Dynamic Compute (Tier 200) or higher for your EdgeWorker. Its
  [limits](https://techdocs.akamai.com/edgeworkers/docs/limitations#flexible-composition-limits)
  cover your code and Centinel together: 4 HTTP sub-requests, 20 ms of CPU, and 5.5 s of wall time
  per event handler. Centinel uses one sub-request in `onClientRequest` and waits up to
  `PMUSER_EW_CENTINEL_TIMEOUT` for it.
* **Property variables**: all `setVariable()` calls in one event handler share a budget of 1,024
  characters, names included, and `setVariable()` throws once it is spent. Centinel uses up to about
  950 of them in `onClientRequest`. If your code also sets variables there, ask your Akamai
  representative to raise the limit to 4,000.
* **Updates**: with `"version": "active"`, activating a new Centinel version reactivates your
  EdgeWorker automatically. To decide when Centinel changes,
  [import a fixed revision](https://techdocs.akamai.com/edgeworkers/docs/review-a-static-activation)
  instead.
* **Permissions**: Akamai lets a parent import children from the same account. Whoever activates
  your EdgeWorker needs Publisher access to it and Viewer access to the Centinel EdgeWorker.
* **subWorkers**: if your `bundle.json` sets `invoke-for-edgeworker-clients` to `true`, turn the
  EdgeWorkers behavior off on the `Centinel Validator` rule, so your EdgeWorker does not run on the
  validator call.

### Configuration reference

#### Required variables

| Variable                        | Type     | Description                                      |
| ------------------------------- | -------- | ------------------------------------------------ |
| `PMUSER_EW_CENTINEL_SECRET_KEY` | `string` | Your Centinel secret key for API authentication. |

#### Optional variables

| Variable                                       | Type     | Default | Description                                                               |
| ---------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------- |
| `PMUSER_EW_CENTINEL_TIMEOUT`                   | `number` | `500`   | Validator timeout in milliseconds.                                        |
| `PMUSER_EW_CENTINEL_PROTECTED_PATHS_INCLUSION` | `string` | –       | Regex pattern to protect only matching paths. Leave empty to protect all. |
| `PMUSER_EW_CENTINEL_PROTECTED_PATHS_EXCLUSION` | `string` | –       | Regex pattern to skip validation. Static assets are excluded by default.  |
| `PMUSER_EW_CENTINEL_ENABLE_DEBUGGING`          | `string` | `false` | Set to `true` to write JSON debug lines to the EdgeWorker log.            |

#### Notes

* **Timeout**: 500ms by default, adjustable with `PMUSER_EW_CENTINEL_TIMEOUT`.
* **Logging**: Uses Akamai's built-in `logger` module. Check EdgeWorker logs in Control Center.
* **Fails open**: any validator error, timeout, unparseable response, or missing secret key allows the request through. An unreachable validator means unprotected traffic, not blocked traffic.
* **Challenge size**: a block or challenge page larger than 2000 characters cannot be delivered. Blocks fall back to a generic page, and oversized challenges are skipped entirely.

## Verify

* Browse your site to confirm traffic flows normally.
* Check that static assets (`.js`, `.css`, `.png`, etc.) load without delays.
* Confirm a protected response carries a `Server-Timing: validator;dur=...` header.
* On a page Akamai caches, send two requests with a browser `User-Agent`, no cookies, and the header `Pragma: akamai-x-cache-on`. The second should show `X-Cache: TCP_HIT` or `TCP_MEM_HIT`. Each response should carry its own `_centinel` value.
* If the `Server-Timing` header is missing, send a `GET` to `/centinel-validate` on your protected hostname: it should return `405 Method Not Allowed`. Repeat as a `POST`; a `403 Forbidden` means the rule still needs the **Allow POST** behavior.
* For detail, set `PMUSER_EW_CENTINEL_ENABLE_DEBUGGING` to `true` and read the JSON log lines in **Control Center → EdgeWorkers → Logs**.

## Changelog

* **v3.0.5** — Current release, rebuilt from source
* **v3.0.4** — Fixed challenge cookie delivery
* **v3.0.2** — Crawler-aware handling
* **v3.0.1** — Response handling update
* **v3.0.0** — Fixed timeout, logging refactor
* **v2.0.1** — Logging and error handling
* **v2.0.0** — Cookie handling improvements
* **v1.0.0** — Initial release

---

# AWS CloudFront

> Deploy Centinel Analytica on an existing CloudFront distribution via Lambda@Edge.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/aws-cloudfront

## Overview

This guide covers the console workflow for installing the Centinel Lambda\@Edge function.
After associating the function, allow 15-20 minutes for CloudFront to propagate the protection globally.

## Prerequisites

* Centinel secret key
* CloudFront distribution you can edit
* AWS Console access with Lambda and CloudFront permissions

## Install

1. **Prepare the package**

   1. Download [`centinel-cloudfront.js`](https://docs.centinelanalytica.com/downloads/centinel-cloudfront.js).
   2. Open the file and replace the empty `CENTINEL_SECRET_KEY` value with your key.
   3. Zip the modified `centinel-cloudfront.js` to create a deployment archive.

2. **Create the Lambda function**

   1. Switch the AWS Console region to &#x2A;*N. Virginia (us-east-1)**.
   2. Go to **Lambda → Create function → Author from scratch**.
   3. Name the function (e.g. `centinel-cloudfront`), choose a currently supported **Lambda\@Edge Node.js runtime**, and create it.
   4. In the **Code** tab, select **Upload from → .zip file** and upload your archive.
   5. Under **Configuration → Runtime settings**, set **Handler** to `centinel-cloudfront.handler`.
   6. Under **Configuration → General configuration**, set **Timeout** to 5 seconds and **Memory** to 128 MB. These are the Lambda\@Edge maxima for a viewer-request function, not preferences. If the validator is slow, lower `CENTINEL_TIMEOUT` rather than raising these.
   7. Under **Configuration → Permissions**, edit the execution role's trust relationship so it trusts both `lambda.amazonaws.com` and `edgelambda.amazonaws.com`. CloudFront refuses the association without the second principal.
   8. Choose **Actions → Publish new version** and note the versioned ARN. CloudFront rejects `$LATEST`, so always associate a published version.

3. **Associate with CloudFront**

   1. Open **CloudFront → Distributions**, select the distribution to protect, and edit the cache behavior you want covered.
   2. In **Function associations**, click **Add function**, choose **Lambda\@Edge**, paste the versioned ARN, and set the event type to **Viewer request**.
   3. Click **Add function** again and add the **same ARN** with the event type **Viewer response**. One function, two associations: the viewer-request pass decides, the viewer-response pass delivers the session cookie. Without it, allowed visitors never receive a cookie and every request is revalidated.
   4. Save the behavior to start global deployment.

## Configure

Edit these constants at the top of `centinel-cloudfront.js` before zipping it.

| Setting                      | Default                           | Purpose                                                        |
| ---------------------------- | --------------------------------- | -------------------------------------------------------------- |
| `CENTINEL_SECRET_KEY`        | empty                             | Required. While empty, every request is forwarded unvalidated. |
| `CENTINEL_PROTECTED_PATHS`   | empty (all paths)                 | Paths to protect. `*` matches a single path segment only.      |
| `CENTINEL_UNPROTECTED_PATHS` | 30 static extensions              | Paths to skip. `*.ext` matches at any depth.                   |
| `CENTINEL_VALIDATOR_URL`     | `validator.centinelanalytica.com` | Alternate validator endpoint.                                  |
| `CENTINEL_TIMEOUT`           | `300`                             | Validator timeout in ms. Unrelated to the Lambda timeout.      |
| `CENTINEL_LOG_ENABLED`       | `true`                            | Gates the `[Centinel]` log lines the Verify step looks for.    |

Two behaviors worth knowing before you deploy:

* **Fails open.** A missing key, a timeout, an unparseable response, or an error all allow the request through. After a validator failure the function also stops calling the validator for a spell, backing off up to five minutes, so a sustained outage leaves traffic unvalidated for that window.
* **Allowed requests go straight to the origin.** A viewer-request function cannot both forward a request and set a cookie on the response, so the session cookie is carried to the viewer-response pass on an `x-centinel-set-cookie` request header and written out there. That header also reaches your origin, where it is inert; strip it in an origin-request function if unknown headers are logged.

Viewer-request functions can only return a small generated response, so a large block or challenge
page cannot be delivered on this platform and CloudFront answers 502 instead. Keep custom pages small.

## Verify

* Watch the distribution status until it says **Deployed** (15-20 minutes).
* Lambda\@Edge logs land in the region nearest the viewer, in the log group `/aws/lambda/us-east-1.<function-name>`, not in us-east-1.
* Browse the distribution domain to confirm traffic flows normally.
* Check CloudWatch logs for entries prefixed with `[Centinel]` if you need to troubleshoot.

## Changelog

* **v1.2.0** — Session cookie via viewer-response
* **v1.1.0** — Honor validator status codes
* **v1.0.2** — Typo fix
* **v1.0.1** — Response header passthrough
* **v1.0.0** — Initial release

---

# F5 BIG-IP iRules

> Deploy Centinel Analytica on F5 BIG-IP load balancers using iRules for bot detection.

Source: https://docs.centinelanalytica.com/platforms/cdn-edge/f5-bigip

## Overview

The Centinel iRule runs on your F5 BIG-IP, calls the Centinel API for each request, and blocks or challenges traffic based on the response.

## Prerequisites

* Centinel secret key (from your dashboard)
* F5 BIG-IP device with LTM module (v11.5+ recommended)
* SSH or TMSH access to the F5 device
* BIG-IP local caching nameserver (BIND) that resolves `validator.centinelanalytica.com`

> **DNS resolver required:** The iRule uses `RESOLV::lookup` without an explicit nameserver to resolve `validator.centinelanalytica.com`. BIG-IP sends this lookup to its local caching nameserver (BIND).
>
> Configure the local caching nameserver to resolve the API hostname. A shell DNS test does not test the iRule DNS path.

## Install

1. **Download and extract the iRule package**

   Download [centinel-f5-irules.zip](https://docs.centinelanalytica.com/downloads/centinel-f5-irules.zip) and extract it:

   ```bash
   curl -O https://docs.centinelanalytica.com/downloads/centinel-f5-irules.zip
   unzip centinel-f5-irules.zip
   ```

   The zip contains:

   * `Centinel.tcl` — the main iRule, with the API integration
   * `Centinel-SSL-Helper.tcl` — the SSL connection handler

2. **Upload the iRule files**

   Log into your F5 BIG-IP management interface and upload both iRule files:

   **Via Web UI:**

   1. Navigate to **Local Traffic → iRules → iRules List**
   2. Click **Create**
   3. Enter name: `Centinel`
   4. Paste the contents of `Centinel.tcl`
   5. Click **Finished**
   6. Repeat for `Centinel-SSL-Helper` with `Centinel-SSL-Helper.tcl`

   **Via TMSH:**

   ```bash
   # Copy files to BIG-IP first
   scp Centinel.tcl Centinel-SSL-Helper.tcl root@<bigip-mgmt-ip>:/var/tmp/

   # Wrap and load each iRule
   { echo 'ltm rule Centinel {'; cat /var/tmp/Centinel.tcl; echo '}'; } > /var/tmp/Centinel.conf
   tmsh load sys config merge file /var/tmp/Centinel.conf

   { echo 'ltm rule Centinel-SSL-Helper {'; cat /var/tmp/Centinel-SSL-Helper.tcl; echo '}'; } > /var/tmp/Centinel-SSL-Helper.conf
   tmsh load sys config merge file /var/tmp/Centinel-SSL-Helper.conf
   ```

3. **Configure your API key**

   Edit the `Centinel` iRule and update the secret key on line 8:

   ```tcl
   # Replace with your actual API key
   set static::CENTINEL_SECRET_KEY "sk_live_your_key_here"
   ```

   **Via Web UI:**

   1. Navigate to **Local Traffic → iRules → iRules List**
   2. Click on `Centinel`
   3. Click **Edit**
   4. Update line 8 with your secret key
   5. Click **Finished**

   **Via TMSH:**

   ```bash
   tmsh edit ltm rule Centinel
   # Update the key, then save and exit
   ```

4. **Create the API virtual server**

   Create a virtual server for making outbound HTTPS calls to the Centinel API:

   **Via Web UI:**

   1. Navigate to **Local Traffic → Virtual Servers → Virtual Server List**
   2. Click **Create**
   3. Configure:
      * **Name**: `centinel_api_ssl_vs`
      * **Destination Address/Mask**: `0.0.0.0/0` (any)
      * **Service Port**: `443`
      * **Protocol**: `TCP`
      * **HTTP Profile (Client)**: `http`
      * **SSL Profile (Server)**: `serverssl-insecure-compatible`
      * **Source Address Translation**: `Auto Map`
      * **Address Translation**: `Enabled`
      * **Port Translation**: `Enabled`
   4. Click **Finished**

   > **Upstream TLS behavior:** The SSL helper sends `validator.centinelanalytica.com` in SNI.
   >
   > These instructions do not configure a trusted CA, require a server certificate, or set an Authenticate Name. The supplied setup does not authenticate the API certificate or hostname.
   >
   > If the API call fails, the main iRule allows the application request.

   **Via TMSH:**

   ```bash
   tmsh create ltm virtual centinel_api_ssl_vs \
       destination 0.0.0.0:443 \
       ip-protocol tcp \
       mask 0.0.0.0 \
       profiles add { tcp http { context all } serverssl-insecure-compatible { context serverside } } \
       source 0.0.0.0/0 \
       source-address-translation { type automap } \
       translate-address enabled \
       translate-port enabled
   ```

5. **Apply SSL helper to API virtual server**

   Attach the `Centinel-SSL-Helper` iRule to the API virtual server:

   **Via Web UI:**

   1. Navigate to **Local Traffic → Virtual Servers**
   2. Click on `centinel_api_ssl_vs`
   3. Go to **Resources** tab
   4. Under **iRules**, click **Manage**
   5. Move `Centinel-SSL-Helper` from Available to Enabled
   6. Click **Finished**

   **Via TMSH:**

   ```bash
   tmsh modify ltm virtual centinel_api_ssl_vs rules { Centinel-SSL-Helper }
   ```

6. **Apply main iRule to application virtual server**

   Attach the `Centinel` iRule to your application's virtual server(s):

   **Via Web UI:**

   1. Navigate to **Local Traffic → Virtual Servers**
   2. Click on your application virtual server (e.g. `www_vs`)
   3. Go to **Resources** tab
   4. Under **iRules**, click **Manage**
   5. Move `Centinel` from Available to Enabled
   6. Click **Finished**

   **Via TMSH:**

   ```bash
   tmsh modify ltm virtual your_application_vs rules { Centinel }
   ```

   > **Note:** The `Centinel` iRule can be applied to multiple virtual servers.

7. **Save configuration**

   Save your changes to persistent storage:

   **Via Web UI:** Click **System → Configuration → Save Configuration**

   **Via TMSH:**

   ```bash
   tmsh save sys config
   ```

## Configure

### Advanced configuration

**Path filtering**

#### URI path filtering

By default, static assets (images, CSS, JS, fonts) are excluded from validation for better performance.

##### Exclude additional paths

Edit `CENTINEL_URI_REGEX_EXCLUSION` (line 28) to skip more paths:

```tcl
# Example: Exclude health checks and metrics
set static::CENTINEL_URI_REGEX_EXCLUSION {(?i)\.(avi|flv|mka|mkv|mov|mp4|mpeg|mpg|mp3|flac|ogg|ogm|opus|wav|webm|webp|bmp|gif|ico|jpeg|jpg|png|svg|svgz|swf|eot|otf|ttf|woff|woff2|css|less|js)$|^/health$|^/metrics$}
```

##### Protect only specific paths

Add `CENTINEL_URI_REGEX` to validate only certain paths (unset by default, meaning all paths are checked):

```tcl
# Only protect paths starting with /api/ or /admin
set static::CENTINEL_URI_REGEX {^/(api|admin)/}
```

**Timeouts**

#### Timeout configuration

Adjust API timeout for your network. Default is 150ms.

```tcl
set static::CENTINEL_timeout 300
```

**Logging**

#### Debug logging

Enable detailed logging for troubleshooting:

Edit the `Centinel` iRule and set these variables:

```tcl
# Enable debug logging
set static::CENTINEL_LOG_REQUEST_HEADERS 1
set static::CENTINEL_LOG_RESPONSE_HEADERS 1
set static::CENTINEL_LOG_REQUEST_TIME 1
```

View logs:

```bash
# Real-time log monitoring
tail -f /var/log/ltm | grep CENTINEL

# Search for errors
grep "CENTINEL ERROR" /var/log/ltm
```

For high-traffic environments, use High-Speed Logging (HSL) to avoid flooding the local log:

```tcl
set static::CENTINEL_LOG_PUBLISHER "/Common/remote_log_publisher"
```

**Performance**

#### Performance optimization

1. Connection pooling is automatic — the iRule reuses TLS connections to the Centinel API across requests. No configuration needed.

2. Raise the connection limit on the API virtual server if needed:
   ```bash
   tmsh modify ltm virtual centinel_api_ssl_vs connection-limit 10000
   ```

3. Apply the iRule to multiple F5 devices in an HA pair or cluster — each device maintains its own connection pool.

### Configuration reference

#### Main iRule variables

Edit these in the `Centinel` iRule (inside `when RULE_INIT`):

| Variable                        | Default                       | Description                                                                              |
| ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
| `CENTINEL_SECRET_KEY`           | (required)                    | Your API key from Centinel dashboard                                                     |
| `CENTINEL_MODULE_VERSION`       | `1.1.1`                       | Module version (informational)                                                           |
| `CENTINEL_vs`                   | `/Common/centinel_api_ssl_vs` | Name of API virtual server                                                               |
| `CENTINEL_timeout`              | `150`                         | API timeout in milliseconds                                                              |
| `CENTINEL_URI_REGEX`            | (unset)                       | Regex pattern for paths to validate. Unset validates all paths                           |
| `CENTINEL_URI_REGEX_EXCLUSION`  | (see code)                    | Regex pattern for paths to skip                                                          |
| `CENTINEL_HEADER_WHITELIST`     | (see code)                    | List of HTTP headers sent to API (customizable)                                          |
| `CENTINEL_LOG_REQUEST_HEADERS`  | `0`                           | Log outbound request headers (0=off, 1=on)                                               |
| `CENTINEL_LOG_RESPONSE_HEADERS` | `0`                           | Log API response headers (0=off, 1=on)                                                   |
| `CENTINEL_LOG_REQUEST_TIME`     | `0`                           | Log request timing (0=off, 1=on)                                                         |
| `CENTINEL_LOG_PUBLISHER`        | (unset)                       | High-Speed Logging publisher. Unset logs to `/var/log/ltm`                               |
| `CENTINEL_LOG_POOL`             | (unset)                       | UDP syslog pool for High-Speed Logging. Used only when `CENTINEL_LOG_PUBLISHER` is unset |

## Verify

1. **Verify the API DNS lookup**

   The iRule resolves `validator.centinelanalytica.com` through the BIG-IP local caching nameserver (BIND).

   Send a test request to your application. Then confirm that the request appears in the Centinel dashboard.

   The command `run /util dig validator.centinelanalytica.com` tests the shell resolver. It does not test the TMM `RESOLV::lookup` path.

   The application request can still succeed when the API DNS lookup fails. The iRule fails open for an unavailable API response.

2. **Test the integration**

   1. **Check logs**: Monitor for Centinel activity
      ```bash
      tail -f /var/log/ltm
      ```

   2. **Test normal traffic**: Visit your application to confirm requests work normally

   3. **Check statistics**: View iRule execution stats
      ```bash
      tmsh show ltm rule Centinel
      ```

   4. **Monitor Centinel dashboard**: Verify requests appear in your Centinel dashboard

## Changelog

* **v1.1.1** — F5 string limit fix
* **v1.1.0** — Performance optimizations
* **v1.0.5** — Send all headers
* **v1.0.3** — TLS connection reuse
* **v1.0.2** — TCL 8.4 compatibility
* **v1.0.0** — Initial release

---

# Nginx / OpenResty

> Bot protection for Nginx and OpenResty using a Lua module.

Source: https://docs.centinelanalytica.com/platforms/web-server/nginx

## Overview

Centinel protects Nginx and OpenResty using a Lua module that intercepts every request in the `access_by_lua_block` phase, validates it against the Centinel API, and enforces the returned decision before your backend sees the traffic.

## Prerequisites

* Secret key from your [dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
* OpenResty 1.19+ or nginx with lua-nginx-module

## Install

1. **Install the module**

   ```bash
   curl -o /usr/local/openresty/site/lualib/centinel-nginx.lua \
     https://docs.centinelanalytica.com/downloads/centinel-nginx.lua
   ```

   Install the `lua-resty-http` dependency:

   ```bash
   opm get ledgetech/lua-resty-http
   ```

   No `opm`? Install manually:

   ```bash
   mkdir -p /usr/local/openresty/site/lualib/resty
   curl -o /usr/local/openresty/site/lualib/resty/http.lua \
     https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http.lua
   curl -o /usr/local/openresty/site/lualib/resty/http_headers.lua \
     https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http_headers.lua
   curl -o /usr/local/openresty/site/lualib/resty/http_connect.lua \
     https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http_connect.lua
   ```

2. **Configure nginx.conf**

   ```nginx
   # At the top, before events {} — required for os.getenv() to work in OpenResty
   env CENTINEL_SECRET_KEY;
   env CENTINEL_VALIDATOR_URL;

   events {
       worker_connections 1024;
   }

   http {
       lua_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
       lua_ssl_verify_depth 3;
       resolver 8.8.8.8 valid=30s ipv6=off;
       lua_shared_dict centinel_cache 10m;
       lua_package_path '/usr/local/openresty/site/lualib/?.lua;;';

       init_by_lua_block {
           centinel = require("centinel-nginx")
           centinel.init({
               secret_key         = os.getenv("CENTINEL_SECRET_KEY"),
               validator_url      = os.getenv("CENTINEL_VALIDATOR_URL")
                                  or "https://validator.centinelanalytica.com/validate",
               timeout_ms         = 1000,
               connect_timeout_ms = 500
           })
       }

       server {
           listen 80;

           location / {
               access_by_lua_block { centinel.access_handler() }
               proxy_pass http://your-backend;
           }
       }
   }
   ```

   > **Do not use return as your content directive:** `return 200` runs in the rewrite phase, before `access_by_lua_block`. Centinel will never execute. Use `proxy_pass` or `content_by_lua_block` instead.

3. **Set your secret key in the service environment**

   An `nginx -s reload` command does not copy environment variables from your shell into the running master process. Set the key in the service that starts nginx.

   For systemd, create a unit drop-in:

   ```bash
   sudo systemctl edit nginx
   ```

   ```ini
   [Service]
   Environment="CENTINEL_SECRET_KEY=YOUR_SECRET_KEY"
   ```

   Then reload the unit configuration and restart nginx:

   ```bash
   sudo systemctl daemon-reload
   sudo systemctl restart nginx
   ```

### Docker

```dockerfile
FROM openresty/openresty:alpine

RUN apk add --no-cache ca-certificates

RUN mkdir -p /usr/local/openresty/site/lualib/resty && \
    wget -q -O /usr/local/openresty/site/lualib/resty/http.lua \
    https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http.lua && \
    wget -q -O /usr/local/openresty/site/lualib/resty/http_headers.lua \
    https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http_headers.lua && \
    wget -q -O /usr/local/openresty/site/lualib/resty/http_connect.lua \
    https://raw.githubusercontent.com/ledgetech/lua-resty-http/master/lib/resty/http_connect.lua

RUN wget -q -O /usr/local/openresty/site/lualib/centinel-nginx.lua \
    https://docs.centinelanalytica.com/downloads/centinel-nginx.lua

COPY nginx.conf /usr/local/openresty/nginx/conf/nginx.conf

EXPOSE 80
CMD ["/usr/local/openresty/bin/openresty", "-g", "daemon off;"]
```

```bash
docker run -e CENTINEL_SECRET_KEY="sk_live_xxx" -p 80:80 your-image
```

In a Docker Compose network, set `resolver 127.0.0.11 valid=30s ipv6=off;` instead of `8.8.8.8`. Docker's embedded DNS at `127.0.0.11` handles both container names and external hostnames.

## Configure

**Path protection**

All paths are protected by default except static assets. Override in `centinel.init()`:

```lua
centinel.init({
    secret_key = os.getenv("CENTINEL_SECRET_KEY"),
    protected_paths = { "^/api/", "^/admin" },  -- empty = protect all
    unprotected_paths = { "^/health$", "^/metrics$" }
})
```

Excluded by default: images (`.gif`, `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.webp`, `.avif`, `.bmp`), fonts (`.eot`, `.otf`, `.ttf`, `.woff`, `.woff2`), styles (`.css`, `.less`), scripts (`.js`, `.map`), media (`.mp3`, `.mp4`, `.webm`, `.wav`, `.flac`, and others), archives (`.gz`, `.zip`), and `.json`, `.xml`.

**Keepalive pool**

Uses nginx's native proxy to call the validator. Connections to the upstream are pooled and reused, so each request skips the TLS handshake overhead.

Add to the `http {}` block:

```nginx
upstream centinel_validator {
    server validator.centinelanalytica.com:443;
    keepalive 16;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}
```

Add to the `server {}` block:

```nginx
set $centinel_h2_enabled "1";

location = /_centinel_validate {
    internal;

    rewrite_by_lua_block {
        ngx.req.set_header("x-api-key",        ngx.ctx.centinel_api_key or "")
        ngx.req.set_header("x-origin-module",  "nginx")
        ngx.req.set_header("x-origin-version", ngx.ctx.centinel_version or "")
    }

    proxy_pass              https://centinel_validator/validate;
    proxy_http_version      1.1;

    proxy_set_header        Host         "validator.centinelanalytica.com";
    proxy_set_header        Content-Type "application/json";
    proxy_set_header        Connection   "";

    proxy_ssl_server_name   on;
    proxy_ssl_name          validator.centinelanalytica.com;
    proxy_ssl_verify        on;
    proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
    proxy_ssl_session_reuse on;

    proxy_connect_timeout   1s;
    proxy_send_timeout      2s;
    proxy_read_timeout      2s;
}
```

When `$centinel_h2_enabled` is set, the module uses this location. Without it, it falls back to lua-resty-http.

> **validator\_url does not apply on this path:** Requests routed through this location go to the `upstream` block above, so `validator_url` and `CENTINEL_VALIDATOR_URL` are ignored. The module still logs the configured URL, which makes the mismatch easy to miss. To point at a different validator, change the `upstream` server plus the `Host` and `proxy_ssl_name` values here.

**Timeouts**

```lua
centinel.init({
    secret_key         = os.getenv("CENTINEL_SECRET_KEY"),
    timeout_ms         = 1000,  -- default: 100 (increase if not using the keepalive pool)
    connect_timeout_ms = 500,   -- default: 100
    fail_open          = true   -- default: true (allow requests if API is down)
})
```

On API failure the module backs off exponentially: 1s → 2s → 4s → 8s → 5min max. Requests pass through during backoff.

**Debug**

```lua
centinel.init({
    secret_key = os.getenv("CENTINEL_SECRET_KEY"),
    debug = true
})
```

Or set `CENTINEL_DEBUG=true` as an environment variable (requires `env CENTINEL_DEBUG;` in nginx.conf).

Check the error log for `[Centinel]` entries:

```bash
tail -f /var/log/nginx/error.log | grep Centinel
```

### Configuration reference

| Option               | Type    | Default                                            | Description                                   |
| -------------------- | ------- | -------------------------------------------------- | --------------------------------------------- |
| `secret_key`         | string  | —                                                  | API key from the dashboard. Required.         |
| `validator_url`      | string  | `https://validator.centinelanalytica.com/validate` | Validator endpoint.                           |
| `timeout_ms`         | number  | `100`                                              | Request timeout (ms).                         |
| `connect_timeout_ms` | number  | `100`                                              | Connection timeout (ms).                      |
| `fail_open`          | boolean | `true`                                             | Allow requests when API is unreachable.       |
| `ssl_verify`         | boolean | `true`                                             | Verify SSL certificates.                      |
| `debug`              | boolean | `false`                                            | Verbose logging.                              |
| `log_enabled`        | boolean | `true`                                             | Enable all logging.                           |
| `protected_paths`    | table   | `{}`                                               | Lua patterns to protect. Empty = protect all. |
| `unprotected_paths`  | table   | `[static assets]`                                  | Lua patterns to skip.                         |

## Verify

`nginx -t` does not execute `init_by_lua_block`, so a successful config test does not prove the
module loaded. Reload, then check both a log line and a real request:

```bash
nginx -t && nginx -s reload
tail -f /var/log/nginx/error.log | grep Centinel   # expect: Centinel module initialized
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost/api/test
```

A 500 on the first request usually means `lua-resty-http` is missing or the module is not on
`lua_package_path`. Without a `lua_shared_dict centinel_cache`, the module logs a warning and runs
with backoff disabled.

## Changelog

* **v1.1.1** — Response header passthrough
* **v1.1.0** — Cookie and proxy fixes
* **v1.0.0** — Initial release

---

# Apache HTTP Server

> Bot protection for Apache HTTP Server using a Lua module with mod_lua.

Source: https://docs.centinelanalytica.com/platforms/web-server/apache

## Overview

Centinel protects Apache HTTP Server using a Lua module loaded via `mod_lua`. An access checker hook intercepts every request, validates it against the Centinel API, and enforces the returned decision before your application logic runs.

## Prerequisites

* Secret key from your [dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
* Apache 2.4+ with `mod_lua` enabled
* Lua 5.1 libraries: `lua-curl`, `lua-socket`, `lua-cjson`

> **Debian/Ubuntu users:** The `lua-curl` package from `apt` does not work with `mod_lua`. It installs, but the shared object file that `require("lcurl")` needs is never created. Follow the luarocks install method in the Debian/Ubuntu tab below.

## Install

1. **Download and extract the module**

   Download [centinel-apache.zip](https://docs.centinelanalytica.com/downloads/centinel-apache.zip) and extract both files to your Lua module directory:

   ```bash
   curl -O https://docs.centinelanalytica.com/downloads/centinel-apache.zip
   unzip centinel-apache.zip -d /usr/local/lib/lua/
   ```

   The zip contains:

   * `centinel-apache.lua` - core module
   * `centinel-handler.lua` - Apache hook entry point

2. **Install dependencies**

   On Alpine Linux:

   ```bash
   apk add apache2-lua lua5.1-curl lua5.1-socket lua5.1-cjson
   ```

   On Debian/Ubuntu:

   ```bash
   apt-get install apache2 lua-socket lua-cjson luarocks libcurl4-openssl-dev lua5.1-dev
   a2enmod lua
   luarocks install Lua-cURLv3 LUA_VERSION=5.1 CURL_INCDIR=/usr/include
   ```

   > **Why luarocks instead of apt for lcurl:** The Debian `lua-curl` apt package does not install the `lcurl.so` shared object that `mod_lua` loads via `require("lcurl")`. luarocks builds it directly. The `LUA_VERSION=5.1` flag is required because luarocks compiles against Lua 5.3/5.4 headers by default, but `mod_lua` uses Lua 5.1. Without it, Apache fails to load the module with `undefined symbol: lua_tointeger`.

3. **Configure httpd.conf**

   ```apache
   # Load mod_lua
   LoadModule lua_module modules/mod_lua.so

   # Lua package paths (adjust for your distro)
   LuaPackagePath /usr/share/lua/5.1/?.lua
   LuaPackagePath /usr/share/lua/5.1/?/init.lua
   LuaPackageCPath /usr/lib/lua/5.1/?.so

   # Centinel module path
   LuaPackagePath /usr/local/lib/lua/?.lua

   # Pass environment variables to Lua
   PassEnv CENTINEL_SECRET_KEY
   PassEnv CENTINEL_VALIDATOR_URL
   PassEnv CENTINEL_DEBUG

   # Persist Lua state across requests (required for connection reuse)
   LuaScope server

   # Centinel access checker — runs on every request
   LuaHookAccessChecker /usr/local/lib/lua/centinel-handler.lua access_check early
   ```

   > **LuaScope server is required:** Without `LuaScope server`, Apache creates a fresh Lua state per request. The module reuses a persistent HTTP/2 connection to the validator API. Dropping that state on every request forces a new TLS handshake per validation.

4. **Set your secret key and restart**

   ```bash
   export CENTINEL_SECRET_KEY="sk_live_your_key_here"
   apachectl configtest && apachectl restart
   ```

   For systemd:

   ```ini
   [Service]
   Environment="CENTINEL_SECRET_KEY=sk_live_your_key_here"
   ```

### Docker

```dockerfile
FROM alpine:3.21

RUN apk add --no-cache \
    apache2 \
    apache2-lua \
    apache2-proxy \
    lua5.1-curl \
    lua5.1-socket \
    lua5.1-cjson \
    ca-certificates

RUN mkdir -p /run/apache2

RUN wget -q -O /tmp/centinel-apache.zip \
    https://docs.centinelanalytica.com/downloads/centinel-apache.zip && \
    unzip /tmp/centinel-apache.zip -d /usr/local/lib/lua/ && \
    rm /tmp/centinel-apache.zip

COPY httpd.conf /etc/apache2/httpd.conf

EXPOSE 80
CMD ["httpd", "-D", "FOREGROUND", "-f", "/etc/apache2/httpd.conf"]
```

```bash
docker run -e CENTINEL_SECRET_KEY="sk_live_xxx" -p 80:80 your-image
```

## Configure

**Path protection**

All paths are protected by default except static assets. Override in `centinel.init()`:

```lua
centinel.init({
    secret_key = os.getenv("CENTINEL_SECRET_KEY"),
    protected_paths = { "^/api/", "^/admin" },  -- empty = protect all
    unprotected_paths = { "^/health$", "^/metrics$" }
})
```

Excluded by default: images (`.gif`, `.ico`, `.jpg`, `.jpeg`, `.png`, `.svg`, `.webp`, `.avif`, `.bmp`), fonts (`.eot`, `.otf`, `.ttf`, `.woff`, `.woff2`), styles (`.css`, `.less`), scripts (`.js`, `.map`), media (`.mp3`, `.mp4`, `.webm`, `.wav`, `.flac`, and others), archives (`.gz`, `.zip`), and `.json`, `.xml`.

**Timeouts**

```lua
centinel.init({
    secret_key = os.getenv("CENTINEL_SECRET_KEY"),
    timeout_ms = 500,          -- default: 500
    connect_timeout_ms = 300,  -- default: 300
})
```

> **This module always fails open:** If the validator is unreachable, slow, or returns an error, the request is allowed through. There is no fail-closed mode and no configurable backoff. If you need requests denied during a validator outage, use a different integration.

**Debug**

```lua
centinel.init({
    secret_key = os.getenv("CENTINEL_SECRET_KEY"),
    debug = true
})
```

Or set `CENTINEL_DEBUG=true` as an environment variable (requires `PassEnv CENTINEL_DEBUG` in httpd.conf).

Check the error log for `[Centinel]` entries:

```bash
tail -f /var/log/apache2/error.log | grep Centinel
```

**Custom handler**

Replace `centinel-handler.lua` with your own handler to control initialization directly:

```lua
local centinel = require("centinel-apache")

local initialized = false

function access_check(r)
    if not initialized then
        centinel.init({
            secret_key = r.subprocess_env["CENTINEL_SECRET_KEY"]
                or os.getenv("CENTINEL_SECRET_KEY"),
            validator_url = os.getenv("CENTINEL_VALIDATOR_URL")
                or "https://validator.centinelanalytica.com/validate",
            timeout_ms = 500,
            debug = false,
            protected_paths = { "^/api/", "^/admin" },
            unprotected_paths = { "^/health$", "^/metrics$" }
        })
        initialized = true
    end

    return centinel.access_handler(r)
end
```

Point `LuaHookAccessChecker` to your custom handler file.

### Configuration reference

| Option               | Type    | Default                                            | Description                                                                                      |
| -------------------- | ------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `secret_key`         | string  | —                                                  | API key from the [dashboard](https://docs.centinelanalytica.com/install/dashboard.md). Required. |
| `validator_url`      | string  | `https://validator.centinelanalytica.com/validate` | Validator endpoint.                                                                              |
| `timeout_ms`         | number  | `500`                                              | Request timeout (ms).                                                                            |
| `connect_timeout_ms` | number  | `300`                                              | Connection timeout (ms).                                                                         |
| `ssl_verify`         | boolean | `true`                                             | Verify SSL certificates.                                                                         |
| `debug`              | boolean | `false`                                            | Verbose logging.                                                                                 |
| `log_enabled`        | boolean | `true`                                             | Enable all logging.                                                                              |
| `protected_paths`    | table   | `{}`                                               | Lua patterns to protect. Empty = protect all.                                                    |
| `unprotected_paths`  | table   | `[static assets]`                                  | Lua patterns to skip.                                                                            |

### Environment variables

| Variable                 | Description                             |
| ------------------------ | --------------------------------------- |
| `CENTINEL_SECRET_KEY`    | API key. Required.                      |
| `CENTINEL_VALIDATOR_URL` | Custom validator endpoint.              |
| `CENTINEL_DEBUG`         | Set to `true` or `1` for debug logging. |

All three require `PassEnv` directives in httpd.conf to be accessible from Lua.

## Verify

Reload Apache, then send a request that should be denied:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost/api/test
tail -f /var/log/apache2/error.log | grep Centinel
```

A `403` means enforcement is live. A `200` with nothing in the error log usually means the module
never loaded, or a Lua dependency is missing. See Troubleshooting below.

## Troubleshooting

### `module 'lcurl' not found`

The `lua-curl` apt package on Debian/Ubuntu installs without producing `lcurl.so`, so `require("lcurl")` fails. Install via luarocks instead:

```bash
apt-get install luarocks libcurl4-openssl-dev lua5.1-dev
luarocks install Lua-cURLv3 LUA_VERSION=5.1 CURL_INCDIR=/usr/include
```

### `undefined symbol: lua_tointeger`

Full error:

```text
error loading module 'lcurl' from file '/usr/local/lib/lua/5.1/lcurl.so':
    /usr/local/lib/lua/5.1/lcurl.so: undefined symbol: lua_tointeger
```

luarocks compiled `lcurl` against Lua 5.3 or 5.4 headers, but `mod_lua` uses Lua 5.1. Reinstall with the correct target:

```bash
luarocks remove Lua-cURLv3
luarocks install Lua-cURLv3 LUA_VERSION=5.1 CURL_INCDIR=/usr/include
```

### Module loads but requests time out or fail

Check that `LuaScope server` is set in `httpd.conf`. Without it, Apache creates a fresh Lua state per request, forcing a new TLS handshake to the validator on every hit. That causes severe latency and request timeouts under load.

```apache
LuaScope server
```

### Protection appears to do nothing

The module loads its dependencies defensively, so a missing Lua library disables protection rather
than erroring. Both failures are silent in normal operation:

* Without `lcurl`, no validator call is made and every request is allowed. Look for `[Centinel] HTTP backend` in the error log.
* Without `mime` (from luasocket), base64 decoding always fails, so every interstitial challenge turns into an allow. Blocks still serve a generic fallback page.

Check the module loaded and both libraries resolved:

```bash
grep -i version /usr/local/lib/lua/centinel-apache.lua
tail -f /var/log/apache2/error.log | grep Centinel
```

### Only one Set-Cookie header is sent

`mod_lua` can set a response header but not append to it, so the module emits at most one
`Set-Cookie` and logs the rest as dropped. If a challenge needs more than one cookie, this platform
cannot deliver it.

## Changelog

* **v1.2.0** — Failover backoff fix
* **v1.1.1** — Response header passthrough
* **v1.1.0** — HTTP/2 via lcurl
* **v1.0.0** — Initial release

---

# HAProxy

> Bot protection for HAProxy 2.4+ using SPOE and Lua hooks.

Source: https://docs.centinelanalytica.com/platforms/web-server/haproxy

## Overview

Centinel integrates with HAProxy via the SPOE (Stream Processing Offload Engine) filter. HAProxy sends request metadata to the Centinel SPOA over SPOP, receives a decision, and Lua hooks enforce it — routing blocked or challenged requests to the built-in block service before they reach your backend.

## Prerequisites

* Secret key from your [dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
* HAProxy 2.4+ compiled with Lua 5.3 and SPOE support

## Install

1. **Download and extract the module**

   Download [centinel-haproxy.zip](https://docs.centinelanalytica.com/downloads/centinel-haproxy.zip) and extract the three files to your HAProxy configuration directory:

   ```bash
   curl -O https://docs.centinelanalytica.com/downloads/centinel-haproxy.zip
   unzip centinel-haproxy.zip -d /etc/haproxy/lua/
   mv /etc/haproxy/lua/spoe-centinel.conf /etc/haproxy/
   ```

   The zip contains:

   * `centinel-spoe.lua` — Lua hooks for request routing, response headers, and block pages
   * `json.lua` — JSON encoder/decoder used by the Lua hooks
   * `spoe-centinel.conf` — SPOE filter configuration

2. **Configure haproxy.cfg**

   ```yaml
   global
       lua-prepend-path /etc/haproxy/lua/?.lua
       lua-load /etc/haproxy/lua/centinel-spoe.lua

   defaults
       mode http
       timeout connect 5s
       timeout client 30s
       timeout server 30s

   frontend http-in
       bind *:80
       filter spoe engine centinel config /etc/haproxy/spoe-centinel.conf
       http-request lua.centinel-request-hook
       http-response lua.centinel-response-hook
       use_backend centinel-block if { var(txn.centinel_status) -m str blocked }
       default_backend servers

   backend servers
       server app1 127.0.0.1:8080 check

   backend centinel-block
       http-request use-service lua.centinel-block-service

   backend spoe-centinel
       mode tcp
       server spoa validator.centinelanalytica.com:9000 ssl sni str(validator.centinelanalytica.com) verify required verifyhost validator.centinelanalytica.com ca-file /etc/ssl/certs/ca-certificates.crt
   ```

   > **The defaults block is required:** Centinel's hooks are HTTP-mode rules. Without `mode http`, HAProxy discards every `http-request` and `http-response` line, reports the config as valid, starts normally, and enforces nothing. Run `haproxy -c -f /etc/haproxy/haproxy.cfg` and read the warnings: a line saying rules were "ignored for frontend" means protection is off.

   > **Fail-open by design:** If the SPOA is unreachable or doesn't respond within `timeout processing` (500ms default), HAProxy lets the request through. A down SPOA never blocks traffic.

   `verifyhost` and `sni` are not optional. The secret key travels on this connection as a SPOE
   argument, and `verify required` on its own checks the certificate chain without checking the
   hostname.

3. **Set your secret key and reload**

   ```bash
   export CENTINEL_SECRET_KEY="sk_live_your_key_here"
   haproxy -f /etc/haproxy/haproxy.cfg -sf $(cat /var/run/haproxy.pid)
   ```

   For systemd:

   ```ini
   [Service]
   Environment="CENTINEL_SECRET_KEY=sk_live_your_key_here"
   ```

## Configure

### How it works

HAProxy's SPOE filter sends request metadata to the hosted SPOA over SPOP. The SPOA validates the request and returns a decision. Lua hooks then route the request:

* **allow / not\_matched** — request goes to your backend. Response headers and cookies from the validator get applied on the way out.
* **block / redirect** — request hits the `centinel-block-service` Lua applet, which serves the block page or challenge HTML.

Static assets (images, fonts, CSS, JS, media files) are excluded by an ACL in `spoe-centinel.conf` and never reach the SPOA.

**SPOE timeouts**

Timeouts are configured in `spoe-centinel.conf`:

```text
spoe-agent centinel-agent
  timeout hello 500ms
  timeout idle 30s
  timeout processing 500ms
```

| Timeout              | Default | Description                                                                                                           |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `timeout processing` | `500ms` | Max wait for the SPOA response. If exceeded, request is allowed (fail-open). Increase if you see frequent timeouts.   |
| `timeout hello`      | `500ms` | TLS + SPOP handshake timeout. Only matters on first connection — subsequent requests reuse the persistent connection. |
| `timeout idle`       | `30s`   | Idle connection timeout before HAProxy drops the SPOA connection.                                                     |

**Static asset bypass**

Static files are excluded by the `static_file` ACL in the `spoe-message` section of `spoe-centinel.conf`. These requests skip the SPOE pipeline entirely.

Default exclusions: `.avi`, `.avif`, `.bmp`, `.css`, `.eot`, `.flac`, `.flv`, `.gif`, `.gz`, `.ico`, `.jpeg`, `.jpg`, `.js`, `.less`, `.map`, `.mka`, `.mkv`, `.mov`, `.mp3`, `.mp4`, `.mpeg`, `.mpg`, `.ogg`, `.ogm`, `.opus`, `.otf`, `.png`, `.svg`, `.svgz`, `.swf`, `.ttf`, `.wav`, `.webm`, `.webp`, `.woff`, `.woff2`.

Edit the `path_reg` ACL in `spoe-centinel.conf` to add or remove extensions.

**Path exclusions**

Path exclusions belong in `spoe-centinel.conf`, next to the `static_file` ACL. Add your own ACL in
the `spoe-message` section and extend the event condition:

```text
[centinel]

spoe-message check-centinel
    args secret_key=str(...) url=... method=... ip=... cookie=... referrer=... headers=...
    acl static_file path_reg \.(css|js|png|jpg|woff2)$
    acl no_centinel path_beg /health /metrics /internal/
    event on-frontend-http-request unless static_file or no_centinel
```

> **A frontend ACL is not enough:** Adding `unless no_centinel` to the `http-request` hooks in `haproxy.cfg` only skips enforcement. HAProxy filters take no conditions, so the SPOE event still fires and the request is still sent to the SPOA and on to `/validate`. Excluding a path from the event, as above, is what actually keeps it out of the pipeline.

### Configuration reference

#### Environment variables

| Variable              | Description                                                                                      |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `CENTINEL_SECRET_KEY` | API key from the [dashboard](https://docs.centinelanalytica.com/install/dashboard.md). Required. |

#### HAProxy config directives

| Directive                                  | Purpose                                             |
| ------------------------------------------ | --------------------------------------------------- |
| `lua-prepend-path`                         | Path to Lua module directory                        |
| `lua-load`                                 | Loads the Centinel Lua hooks at startup             |
| `filter spoe`                              | Activates the SPOE filter with `spoe-centinel.conf` |
| `http-request lua.centinel-request-hook`   | Routes requests based on SPOA decision              |
| `http-response lua.centinel-response-hook` | Applies response headers/cookies on allow           |
| `use_backend centinel-block`               | Routes blocked requests to the block service        |
| `backend spoe-centinel`                    | TLS+TCP backend pointing to the hosted SPOA         |

## Verify

Check the config first, and read the warnings rather than only the exit status:

```bash
haproxy -c -f /etc/haproxy/haproxy.cfg
```

Any warning that `http-request` or `http-response` rules were "ignored for frontend" means the
frontend is in TCP mode and Centinel is doing nothing. Add the `defaults` block from Install.

Then reload and send a request that should be denied:

```bash
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost/
```

If everything is allowed, the usual causes are a missing `mode http`, a failed SPOA TLS handshake, or
`timeout processing` being exceeded, which fails open by design.

## Changelog

* **v1.1.0** — TLS for SPOA connection
* **v1.0.0** — Initial release

---

# Varnish

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

Source: https://docs.centinelanalytica.com/platforms/web-server/varnish

## 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. Blocked and challenged requests get a synthetic page. Allowed requests continue into your own VCL, so your backends, directors, and cache policy apply unchanged.

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 in front of `validator.centinelanalytica.com` and point the `validator` backend at it over plain HTTP on localhost. Reuse an nginx or HAProxy you already run, or add a ghostunnel sidecar; the install steps show both. Varnish Enterprise users can use a native TLS backend and skip the proxy. hitch won't work here: it only terminates inbound TLS and can't originate the outbound TLS this leg needs.

## Prerequisites

* Secret key from your [dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
* Varnish Cache 6.0 LTS (open source) or Varnish Enterprise 6, plus the matching `varnish-dev` headers. Distro-stock Varnish 6.5 and 7.x are not supported: the VMOD is built with a strict ABI, so rebuild it after any Varnish upgrade.
* Build tools: `autoconf`, `automake`, `libtool`, `pkg-config`, `python3-docutils`
* A local TLS proxy for the HTTPS validator (an existing nginx/HAProxy, or a ghostunnel sidecar)
* A configured origin backend

## Install

1. **Download and extract the package**

   Download [centinel-varnish.zip](https://docs.centinelanalytica.com/downloads/centinel-varnish.zip) and extract it:

   ```bash
   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 Centinel VCL, which you include from your own VCL
   * `example.vcl`: a minimal site VCL that includes it
   * `src/`: source for the `libvmod_centinel` VMOD, which decodes block pages
   * `autogen.sh`, `configure.ac`, `Makefile.am`: the autotools build files

2. **Build and install the VMOD**

   Debian and Ubuntu ship a newer Varnish and no `varnish-dev` package, so add the 6.0 LTS
   repository and pin it. Without the pin, Debian 12 and Ubuntu 24.04 install their own
   Varnish 7 and fail with `varnish-dev : Depends: varnish (= 6.0.x)`. Then install the build
   tools and build:

   ```bash
   curl -s https://packagecloud.io/install/repositories/varnishcache/varnish60lts/script.deb.sh \
     | sudo bash

   printf 'Package: varnish varnish-dev\nPin: origin packagecloud.io\nPin-Priority: 1001\n' \
     | sudo tee /etc/apt/preferences.d/varnish60lts

   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.

3. **Run a TLS proxy to the validator**

   Open-source Varnish can't speak TLS to a backend, so a local proxy accepts plain HTTP on `127.0.0.1:8443` and originates TLS (with SNI) to the validator. All three options keep the validator connection warm under load; pick by what's already on the host.

   **Reuse nginx/HAProxy (recommended)**

   If the host already runs nginx (or HAProxy), add a TLS-originating proxy. There's no extra daemon to run, and it used the least CPU and memory in our benchmark. The `keepalive`, `proxy_ssl_session_reuse` and `Connection ""` lines keep the upstream TLS connection warm. Don't drop `proxy_ssl_verify` or `proxy_ssl_name`: without them nginx sends the upstream group name as SNI and accepts any certificate, so anyone on the network path could pose as the validator and read your API key.

   ```nginx
   # nginx.conf
   upstream centinel_validator { server validator.centinelanalytica.com:443; keepalive 16; }
   server {
     listen 127.0.0.1:8443;
     location / {
       proxy_pass https://centinel_validator;
       proxy_ssl_server_name on;                              # SNI
       proxy_ssl_name validator.centinelanalytica.com;        # SNI defaults to the upstream name, not the host
       proxy_ssl_verify on;                                   # verify the validator's cert
       proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt;
       proxy_ssl_verify_depth 3;
       proxy_ssl_session_reuse on;
       proxy_http_version 1.1;
       proxy_set_header Connection "";
       proxy_set_header Host validator.centinelanalytica.com;
     }
   }
   ```

   HAProxy equivalent: a backend with `server centinel validator.centinelanalytica.com:443 ssl sni str(validator.centinelanalytica.com) verify required ca-file /etc/ssl/certs/ca-certificates.crt` plus `http-reuse always`.

   **ghostunnel sidecar**

   [ghostunnel](https://github.com/ghostunnel/ghostunnel) is a maintained single-binary TLS proxy (Prometheus metrics, cert hot-reload, graceful restart):

   ```bash
   ghostunnel client \
     --listen 127.0.0.1:8443 \
     --target validator.centinelanalytica.com:443 \
     --disable-authentication   # present no client cert; the server cert is still verified
   ```

   The connection stays warm as long as Varnish keeps its (pooled) front-side connection open.

   **stunnel (legacy)**

   stunnel works too, though it used the most CPU of the options we measured:

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

   [centinel]
   client      = yes
   accept      = 127.0.0.1:8443
   connect     = validator.centinelanalytica.com:443
   sni         = validator.centinelanalytica.com
   verifyChain = yes                                   # sni alone does not verify the cert
   checkHost   = validator.centinelanalytica.com
   CAfile      = /etc/ssl/certs/ca-certificates.crt
   ```

   ```bash
   stunnel /etc/stunnel/centinel.conf
   ```

4. **Configure centinel.vcl**

   Copy `centinel.vcl` next to your VCL (for example `/etc/varnish/`) and edit it:

   1. Point the `validator` backend at the TLS proxy (`127.0.0.1:8443`).
   2. Set your secret key in `vcl_backend_fetch` (`set bereq.http.X-API-Key = "...";`).
   3. List the proxies in front of Varnish in `acl centinel_trusted_proxy` (see
      [Client IP behind a proxy](#client-ip-behind-a-proxy)).

   ```c
   backend validator {
       .host = "127.0.0.1";
       .port = "8443";
       .max_connections     = 200;
       .connect_timeout     = 3s;
       .first_byte_timeout  = 5s;
       .between_bytes_timeout = 2s;
   }
   ```

   Keep the three timeouts. Varnish defaults `first_byte_timeout` to 60s, so without them a hung
   validator stalls each client request for a minute instead of failing open in five seconds.

5. **Include it from your VCL**

   Add one line to your site VCL, after your backend declarations and before your own
   subroutines:

   ```c
   vcl 4.1;

   backend origin { .host = "127.0.0.1"; .port = "8080"; }   # your first backend stays the default

   include "centinel.vcl";

   sub vcl_recv { ... }   # your routing, directors and cache policy, unchanged
   ```

   Varnish runs same-named subroutines in include order, so Centinel validates the request
   first and then hands the original request to your `vcl_recv`. No site VCL yet? Start from
   the bundled `example.vcl`.

   Declare your backends before the include. Varnish uses the first backend declared as the
   default, and that must be your origin, not `validator`.

6. **Load it**

   ```bash
   varnishd -f /etc/varnish/default.vcl -a :80 -s malloc,256m \
     -p workspace_client=256k -p workspace_backend=256k \
     -p http_resp_hdr_len=96k -p http_resp_size=128k
   ```

   Or on a running instance:

   ```bash
   varnishadm vcl.load centinel /etc/varnish/default.vcl && varnishadm vcl.use centinel
   ```

   The four `-p` values let a block page up to the validator's 64k cap through. With the
   defaults, a page over about 23k fails the validator fetch and the request is allowed.

## Configure

### How it works

On every request, the VCL:

1. Bypasses static assets. The regex in `centinel_validate` matches the path only, so a query
   string or `;` parameter cannot fake an extension. Varnish caches these as usual.
2. Validates `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`, and `OPTIONS`. Other methods,
   such as `PURGE` and `BAN`, and ESI fragments go straight to your VCL.
3. Buffers a request body up to 1 MB so it still reaches your origin after the validator hop.
   A larger body gets `413`.
4. Rejects a malformed `Host` header with `400`, because the validator cannot parse the URL.
5. Reads the decision from `x-centinel-*` response headers. `centinel.b64decode()` decodes the
   block or challenge page.
6. Applies the decision:
   * `allow`: the original request continues into your `vcl_recv`
   * `block`: 403 and the block page
   * `redirect`: the challenge page
7. Forwards the validator's first `Set-Cookie` and a fixed set of response headers
   (`Content-Type`, `Cache-Control`, `X-Content-Type-Options`, `X-Frame-Options`,
   `Content-Security-Policy`, `Referrer-Policy`).

The client's `Cookie` (other than `_centinel`) and `Authorization` headers are never sent to
the validator. Your origin still receives them.

> **Caching and the validator:** Allowed requests follow your own cache policy, so cached pages stay cached and your origin
> sees no extra traffic. The validator is still called on every protected request, including
> cache hits, so a bot cannot read a cached page. Each allowed request costs one internal
> restart. Directors, multiple storage backends, ESI, and tiered Varnish setups work unchanged.

### Client IP behind a proxy

Varnish takes the client address from the TCP connection. If a TLS terminator, load balancer,
or another Varnish sits in front, add its address to `acl centinel_trusted_proxy` in
`centinel.vcl`. For a trusted peer, the VCL reads the client IP from the last
`X-Forwarded-For` entry that peer added and honours `X-Forwarded-Proto: https`. For any other
peer, both headers are ignored, so a client cannot choose the IP the validator scores.

```c
acl centinel_trusted_proxy {
    "127.0.0.1";
    "::1";
    "10.0.0.0"/8;   # your load balancers
}
```

Pure VCL cannot modify a response body, so this integration does not inject the browser script. Add
the [script tag](https://docs.centinelanalytica.com/install/scripts.md) to your HTML yourself, or use Fastly Compute if you want it
injected for you.

### Configuration reference

| Setting              | Where                                               | Default               |
| -------------------- | --------------------------------------------------- | --------------------- |
| Secret key           | `vcl_backend_fetch` → `X-API-Key`                   | none, required        |
| Origin backend       | your VCL, declared before the include               | your app              |
| Validator backend    | `backend validator`                                 | TLS proxy → validator |
| Trusted proxies      | `acl centinel_trusted_proxy`                        | localhost             |
| Protected paths      | `centinel_validate` static-asset regex              | static assets bypass  |
| Block/challenge page | from the validator (`x-centinel-response-html-b64`) | served via `synth`    |

### Keep-alive & tuning

Varnish pools the localhost hop to the proxy on its own (`.max_connections` on the `validator` backend). The proxy has to keep its upstream TLS connection open so the handshake happens once, not on every request. nginx does this with `keepalive` and `proxy_ssl_session_reuse`, HAProxy with `http-reuse always`. stunnel and ghostunnel stay warm as long as Varnish keeps its pooled connection to them.

On low-traffic sites, Varnish closes idle backend connections after `backend_idle_timeout` (60s by default). Raise it, for example `-p backend_idle_timeout=300`, so a quiet spell doesn't cost a fresh TLS handshake.

The block or challenge page arrives in a response header (`x-centinel-response-html-b64`). Varnish caps a single header (`http_resp_hdr_len`, 8k by default) and all headers together (`http_resp_size`, 32k by default). If the page goes over either, the fetch fails and the request is let through, so keep the four `-p` values from the launch command. The validator never sends more than 64k of HTML; a bigger page is replaced with a short generic one.

Varnish keeps at most 64 headers per request (`http_max_hdr`). A request that comes close is refused instead of reaching the validator without its key. If real clients send more than about 40 headers, raise `-p http_max_hdr`.

The cookie attributes are fixed. The VCL forwards only the first cookie, as `Path=/; HttpOnly; SameSite=Lax; Max-Age=86400`, and adds `Secure` when the request came in over HTTPS. The validator's own attributes are dropped on this platform.

## Verify

Confirm the VCL loaded, watch the validator hop, then send a request that should be denied:

```bash
varnishadm vcl.list
varnishlog -g request -q 'ReqURL eq "/validate"'
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost/
```

If the VMOD will not load, it was built against a different Varnish version; rebuild it. If
everything is allowed, check that the validator backend is healthy and that
`http_resp_hdr_len` is large enough for your block page, since an oversized header fails the fetch
and the request is let through.

## Changelog

* **v1.1.0** — Includable VCL, bypass fixes
* **v1.0.1** — TLS proxy and keep-alive guidance
* **v1.0.0** — Initial release

---

# Next.js

> Add Centinel Analytica to your Next.js application.

Source: https://docs.centinelanalytica.com/platforms/application/nextjs

## Overview

Centinel validates each request before it reaches your application. Suspicious requests are blocked or redirected to a verification page. The client script helps distinguish legitimate users from bots.

Blocked requests are redirected to `/block` and challenges to `/interstitial`. Create both pages in your app. Neither path is configurable in the current release.

## Prerequisites

* Site key (public, used by the browser script)
* Secret key (server-only, used for validation)
* Next.js 13 or later with the App Router, React 18+, and Node.js 18+
* A `/block` page and an `/interstitial` page in your app. The middleware sends visitors to these paths, and neither path is configurable.

## Install

In your Next.js project:

```bash
npm install @centinel/nextjs
```

## Configure

1. **Environment variables**

   Add your Centinel keys to `.env`:

   ```bash
   CENTINEL_SITE_KEY=YOUR_SITE_KEY
   CENTINEL_SECRET_KEY=YOUR_SECRET_KEY
   NEXT_PUBLIC_CENTINEL_SITE_KEY=YOUR_SITE_KEY
   ```

   > **Key safety:** Use `CENTINEL_SECRET_KEY` server-side only. Don't expose it to the browser.

   > **Which site key to use:** Use `CENTINEL_SITE_KEY` for server-side code (layouts, middleware). Use{' '}
   > `NEXT_PUBLIC_CENTINEL_SITE_KEY` if using `CentinelLayout` in client-side pages.

2. **Client script**

   Add CentinelLayout to your root layout:

   ```typescript
   // app/layout.tsx (server-side)
   import { CentinelLayout } from '@centinel/nextjs';

   export default function RootLayout({
     children,
   }: {
     children: React.ReactNode;
   }) {
     return (
       <html>
         <body>
           <CentinelLayout siteKey={process.env.CENTINEL_SITE_KEY!}>
             {children}
           </CentinelLayout>
         </body>
       </html>
     );
   }
   ```

   Or if using in a client-side page:

   ```typescript
   // app/page.tsx (client-side)
   'use client';
   import { CentinelLayout } from '@centinel/nextjs';

   export default function HomePage(): React.JSX.Element {
     return (
       <CentinelLayout siteKey={process.env.NEXT_PUBLIC_CENTINEL_SITE_KEY!}>
         {/* Your page content */}
       </CentinelLayout>
     );
   }
   ```

3. **Protection**

   Choose between automatic middleware or manual validation:

   **Middleware (recommended)**

   Create `middleware.ts` in your project root. On Next.js 16 the file is `proxy.ts` and the export is `proxy` instead; run `npx @next/codemod@canary middleware-to-proxy` to convert.

   ```typescript
   import type { NextRequest } from 'next/server';
   import { createCentinelMiddlewareFromEnv } from '@centinel/nextjs';

   const centinel = createCentinelMiddlewareFromEnv();

   export default async function middleware(request: NextRequest) {
     const result = await centinel(request);
     return result.response;
   }

   export const config = {
     matcher: ['/api/:path*', '/dashboard/:path*']
   };
   ```

   > **Return result.response, not the handler:** `createCentinelMiddlewareFromEnv()` returns a function resolving to a `CentinelResult` object, not a `Response`. Exporting it directly makes Next.js reject the return value and every matched request fails with a 500.

   > **Next.js 16 ignores middleware.ts:** Next.js 16 replaced the `middleware` convention with `proxy.ts`. A leftover `middleware.ts` is skipped at build time without an error, so protection silently stops running after the upgrade.

   **Manual validation**

   Use in specific API routes when middleware doesn't fit:

   ```typescript
   // app/api/login/route.ts
   import { createRequestValidatorFromEnv } from '@centinel/nextjs';
   import { NextRequest, NextResponse } from 'next/server';

   const { isBot } = createRequestValidatorFromEnv();

   export async function POST(request: NextRequest) {
     if (await isBot(request)) {
       return NextResponse.json({ error: 'Blocked' }, { status: 403 });
     }
     return handleLogin(request);
   }
   ```

   Or with custom configuration:

   ```typescript
   // app/api/protected/route.ts
   import { createRequestValidator } from '@centinel/nextjs';
   import { NextRequest, NextResponse } from 'next/server';

   const { isBot } = createRequestValidator({
     siteKey: 'YOUR_SITE_KEY',
     secretKey: 'YOUR_SECRET_KEY'
   });

   export async function POST(request: NextRequest) {
     if (await isBot(request)) {
       return NextResponse.json({ error: 'Access denied' }, { status: 403 });
     }
     
     // Your protected logic
   }
   ```

### Custom configuration

Pass config directly instead of using environment variables:

```typescript
import type { NextRequest } from 'next/server';
import { createCentinelMiddleware } from '@centinel/nextjs';

const centinel = createCentinelMiddleware({
  siteKey: 'YOUR_SITE_KEY',
  secretKey: 'YOUR_SECRET_KEY',
  timeout: 500,
});

export default async function middleware(request: NextRequest) {
  return (await centinel(request)).response;
}
```

The validator call times out after 500ms by default and fails open. After repeated failures the
middleware stops calling the validator at all, backing off from one second up to five minutes, so a
sustained outage leaves traffic unvalidated for that window.

### Route matching

Specify which routes to protect:

```typescript
export const config = {
  matcher: [
    '/api/:path*',        // All API routes
    '/dashboard/:path*',  // Dashboard pages
    '/admin/:path*'       // Admin area
  ]
};
```

## Verify

Run the dev server with debug output on and load a protected route:

```bash
DEBUG=centinel:* next dev
```

Look for `Validation completed in Nms`. Then confirm in your browser's dev tools that a `_centinel`
cookie is set and that `script.js` is requested from the collector host.

If every request is allowed, check the secret key first: a 4xx from the validator logs
`Validator service responded with 401` and then fails open. If requests hang or 500 instead, confirm
that `/block` and `/interstitial` both exist, and on Next.js 16 that your file is named `proxy.ts`.

## Changelog

* **v1.2.2** — Response header passthrough

---

# ASP.NET Core

> Add Centinel Analytica to your ASP.NET Core application.

Source: https://docs.centinelanalytica.com/platforms/application/aspnet-core

## Overview

The Centinel middleware runs before your endpoints, sending request metadata to the validator API. The validator decides if the request should be allowed, blocked, redirected, or didn't match any protected path. Blocked and challenged responses are rendered from HTML the validator returns, so that traffic never reaches your endpoints. Two cases do fall through to your app: a challenge that arrives without HTML, and a misconfigured `CentinelConfiguration` section.

## Prerequisites

* .NET 9.0 SDK or later (the package targets `net9.0`)
* NuGet package access
* Centinel secret key (from the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md))

## Install

In your ASP.NET Core project:

```bash
dotnet add package Centinel.AspNetCore
```

## Configure

1. **Configuration**

   Add your Centinel settings to `appsettings.json` (or any other configuration provider):

   ```json
   {
     "CentinelConfiguration": {
       "SecretKey": "YOUR_SECRET_KEY",
       "ValidatorApiUrl": "https://validator.centinelanalytica.com/validate",
       "ProtectedPaths": ["/api", "/dashboard"],
       "ExcludedPaths": ["/health", "/static"],
       "FailOpen": true
     }
   }
   ```

   | Property          | Type       | Required | Default                                            | Description                                                                                         |
   | ----------------- | ---------- | -------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
   | `SecretKey`       | `string`   | Yes      | –                                                  | Secret key for the validator API.                                                                   |
   | `ValidatorApiUrl` | `string`   | No       | `https://validator.centinelanalytica.com/validate` | Validator endpoint URL.                                                                             |
   | `ProtectedPaths`  | `string[]` | No       | –                                                  | Routes to validate. If empty, all routes are protected.                                             |
   | `ExcludedPaths`   | `string[]` | No       | –                                                  | Routes to skip validation on.                                                                       |
   | `FailOpen`        | `boolean`  | No       | `true`                                             | If `false`, return 503 with `Service temporarily unavailable` when the Centinel API is unreachable. |
   | `RequestTimeout`  | `TimeSpan` | No       | `00:00:05`                                         | Validator request timeout.                                                                          |
   | `EnableLogging`   | `boolean`  | No       | `true`                                             | Emit validator request and response logs.                                                           |
   | `CookieName`      | `string`   | No       | `_centinel`                                        | Session cookie the middleware reads.                                                                |

   `ProtectedPaths` and `ExcludedPaths` are case-insensitive prefix matches with no wildcards, and
   exclusions always win. A prefix of `/api` therefore also matches `/apiary`, so add a trailing
   slash (`/api/`) when you mean a path segment.

2. **Register services**

   Register Centinel in `Program.cs`:

   ```csharp
   using Centinel.AspNetCore.Extensions;

   var builder = WebApplication.CreateBuilder(args);

   builder.Services.AddCentinel(builder.Configuration);
   // Or configure manually:
   // builder.Services.AddCentinel(options =>
   // {
   //     options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
   //     options.ProtectedPaths = new() { "/api", "/admin" };
   // });

   var app = builder.Build();
   ```

3. **Add middleware**

   Put the Centinel middleware in your request pipeline before endpoint execution:

   ```csharp
   using Centinel.AspNetCore.Extensions;

   app.UseCentinel();
   app.UseRouting();
   app.UseAuthentication();
   app.UseAuthorization();

   app.MapControllers();
   ```

   Put `UseCentinel()` first. The middleware reads `context.Request.Path` directly and needs no routing
   data, so placing it ahead of routing and auth keeps unwanted traffic away from that work entirely.

   > **Confirm the config actually bound:** If the `CentinelConfiguration` section is missing or misspelled, the middleware allows every request and logs `Centinel configuration is invalid. Requests will be allowed through.` The check runs per request, not at startup, so send a request first and then read the logs. Nothing appears in your startup output either way, and under production traffic this line repeats on every request.

   The NuGet package does not inject the browser script. Add the [script tag](https://docs.centinelanalytica.com/install/scripts.md)
   to `_Layout.cshtml` yourself if you want browser-side signals.

### Middleware

With `app.UseCentinel()`, every matching request is validated automatically. Use `ProtectedPaths` and `ExcludedPaths` in your configuration to control which routes get checked.

Inject `ICentinelValidator` to apply Centinel only where you need it (e.g. sensitive APIs) without middleware-wide protection.

### Custom validator endpoint

Override the validator URL or request timeout if you're using a self-hosted validator:

```csharp
builder.Services.AddCentinel(options =>
{
    options.SecretKey = Environment.GetEnvironmentVariable("CENTINEL_SECRET_KEY")!;
    options.ValidatorApiUrl = "https://validator.yourdomain.com/validate";
    options.RequestTimeout = TimeSpan.FromSeconds(10);
});
```

### Deployment notes

Make sure your production configuration or environment variables include the `CentinelConfiguration` values (especially `SecretKey` and any custom validator URL). Restart your app after updating keys so the middleware picks up the new settings.

## Verify

With `EnableLogging` on and the log level at `Debug`, curl an excluded path and then a protected one.
A protected request logs `Sending validation request to Centinel API for URL: {Url}` followed by
`Received validation response: {Decision}`.

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:5000/health
curl -s -o /dev/null -w '%{http_code}\n' -A 'python-requests/2.31' http://localhost:5000/api/items
```

Four log lines tell you what went wrong when it doesn't work:

| Log line                                             | Meaning                                                 |
| ---------------------------------------------------- | ------------------------------------------------------- |
| `Centinel configuration is invalid`                  | The config section did not bind. Everything is allowed. |
| `Centinel API returned status {StatusCode}`          | Usually a wrong secret key.                             |
| `Centinel API request timed out for URL`             | Raise `RequestTimeout`, or check egress.                |
| `Centinel API unavailable, allowing request through` | Fail-open engaged.                                      |

The repo ships a runnable demo under `demo/` with public and protected routes if you want to see all
of this without touching your own app.

## Changelog

* **v1.0.1** — Response header passthrough

---

# Azure Functions

> Deploy Centinel Analytica using Azure Functions for request validation.

Source: https://docs.centinelanalytica.com/platforms/application/azure-functions

## Overview

This guide deploys Centinel as an Azure Function that validates incoming requests. Two modes are available:

* **Validation-only mode**: Function validates and returns allow/block decisions. Use as a standalone validation endpoint.
* **Reverse proxy mode**: Function validates and proxies allowed traffic to your backend.

Deployment takes 5-10 minutes.

## Prerequisites

* Centinel secret key
* Azure subscription with permissions to create Function Apps
* Backend application URL (your existing app)
* Azure CLI installed (optional, for CLI deployment)

## Install

1. **Download the function package**

   1. Download [`centinel-azure-functions.zip`](https://docs.centinelanalytica.com/downloads/centinel-azure-functions.zip).
   2. Extract to review contents:
      * `host.json` - Azure Functions host configuration
      * `package.json` - Node.js package metadata
      * `centinel/index.js` - Main function code
      * `centinel/function.json` - HTTP trigger bindings

2. **Create the Function App**

   1. Go to the [Azure Portal](https://portal.azure.com).
   2. Click **Create a resource** → search for **Function App** → **Create**.
   3. Configure:
      * **Subscription**: Select your subscription
      * **Resource Group**: Create new or select existing
      * **Function App name**: Pick a unique name (e.g. `centinel-middleware`)
      * **Runtime stack**: Node.js
      * **Version**: 18 or 20
      * **Region**: Pick the region closest to your backend
   4. Click **Review + create** → **Create**.
   5. Wait for deployment.

3. **Deploy the function code**

   1. In your Function App, go to **Deployment** → **Deployment Center**.
   2. For quick deployment, use **Local Git** or **Zip Deploy**:
      * **Zip Deploy**: Go to **Advanced Tools** → **Go** → **Debug console** → **CMD**
      * Navigate to `site/wwwroot`
      * Drag and drop the extracted zip contents (or use the zip file directly)
   3. Or deploy via Azure CLI (see the Configure section below).

## Configure

1. **Configure app settings**

   1. Open your Function App in the Azure Portal.
   2. Go to **Settings** → **Environment variables**.
   3. Add:

   | Name                   | Required | Value                                                                               |
   | ---------------------- | -------- | ----------------------------------------------------------------------------------- |
   | `CENTINEL_SECRET_KEY`  | Yes      | Your Centinel secret key                                                            |
   | `CENTINEL_BACKEND_URL` | No       | Your backend URL for reverse proxy mode (e.g. `https://your-app.azurewebsites.net`) |

   > **Deployment modes:** **Validation-only mode** (no `CENTINEL_BACKEND_URL`): Function returns JSON with `X-Centinel-Decision` header.
   >
   > * Allowed: `200 OK` with `{"success": true, "decision": "allow"}`
   > * Blocked: Challenge page with `429` or `403` status
   >
   > **Reverse proxy mode** (with `CENTINEL_BACKEND_URL`): Function validates and proxies allowed traffic to your backend.

   4. (Optional) Add:

   | Name                       | Default | Description                       |
   | -------------------------- | ------- | --------------------------------- |
   | `CENTINEL_TIMEOUT`         | `100`   | Validator timeout in milliseconds |
   | `CENTINEL_LOG_ENABLED`     | `true`  | Enable detailed logging           |
   | `CENTINEL_REDIRECT_STATUS` | `429`   | HTTP status for challenge pages   |
   | `CENTINEL_BLOCK_STATUS`    | `403`   | HTTP status for blocked requests  |

   5. Click **Apply** to save.

2. **Configure Azure Front Door (optional)**

   For CDN capabilities, put Azure Front Door in front of your function:

   1. Go to **Create a resource** → **Front Door and CDN profiles**.
   2. Select **Azure Front Door** → **Quick create** or **Custom create**.
   3. Configure the origin:
      * **Origin type**: App services
      * **Origin host name**: Your Function App (`centinel-middleware.azurewebsites.net`)
   4. Create a route that forwards all traffic (`/*`) to the function origin.
   5. Wait for deployment (5-10 minutes for global propagation).

### Path protection

Edit `centinel/index.js` to customize path protection (lines 50-86):

```javascript
// Protect specific paths only (empty array = protect all paths)
var CENTINEL_PROTECTED_PATHS = [
    '/admin/*',
    '/api/*',
    '/login'
];

// Skip validation for static assets (default includes common extensions)
var CENTINEL_UNPROTECTED_PATHS = [
    '*.js', '*.css', '*.png', '*.jpg', '*.gif',
    '*.woff', '*.woff2', '*.ico', '*.svg'
];
```

**Pattern examples:**

* `/admin/*` - Protects `/admin/dashboard`, `/admin/users`, etc.
* `/api/*` - Protects all API routes
* `*.js` - Excludes all JavaScript files at any path depth

Redeploy after editing.

### Deploy via Azure CLI

Deploy with Azure CLI for automation:

```bash
# Login to Azure
az login

# Create resource group
az group create --name centinel-rg --location eastus

# Create storage account (required for Functions)
az storage account create \
  --name centinelstorage \
  --resource-group centinel-rg \
  --location eastus \
  --sku Standard_LRS

# Create Function App
az functionapp create \
  --name centinel-middleware \
  --resource-group centinel-rg \
  --storage-account centinelstorage \
  --consumption-plan-location eastus \
  --runtime node \
  --runtime-version 18 \
  --functions-version 4

# Configure settings (validation-only mode)
az functionapp config appsettings set \
  --name centinel-middleware \
  --resource-group centinel-rg \
  --settings \
    CENTINEL_SECRET_KEY="sk_live_your_key_here"

# For reverse proxy mode, also add:
# CENTINEL_BACKEND_URL="https://your-backend.azurewebsites.net"

# Deploy code (from extracted zip directory)
cd centinel-azure-functions
zip -r deploy.zip .
az functionapp deployment source config-zip \
  --name centinel-middleware \
  --resource-group centinel-rg \
  --src deploy.zip
```

## Verify

* Test the function URL directly: `https://your-function.azurewebsites.net/`
* If using Front Door, test: `https://your-frontdoor.azurefd.net/`
* Check logs in **Monitor** → **Log stream** for entries prefixed with `[Centinel]`.
* Verify requests appear in your Centinel dashboard.

## Troubleshooting

### Monitoring and logs

**Application Insights:**

Enable Application Insights for detailed monitoring:

1. In your Function App, go to **Settings** → **Application Insights**.
2. Click **Turn on Application Insights**.
3. Query logs with:

```kusto
traces
| where message startswith "[Centinel]"
| order by timestamp desc
```

**Real-time logs:**

```bash
# Stream logs via Azure CLI
az functionapp log tail --name centinel-middleware --resource-group centinel-rg
```

**Log entries to look for:**

* `[Centinel] Processing request` - Request received
* `[Centinel] Validator response received` - Validation completed with timing
* `[Centinel] Allowing request` / `[Centinel] Blocking request` - Decision applied
* `[Centinel] Validation-only mode: request allowed` - Request allowed (validation-only mode)

## Changelog

* **v1.0.0** — Initial release

---

# WordPress

> Add Centinel Analytica to your WordPress website.

Source: https://docs.centinelanalytica.com/platforms/cms/wordpress

## Overview

This guide covers installing, configuring, and verifying the Centinel Analytica WordPress plugin. You'll upload the plugin ZIP, enter your keys, choose what to protect, and optionally gate uploads.

> **Get your keys first:** Go to the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
> and copy your **Site Key** and **Secret Key**.

## Prerequisites

* WordPress 5.6+ (tested up to 6.7) and PHP 8.0+
* Administrator access
* Ability to upload and activate plugins
* Server rewrite access if you enable uploads protection on nginx or IIS

## Install

1. **Download the plugin ZIP**

   [Download the WordPress plugin ZIP](https://docs.centinelanalytica.com/downloads/centinel-analytica-wordpress.zip). Keep it as a `.zip` file, don't unzip.

2. **Upload and activate the plugin**

   **WordPress Admin UI**

   1. Go to **Plugins → Add New**.
   2. Click **Upload Plugin**.
   3. Select the downloaded `centinel-analytica-wordpress.zip`.
   4. Click **Install Now**, then **Activate Plugin**.

   **WP-CLI**

   ```bash
   wp plugin install /path/to/centinel-analytica-wordpress.zip --activate
   ```

3. **Configure the plugin**

   Go to **Settings → Centinel Analytica** and fill in:

   * **Site Key** and **Secret Key** from your dashboard.
   * **Block Page URL** where blocked users land (default: `/block`).
   * **Apply protection to** the areas you want covered:
     * **Front-end pages**, **WP REST API**, **Login**, and optional **Uploads directory**.

   The Login option validates login attempts. It does not validate later requests to `/wp-admin/`.

   * **Uploads directory** protection routes `/wp-content/uploads/*` requests through the validator. Enable it only for gated downloads, premium PDFs, or media that needs bot protection.

   * **Included Paths** limits protection to specific paths (one per line, leave empty to protect everything). Supports wildcards: `/checkout`, `/api/*`, `/wp-login.php`.

   * **Excluded Paths** skips protection on matching paths (one per line, wins over included). Supports wildcards: `/api/webhook`, `/wp-content/uploads/*`, `*.jpg`.

   Click **Save Changes**.

   > **Tip:** Start with front-end, REST API, and login protection enabled. Add uploads protection only for folders that need static-file gating.

4. **Enable uploads protection (optional)**

   Turn on **Uploads directory** if you want Centinel to validate files under `/wp-content/uploads/*`.

   **Apache / LiteSpeed**

   On Apache or LiteSpeed, the plugin attempts to write the required `.htaccess` rewrite automatically when you save settings. If WordPress shows a warning, copy the `.htaccess` block from the settings panel into your site root `.htaccess` file.

   **nginx**

   Copy the nginx snippet from the settings panel into your server block, then reload nginx. The rewrite sends uploads requests to WordPress with `ca_uploads_file` so the plugin can validate and serve the file.

   **IIS**

   Copy the IIS rewrite rule from the settings panel into `<system.webServer><rewrite><rules>` in `web.config`, then reload the site.

   > **Uploads protection adds request overhead:** Every protected upload request boots WordPress and calls the validator. Use included paths to narrow protection to sensitive folders like `/wp-content/uploads/private/*`, and excluded paths to skip public images or thumbnails.

5. **Edit the block page (optional)**

   The plugin creates a `/block` page on activation. Edit it under **Pages → Access Blocked** whenever you want.

   > **Changing the URL:** Update **Block Page URL** in plugin settings to match the new permalink.

## Configure

### Script injection

On WordPress 6.3 and later, the plugin loads the [collector script](https://docs.centinelanalytica.com/install/scripts.md) in `<head>` with `async` on every front-end page and `wp-login.php`. On WordPress 5.6 through 6.2, WordPress loads the script in the footer. The plugin uses the Site Key from settings automatically. No manual script placement is needed.

A `whenCentinelReady(cb)` helper is injected after the script for theme developers who need to gate actions on collector readiness.

### Path rules

When both included and excluded paths are set:

1. Excluded match → skip (no validator call).
2. Included paths set but no match → skip.
3. Everything else → protect.

Excluded always wins over included.

### Uploads protection

The uploads toggle protects files under `/wp-content/uploads/*` by routing static-file requests through WordPress before the file is served. Included and excluded paths apply to the public uploads URL, so `/wp-content/uploads/private/*` can be protected while `/wp-content/uploads/cache/*` stays public.

The plugin serves allowed files with `Last-Modified`, `ETag`, and `Range` support so browsers can cache, resume, and stream PDFs, video, and audio. It rejects path traversal, null bytes, and script-like file extensions before validation.

If your WordPress install stores uploads outside the default location, developers can override the resolved base directory with the `centinel_uploads_basedir` filter.

### Decision handling

| Decision                | Front-end                                                                                 | REST API                                                                            | Login       | Uploads                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------- |
| `allow` / `not_matched` | Pass through                                                                              | Pass through                                                                        | Proceed     | Serve file                                                                        |
| `block`                 | Redirect to block page                                                                    | 403 JSON                                                                            | Login error | Block HTML or 403                                                                 |
| `redirect`              | Interstitial HTML when `response_html` is present. Otherwise, redirect to the block page. | HTML in JSON when `response_html` is present. Otherwise, return the block-page URL. | Login error | Challenge HTML when `response_html` is present. Otherwise, return a block status. |

## Verify

Browse your site and check **Centinel Analytica → Analytics** for incoming traffic.

## Changelog

* **v1.7.0** — Uploads directory protection
* **v1.6.1** — Response header passthrough
* **v1.6.0** — Login page script support
* **v1.5.0** — Wildcard path matching
* **v1.4.0** — Cookie forwarding
* **v1.3.0** — Auto-create block page
* **v1.2.0** — REST API protection
* **v1.1.0** — Configurable block page
* **v1.0.0** — Initial release

---

# Drupal 8+

> Add Centinel Analytica to your Drupal 8+ website.

Source: https://docs.centinelanalytica.com/platforms/cms/drupal-8

## Overview

This guide covers installing, configuring, and verifying Centinel Analytica in Drupal 8+. You'll upload a .TAR.GZ module, enter your keys, choose what to protect (front-end, REST API), and create a block page.

> **Get your keys first:** Go to the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
> and copy your **Site Key** and **Secret Key**.

## Prerequisites

* Drupal 8 or higher
* Administrator access
* Ability to upload and configure modules

## Install

1. **Download the module (.TAR.GZ)**

   [Download Drupal 8+ Module](https://docs.centinelanalytica.com/downloads/centinel_analytica-8.x-1.2.tar.gz). Keep the file compressed—don't decompress it.

2. **Upload and activate the module**

   On Drupal 10.4 and later, and on Drupal 11, core no longer offers tarball installation. Unpack
   the archive into `modules/custom/centinel_analytica`, then enable it:

   ```bash
   drush en centinel_analytica -y
   ```

   On Drupal 8 and 9 you can still use the admin UI:

   1. Log in as administrator.
   2. Go to **Extend** in the main menu.
   3. Click **Install new module**.

   <img alt="Install new module" src="__img0" />
   <img alt="Select module file" src="__img1" />

   4. Once the module is enabled, go to **Configuration → System → Centinel Analytica** (`/admin/config/security/centinel-analytica`). The `administer centinel analytica` permission is required, so grant it under **People → Permissions** if the page is not visible.

   <img alt="Centinel Analytica Settings" src="__img2" />

   5. Enter your API keys from the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md).

   <img alt="API Keys" src="__img3" />

   * **Site Key** – paste from your dashboard. Required.
   * **Secret Key** – paste from your dashboard. Required; leave it empty and protection is disabled.
   * **Apply protection to** – check the areas to protect:
     * **Frontend pages** – public pages.
     * **REST API endpoints** – paths under `/jsonapi` or `/api`, and requests sent with a JSON content type.
   * **Block page** – where blocked visitors go (default: `/block`).
   * **Enable debug logging** – logs each validation request and response to the `centinel_analytica` channel.
   * **Excluded paths** – one glob per line, matched case-insensitively. Ships with 13 static-asset patterns (`*.css`, `*.js`, `*.png`, `/sites/default/files/*`, and similar).

   Click **Save configuration**.

   Requests under `/admin` and the block page itself are always skipped.

   > **Create the block page:** A `block` decision with no page from the validator redirects to your block page. If that path does not exist, blocked visitors land on a Drupal 404. Create it under **Content → Add content → Basic page** with the URL alias you configured.

   > **The module does not inject the browser script:** Despite requiring a site key, this module adds no script tag. To collect browser signals, add the [script tag](https://docs.centinelanalytica.com/install/scripts.md) to your theme's `html.html.twig` yourself. Without it, detection runs on server-side signals only.

   To confirm it works, tick **Enable debug logging**, load a protected page, then read
   **Reports → Recent log messages** and filter on `centinel_analytica`. Validator failures appear
   there as warnings, and the module fails open when the validator is unreachable. The validator call
   times out after 300ms.

   > **Cache:** If needed, clear the cache at **Configuration → Development → Performance**.

3. **Verify installation**

   In **Centinel Analytica → Analytics** you should see traffic appearing as you browse your site.

## Configure

All settings live on the module's settings page at
`/admin/config/security/centinel-analytica`, which requires the
`administer centinel analytica` permission.

| Setting              | Notes                                                          |
| -------------------- | -------------------------------------------------------------- |
| Site Key             | Stored but unused: this module injects no script.              |
| Secret Key           | Required. Empty means protection is off.                       |
| Apply protection to  | Frontend pages, REST API endpoints, or both.                   |
| Block page           | Must exist as a node, or blocked visitors see a 404.           |
| Enable debug logging | Logs each validation to the `centinel_analytica` channel.      |
| Excluded paths       | One glob per line, case-insensitive. 13 static-asset defaults. |

Requests under `/admin` and the block page are always skipped. The validator call times out after
300ms and fails open.

## Verify

Tick **Enable debug logging**, load a protected page, then read **Reports → Recent log messages**
and filter on `centinel_analytica`. You should see the validation request and its response. Validator
failures appear as warnings on the same channel.

## Changelog

* **v1.2** — Response header passthrough
* **v1.1** — Exclude paths option
* **v1.0** — Initial release

---

# Drupal 7

> Add Centinel Analytica to your Drupal 7 website.

Source: https://docs.centinelanalytica.com/platforms/cms/drupal-7

## Overview

This guide covers installing, configuring, and verifying Centinel Analytica in Drupal 7. You'll upload a .TAR.GZ module, enter your keys, choose what to protect (front-end, API), and create a block page.

> **Get your keys first:** Go to the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md)
> and copy your **Site Key** and **Secret Key**.

## Prerequisites

* Drupal 7
* Administrator access
* Ability to upload and configure modules

## Install

1. **Download the module (.TAR.GZ)**

   [Download Drupal 7 Module](https://docs.centinelanalytica.com/downloads/centinel_analytica-7.x-1.2.tar.gz). Keep the file compressed—don't decompress it.

2. **Upload and activate the module**

   1. Log in as administrator.
   2. Go to **Modules** in the main menu.
   3. Click **Install new module**.

   <img alt="Install new module" src="__img0" />
   <img alt="Select module file" src="__img1" />

   4. Once installation completes, go to **Configuration → Security → Centinel Analytica Settings** (`/admin/config/security/centinel-analytica`). The `administer centinel analytica` permission is required, so grant it at `/admin/people/permissions` if the page is not visible.

   <img alt="Centinel Analytica Settings" src="__img2" />

   5. Enter your API keys from the [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md).

   <img alt="API Keys" src="__img3" />

   * **Site Key** – paste from your dashboard. The module injects the browser script when this is set.
   * **Secret Key** – paste from your dashboard. Leave it empty and protection is disabled.
   * **Block Page URL** – where users go when blocked (default: `/block`).
   * **Apply protection to** – check **Front-end pages**.
   * **Excluded paths** – one glob per line, matched case-insensitively. Ships with 13 static-asset patterns.

   Click **Save Changes**.

   > **Only front-end protection is enforced on Drupal 7:** The **JSON:API / REST** checkbox is a placeholder for forward compatibility. Drupal 7 has no API-request detection, and the module returns early unless **Front-end pages** is checked. Do not rely on it to protect an API.

   Requests under `/admin` and the block page itself are always skipped.

   > **Create the block page:** A `block` decision with no page from the validator redirects to your block page. If that path does not exist, blocked visitors land on a Drupal 404.

   Drupal 7 does not pass validator response headers through, and it ignores the validator's
   `status_code`: a `redirect` is always delivered as a 403. To confirm the module is live, view source
   for `id="ca-collector"` and check **Reports → Recent log messages** for `centinel_analytica`
   entries.

   > **Cache:** If needed, clear the cache at `https://yoursite.com/admin/config/development/performance`.

3. **Verify installation**

   In **Centinel Analytica → Analytics** you should see traffic appearing as you browse your site.

## Configure

All settings live on the module's settings page at
`/admin/config/security/centinel-analytica`.

| Setting             | Notes                                                |
| ------------------- | ---------------------------------------------------- |
| Site Key            | Enables the collector script injection.              |
| Secret Key          | Required. Empty means protection is off.             |
| Block Page URL      | Must exist as a node, or blocked visitors see a 404. |
| Apply protection to | Only **Front-end pages** is enforced on Drupal 7.    |
| Excluded paths      | One glob per line, case-insensitive.                 |

The module hooks `hook_init`, so it runs on every page request. Requests under `/admin` and the
block page are always skipped, and the validator call fails open.

## Verify

View the page source of a public page and look for `id="ca-collector"`, which confirms the script
injection is active. Then check **Reports → Recent log messages** and filter on
`centinel_analytica`: validator errors appear there as warnings.

## Changelog

* **v1.2** — Drupal middleware improvements
* **v1.1** — Exclude paths option
* **v1.0** — Initial release

---

# Validation

> Reference for the POST /validate endpoint used by every Centinel integration.

Source: https://docs.centinelanalytica.com/api/validation

## POST /validate

Validate a request

Returns a decision for one HTTP request: `allow`, `block`, or `redirect`. Call this endpoint from your backend for every protected request.

See the [integration guide](https://docs.centinelanalytica.com/install/validation.md) for backend handling patterns.

Servers:

- `https://validator.centinelanalytica.com` (Production)

Authentication, any one of:

- `apiKey`: apiKey in the `x-api-key` header. Your secret API key. Server-only — never call /validate from a browser.

### Request body

Content type `application/json`, required.

Schema:

```json
{
  "type": "object",
  "required": [
    "url",
    "ip"
  ],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Full URL the user requested.",
      "example": "https://example.com/article"
    },
    "method": {
      "type": "string",
      "description": "HTTP method (GET, POST, etc). Optional, but strongly recommended for detection accuracy.",
      "example": "GET"
    },
    "ip": {
      "type": "string",
      "description": "Real client IP. If you are behind a CDN, use X-Forwarded-For (not the proxy IP).",
      "example": "1.2.3.4"
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "All request headers. More headers improve detection accuracy. Optional, but detection accuracy drops sharply without them."
    },
    "referrer": {
      "type": "string",
      "description": "Value of the `Referer` request header.",
      "example": "https://example.com"
    },
    "cookie": {
      "type": "string",
      "description": "The `_centinel` cookie value, as a bare UUID rather than the whole `Cookie` header. A malformed value is silently ignored. If omitted, the validator falls back to extracting `_centinel` from the `Cookie` request header."
    }
  }
}
```

Example:

```json
{
  "url": "https://example.com/article",
  "method": "GET",
  "ip": "1.2.3.4",
  "referrer": "https://example.com",
  "cookie": "<_centinel-cookie-value>",
  "headers": {
    "Host": "example.com",
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36",
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Language": "en-US,en;q=0.9",
    "Sec-Fetch-Dest": "document",
    "Sec-Fetch-Mode": "navigate",
    "Sec-Fetch-Site": "none"
  }
}
```

### Responses

#### 200

Valid request. The `decision` field carries the verdict, and `status_code` carries the HTTP status to send. Rate limiting is signalled in-band here; `/validate` never answers HTTP 429.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "decision"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "`true` on a valid response.",
      "example": true
    },
    "decision": {
      "type": "string",
      "enum": [
        "allow",
        "block",
        "redirect"
      ],
      "description": "The validation decision. A `block` rendered from a custom block page is reported as `redirect`, so read `status_code` rather than inferring intent from this field."
    },
    "status_code": {
      "type": "integer",
      "enum": [
        200,
        302,
        401,
        403,
        404,
        418,
        429,
        451,
        460,
        503
      ],
      "description": "The HTTP status to return to the client. When present, send this value instead of a hardcoded status. It is 200 on standard `allow` responses and 403 on standard `block` and `redirect` responses unless a policy rule or tenant setting overrides it. Treat an absent value as an internal or intercept edge case, and apply your documented safe fallback.",
      "example": 403
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "HTTP headers to set on your response. A response can include them on any decision, including an `allow` that contains a validator-owned response such as managed `robots.txt`. Guard for a missing field before you iterate."
    },
    "response_html": {
      "type": "string",
      "description": "Base64-encoded UTF-8 response body. It can contain HTML or validator-owned plain text such as managed `robots.txt`. Read `headers.Content-Type` before you serve it. It usually exists on `block` and `redirect`. If a `redirect` lacks this field, deny the request with `status_code` and a safe fallback body. Do not pass the request to your application."
    },
    "cookies": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "value",
          "domain",
          "path",
          "secure",
          "same_site",
          "max_age"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "_centinel"
          },
          "value": {
            "type": "string",
            "example": "<session-value>"
          },
          "domain": {
            "type": "string",
            "example": "",
            "description": " Empty means host-only; do not substitute your own domain."
          },
          "path": {
            "type": "string",
            "example": "/"
          },
          "secure": {
            "type": "boolean",
            "description": "Set the `Secure` attribute.",
            "example": true
          },
          "same_site": {
            "type": "string",
            "description": "Value for the `SameSite` attribute.",
            "example": "Lax"
          },
          "max_age": {
            "type": "integer",
            "description": "Lifetime in seconds for the `Max-Age` attribute. Preserve this value to retain the validator-specified cookie persistence lifetime.",
            "example": 86400
          }
        }
      },
      "description": "Cookies to set on your response. Can appear on any decision."
    },
    "crawler": {
      "type": "object",
      "required": [
        "id",
        "name",
        "access_allowed"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Crawler identifier (UUID).",
          "example": "4a7d7c8a-3fcb-4b91-8f7e-3f6ac1f5b6c1"
        },
        "name": {
          "type": "string",
          "description": "Human-readable crawler name.",
          "example": "Googlebot"
        },
        "access_allowed": {
          "type": "boolean",
          "description": "`true` only when the identified crawler source IP is verified and the crawler is allowlisted for your tenant. Use the top-level decision to enforce the validation result."
        },
        "category": {
          "type": "string",
          "description": "Catalog crawler type, copied unchanged. This is not the policy crawler.category value.",
          "example": "LLM"
        },
        "rsl_category": {
          "type": "string",
          "description": "Catalog RSL category, copied unchanged. It is independent of category and policy matching does not use it.",
          "example": "ai-all"
        }
      }
    },
    "block_reasons": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Identifiers of the signals that drove a `block`. Still populated in monitor mode, where the decision is reported as `allow`. Treat it as an open list of strings."
    },
    "block_reason_categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "bot_identity",
          "automated_browser",
          "header_anomaly",
          "fingerprint_mismatch",
          "suspicious_network",
          "challenge_failure",
          "crawler_impersonator",
          "unknown"
        ]
      },
      "description": "Higher-level grouping of `block_reasons`. One of `bot_identity`, `automated_browser`, `header_anomaly`, `fingerprint_mismatch`, `suspicious_network`, `challenge_failure`, `crawler_impersonator`, or `unknown`."
    },
    "country_code": {
      "type": "string",
      "description": "ISO 3166-1 alpha-2 country resolved for the client IP. Present only on `allow`, and only when country enrichment is enabled for your tenant."
    },
    "rate_limited": {
      "type": "boolean",
      "description": "`true` when the decision was driven by a rate-limit hit."
    },
    "retry_after": {
      "type": "integer",
      "description": "Seconds the client should wait before retrying when `rate_limited` is `true`."
    }
  }
}
```

Example `allow` (Allow):

```json
{
  "success": true,
  "decision": "allow",
  "status_code": 200
}
```

Example `allowWithCrawler` (Allow with crawler metadata):

```json
{
  "success": true,
  "decision": "allow",
  "crawler": {
    "id": "4a7d7c8a-3fcb-4b91-8f7e-3f6ac1f5b6c1",
    "name": "Googlebot",
    "access_allowed": true,
    "category": "LLM",
    "rsl_category": "ai-all"
  },
  "status_code": 200
}
```

Example `block` (Block):

```json
{
  "success": true,
  "decision": "block",
  "status_code": 403,
  "response_html": "PGh0bWw+PGJvZHk+QmxvY2tlZDwvYm9keT48L2h0bWw+",
  "headers": {
    "Content-Type": "text/html; charset=utf-8",
    "X-Content-Type-Options": "nosniff",
    "X-Frame-Options": "DENY"
  },
  "block_reasons": [
    "datacenter_ip"
  ],
  "block_reason_categories": [
    "suspicious_network"
  ]
}
```

Example `redirect` (Redirect (interstitial challenge)):

```json
{
  "success": true,
  "decision": "redirect",
  "status_code": 403,
  "response_html": "PGh0bWw+PGJvZHk+Q2hhbGxlbmdlPC9ib2R5PjwvaHRtbD4=",
  "cookies": [
    {
      "name": "_centinel",
      "value": "<session-uuid>",
      "domain": "",
      "path": "/",
      "secure": true,
      "same_site": "Lax",
      "max_age": 86400
    }
  ],
  "headers": {
    "Content-Type": "text/html; charset=utf-8",
    "Content-Security-Policy": "script-src 'nonce-<per-response>'",
    "X-Content-Type-Options": "nosniff"
  }
}
```

Example `rateLimited` (Rate limited (in-band on a 200)):

```json
{
  "success": true,
  "decision": "block",
  "status_code": 403,
  "response_html": "PGh0bWw+PGJvZHk+QmxvY2tlZDwvYm9keT48L2h0bWw+",
  "block_reasons": [
    "rate_limit_exceeded"
  ],
  "block_reason_categories": [
    "suspicious_network"
  ],
  "rate_limited": true,
  "retry_after": 30
}
```

#### 400

Request rejected. Fail closed on this status.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "error": {
      "type": "object",
      "required": [
        "type",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable error identifier (e.g., `invalid_request`, `invalid_api_key`).",
          "example": "invalid_request"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error description."
        }
      }
    }
  }
}
```

Example:

```json
{
  "success": false,
  "error": {
    "type": "missing_fields",
    "message": "Missing required fields: URL and IP are required"
  }
}
```

#### 401

Missing or invalid `x-api-key` header, as `missing_api_key` or `invalid_api_key`. Fail closed on this status.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "error": {
      "type": "object",
      "required": [
        "type",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable error identifier (e.g., `invalid_request`, `invalid_api_key`).",
          "example": "invalid_request"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error description."
        }
      }
    }
  }
}
```

Example:

```json
{
  "success": false,
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid API key"
  }
}
```

#### 500

Validator error. Fail open on this status so your site stays available.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "error": {
      "type": "object",
      "required": [
        "type",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable error identifier (e.g., `invalid_request`, `invalid_api_key`).",
          "example": "invalid_request"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error description."
        }
      }
    }
  }
}
```

Example:

```json
{
  "success": false,
  "error": {
    "type": "internal_server_error",
    "message": "Internal server error"
  }
}
```

#### 503

The validation pipeline exceeded its time budget. Fail open on this status.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "error": {
      "type": "object",
      "required": [
        "type",
        "message"
      ],
      "properties": {
        "type": {
          "type": "string",
          "description": "Stable error identifier (e.g., `invalid_request`, `invalid_api_key`).",
          "example": "invalid_request"
        },
        "message": {
          "type": "string",
          "description": "Human-readable error description."
        }
      }
    }
  }
}
```

Example:

```json
{
  "success": false,
  "error": {
    "type": "validation_timeout",
    "message": "Validation process timed out, please retry"
  }
}
```

The full OpenAPI document is at https://docs.centinelanalytica.com/openapi.json.

---

# Health Check

> Reference for the GET /health endpoint used to check that the Centinel service is reachable and ready.

Source: https://docs.centinelanalytica.com/api/health

## GET /health

Health check

Liveness and readiness check for a Centinel service. Both hosts accept a health-authorized customer `x-api-key` or the internal `x-health-check-token`. The collector also accepts a case-insensitive `User-Agent` match for `Amazon-Route53-Health-Check-Service`.

Use `https://validator.centinelanalytica.com/health` for the validator and `https://collector.centinelanalytica.com/health` for the collector. Each returns `200` with `{"status":"ok"}` when ready. Internal authorization can also return `centinel_stack_version`. The service returns `403` when authorization fails.

Servers:

- `https://validator.centinelanalytica.com` (Validator)
- `https://collector.centinelanalytica.com` (Collector)

Authentication, any one of:

- `apiKey`: apiKey in the `x-api-key` header. Your secret API key. Server-only — never call /validate from a browser.
- `healthCheckToken`: apiKey in the `x-health-check-token` header. Internal health-check credential.

### Responses

#### 200

Service is up and ready.

Content type `application/json`.

Schema:

```json
{
  "type": "object",
  "required": [
    "status"
  ],
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "ok"
      ],
      "description": "`ok` when the service is healthy.",
      "example": "ok"
    },
    "centinel_stack_version": {
      "type": "string",
      "description": "Stack version. Present only with internal health authorization."
    }
  }
}
```

Example:

```json
{
  "status": "ok"
}
```

#### 403

Authorization failed. The body is empty.

#### 503

Authorized but not ready to serve yet. The body is empty.

The full OpenAPI document is at https://docs.centinelanalytica.com/openapi.json.

---

# Crawlers

> Crawler object schema returned by the /validate endpoint.

Source: https://docs.centinelanalytica.com/api/crawlers

## Overview

When `/validate` detects a known crawler and crawler metadata is enabled for your tenant, the response includes a `crawler` object. It identifies the crawler and reports whether the request meets source-IP verification and tenant allowlist requirements.

## Crawler object

| Field            | Type    | Required | Description                                                                                                      |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `id`             | string  | yes      | Crawler identifier (UUID).                                                                                       |
| `name`           | string  | yes      | Human-readable name (e.g., `Googlebot`).                                                                         |
| `access_allowed` | boolean | yes      | `true` only when the crawler source IP is verified and the crawler is on your allowlist.                         |
| `category`       | string  | no       | The catalog crawler `type`, copied unchanged. This is not the policy `crawler.category` value.                   |
| `rsl_category`   | string  | no       | The catalog RSL category, copied unchanged. It is independent of `category` and policy matching does not use it. |

When the response contains a `crawler` object, `id`, `name`, and `access_allowed` are present.
Either optional field can be absent when the crawler catalog has no value. `access_allowed`
identifies the crawler's standing; enforce the `/validate` result from the top-level `decision`
field.

## Category metadata

The API does not publish or enforce a fixed mapping between `category` and `rsl_category`. A
crawler can return `category: "LLM"` and `rsl_category: "ai-all"`. Both fields use open string
values, copied from the catalog without normalization.

The policy matcher field `crawler.category` is different from the API response field. Policy
normalizes the catalog crawler `type` into a closed set of values. It does not read
`rsl_category`, and it does not compare the API `category` value unchanged. See
[Policy rules](https://docs.centinelanalytica.com/admin/policy.md) for the allowed policy values and operators.

When a catalog `type` has no policy normalization, a `crawler.category not_in` rule can match the
request. Do not assume that an unknown API category is `other`.

---

# Analytics Query API

> Query your raw bot detection events with read-only SQL over HTTP.

Source: https://docs.centinelanalytica.com/api/analytics

## Overview

The Analytics Query API gives you direct SQL access to your event data. Centinel writes validation and collection events to this table. A request row has a nonzero `request_id`. You query the rows with ClickHouse SQL. The API returns the format that you select.

Use the API to build a custom report. You can also load the data into a warehouse, or answer a question that the dashboard does not show.

The API uses a read-only ClickHouse account. It applies a tenant row policy to every query.

> **Note:** Your key reads only the events of your own organisation. The server applies this filter. You cannot disable it.

## Authentication

Each request must have an API key in an `Authorization` header. Use the `Bearer` scheme:

```bash
Authorization: Bearer sk_api_ro_your_key_here
```

Create a key in the [dashboard](https://docs.centinelanalytica.com/install/dashboard.md). You can also revoke a key there. Treat a key as a password. The key gives read access to all of your event data. Keep the key on your server. Do not put the key in a client application.

If the key is missing, malformed, or unknown, the API returns `401` and an empty body. The API accepts no other authentication scheme.

## Send a request

Send a `POST` request to the query endpoint. Put your SQL in the request body:

```bash
curl -X POST https://api.centinelanalytica.com/query \
  -H "Authorization: Bearer sk_api_ro_your_key_here" \
  -H "Content-Type: text/plain" \
  --data-binary "SELECT count() FROM events_distributed WHERE request_id != toUUID('00000000-0000-0000-0000-000000000000')"
```

The request has four constraints:

* The API accepts only the `POST` method.
* The SQL must be in the request body. The API ignores query string parameters.
* Each request must have one statement. The API rejects multiple statements.
* The request body has a limit of 64 KB.

The endpoint sends no CORS headers. Therefore, a browser cannot call the API. Call the API from your server.

## Write a query

Query the `events_distributed` table. Name the columns that you need:

```sql
SELECT created_at, hostname, decision
FROM events_distributed
WHERE created_at > now() - INTERVAL 1 DAY
LIMIT 100
```

Avoid `SELECT *`. A named column list protects your result-size limit and makes the query stable when the schema changes.

Use single quotes for a string value. In ClickHouse, double quotes identify a column. Thus `WHERE hostname = "example.com"` reads a column with the name `example.com`. The query then fails and returns an unknown identifier error.

```sql
SELECT count() FROM events_distributed
WHERE hostname = 'www.example.com'
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
```

> **Warning:** The API has no bound query parameters. Escape a value only when you put it inside an already-delimited SQL string. Allowlist identifiers, operators, sort directions, limits, and every other SQL fragment. Quote escaping alone cannot secure structural SQL.

Put a `created_at` filter in each query. The `created_at` column is the sort key of the table. A bounded time range prevents the execution timeout.

## Response formats

The API returns tab-separated values by default. Add a `FORMAT` clause to select a different format:

```sql
SELECT hostname, count() FROM events_distributed GROUP BY hostname FORMAT JSONEachRow
```

These formats are the most useful:

| Format          | Use for                                                                             |
| --------------- | ----------------------------------------------------------------------------------- |
| `TabSeparated`  | The default format. It is compact and has no header row.                            |
| `TSVWithNames`  | Tab-separated values with a header row.                                             |
| `CSVWithNames`  | A spreadsheet import.                                                               |
| `JSON`          | One object with the `meta` field, the `data` field, and row statistics.             |
| `JSONEachRow`   | One JSON object on each line. Use this format to load data into a different system. |
| `PrettyCompact` | A table for a person to read.                                                       |

The API does not compress the response.

## Event schema

The table retains rows for 90 days. The `headers` and `body` columns clear 14 days after the event. Other row data remains available for the full 90 days.

Use `request_id != toUUID('00000000-0000-0000-0000-000000000000')` when you count or group requests. This excludes collection and enrichment rows that have no request ID.

| Column                          | Type                 | Description                                                                                                      |
| ------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `created_at`                    | DateTime64(3, 'UTC') | The time of the evaluation. The value has millisecond precision.                                                 |
| `session_id`                    | UUID                 | The visitor session. Use this column to group the requests of one visitor.                                       |
| `request_id`                    | UUID                 | Unique for each request. Use this column to count distinct requests.                                             |
| `ip`                            | IPv6                 | The client IP address. An IPv4 address has a mapped form, for example `::ffff:203.0.113.10`.                     |
| `url`                           | String               | The full request URL.                                                                                            |
| `referrer`                      | String               | The referrer header. The value is empty if the header is absent.                                                 |
| `method`                        | String               | The HTTP method.                                                                                                 |
| `hostname`                      | String               | The host that serves the request.                                                                                |
| `endpoint_path`                 | String               | The path of the URL, without the query string.                                                                   |
| `headers`                       | String               | The request headers as a JSON object. The value is empty 14 days after the event.                                |
| `body`                          | String               | The request body. The value is empty 14 days after the event.                                                    |
| `user_agent`                    | String               | The raw User-Agent header.                                                                                       |
| `decision`                      | String               | The conclusion of the detection engine. Refer to [Decisions and actions](#decisions-and-actions).                |
| `action`                        | String               | The action that your policy applied to the request.                                                              |
| `block_reason_categories_added` | Array(String)        | The reasons that the engine flagged the request. The array is empty for clean traffic.                           |
| `ip_country_code`               | String               | The two-letter country code from IP geolocation.                                                                 |
| `ip_region_code`                | String               | The region or state code, if known.                                                                              |
| `browser`                       | String               | The browser family. The value is empty if the engine cannot identify the browser.                                |
| `os`                            | String               | The operating system.                                                                                            |
| `device_type`                   | String               | One of `desktop`, `mobile`, `tablet`, or `other`.                                                                |
| `is_mobile`                     | Bool                 | True if the client has the properties of a mobile device.                                                        |
| `crawler_name`                  | String               | The name of the crawler, for example `Googlebot`. The value is empty for other traffic.                          |
| `crawler_type`                  | String               | The crawler category. Refer to [Crawlers](https://docs.centinelanalytica.com/api/crawlers.md) for the full list. |
| `is_datacenter`                 | Bool                 | True if the IP address belongs to a hosting or datacenter network.                                               |
| `is_proxy`                      | Bool                 | True if the IP address is a known proxy.                                                                         |
| `is_vpn`                        | Bool                 | True if the IP address is a known consumer VPN exit.                                                             |
| `is_tor`                        | Bool                 | True if the IP address is a Tor exit node.                                                                       |
| `asn`                           | UInt32               | The autonomous system number of the client network.                                                              |
| `asn_organisation`              | String               | The name of the network operator.                                                                                |

To read the current column list, query the system catalog:

```sql
SELECT name, type FROM system.columns
WHERE database = 'default' AND table = 'events_distributed'
ORDER BY position
```

## Decisions and actions

The `decision` column and the `action` column answer two different questions. If you confuse them, your numbers will be incorrect.

| Column     | Values                                 | Meaning                    |
| ---------- | -------------------------------------- | -------------------------- |
| `decision` | `allow`, `block`, `redirect`           | The verdict of the engine. |
| `action`   | `allow`, `monitor`, `skip`, `redirect` | The enforcement result.    |

The difference between the two columns is intentional. A rule in monitor mode writes `decision = 'block'` and `action = 'monitor'`. The engine flagged the request, and the visitor received the page.

To count the traffic that you stopped, filter on `action`:

```sql
SELECT count() FROM events_distributed
WHERE action = 'redirect'
  AND created_at > now() - INTERVAL 7 DAY
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
```

To count the traffic that the engine would stop when every rule enforces, filter on `decision`:

```sql
SELECT count() FROM events_distributed
WHERE decision = 'block'
  AND created_at > now() - INTERVAL 7 DAY
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
```

> **Warning:** If one rule is in monitor mode, the count of `decision = 'block'` is more than the number of requests that you stopped. Do not report that count as blocked requests.

## Example queries

Daily traffic by decision:

```sql
SELECT toDate(created_at) AS day, decision, count() AS requests
FROM events_distributed
WHERE created_at > now() - INTERVAL 30 DAY
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
GROUP BY day, decision
ORDER BY day DESC, requests DESC
FORMAT JSONEachRow
```

The crawlers that made the most requests in the last seven days:

```sql
SELECT crawler_name, crawler_type, count() AS requests
FROM events_distributed
WHERE created_at > now() - INTERVAL 7 DAY
  AND crawler_name != ''
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
GROUP BY crawler_name, crawler_type
ORDER BY requests DESC
LIMIT 25
```

The reasons that the engine flagged traffic:

```sql
SELECT arrayJoin(block_reason_categories_added) AS reason, count() AS hits
FROM events_distributed
WHERE created_at > now() - INTERVAL 7 DAY
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
GROUP BY reason
ORDER BY hits DESC
```

Datacenter traffic by network. This query is a good first check for a scraper:

```sql
SELECT asn_organisation, count() AS requests, uniqExact(session_id) AS sessions
FROM events_distributed
WHERE created_at > now() - INTERVAL 7 DAY
  AND is_datacenter
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
GROUP BY asn_organisation
ORDER BY requests DESC
LIMIT 25
```

The paths that flagged traffic requested most often:

```sql
SELECT endpoint_path, count() AS requests
FROM events_distributed
WHERE created_at > now() - INTERVAL 1 DAY
  AND decision = 'block'
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
GROUP BY endpoint_path
ORDER BY requests DESC
LIMIT 50
```

## Limits

| Limit                          | Value      |
| ------------------------------ | ---------- |
| Query execution time           | 30 seconds |
| Rows returned                  | 1,000,000  |
| Request body                   | 64 KB      |
| Response body                  | 4 MiB      |
| Row retention                  | 90 days    |
| `headers` and `body` retention | 14 days    |

If a query exceeds a limit, the API cancels the query. The API returns an error, not a truncated result. If a query exceeds the execution time, decrease the time range. As an alternative, aggregate the data in the database.

The gateway collects each answer before it relays it. An answer above 4 MiB returns `502` with the text `clickhouse response too large`. Split a large export into time windows before it reaches that limit:

```sql
SELECT created_at, session_id, decision
FROM events_distributed
WHERE created_at >= '2026-08-01 00:00:00'
  AND created_at <  '2026-08-01 00:15:00'
  AND request_id != toUUID('00000000-0000-0000-0000-000000000000')
FORMAT JSONEachRow
```

Then move the window forward and send the next request. Do not use `LIMIT` with a large `OFFSET`. If a response reaches the relay limit, divide the window and send the query again. The correct window size depends on your traffic and the selected columns.

You cannot change the session settings. The API rejects a `SET` statement and a `SETTINGS` clause. This includes a change that decreases a limit.

## Errors

The API returns an error as a plain-text body. A ClickHouse error has a code, a message, and an identifier:

```text
Code: 62. DB::Exception: Syntax error (Multi-statements are not allowed): failed at position 9 (end of query): ; SELECT 2. . (SYNTAX_ERROR) (version 26.2.19.43 (official build))
```

The `Code` value and the identifier show the cause. These errors are the most frequent:

| Code | Identifier               | Cause                                                                              |
| ---- | ------------------------ | ---------------------------------------------------------------------------------- |
| 62   | `SYNTAX_ERROR`           | The SQL is malformed. The API also returns this error for multiple statements.     |
| 47   | `UNKNOWN_IDENTIFIER`     | The column does not exist. A double-quoted string literal is a frequent cause.     |
| 60   | `UNKNOWN_TABLE`          | The table does not exist. Query `events_distributed`.                              |
| 497  | `ACCESS_DENIED`          | The query reads a table that your key cannot access, or it attempts to write data. |
| 396  | `TOO_MANY_ROWS_OR_BYTES` | The result is more than one million rows.                                          |
| 164  | `READONLY`               | The query tries to change a setting or to write data.                              |

The API returns an empty body if the key is missing or unknown. The gateway can refuse an answer at 4 MiB before ClickHouse returns a size error.

If a query runs longer than 30 seconds, the API cancels it. The error shows the elapsed time and the maximum.

## See also

* [MCP Server](https://docs.centinelanalytica.com/api/mcp.md) to give an AI assistant the same access
* [OpenAPI document](https://docs.centinelanalytica.com/openapi.json), which describes this endpoint as `POST /query` for client generators
* [Crawlers](https://docs.centinelanalytica.com/api/crawlers.md) for the crawler categories
* [Glossary](https://docs.centinelanalytica.com/concepts/glossary.md) for the block reason categories
* [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md) to create and revoke API keys

---

# MCP Server

> Connect an AI assistant to your event data through the Model Context Protocol.

Source: https://docs.centinelanalytica.com/api/mcp

## Overview

The MCP server gives an AI assistant the same read-only access as the [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md). The assistant writes the SQL. The server runs it under the ClickHouse account of your organisation and returns the rows.

The endpoint is `POST https://api.centinelanalytica.com/mcp`. It speaks the Streamable HTTP transport of protocol revision `2025-06-18`.

The server keeps no state between requests. There is no event stream and no session identifier. Each request carries its own key, and each request receives one answer.

> **Note:** The assistant reads only the events of your own organisation. The server applies this filter to every statement. A statement cannot widen past your own rows.

## Connect a client

Each request must have your API key in an `Authorization` header. This rule includes the `initialize` request. The server has no unauthenticated method and no OAuth flow.

Use the same key as the Analytics Query API. Create a key in the [dashboard](https://docs.centinelanalytica.com/install/dashboard.md).

Add the server to Claude Code with one command:

```bash
claude mcp add --transport http centinel https://api.centinelanalytica.com/mcp \
  --header "Authorization: Bearer sk_api_ro_your_key_here"
```

For a client that reads a JSON configuration file, add this block:

```json
{
  "mcpServers": {
    "centinel": {
      "type": "http",
      "url": "https://api.centinelanalytica.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_api_ro_your_key_here"
      }
    }
  }
}
```

> **Warning:** The key gives read access to all of your event data. Keep the configuration file on a machine that you control. Do not commit the key to a repository.

To test the connection without a client, send the `initialize` request yourself:

```bash
curl -X POST https://api.centinelanalytica.com/mcp \
  -H "Authorization: Bearer sk_api_ro_your_key_here" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

The server returns the protocol revision and its one capability:

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{"listChanged":false}},"serverInfo":{"name":"centinel-analytics","version":"1"}}}
```

## Tools

The server has three tools. The list is the same for each caller: the tenant boundary is the database account, not the tool list.

| Tool           | Arguments | Returns                                                                 |
| -------------- | --------- | ----------------------------------------------------------------------- |
| `query`        | `sql`     | The rows of one read-only `SELECT`.                                     |
| `query_help`   | none      | The rules of the account, and example queries.                          |
| `list_columns` | none      | Each readable column of `events_distributed`, with its ClickHouse type. |

Call `query` with one statement:

```bash
curl -X POST https://api.centinelanalytica.com/mcp \
  -H "Authorization: Bearer sk_api_ro_your_key_here" \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"query","arguments":{"sql":"SELECT action, uniqExact(request_id) AS requests FROM events_distributed WHERE created_at >= now() - INTERVAL 1 DAY GROUP BY action FORMAT JSONEachRow"}}}'
```

The `query_help` tool returns the account rules and worked examples. Call it once before your first statement, because it reads no data and costs no query time.

The `list_columns` tool reads the column grant live. `DESCRIBE` and `SHOW CREATE` are denied to the account, so this tool is the only way to read the current column list. Where a document and this tool disagree, this tool is correct.

### Query rules

The tool descriptions carry the rules that the assistant must know. Two of them change your numbers rather than fail:

* Select `FROM events_distributed`. A per-shard table such as `events` holds the rows of one shard. The query succeeds, the count comes back low, and nothing reports it.
* `decision` is what the engine concluded. `action` is what your policy enforced. Most blocks run in monitor first, so `decision = 'block'` overstates the traffic that you stopped.

Refer to [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md) for the event schema and the full rule list.

## Errors

The server separates a failed statement from a failed request. The two have different shapes, because an assistant can correct only the first.

A tool error means that the assistant can correct the call itself. The status is `200`. The result has `isError` set to `true`, and the text says what to change. A statement that the database refused carries the message of the database:

```json
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"Code: 47. DB::Exception: Unknown expression identifier `hostnme` ..."}],"isError":true}}
```

The assistant reads that message and writes the statement again. A `query` call without a `sql` argument is a tool error too. That call never reaches the database, but the assistant supplies the argument and calls again.

A protocol error gives the assistant nothing to correct, so the server uses one only when the request never became a tool call:

| Code     | Meaning                                                                                |
| -------- | -------------------------------------------------------------------------------------- |
| `-32700` | The request body is not valid JSON.                                                    |
| `-32600` | The body is valid JSON, but it is not a JSON-RPC 2.0 request.                          |
| `-32601` | The method is unknown. The server serves `initialize`, `tools/list`, and `tools/call`. |
| `-32602` | The tool name is unknown. The server has `query`, `query_help`, and `list_columns`.    |

Three failures happen before the JSON-RPC layer:

* The server returns `401` and an empty body if the key is absent, unknown, revoked, or expired.
* The server returns `405` for each method other than `POST`.
* The server returns `202` and an empty body for a notification. A notification is a request without an `id`, and the protocol gives it no answer.

## Limits

| Limit                          | Value        |
| ------------------------------ | ------------ |
| Statement in one `query` call  | 65,456 bytes |
| Request body                   | 64 KB        |
| Answer of one tool call        | 256 KiB      |
| Query execution time           | 30 seconds   |
| Rows returned                  | 1,000,000    |
| Row retention                  | 90 days      |
| `headers` and `body` retention | 14 days      |

An answer above 256 KiB is discarded, not shortened. The server returns a tool error that asks for a `LIMIT`, because a truncated answer would look complete to the assistant.

This route collects the whole answer before it sends it, because a JSON-RPC result carries the answer as one string. The [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md) streams the answer instead, so the 256 KiB cap does not apply there. Use that endpoint for a large export.

The database gateway collects each answer before it relays it, and it refuses an answer above 4 MiB. That ceiling applies to both endpoints. On this route the 256 KiB cap is reached first.

## See also

* [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md) for the event schema and the raw SQL endpoint
* [Docs MCP Server](https://docs.centinelanalytica.com/api/docs-mcp.md) to let an assistant search this documentation
* [Crawlers](https://docs.centinelanalytica.com/api/crawlers.md) for the crawler categories
* [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md) to create and revoke API keys

---

# Docs MCP Server

> Let an AI assistant search and read this documentation through the Model Context Protocol.

Source: https://docs.centinelanalytica.com/api/docs-mcp

## Overview

The docs MCP server lets a coding assistant, such as Claude Code or Cursor, search this documentation and read its pages as Markdown. The assistant then answers from the current docs, not from its training data.

The endpoint is `POST https://docs.centinelanalytica.com/mcp`. It speaks the Streamable HTTP transport of protocol revision `2025-06-18`.

The server is public and read-only. It needs no API key. It keeps no state between requests, and each request receives one answer.

> **Note:** This server reads the documentation only. To give an assistant your event data, use the [MCP Server](https://docs.centinelanalytica.com/api/mcp.md) at `api.centinelanalytica.com` with an API key.

## Connect a client

Add the server to Claude Code with one command:

```bash
claude mcp add --transport http centinel-docs https://docs.centinelanalytica.com/mcp
```

For a client that reads a JSON configuration file, add this block:

```json
{
  "mcpServers": {
    "centinel-docs": {
      "type": "http",
      "url": "https://docs.centinelanalytica.com/mcp"
    }
  }
}
```

## Tools

| Tool          | Arguments                                     | Returns                                                               |
| ------------- | --------------------------------------------- | --------------------------------------------------------------------- |
| `search_docs` | `query`, and `limit` from 1 to 20 (default 8) | The matching pages and sections, each with its path and Markdown URL. |
| `get_page`    | `path`                                        | One page as Markdown.                                                 |

The `get_page` tool accepts a path such as `/api/analytics`, the same path with `.md`, or a full `https://docs.centinelanalytica.com` URL. It also reads a crawler profile, for example `/crawlers/googlebot`.

Call `search_docs` without a client:

```bash
curl -X POST https://docs.centinelanalytica.com/mcp \
  -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_docs","arguments":{"query":"akamai timeout"}}}'
```

## Errors

A tool error has status `200` and `isError` set to `true`. The text says what to change, for example an empty `query` or a path with no page. The assistant can correct the call and send it again.

| Code     | Meaning                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------- |
| `-32700` | The request body is not valid JSON.                                                            |
| `-32600` | The body is valid JSON, but it is not a JSON-RPC 2.0 request.                                  |
| `-32601` | The method is unknown. The server serves `initialize`, `ping`, `tools/list`, and `tools/call`. |
| `-32602` | The tool name is unknown.                                                                      |

The server returns `202` and an empty body for a notification. It returns `405` for a `GET`, and `413` for a request body above 16 KiB.

## Other formats

An agent that does not use MCP can read the same content directly:

* [`/llms.txt`](https://docs.centinelanalytica.com/llms.txt) lists every page with its Markdown URL.
* [`/llms-full.txt`](https://docs.centinelanalytica.com/llms-full.txt) holds every page in one file.
* Any page URL returns Markdown when you append `.md`, or when the request sends `Accept: text/markdown`.
* [`/openapi.json`](https://docs.centinelanalytica.com/openapi.json) describes the validation, health, and analytics query endpoints.

## See also

* [MCP Server](https://docs.centinelanalytica.com/api/mcp.md) to query your event data from an assistant
* [Analytics Query API](https://docs.centinelanalytica.com/api/analytics.md) for the event schema

---

# Policy Rules

> How to write rules that allow, block, rate-limit, or watch requests, and where the crawler allowlist fits in.

Source: https://docs.centinelanalytica.com/admin/policy

## Overview

A policy rule has two parts. The **matcher** says when the rule applies. The **directives** say what the rule does. Rules live on the [Policy page](https://dash.centinelanalytica.com/policy) in the dashboard.

The validator checks your rules in priority order. For each thing a rule can set, the first rule that matches wins.

Policy runs partway through the checks. By the time your rules run, the validator has already identified any known crawler and looked up the visitor's country and network. It has not scored the request for bot behavior yet. So your rules can use what the validator knows about a crawler, and a rule can decide the request before scoring runs.

## Evaluation order

1. Rules are sorted by `priority`, lowest number first. Priorities are unique per organisation, so two rules cannot share a number.

2. For each request, the validator goes down the list. A rule can set five things: `verdict`, `bot_detect`, `rate_limit`, `monitor`, and `response`. The first rule to set one of these wins, and no later rule can change it.

3. As soon as a rule sets a `verdict`, the validator stops. No later rule runs, not even the built-in crawler rules below. Anything earlier rules already set stays in place.

4. If no rule sets a verdict, policy does not decide the request. It passes the request on to bot detection, which uses the protection level from your settings. If no rule set a `verdict`, `bot_detect`, or `rate_limit`, the validator turns on monitor logging for that request.

When no rule matches, policy adds nothing of its own. It does not allow the request and does not
touch your protection level; it only turns on monitor logging. A rule can also set just
`bot_detect` and leave the verdict to a later rule, or to scoring.

> **Order matters, absolute numbers don't:** Reordering rules in the dashboard renumbers them from 1 upwards, and importing a rule set does the same.

### Rules that fail to load

Policy is fail-closed per rule. If any part of a matcher is invalid, the **whole rule** is disabled
and matches nothing, silently. That covers an unknown field or operator, a value of the wrong
shape, a pattern that doesn't compile, a bad CIDR, and a nested group that would match everything.
A disabled rule still looks active in the dashboard, so check the rule you just wrote actually
fires before trusting it.

### Crawler allowlist priority

The crawler allowlist is not a separate step that runs first. Instead, the validator adds two built-in rules for you. Both sit at the highest possible priority number, so they run **after** every rule you write:

* An identified crawler **on** your allowlist gets `verdict: allow`.
* An identified crawler **not** on your allowlist gets `verdict: block`.

Both rules only apply to identified crawlers. Neither one fires unless the request matched a known crawler. Normal browser traffic is never affected. So by default, the allowlist decides what happens to crawlers. Allowlisted crawlers pass, and every other identified crawler is blocked.

Because the built-in rules run last, any rule of yours that sets a verdict wins over them. To let through a crawler that is not on your allowlist, or block one that is, write your own rule with a lower priority number. Any number works, since the built-ins sit at the highest possible one. Your rule sets the verdict, evaluation stops, and the built-in never runs.

```json
{
  "priority": 100,
  "note": "Let our partner's crawler through even though it is not allowlisted",
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "crawler.name", "op": "literal", "value": "PartnerBot" }
    ]
  },
  "set_directives": { "verdict": "allow", "bot_detect": "off" }
}
```

## Matchers

A matcher is a group of clauses. The group has a `combinator` (`and` or `or`) and a list of `rules`. Each clause in `rules` has a `field`, an operator (`op`), and a `value`. With `and`, every clause must match. With `or`, any one clause matches.

```json
"when_matcher": {
  "combinator": "and",
  "rules": [
    { "field": "url", "op": "glob",  "value": "/checkout/**" },
    { "field": "ua",  "op": "regex", "value": "(?i)curl|wget" }
  ]
}
```

A `rules` entry can also be another group. The dashboard accepts at most 10 nesting levels. The validator also has a 64-level defensive limit. Nest groups only when you need to mix `and` and `or` in one matcher.

```json
"when_matcher": {
  "combinator": "and",
  "rules": [
    { "field": "url", "op": "glob", "value": "/checkout/**" },
    {
      "combinator": "or",
      "rules": [
        { "field": "country", "op": "in", "value": ["RU", "CN"] },
        { "field": "asn", "op": "eq", "value": "15169" }
      ]
    }
  ]
}
```

Rules apply across your whole organisation. To limit one to a single site, add a `hostname` clause.

The table below lists every field and the operators it accepts. You will usually build rules in the
dashboard editor, but this JSON is the shape the editor stores and an import file carries, so you
can copy it. `query` and `cookie` are only available in the expression editor, not the visual
builder.

| Field              | Operators                            | Matches                                                                                                                        |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `url`              | `literal`, `glob`, `regex`           | The request path, and also the full absolute URL. A clause matches if either form matches.                                     |
| `ua`               | `literal`, `regex`                   | The `User-Agent` header.                                                                                                       |
| `ip`               | `cidr`, `literal`, `eq`              | The client IP. IPv4 and IPv6.                                                                                                  |
| `hostname`         | `literal`, `glob`                    | The host part of the request URL, without the port.                                                                            |
| `method`           | `eq`, `in`, `not_in`                 | The HTTP method. Case-insensitive.                                                                                             |
| `referer`          | `literal`, `glob`, `regex`, `exists` | The `Referer` header.                                                                                                          |
| `query`            | `exists`, `eq`, `regex`              | A named query-string parameter's value. Takes an object value.                                                                 |
| `cookie`           | `exists`, `eq`, `regex`              | A named cookie's value. Takes an object value.                                                                                 |
| `time_of_day`      | `between`                            | The request time inside a local-time window.                                                                                   |
| `country`          | `eq`, `in`, `not_in`                 | The two-letter ISO 3166-1 country of the client IP, from geo lookup.                                                           |
| `asn`              | `eq`, `in`, `not_in`                 | The autonomous-system number of the client IP. Write it as `15169` or `AS15169`.                                               |
| `crawler.verified` | `is`, `is_not`                       | Whether an identified crawler passed ownership verification.                                                                   |
| `crawler.allowed`  | `is`, `is_not`                       | Whether an identified crawler is on your allowlist.                                                                            |
| `crawler.name`     | `literal`, `regex`                   | The crawler name, such as `Googlebot` or `GPTBot`.                                                                             |
| `crawler.category` | `eq`, `in`, `not_in`                 | The crawler category (see below).                                                                                              |
| `passport`         | `exists`, `eq`                       | The [passport](https://docs.centinelanalytica.com/admin/passports.md) the request presented, if any. `eq` takes a passport id. |

`country` and `asn` only match when the IP lookup returned a value. If the lookup has no data for an IP, the clause does not match. A rule based on country or ASN skips that request rather than guess.

### Crawler clauses

Every `crawler.*` clause is false unless the request matched a known crawler. There is no `crawler.identified` field, because identification is built in: match any `crawler.*` field and you are already requiring an identified crawler. To act only on verified crawlers, add `crawler.verified` with `op: is` and `value: true`.

`crawler.category` is one of `search`, `seo`, `ai_training`, `ai_assistant`, `ai_search`, `ai_agent`, `scraper`, `archive`, `monitoring`, `social_media`, `aggregator`, `accessibility`, `advertising`, `feed_reader`, `preview`, `research`, `security`, `other`.

### Operators

Pick the simplest operator that fits the field.

* **`literal`**: an exact text match. No wildcards, and uppercase and lowercase count as different.
* **`eq`**: a match on the whole value. Only `method` and `country` ignore case. `crawler.category`, `query`, and `cookie` are case-sensitive. On `ip` it compares addresses rather than text, and on `asn` it accepts either the bare number or an `AS` prefix.
* **`in` / `not_in`**: checks whether the value is (or is not) in a list you give. Used by `method`, `country`, `asn`, and `crawler.category`.
* **`is` / `is_not`**: a true/false test, for `crawler.verified` and `crawler.allowed`.
* **`exists`**: checks that the field is there at all. `referer` exists when the header is not empty; `query` and `cookie` exist when the named parameter is set.
* **`between`**: for `time_of_day`, a local-time window (see below).
* **`glob`*&#x2A;, &#x2A;*`regex`*&#x2A;, and &#x2A;*`cidr`**: pattern operators, described next.

#### Naming a query parameter or cookie

`query` and `cookie` clauses take an object value with a `name` and a `value`, because the clause
has to say which parameter it means. Include `name` even with `exists`, and pass `value` as an
empty string there. A bare string value disables the rule.

```json
{ "field": "query",  "op": "exists", "value": { "name": "utm_source", "value": "" } }
{ "field": "cookie", "op": "regex",  "value": { "name": "sid", "value": "^[a-f0-9]{32}$" } }
```

If a parameter appears more than once in the query string, the last occurrence is the one matched.

#### `glob` (shell-style)

Available for `url`, `hostname`, and `referer`. Supports:

| Token     | Meaning                                                                    |
| --------- | -------------------------------------------------------------------------- |
| `*`       | Any run of characters, including `/`.                                      |
| `**`      | The same as `*` here.                                                      |
| `?`       | Any single character, including `/`.                                       |
| `[abc]`   | Any one of the listed characters. `[a-z]` for a range, `[!abc]` to negate. |
| `{a,b,c}` | Alternation.                                                               |

> **Globs are not path-aware:** `*` does not stop at a `/`, so `*` and `**` behave identically. If you need to match a single path segment, end the pattern with a literal, or use a `regex` clause with an anchor.

```text
/api/*           matches /api/users and /api/users/42
/files/*.json    matches /files/data.json and /files/v2/data.json
*.example.com    matches shop.example.com and api.example.com
```

#### `regex` (RE2)

Available for `url`, `ua`, `referer`, `crawler.name`, and the value side of `query` and `cookie`. Patterns compile with Go's [`regexp`](https://pkg.go.dev/regexp) package, which uses [RE2 syntax](https://github.com/google/re2/wiki/Syntax).

RE2 looks like Perl or PCRE, with two differences to know about:

* No backreferences (`\1`, `\2`).
* No lookaround (`(?=...)`, `(?!...)`, `(?<=...)`, `(?<!...)`).

In exchange, matching stays fast no matter the input. A bad pattern cannot slow the validator down the way it can with PCRE.

> **Regex matches are substring matches:** The matcher looks for the pattern anywhere in the value. To require a full-string match, anchor with `^` and `$`. Without anchors, `/admin` as a regex matches `/v2/admin/users` too.

```text
(?i)bot|crawler|spider     matches anywhere in the UA, any case
^/admin(/|$)               path is /admin, or starts with /admin/
^Mozilla/5\.0 \(.*Linux    literal dot, parens are escaped
[a-z]{3,8}                 three to eight lowercase letters
```

To ignore case, put `(?i)` at the start of the pattern.

The dashboard catches most bad patterns when you save, but it checks them with the browser's regex engine. A lookaround or backreference saves cleanly and is then rejected by the validator, which disables the whole rule. The rule keeps looking active in the editor while matching nothing, so avoid both constructs.

#### `cidr`

Available for `ip`. Uses Go's `net.ParseCIDR`. IPv4 and IPv6 both work. For a single address, use `literal` instead.

```text
192.168.0.0/16
10.0.0.0/8
2001:db8::/32
```

#### `between` (time of day)

`time_of_day` takes a `start` and `end` time in 24-hour `HH:MM` form, plus a time zone (`tz`) like `America/New_York`. The window includes the start time and stops just before the end time. If `start` is later than `end`, the window runs past midnight into the next day. The value is an object, so the whole clause looks like this:

```json
{ "field": "time_of_day", "op": "between", "value": { "start": "22:00", "end": "06:00", "tz": "America/New_York" } }
```

## Directives

A rule must set at least one directive. The first rule to set a directive wins it, and no later rule can change it.

| Directive    | Values                         | Effect                                                                                                                                                                    |
| ------------ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verdict`    | `allow`, `block`               | Final decision. `allow` lets the request through. `block` returns a 403 (or your configured block response). Setting it stops evaluation.                                 |
| `bot_detect` | `off`, `low`, `normal`, `high` | How hard the validator scores for bots. `off` skips scoring. `high` is the strictest.                                                                                     |
| `rate_limit` | object                         | Per-scope budget. Fields: `max_requests` (1 to 1,000,000), `window_seconds` (1 to 86,400), `scope` (`session`, `ip`, or `session_or_ip`), `phase` (currently only `pre`). |
| `monitor`    | `true`, `false`                | Puts the request in shadow mode. Blocks are logged and reported as allow.                                                                                                 |
| `response`   | object                         | Change the page and status returned on a block or challenge. Fields: `block_page`, `block_status`, `challenge_page`, `challenge_status`.                                  |

The status fields only accept these codes: `200`, `302`, `401`, `403`, `404`, `418`, `429`, `451`, `460`, or `503`. The page fields name a template you have set up, not raw HTML.

### What `monitor` really covers

`monitor: true` is not scoped to the rule that sets it. It puts the **whole request** into shadow
mode. Every terminal block returns as `allow` and is logged. This includes blocks from this rule,
later rules, rate limiting, and bot scoring. Challenges still return normally.

The first rule to set `monitor` wins it. A broad rule with a low priority number can put your
entire organisation into shadow mode. Keep `monitor` on narrow rules while you test them.

`monitor: false` does not move traffic into enforcement. When only `monitor: false` and/or
`response` resolve, policy replaces `false` with its `monitor: true` fallback. `false` remains only
when a `verdict`, `bot_detect`, or `rate_limit` also resolves. It also cannot override an earlier
`monitor: true`.

### What `rate_limit` really does

Requests over the budget are blocked, with a `rate_limit_exceeded` reason and a `retry_after` value
your backend should send as `Retry-After`. Rate limiting is also fail-closed on binding: if the
scope key cannot be resolved, the request is blocked outright with `policy_rate_limit_missing_binding`.

Rate limiting runs before session validation, so `scope: "session"` has no session to key on for a
first-time visitor. Use `session_or_ip` unless you know every request already carries a session.

## Examples

### Block obvious scraping clients on the checkout

```json
{
  "priority": 100,
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "url", "op": "glob",  "value": "/checkout/**" },
      { "field": "ua",  "op": "regex", "value": "(?i)curl|wget|python-requests|httpie" }
    ]
  },
  "set_directives": { "verdict": "block" }
}
```

### Always allow verified search engines, no scoring

```json
{
  "priority": 50,
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "crawler.verified", "op": "is", "value": true },
      { "field": "crawler.category", "op": "eq", "value": "search" }
    ]
  },
  "set_directives": {
    "verdict": "allow",
    "bot_detect": "off"
  }
}
```

### Rate-limit the public API per IP

```json
{
  "priority": 200,
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "url", "op": "glob", "value": "/api/v1/**" }
    ]
  },
  "set_directives": {
    "rate_limit": {
      "max_requests": 60,
      "window_seconds": 60,
      "scope": "ip",
      "phase": "pre"
    }
  }
}
```

### Turn detection up for a set of countries

```json
{
  "priority": 150,
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "country", "op": "in", "value": ["CN", "RU", "BR"] }
    ]
  },
  "set_directives": { "bot_detect": "high" }
}
```

### Shadow-test a new block rule for a week

```json
{
  "priority": 80,
  "note": "Trial run for AI-agent block, 2026-05",
  "when_matcher": {
    "combinator": "and",
    "rules": [
      { "field": "crawler.category", "op": "eq", "value": "ai_agent" }
    ]
  },
  "set_directives": { "verdict": "block", "monitor": true }
}
```

### Catch-all fallback at the bottom

The validator treats a top-level empty `and` group (`{ "combinator": "and", "rules": [] }`) as a
match-everything matcher. The dashboard cannot safely create or import this matcher for a new
policy rule. The editor rejects a new empty matcher, and import removes default matchers.

Do not use the dashboard **Default** rule as an enforcement fallback. The validator treats its
`{ "is_default": true }` matcher as invalid and skips the rule, so it enforces nothing. Use explicit
matching rules for policy actions. Use your configured protection level for requests that policy
does not decide, and verify that each new rule fires.

### Common mistakes

* **Forgetting to anchor a regex.** `/admin` matches `/v2/admin/users`. Use `^/admin(/|$)` if you mean only `/admin` and its sub-paths.
* **Treating `.` as a literal dot.** In regex, `.` is any character. Escape it as `\.` inside hostnames or paths.
* **Expecting a glob to stop at a path segment.** `*` crosses `/`, so `/api/*` also matches `/api/users/42`. Use an anchored `regex` clause when you need segment boundaries.
* **Expecting a rule after a verdict to run.** Once any rule sets `verdict`, evaluation stops. Put the directives you always want (like `rate_limit` or `bot_detect`) on a higher-priority rule, or on the same rule as the verdict.
* **Matching a crawler without identification.** Every `crawler.*` clause only fires for identified crawlers. A rule keyed on `crawler.category` never matches ordinary browser traffic.
* **Trying to use lookaround or backreferences.** RE2 does not support them. Split the matcher into a glob plus a second clause, or rewrite the pattern.
* **Combining clauses expecting OR.** Clauses use the group's `combinator`. With `and` (the usual case), every clause must match. For OR, set `combinator` to `or`, nest an `or` group inside your `and` group, or use `|` inside a regex.
* **Putting `monitor: true` on a broad rule.** It shadow-modes every block on the request, not just this rule's. Test new rules in monitor mode, but keep the matcher narrow while you do.
* **Assuming an invalid rule fails loudly.** One bad clause disables the whole rule, and it still looks active in the editor. Confirm a new rule fires before relying on it.

### Related

* [Validation](https://docs.centinelanalytica.com/install/validation.md): How the validator returns decisions and how to enforce them in your backend.
* [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md): Where to find your API keys and configure protected endpoints.

---

# Passports

> Issue a credential that lets one tool or partner through your bot protection, verified on every request.

Source: https://docs.centinelanalytica.com/admin/passports

## Overview

A **passport** is a credential you issue to one tool or partner so their requests get through your bot protection.

Use it when you cannot allow that traffic by IP or user agent: the addresses change, or the user agent is one anyone can copy. A passport is checked on every request instead, so you know the traffic is theirs.

Passports are yours alone. No other organisation sees them, and you do not wait on us to add anything.

If the traffic is a public crawler we already track, use the [crawler catalog](https://docs.centinelanalytica.com/concepts/crawler-catalog.md) instead. That is one toggle and no credential to exchange.

You manage passports on the [Passports page](https://dash.centinelanalytica.com/passports), under **Configuration** in the sidebar.

## Verification methods

A passport verifies one of two ways. You choose when you issue it, and the choice is fixed for that passport's life.

**Static Key**

We generate a secret. The holder sends it in an `X-Passport-Key` header on every request:

```bash
curl https://example.com/api/prices \
  -H "X-Passport-Key: cbp_abcdefghijklmnopqrstuvwxyz"
```

Choose this when the other side has no signing setup. All it asks of them is the ability to set a header.

It does ask something of you: the header has to survive your edge. Every integration we ship forwards it. Most forward whatever the client sent; the Apache module reads a fixed list of header names, so it has to be a build from this release or newer.

**Web Bot Auth**

The other side signs each request under [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html) and publishes the public half of their signing key at a **key directory host**: a domain they control, serving a JSON document at a fixed path.

```text
https://partner.example.com/.well-known/http-message-signatures-directory
```

You enter only the host. We build the rest of that URL, fetch the document on our own schedule, and check each signature against the Ed25519 keys it lists:

```json
{
  "keys": [
    { "kty": "OKP", "crv": "Ed25519", "x": "<base64url public key>" }
  ]
}
```

No secret is exchanged, and keys are rotated by editing that document.

> **Name a host the other side controls:** Whoever controls that hostname decides which keys we trust for this passport. We check the value is a hostname — not an address, a port or a URL — and nothing more.

## Issue a passport

1. ### Name the holder

   Name the tool or partner that holds the passport, not the person who asked for it. The name is what you match against when you come back to revoke it.

2. ### Choose the method and an expiry

   Pick **Static key** or **Web bot auth**, and for web bot auth enter the key directory host. Then choose a lifetime, or **Never**. An expiry is what eventually forces someone to look at the credential again, so prefer a date you are willing to revisit.

3. ### Send the key

   The key is shown with a `curl` command carrying it, so you can check the passport works before you hand it over. Send it over a channel you trust. You can read it again later from the Show key action on its row.

## What a passport changes

A verified request is allowed, and **it beats crawler denial**. If you have denied a catalogued crawler and then issue a passport to a partner whose fetcher sends that crawler's user agent, the passport wins. If that is not what you want, revoke the passport rather than changing the crawler setting.

Your own rules still run, and they are read before the passport is. A passport turns off the bot verdict, not your policy, so you can hold a holder to certain paths, or block one passport during an incident without revoking it. Use the [`passport` field](https://docs.centinelanalytica.com/admin/policy.md) in a rule.

A rule that only rate-limits does not apply here. The passport allows the request outright, and that answer ends the check before any limit is counted, the same way an allowed crawler does. Policy can narrow a passport or block it, not meter it.

## Review and revoke

The Passports page lists every live passport with the requests it admitted in the last day. Open one to see the last seven days in detail: how many requests, from which addresses, and which endpoints they asked for.

The addresses are the part worth checking. A passport goes to one holder, so a credential answering from addresses you do not recognise is the clearest sign a key has leaked.

Revoking is immediate on your side and takes up to a minute to reach every server checking requests. To rotate instead, issue the second passport and send the new key before revoking the old one, so nobody is locked out mid-rotation.

### Related

* [Crawler catalog](https://docs.centinelanalytica.com/concepts/crawler-catalog.md): Allowing bots Centinel already tracks, without issuing anything.
* [Policy rules](https://docs.centinelanalytica.com/admin/policy.md): Writing rules, including rules that match a passport.
* [Security groups](https://docs.centinelanalytica.com/admin/security-groups.md): Who on your team may issue and revoke one.

---

# Security Groups

> Grant scoped read, write, or admin access to specific resources. Covers default groups, allow vs deny, and the resolver.

Source: https://docs.centinelanalytica.com/admin/security-groups

## Overview

A **security group** is a named bundle of permissions plus a list of people. For dashboard actions wired to security-group authorization, the server resolves the member's groups together with their role baseline before it allows the action.

If your team is "everyone is an admin", the default groups already cover you and you do not need
this page.

You manage groups on the [Security groups page](https://dash.centinelanalytica.com/organisation/security-groups), reachable from the sidebar under **Organisation**. The [Team & Security page](https://dash.centinelanalytica.com/organisation/team) links to it too, and has a per-member **Manage groups** action.

## Vocabulary

> **Four terms used throughout this page:**
>
> * **Role**: `owner`, `admin`, or `member`. Set when you invite someone from the Team tab. The role gives every user a baseline of permissions (see [Role baseline](#how-the-resolver-decides) below).
> * **Resource**: a category of thing in the dashboard: `analytics`, `crawlers`, `policy_rules`, `members`, `settings`, `security_groups`.
> * **Level**: `read`, `write`, or `admin`. Higher levels include lower ones, so `admin` covers `write` and `read`.
> * **Effect**: `allow` or `deny`. A group permission combines a resource, an effect, and a level: for example, `allow: write` on `policy_rules`.

## Default groups

Every organisation starts with two groups, created automatically when the organisation is created and re-created on demand if they ever go missing:

* **Admins**: full admin on every resource. Anyone you invite as an admin (or the org owner) joins automatically.
* **Members**: read access on analytics, crawlers, and policy rules. Anyone invited as a member joins automatically.

You can edit either default group. You can't delete them. The system identifies them by an internal tag (`seed_kind: admin` or `seed_kind: member`), not by name, so renaming them is safe but losing them is not.

## Custom groups

### Resources

A group can grant or deny access on any of these:

| Resource          | What it covers                                                                                                      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `analytics`       | A permission resource only. No dashboard analytics view checks it yet, so it does not hide traffic data on its own. |
| `crawlers`        | Crawler whitelist changes and robots.txt monitor settings.                                                          |
| `policy_rules`    | The full [Policy rules](https://docs.centinelanalytica.com/admin/policy.md) editor.                                 |
| `members`         | Invite, role-change, and remove team members.                                                                       |
| `settings`        | Organisation settings, API key rotation, 2FA requirement, deletion.                                                 |
| `security_groups` | Create and edit security groups themselves.                                                                         |

### Allow vs deny

A permission is one of two effects, applied at a specific level:

* **`allow`** grants access at the given level. If two groups grant the same resource, the higher level wins.
* **`deny`** blocks access. Deny always beats allow.

Deny is level-aware: **`deny: L` blocks every check that requires level L or higher**. The strictest deny across all the user's groups wins.

| Deny          | Blocks                           | Leaves      |
| ------------- | -------------------------------- | ----------- |
| `deny: read`  | read, write, admin (full denial) | nothing     |
| `deny: write` | write, admin                     | read        |
| `deny: admin` | admin actions only               | write, read |

So if you put an admin in a group with `deny: write` on `policy_rules`, they retain read access but cannot create, edit, delete, import, or reorder policy rules. `deny: admin` on its own is almost never what you want. It only blocks admin-level actions on a resource, for example API-key rotation on `settings`, and leaves regular writes intact.

> **\`allow: read\` won't lock down an admin:** An admin already has `admin` on every resource via their role. Adding them to a group with `allow: read` is a no-op: the resolver picks the highest level it sees, and the role baseline (admin) is still higher.
>
> To actually restrict an admin you need a `deny` rule, or the &#x2A;*Restricted (read-only override)** template below.

### Pickable templates

When you click **New group** on the security groups page, the dialog asks for a name, a description, and a starting template. The editor opens after you create the group; you can tweak any permission from there.

Groups apply to your whole organisation. Dashboard authorization checks run at organisation scope.

| Template                            | What it sets                                                                                                                                                                                                                                                       |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Blank**                           | No permissions. Configure them yourself in the editor.                                                                                                                                                                                                             |
| **Read-only auditor**               | `allow: read` on every resource. Good for granting visibility to a non-admin. Does not restrict admins.                                                                                                                                                            |
| **Restricted (read-only override)** | `deny: write` on every resource. For an admin, the resolver reduces each resource to effective `read`, blocking resolver-protected write and admin operations. It also prevents that person from opening Security groups, which requires `security_groups: admin`. |
| **Member manager**                  | `allow: admin` on `members`.                                                                                                                                                                                                                                       |
| **Policy editor**                   | `allow: write` on `policy_rules`; `allow: read` on `analytics` and `crawlers`.                                                                                                                                                                                     |

### Adding someone to a group

Two ways:

1. **At invite time.** On [Team & Security](https://dash.centinelanalytica.com/organisation/team), click **Invite member**. The dialog has an **Additional security groups** picker listing your custom groups. Membership of Admins or Members follows the role you pick, so those two are not in the list. Invitees land in the groups you tick the moment they accept.

2. **For an existing member.*&#x2A; Same page, click the &#x2A;*⋯** menu next to their name, choose **Manage groups**. Tick the boxes for the groups you want them in and save.

Team & Security is the single source of truth for who is in which group. The security group editor shows members as a read-only list.

### Groups and roles are one thing

The two default groups and the role field are two views of the same setting, kept in sync both
ways. Changing someone's role moves them between Admins and Members. Changing their groups rewrites
their role: ticking **Admins** in *Manage groups* makes them an admin, and unticking it demotes them
to member. The two groups are mutually exclusive.

Owners are exempt from that projection, and only an owner can edit another owner's groups. An admin
also cannot demote a fellow admin this way.

### How the resolver decides

When the dashboard needs to know whether a user can do something, it runs the same four steps:

1. **Apply deny rules.** Walk every group the user belongs to. For each resource, track the strictest deny level seen (lowest rank = blocks more). `deny: read` is the floor and blocks everything; `deny: write` blocks write+admin; `deny: admin` blocks admin only.

2. **Apply allow rules.** Walk every group again. For each resource, keep the highest allowed level, capped at one level below any deny in force. So `allow: admin` on a resource with `deny: write` ends up as effective `read`.

3. **Role baseline.** Raise each resource to the role's level if that is higher than what the allow rules produced. Owners and admins get `admin` on everything; members get `read` on analytics, crawlers, and policy rules. The same deny cap applies, so a `deny: write` here trims an admin baseline down to `read`. Because this raises rather than fills, an `allow: read` grant cannot demote an admin.

4. **Anything still unfilled is denied.**

The order matters. Deny rules cap allow rules and the role baseline. An admin with `deny: write` on `policy_rules` cannot edit policy rules; the cap brings their effective level down to `read`, even though their role baseline would otherwise grant `admin`.

#### Owner deny-immunity

The org **owner** is one exception. An owner ignores `deny` rules on the `security_groups` resource specifically. That is the bootstrap escape hatch: if an admin locks everyone out of the security groups page, the owner can still open it, remove the bad rule, and let people back in.

The immunity is scoped to `security_groups` only. Owners are subject to deny on every other resource.

Centinel support staff working in an internal view bypass group permissions entirely. That path is
outside your organisation's control and is not affected by anything on this page.

Every change to a group, permission, or membership is recorded with its before and after state, and
shown on the **Activity** page. Group edits also record the role change they projected.

### Examples

Each block below is a set of rows in the group editor, one row per permission.

#### Auditor with read-only visibility

A consultant needs to look at analytics and crawler data, nothing else.

* Invite them as a **member** (not admin).
* They're auto-added to the seeded **Members** group. That's already enough for read access on analytics, crawlers, and policy rules.
* If you want the grant to be explicit (e.g. for an audit trail), add a custom group with:

```text
Resource      Effect  Level
analytics     allow   read
crawlers      allow   read
policy_rules  allow   read
```

#### Policy editor without analytics access

Someone manages policy rules but shouldn't see traffic data.

* Invite as a **member**.
* Add to a custom group:

```text
Resource      Effect  Level
policy_rules  allow   write
crawlers      allow   read
analytics     deny    read
```

The `deny: read` on `analytics` blocks the member-role read baseline. (Use `deny: read` to fully hide a resource; `deny: write` would still leave the read view visible.)

#### Lock an admin to read-only

You want to keep someone in the admin role but stop them from making changes during a freeze.

* Keep them as **admin**.
* Add them to a group built from the &#x2A;*Restricted (read-only override)** template:

```text
Resource         Effect  Level
analytics        deny    write
crawlers         deny    write
policy_rules     deny    write
members          deny    write
settings         deny    write
security_groups  deny    write
```

They retain their admin role, but the resolver reduces their effective permission on every resource to `read`; resolver-protected write and admin operations are refused. Because the Security groups pages require `security_groups: admin`, they cannot open those pages. The owner can remove them from the group when the freeze ends.

### Where enforcement runs

The resolver currently gates these server-side dashboard actions:

| Action                                        | Resource:Level required |
| --------------------------------------------- | ----------------------- |
| Edit policy rules                             | `policy_rules: write`   |
| Save the interstitial / blocked HTML template | `settings: write`       |
| Edit the crawler whitelist                    | `crawlers: write`       |
| Save robots.txt monitor settings              | `crawlers: write`       |
| Invite, change role, remove a member          | `members: admin`        |
| Rotate API keys                               | `settings: admin`       |
| Change the organisation name or require 2FA   | `settings: admin`       |
| Request organisation deletion                 | `settings: admin`       |

Opening either Security groups page requires `security_groups: admin`. A user without that access is redirected away.

### Common mistakes

* **Expecting `allow: read` to take admin access away.** It can't. Allow rules can only grant. Use `deny` for downgrades.
* **Using the Read-only auditor template on an admin and wondering why they can still edit things.** That template is allow-only. Switch to &#x2A;*Restricted (read-only override)**.
* **Forgetting that the seeded Admins group grants admin everywhere.** If you also put the same user in a restrictive group, deny will win; but if you only grant allow rules, the Admins group keeps them at admin.
* **Trying to lock the owner out of `security_groups`.** You can't. The owner is always able to recover. If they're the only admin and you try to remove them from the Admins group, the action is blocked server-side.

### Related

* [Policy rules](https://docs.centinelanalytica.com/admin/policy.md): The rule engine that decides which requests to allow, block, or rate-limit.
* [Dashboard](https://docs.centinelanalytica.com/install/dashboard.md): API keys, and where to find the security groups page.

---

The crawler catalog is left out of this file. It is at https://docs.centinelanalytica.com/concepts/crawler-catalog.md.