# camada: full text of www.camada.app

> camada keeps bad actors out of web apps and APIs: attackers using AI, AI agents that act like attackers, credential stuffers, scrapers and CVE exploit scanners. Customers and verified search crawlers get through.

An SDK inside the app (Node, Next.js, Hono, Python, Go, PHP, Ruby, Java and .NET) sends one redacted event per request. Watchkeeper, camada's AI analyst, reviews the traffic every few minutes and writes a verdict with the evidence behind it. The SDK enforces the resulting blocklist in the app's own process, with a 403 or a challenge page. If camada is down or the SDK fails, the app keeps serving (fail open).

- Plans: Free: $0/month, 100,000 events a month; Starter: $59/month, 1,000,000 events a month; Growth: $249/month, 10,000,000 events a month; Enterprise: price set with each customer, for volume past Growth. Free needs no card. A 14-day trial of Starter or Growth needs a card. Nothing is charged today. Cancel before the trial ends (the date is shown in the app) and you pay nothing. Otherwise the plan's monthly price starts on day 15.
- Sign up and create a project at https://my.camada.app. The project key (CAMADA_KEY) is shown once, when the project is created.
- Every page below is also served as Markdown: the links point at the .md files, and each HTML URL returns the same Markdown when requested with `Accept: text/markdown`.
- Coding agents adding camada to an app: follow the quickstart for the framework, and use the install command it shows (PHP, Java and .NET install from GitHub until they are on their registries). The same steps are at https://www.camada.app/AGENTS.md, and as an agent skill listed at https://www.camada.app/.well-known/agent-skills/index.json.
- Company: Camada Labs, LLC. Contact hello@camada.app; security reports to security@camada.app.

---

Source: https://www.camada.app/

In-app SDKs for Node, Next.js, Hono, Python, Go, PHP, Ruby, Java and .NET

# An AI watchkeeper that keeps bad actors out of your app.

Watchkeeper is camada's AI analyst. Every few minutes it reviews your traffic and catches attackers, and AI agents that act like them. Your app blocks them before your code runs. Customers and verified search crawlers get through. One package and one middleware on most stacks. If camada goes down, your app keeps serving.

[Get started free](https://my.camada.app/) [See how it works ↓](https://www.camada.app/#how)

Free needs no card. A 14-day trial of Starter or Growth needs a card. Nothing is charged today. Cancel before the trial ends (the date is shown in the app) and you pay nothing. Otherwise the plan's monthly price starts on day 15. The analyst runs every few minutes while your project has traffic.

Illustration: Watchkeeper, camada's AI analyst, looks back over requests your app already served and picks clients to block or challenge. Once enforcement is on, your app refuses a blocked client's next request and shows a challenged client a challenge page. Customers and verified crawlers like Googlebot get through.

Illustration. Watchkeeper reviews requests your app already served, every few minutes. Your app enforces what it finds.

The problem

## Bots aren't the problem. Bad actors are.

For product teams with logins, signups or a checkout to protect, and no security team. Half the web is bots, and plenty of them are fine. The danger is the ones sent to attack you.

### Gets in

- Your customers
- Search engines like Googlebot. Fakes pretending to be Googlebot get caught.
- Bots you trust, on your allow-list

### Gets blocked

- Attackers using AI to find holes and break in
- AI agents and scripts that act like attackers
- Credential stuffers testing stolen passwords
- Scrapers copying your prices and content

### Why now

53%

of web traffic in 2025 came from bots, not people.

[Thales Imperva, 2026 Bad Bot Report](https://cpl.thalesgroup.com/resources/application-security/2026-bad-bot-report), 2026

12.5×

more AI-driven bot attacks than a year earlier: 2M a day became 25M.

[Thales Imperva, 2026 Bad Bot Report](https://cpl.thalesgroup.com/resources/application-security/2026-bad-bot-report), 2026

80–90%

of a state-backed intrusion campaign was run by an AI agent, with humans stepping in at a handful of decisions.

[Anthropic, Disrupting AI-orchestrated espionage](https://www.anthropic.com/news/disrupting-AI-espionage), 2025

−7 days

mean time to exploit: attacks now start before the patch ships.

[Mandiant, M-Trends 2026](https://cloud.google.com/blog/topics/threat-intelligence/m-trends-2026), 2026

How camada handles each: [credential stuffing](https://www.camada.app/use-cases/credential-stuffing), [scraping](https://www.camada.app/use-cases/scraping), [AI agent abuse](https://www.camada.app/use-cases/ai-agents) and [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits).

camada can't patch your code or stop a one-off exploit request. It finds clients that scan, probe and keep coming back, and once enforcement is on, keeps them out from its next run.

### Attackers now have AI

People use AI models to scan your app, write exploits and try stolen passwords faster than any human team could.

### Some AI agents act like attackers

Automated agents scrape what they should not, abuse signups and hammer logins. camada judges them by what they do, whoever sent them.

### Both look like customers

Real browsers, home IP addresses, valid requests. One request at a time they look normal, so rate limits miss them. camada looks at the whole session.

The AI analyst

## Meet Watchkeeper, your AI analyst

Every few minutes it reads what your app saw and investigates the clients that look wrong. Each verdict says why, with the requests behind it.

Example verdict · IP · `203.0.113.x`

### Scanner

Malicious · 96% confidence

Blocked for 12 hours

This address walked a list of well-known admin and config paths in a few seconds. Nearly every request ended in a 404, which is how a probe looks and not how a visitor does.

- 212 requests in 40 seconds across 187 distinct paths
- Hit /wp-login.php, /.env, /.git/config and /phpmyadmin in sequence
- 94% of responses were 404 or 403
- No cookies kept and no static assets fetched

In the app, you can lift this block or change how long it lasts.

Example verdict · Session · `ses_7f3a9c1e04b2`

### Credential stuffing

Malicious · 91% confidence

Blocked for 6 hours

This session submitted login attempts for many different accounts with one password pattern. The failure rate and pacing match a stolen-credential list being replayed.

- 38 login attempts for 36 different usernames in 3 minutes
- 97% of attempts returned an invalid credentials response
- Requests spaced at near-identical intervals of about 4.7 seconds
- Login form posted with no prior page view of the form

In the app, you can lift this block or change how long it lasts.

Example verdict · IP · `198.51.100.x`

### Injection

Malicious · 88% confidence

Blocked for 3 days

Query parameters on several endpoints carried SQL fragments and encoded script tags. The same payload shapes were tried against each parameter in turn.

- Parameter values containing ' OR 1=1 -- and UNION SELECT
- Encoded <script> payloads in the query string of the search page
- Same 9 payloads cycled across 14 endpoints
- Server returned 500 on 6 of the requests

In the app, you can lift this block or change how long it lasts.

Example verdict · TLS fingerprint · `tlsx_b81d52ce9a07`

### Scraping

Suspicious · 72% confidence

Challenge recommended for 4 hours

This client fetched product pages in catalog order at a steady pace from many addresses that share one TLS fingerprint. The pattern fits bulk collection, though the volume is below what would justify a block.

- Same TLS fingerprint seen from 23 different addresses in one run window
- Product pages requested in ascending ID order
- No images, scripts or stylesheets loaded
- Pace held within a narrow band of 1.2 to 1.5 seconds per page

In the app, you choose what this category does: block, challenge, alert or ignore.

Example verdict · Session · `ses_c20e6d8f19a5`

### Automation

Suspicious · 64% confidence

Challenge recommended for 2 hours

This session completed a sign-up form faster than a person could type it. The interaction timing was uniform from the first field to the submit.

- Form submitted 1.1 seconds after page load
- No key presses or pointer moves recorded before submit
- Browser reported properties typical of a headless client

In the app, you choose what this category does: block, challenge, alert or ignore.

Example verdict · IP · `66.249.66.x`

### Cleared

Benign · 97% confidence

Allowed

This address belongs to a verified search crawler and is reading public pages at a normal rate. Nothing in its behaviour calls for action.

- IP matches Google's published crawler ranges
- User agent claims Googlebot and the address backs it up
- No logins, signups or form posts
- Request rate stayed under 2 per second

In the app, you can still block this address by hand.

Examples written for this page in the format the app uses. Not live traffic or customer data. Confidence is the model's own estimate.

### How a verdict gets made

1. `1`

   Rules

   63 rules score each client three ways: by IP, by session and by TLS fingerprint. 6 of them look for signs of a real person and lower the score.
2. `2`

   Triage model AI

   Reviews the suspects 15 at a time and picks the ones worth a closer look.
3. `3`

   Investigation agent AI

   Pulls raw request samples and the facts you recorded about your site, then writes a verdict with evidence. When one of your facts explains the traffic, it quotes it.
4. `4`

   Verdict

   Malicious, suspicious or benign, with a confidence, an action and how long it lasts.
5. `5`

   Your blocklist

   Your app pulls it every 30 seconds and checks each request against it in memory.

Stages 2 and 3 are the AI. Today triage runs on Llama 3.3 70B and the investigation agent on DeepSeek V4 Flash, both open-weight models on Cloudflare Workers AI.

The 63 rules only pick suspects. The models decide what each one is, how sure they are and what they recommend.

Fake Googlebots get caught against Google's published IP ranges. The real one gets through.

### The AI is not on your request path.

Your app never waits for a model. The analyst works on events after your app has answered them, and the SDK checks each request against a blocklist it already holds. A model can't add latency to a request or change its answer mid-flight. Enforcement is a plain blocklist, and you can see each entry and its reason in the app.

### Guardrails

Two come straight from its instructions.

- Never block on a user agent alone. (from its instructions)
- Prefer challenge over block when unsure. (from its instructions)
- A block needs a malicious verdict at 80% confidence or more, by default.
- Each new project starts in a learning window that only recommends. A person on your team turns enforcement on.
- If the model answers with junk, camada marks the client suspicious with a placeholder confidence. That can never block it, and at most it gets a challenge. If a model call fails, the run stops and writes no verdicts.

The prompts have a small test set: 15 hand-labelled and prompt-injection cases, run on Workers AI. A case labelled as a real person that comes back blocked scores zero. It catches prompt mistakes. It is too small to prove how well the detection works.

### You're in control

- **Learning window.** See what it would block, and why, before it blocks anything.
- **Allow-list.** Clients on your allow-list stay off the blocklist.
- **Overrides.** Unblock or extend any block, turn rules off, and choose what each category does: block, challenge, alert or ignore.
- **Audit log.** On Enterprise, admins can see who changed blocks, the allow-list, rules and facts.

Spikes reach you by email, Slack or signed webhook, depending on your plan. On Growth and Enterprise you can ask the chat agent why a client was blocked.

### Why its verdicts hold up

It knows which account.

With track(), camada sees which account a failed login, signup or declined payment was for, as a hash, and what happened. A service in front of your app sees the request and the response, but learns your app's outcome only if you send it separately. track() is one extra call in your code for each outcome you report.

It learns from other customers, privately.

An address flagged by 3 or more other paying organizations scores higher for you. camada never shows you who flagged it.

It keeps the evidence.

Each verdict is stored with its summary, evidence and the run report, so you can check its work later.

[Forrester](https://www.forrester.com/blogs/bot-management-graduates-introducing-the-bot-and-agent-trust-management-market/) renamed this market in October 2025, from bot management to bot and agent trust management. camada works on the bad-actor side: finding them and keeping them out. camada does not check signatures from AI agents today, so it can't vouch for the agents you want to let in. It judges agents by what they do, and your allow-list lets in the ones you trust.

Why camada

## Your edge sees packets. Your app sees customers.

camada runs inside your backend, where a scripted signup and a real one look different.

### Runs in your process

The blocklist lives inside your backend and refreshes every 30 seconds. Nothing waits on camada while a request is served.

### Fails open

Every SDK call sits in a try/catch. An outage or a bug in camada never returns a 5xx from your app.

### Shows its work

The analyst writes a verdict for each client it flags, with the requests behind it, so you can read why it acted.

### Open source SDKs

MIT licensed and public on GitHub, linked below. Read the redaction code yourself.

Source on GitHub: [Node](https://github.com/camada-app/camada-node) · [Next.js](https://github.com/camada-app/camada-next) · [Hono](https://github.com/camada-app/camada-hono) · [SvelteKit](https://github.com/camada-app/camada-sveltekit) · [Python](https://github.com/camada-app/camada-python) · [Go](https://github.com/camada-app/camada-go) · [PHP](https://github.com/camada-app/camada-php) · [Ruby](https://github.com/camada-app/camada-ruby) · [Java](https://github.com/camada-app/camada-java) · [.NET](https://github.com/camada-app/camada-dotnet). PHP, Java and .NET install from GitHub until they are on Packagist, Maven Central and NuGet.

### How camada compares

| Topic | Edge bot management | In-app rule libraries | camada |
| --- | --- | --- | --- |
| Setup | Route your traffic through it, usually with a DNS or CDN change | A package in your app | A package in your app. Your CDN stays as it is. |
| Where it runs | In front of your app, usually at the CDN | Inside your app | Enforcement inside your app. The analysis runs in a separate Cloudflare Worker. |
| When it decides | On each request, as it arrives | On each request, as it arrives | Every few minutes, over whole sessions, IPs and TLS fingerprints. Each request only checks a blocklist your app already holds. |
| Account outcomes | Sent separately, if the product supports it | What your code passes in on each request | Your track() outcomes, through the same package that enforces, tied to a hashed account id |

camada runs inside your app, so you can keep your CDN in front of it. Side by side with named products: [camada vs Cloudflare Bot Management](https://www.camada.app/compare/cloudflare-bot-management) · [camada vs Arcjet](https://www.camada.app/compare/arcjet).

Judging after the fact has a cost. A new client's first requests reach your app until a run flags it and your app pulls the new blocklist, unless a path entry or one of your rules already covers it.

### Leaves your app

- Method, path and query shape
- Status, latency, header names and order
- Client IP, session id, browser beacon fields
- A hash of the user id you pass to track()

### Never leaves your app

- Authorization and Cookie values
- Request and response bodies
- Tokens, keys and passwords in query strings
- Raw user ids and emails

[The full list, and how redaction works →](https://www.camada.app/security)

How it works

## Install, watch, enforce.

1. `1`

   ### Install

   Add the package and its middleware, then set one env var. Events ship in the background, off the request path.
2. `2`

   ### Watch

   A learning window runs in recommend-only mode. You see what camada would block and why.
3. `3`

   ### Enforce

   You turn it on. Matching requests get a 403 before your handler runs.

Express · @camada/node

```js
npm i @camada/node

import camada from '@camada/node';
app.use(camada.express());
```

Next.js · @camada/next

```ts
npm i @camada/next

// middleware.ts (Next ≤15) or proxy.ts (Next 16) at the project root
import { camada } from '@camada/next';
export default camada();
export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };

// app/api/camada/[...camada]/route.ts
import { camadaRoute } from '@camada/next';
export const { GET, POST } = camadaRoute();

// app/layout.tsx, inside <head>
import { CamadaBeacon } from '@camada/next';
<CamadaBeacon />
```

[Get started free](https://my.camada.app/) [All 14 frameworks →](https://www.camada.app/frameworks) [The full pipeline →](https://www.camada.app/how-it-works)

What changes

## Same app. Fewer fake users.

### Without camada

- Scrapers copy your prices and content.
- Credential stuffers test leaked passwords on your login.
- Fake signups burn trial credits and skew your metrics.
- AI crawlers run up your compute bill.

### With camada

- Signups and logins come from real customers.
- Every block shows up in the app with its reason.
- Your code never sees the attackers camada blocks.
- You hear about an attack from an alert, not a customer.

### What camada does not do

Outage or bug: your app keeps serving

CAMADA_DISABLED=1 is a per-request kill switch.

Cold start passes traffic

A fresh serverless instance lets its first request through while the blocklist loads.

In-app blocks: IP, path and your own rules

Your custom rules can also match user agent and headers. ASN, country and TLS-fingerprint entries fail open inside your app, except on Cloudflare Workers with @camada/hono, or with @camada/sveltekit on adapter-cloudflare.

You decide when to enforce

camada never switches a project to enforce on its own.

Get started

## See what's hitting your app today.

The free plan shows you everything camada sees. Paid plans turn on blocking and add Slack alerts. Growth and Enterprise add webhooks.

[Get started free](https://my.camada.app/) [See pricing →](https://www.camada.app/pricing)

---

Source: https://www.camada.app/frameworks

Frameworks

# Security middleware for your framework

Pick your framework. Each snippet is the install for that stack: one package and one middleware on most, a few files for Next.js, and PHP, Java and .NET install from GitHub. The variables are the same everywhere, and the key is printed once when you create a project. Every SDK reads them from the process environment; your framework's quickstart says how to set them there.

environment variables

```dotenv
CAMADA_KEY=<ingest_token>.<snap_token>
CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

More JavaScript runtimes, each published on npm with install steps in its README:

- [@camada/sveltekit](https://github.com/camada-app/camada-sveltekit) for SvelteKit, as a handle hook
- [@camada/nuxt](https://github.com/camada-app/camada-nuxt) for Nuxt, as h3 server middleware
- [@camada/remix](https://github.com/camada-app/camada-remix) for React Router framework mode (Remix), as root server middleware
- [@camada/bun](https://github.com/camada-app/camada-bun) for Bun.serve
- [@camada/deno](https://github.com/camada-app/camada-deno) for Deno.serve
- [@camada/react](https://github.com/camada-app/camada-react) adds the beacon to React apps with <CamadaBeacon />

[Node.js 5](https://www.camada.app/frameworks#node) [Python 3](https://www.camada.app/frameworks#python) [Go 1](https://www.camada.app/frameworks#go) [Ruby 1](https://www.camada.app/frameworks#ruby) [PHP 2](https://www.camada.app/frameworks#php) [Java 1](https://www.camada.app/frameworks#java) [.NET 1](https://www.camada.app/frameworks#dotnet)

## Node.js

### Express `@camada/node`

npm i @camada/node

```js
import camada from '@camada/node';
app.use(camada.express());
```

- Works for Connect-style stacks too.
- Register it before your routes so blocked requests never reach them.

[Express quickstart →](https://www.camada.app/docs/quickstart/express)

### Fastify `@camada/node`

npm i @camada/node

```js
import { camadaFastify } from '@camada/node/fastify';
await app.register(camadaFastify);
```

- Register the plugin at the root instance so every route is covered.

[Fastify quickstart →](https://www.camada.app/docs/quickstart/fastify)

### NestJS `@camada/node`

npm i @camada/node

```ts
import { CamadaModule } from '@camada/node/nest';

@Module({ imports: [CamadaModule.forRoot()] })   // Nest ≤10: CamadaModule.forRoot({ routes: '*' })
export class AppModule {}
```

- Default Express platform. On the Fastify platform register the Fastify plugin instead.

[NestJS quickstart →](https://www.camada.app/docs/quickstart/nest)

### Koa `@camada/node`

npm i @camada/node

```js
import { camadaKoa } from '@camada/node/koa';
app.use(camadaKoa());
```

- Mount it first in the middleware chain.

[Koa quickstart →](https://www.camada.app/docs/quickstart/koa)

### Next.js `@camada/next`

npm i @camada/next

```ts
// middleware.ts (Next ≤15) or proxy.ts (Next 16) at the project root
import { camada } from '@camada/next';
export default camada();
export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };

// app/api/camada/[...camada]/route.ts
import { camadaRoute } from '@camada/next';
export const { GET, POST } = camadaRoute();

// app/layout.tsx, inside <head>
import { CamadaBeacon } from '@camada/next';
<CamadaBeacon />
```

- App router. Three files, one env var.
- On Vercel the middleware sees x-vercel-ja4-digest, a real TLS fingerprint, and Vercel's X-Forwarded-For is trusted by default.
- Events ship before the response, so status is unknown at this position. Blocked requests ship with 403.
- Keep the matcher as broad as the example. Every route it excludes is invisible to camada.

[Next.js quickstart →](https://www.camada.app/docs/quickstart/nextjs)

## Python

### FastAPI `camada`

pip install camada

```python
from camada.fastapi import CamadaMiddleware
app.add_middleware(CamadaMiddleware)   # any Starlette app too
```

- A pure ASGI middleware: streaming responses and lifespan are untouched.
- Add it last, so it runs outermost and answers before anything else.

[FastAPI quickstart →](https://www.camada.app/docs/quickstart/fastapi)

### Django `camada`

pip install camada

```python
# settings.py
MIDDLEWARE = ["camada.django.CamadaMiddleware", *MIDDLEWARE]
```

- Put it first, so blocked requests never reach the rest of the stack.
- Sync and async stacks alike; the matched route pattern rides the event.

[Django quickstart →](https://www.camada.app/docs/quickstart/django)

### Flask `camada`

pip install camada

```python
from camada.flask import init_app
init_app(app)   # wraps app.wsgi_app, so camada answers before routing
```

- Wraps the WSGI app rather than registering a before_request hook: the beacon and challenge endpoints answer before routing.

[Flask quickstart →](https://www.camada.app/docs/quickstart/flask)

## Go

### Go `github.com/camada-app/camada-go`

go get github.com/camada-app/camada-go

```go
import "github.com/camada-app/camada-go"

mux := http.NewServeMux()
mux.HandleFunc("GET /{$}", home)
http.ListenAndServe(":8080", camada.Handler(mux))   // outermost, so camada answers before routing
```

- net/http: any router built on http.Handler sits behind it.
- The first request builds the engine and is answered cold; camada.Default().Stop(ctx) before main returns drains the last batch.

[Go quickstart →](https://www.camada.app/docs/quickstart/go)

## Ruby

### Rails `camada`

bundle add camada

```ruby
# config.ru — Sinatra, Hanami, or any Rack app
require "camada"
use Camada::Rack      # first, so camada answers before routing
run App

# Rails — nothing to add: the Railtie inserts Camada::Rack at the top of the middleware stack
```

- One gem, one Rack middleware; the Railtie mounts it for Rails.
- Never request.ip: the middleware reads REMOTE_ADDR and applies your trusted-proxy rules itself.

[Rails quickstart →](https://www.camada.app/docs/quickstart/rails)

## PHP

### PHP `camada/camada`

Not on Packagist yet. Run these in your project's folder: Composer installs it straight from GitHub, composer.lock pins the commit, and composer update camada/camada moves it.

install

```sh
composer config repositories.camada vcs https://github.com/camada-app/camada-php
composer require camada/camada:dev-main
```

```php
<?php
// public/index.php — any front controller
require __DIR__ . '/../vendor/autoload.php';

use Camada\Camada;
use Camada\Http\Sapi;

$cam = Camada::default();      // built lazily from the environment, once per request
$ctx = Sapi::run($cam);        // null: camada answered (block, challenge, beacon) and the script must stop
if ($ctx === null) {
    return;
}
// your app: x-rid and the _sfp cookie are already on the response
```

- Needs nothing but $_SERVER, php://input and header(): FPM, php -S, mod_php.
- The snapshot and event spool live in a file-backed cache every worker shares; both refresh after the response has left.

[PHP quickstart →](https://www.camada.app/docs/quickstart/php)

### Laravel `camada/camada`

Not on Packagist yet. Run these in your project's folder: Composer installs it straight from GitHub, composer.lock pins the commit, and composer update camada/camada moves it.

install

```sh
composer config repositories.camada vcs https://github.com/camada-app/camada-php
composer require camada/camada:dev-main
```

```php
// bootstrap/app.php (Laravel 11+), inside the existing ->withMiddleware(function (Middleware $middleware) { … })
$middleware->prepend(\Camada\Laravel\Middleware::class);   // first in the global stack

// or app/Http/Kernel.php (Laravel 10): the first entry of protected $middleware = [ … ]
\Camada\Laravel\Middleware::class,
```

- Prepend it so blocked requests never reach the rest of the stack.
- terminate() is the post-response phase: the spool ships and the snapshot refreshes after the kernel has sent the response.

[Laravel quickstart →](https://www.camada.app/docs/quickstart/laravel)

## Java

### Spring Boot `dev.camada:camada`

Not on Maven Central yet. From your project's folder: clone it next to the project, build it into your local Maven repository, then add the dependency.

install

```sh
git clone https://github.com/camada-app/camada-java ../camada-java
mvn -q -f ../camada-java install -DskipTests

<!-- then, in pom.xml -->
<dependency>
  <groupId>dev.camada</groupId>
  <artifactId>camada</artifactId>
  <version>0.2.0</version>
</dependency>
```

```java
// CamadaConfig.java, beside your @SpringBootApplication class
package com.example.demo;   // your application's package

import dev.camada.servlet.CamadaFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
class CamadaConfig {
  @Bean
  FilterRegistrationBean<CamadaFilter> camadaFilter() {
    var reg = new FilterRegistrationBean<>(new CamadaFilter());
    reg.setOrder(Ordered.HIGHEST_PRECEDENCE);   // first, so camada answers before routing
    return reg;
  }
}
```

- A plain jakarta.servlet.Filter: Tomcat, Jetty and Undertow take it as is, from web.xml or addFilter at the front of the chain.
- Keep server.forward-headers-strategy=none (the default) so camada judges X-Forwarded-For itself.

[Spring Boot quickstart →](https://www.camada.app/docs/quickstart/spring)

## .NET

### ASP.NET Core `Camada`

Not on NuGet yet. From the folder that holds your .csproj: clone it next to the project, then reference it.

install

```sh
git clone https://github.com/camada-app/camada-dotnet ../camada-dotnet
dotnet add reference ../camada-dotnet/src/Camada/Camada.csproj
```

```csharp
// Program.cs
using Camada.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCamada();      // one engine from the environment, drained on shutdown

var app = builder.Build();
app.UseCamada();                   // FIRST: camada answers before routing, static files, anything
// your routes go here, the beacon one below included: app.Run() blocks, so nothing after it is mapped
app.Run();
```

- Put UseCamada() before UseForwardedHeaders(), if you use it, so camada judges the raw header itself.
- .NET 8; nothing beyond the ASP.NET Core shared framework.

[ASP.NET Core quickstart →](https://www.camada.app/docs/quickstart/aspnet)

Positions

## What each position sees

### @camada/node

Sees the true wire header order, the final status and latency, and app outcomes from track(). Does not see a TLS fingerprint or ASN; those rules skip here. Enforces IP and path entries, and the user-agent and header conditions of your custom rules, with a socket-peer or trusted-proxy IP. ASN, country and TLS-fingerprint entries fail open here.

### @camada/hono

Runs inside a Cloudflare Worker. `request.cf` carries the client's ASN, country and TLS fingerprint, so ASN, country and TLS-fingerprint entries genuinely enforce here, along with IP, path, user-agent and header conditions; events ship through `waitUntil`, off the response path. Workers normalise header order, so the raw wire order is not available. [Docs](https://www.camada.app/docs/hono).

### camada (Python)

The Node position, in a Python process: final status and latency, app outcomes from track(), and the wire's header order under ASGI (FastAPI, Starlette, async Django) but not under WSGI (Flask, sync Django). No TLS fingerprint or ASN; those rules skip here. Enforces IP, path, user-agent and header conditions with a socket-peer or trusted-proxy IP. [Docs](https://www.camada.app/docs/python).

### github.com/camada-app/camada-go (Go)

The Node position, in a Go process: final status and latency, the route pattern, and app outcomes from Track(). net/http parses headers into a map, so the wire's header order is not available; no TLS fingerprint or ASN either, those rules skip here. Enforces IP, path, user-agent and header conditions with a socket-peer or trusted-proxy IP. [Docs](https://www.camada.app/docs/go).

### camada/camada (PHP)

The Node position, one request at a time: final status and latency and app outcomes from track(), with the snapshot and event spool in a file-backed cache every worker shares, refreshed after the response has left. getallheaders() yields a hash, so no header order; no TLS fingerprint or ASN; those rules skip here. Enforces IP, path, user-agent and header conditions with REMOTE_ADDR or a trusted-proxy IP. [Docs](https://www.camada.app/docs/php).

### camada (Ruby)

The Node position, in a Ruby process: final status and latency, the matched route, and app outcomes from Camada.track. The Rack env carries no wire header order; no TLS fingerprint or ASN; those rules skip here. Enforces IP, path, user-agent and header conditions with REMOTE_ADDR or a trusted-proxy IP — never request.ip. [Docs](https://www.camada.app/docs/ruby).

### dev.camada:camada (Java)

The Node position, in a JVM: final status and latency, the Spring MVC route pattern, app outcomes from Camada.track(), and the header order as the container hands it over. No TLS fingerprint or ASN; those rules skip here. Enforces IP, path, user-agent and header conditions with getRemoteAddr() or a trusted-proxy IP. [Docs](https://www.camada.app/docs/java).

### Camada (.NET)

The Node position, in an ASP.NET Core process: final status and latency, the matched route, and app outcomes from CamadaTrack(). Header order is what IHeaderDictionary reports, not the wire's under Kestrel; no TLS fingerprint or ASN; those rules skip here. Enforces IP, path, user-agent and header conditions with the connection peer or a trusted-proxy IP. [Docs](https://www.camada.app/docs/dotnet).

### @camada/next

Runs in middleware before the cache. On Vercel it sees a JA4 TLS digest and a trustworthy client IP. Headers arrive sorted, and events ship before the response, so status is unknown except for blocks. Enforces IP and path entries and the user-agent and header conditions of your custom rules; ASN, country and TLS-fingerprint entries fail open. Needs a trusted-proxy setting off Vercel or IP rules do not enforce.

---

Source: https://www.camada.app/glossary

Glossary

# camada glossary

**Allow-list**

Clients you have said to let through. An allow-list entry always wins over a block, wherever the two overlap. See [Rules and list entries](https://www.camada.app/docs/rules).

**Bad actor**

Anyone abusing your app, whatever they run on: attackers using AI, AI agents that act like attackers, credential stuffers, scrapers and CVE exploit scanners. Customers and verified search crawlers are not bad actors.

**Beacon**

An optional addition to your HTML pages. It cuts false positives by showing which sessions are real browsers. See [Docs](https://www.camada.app/docs).

**Blocklist**

The clients your app refuses. The SDK holds it and checks each request against it, so enforcement never waits for a model. You can see each entry and its reason in the app. See [How it works](https://www.camada.app/how-it-works).

**Challenge**

A small proof-of-work page the SDK serves instead of your app, where it can. A real browser passes it in well under a second and carries on. See [Challenge](https://www.camada.app/docs/challenge).

**Credential stuffing**

Trying stolen username and password pairs against a login, in bulk. See [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

**CVE exploit scan**

Probing an app for known, published vulnerabilities. See [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits).

**Event**

The one redacted record an SDK sends for each request. Events are what the analyst reviews and what your plan counts. See [Security](https://www.camada.app/security).

**Fail open**

If camada is down or the SDK fails, your app keeps serving. See [Security](https://www.camada.app/security).

**Project key**

The CAMADA_KEY your SDK reads from the environment. It is shown once, when you create the project. See [Docs](https://www.camada.app/docs).

**Rogue AI agent**

An AI agent that acts like an attacker. It is judged by the same evidence as any other attacker: what it requests and how. See [AI agent abuse](https://www.camada.app/use-cases/ai-agents).

**Rule**

A condition on traffic and what to do when it matches: block, challenge, alert or ignore. See [Rules and list entries](https://www.camada.app/docs/rules).

**Scraping**

Collecting a site’s content in bulk, usually spread across many addresses to stay under per-address limits. See [Scraping](https://www.camada.app/use-cases/scraping).

**TLS fingerprint**

A signature of how a client sets up its encrypted connection. Many addresses sharing one fingerprint can point to one tool. See [Rules and list entries](https://www.camada.app/docs/rules).

**track()**

The SDK call that reports login failures, signups and checkout declines, the outcomes only your app knows. The identifier is HMAC-hashed in your process. See [Docs](https://www.camada.app/docs).

**Verdict**

What the analyst decides about a client, with the requests behind it and the reason why. See [How it works](https://www.camada.app/how-it-works).

**Verified crawler**

A search crawler, like Googlebot, confirmed to be who it says it is. Verified crawlers get through.

**Watchkeeper**

camada’s AI analyst. Every few minutes it reviews your traffic and writes a verdict on each client that looks wrong. See [How it works](https://www.camada.app/how-it-works).

**x-rid**

A response header the SDK adds. Seeing it on your responses means the key reached your app and the SDK is running. See [Docs](https://www.camada.app/docs).

---

Source: https://www.camada.app/how-it-works

How it works

# How camada works: events in, analysis, blocklist out

Your app runs one camada package. It collects events and enforces the blocklist. The analysis runs in a Cloudflare Worker that stores, scores and investigates, with Watchkeeper, camada's AI analyst, writing the verdicts. Nothing on your request path waits for camada.

1. 1 · Your app

   SDK

   One redacted event per request, batched, off the request path.
2. 2 · camada

   Ingest

   Raw events land in R2 per tenant and hour. Beacon rows join by request id.
3. 3 · camada

   Score

   Every 10 minutes by default: features per IP, session and TLS fingerprint, scored against 63 rules.
4. 4 · camada

   Investigate

   A triage model sorts the grey ones. An investigation agent takes the worst and writes a verdict with evidence.
5. 5 · camada

   Snapshot

   Verdicts become a per-tenant blocklist. The SDK pulls it every 30 s; unchanged costs a 304.

Then back to step 1: the SDK enforces the snapshot in your process and answers matches with a 403 before your handler runs.

Step 1

## Events in

After each response finishes, the SDK builds one event: method, path, query shape, status, latency, header names and sizes, client IP resolved through your trusted-proxy config, the session id, and a request id. It redacts before anything leaves the process, batches events, and posts them without blocking the response.

The SDK also serves the browser beacon from your own origin at `/_cam/b.js`. No third-party domain, so ad blockers and your CSP do not break it. The beacon posts screen, timezone, languages, renderer, automation flags and input counts to `/_cam/fp`, and the request id joins it to the server event.

Every event carries a `tap` (where it was collected) and the Worker stamps a capability mask. A Node SDK sees true header order and app outcomes but not TLS. A Next.js middleware on Vercel sees a JA4 digest but not the final status. Rules only fire where the tap could have seen the signal, so an absent signal is never counted against you.

Step 2

## Analysis

Each project with new events gets one run every 10 minutes by default. The minimum interval is 5 minutes. The run reads the window, builds features per IP, per session and per TLS fingerprint, and scores each one against 63 rules. Six of them subtract points for signs of a real person. At the default sensitivity, thirty points is grey and sixty sends the client to investigation.

Grey clients go to a triage model fifteen at a time. Clients at sixty, or triaged as suspicious or malicious, go to an investigation agent, up to 10 per run, highest scores first. The agent can pull raw request samples and the facts you recorded about your site, and its prompt already carries the client's reputation and network (ASN) context. It gets at most 3 tool rounds, then writes a verdict with the evidence it used. Verdicts younger than six hours are not re-investigated.

Each run ends with a markdown report you can read in the app.

### Signals

| Signal | Source | What it tells |
| --- | --- | --- |
| Client IP, ASN, country | request headers, edge metadata | hosting ASN on a login route; geo velocity across a session |
| TLS fingerprint | edge metadata, Vercel JA4 digest | one fingerprint across many IPs and user agents is a tool or a botnet |
| Header names, sizes, order | the request as your server sees it | browsers send 15 to 25 headers in a stable order; libraries do not |
| Client hints, Sec-Fetch, Accept | request headers | a Chrome user agent without Sec-CH-UA is headless, a proxy or a lie |
| Path, query shape, method | request line | scanner paths like /.env or /wp-login.php; parameter stuffing |
| Status, latency | response finish (Node SDK) | 404 ratio over 50%; logins failing in bursts |
| Session cookie | first-party _sfp | a new session on every request is a client that drops cookies |
| Browser beacon | first-party /_cam/b.js | webdriver flag, software WebGL renderer, zero input events across a session |
| App outcomes | your track() calls | login failed, signup, checkout declined: ground truth no edge position sees |

### Rule weights: a sample of the 63

| Rule | Weight |
| --- | --- |
| webdriver true or automation globals present | `+60` |
| beacon user agent differs from header user agent | `+40` |
| hosting or cloud ASN on a login route | `+30` |
| one TLS fingerprint seen from 50+ IPs within one run window | `+30` |
| 3+ HTML pages served and no beacon (no JavaScript ran) | `+25` |
| 404 ratio over 50% with 20+ requests | `+25` |
| web shell or exploit-kit path (shell.php, /vendor/phpunit, /boaform) | `+60` |
| secret or config file probe (/.env, /.git, wp-config.php, *.sql) | `+30 per distinct path, cap 60` |
| scanner path hit (/wp-login.php, /xmlrpc.php, /phpinfo.php) | `+20 per distinct path, cap 60` |
| claims Googlebot or bingbot from outside the published IP ranges | `+60` |
| password spray: failed logins on 10+ of your accounts, 2 tries each (track()) | `+50` |
| flagged malicious by 3+ other paying organizations in the last 7 days | `+40` |
| beacon with input events within 10 seconds | `-30` |
| consistent user agent, client hints, TLS family and beacon engine | `-15` |

Rules that need ASN or country read them from the request where the position exposes them (edge taps, Hono on Workers) and from the analyst's own geo tables otherwise, so they score every tap; enforcing an ASN or country entry per request still needs a position that sees them. The in-app SDKs (Node, Next.js, Python, Go, PHP, Ruby, Java and .NET) fail open on those entries. Negative weights let humans fall out of grey. You can disable any rule, change what a category does (block, challenge, alert, ignore) and pick a sensitivity per project. Once enforcement is on, a challenge verdict makes your SDK answer with a small proof-of-work page that a real browser solves. SDK versions older than snapshot v4, and any SDK set to `challenge: false`, treat it as a recommendation. [How a challenge works](https://www.camada.app/docs/challenge).

Step 3

## Blocklist out

A verdict becomes a block row with a TTL. When the set of active blocks changes, the Worker publishes a new per-tenant snapshot. The SDK polls it every 30 seconds with an ETag, so an unchanged snapshot costs a 304 and nothing else.

Enforcement happens in your process before your handler runs: a matching IP or path gets a 403 with `x-block-reason`. The blocked request still ships as an event, so you can see what was stopped.

A new project starts in a learning window. During it, verdicts are recommendations you can review in the app. camada never switches a project to enforce on its own. You end the review and turn it on.

Next

## Read the limits before you install

Fail-open behaviour, cold starts, what each position can and cannot enforce, and what data leaves your app are on the [security page](https://www.camada.app/security). Install steps per framework are under [frameworks](https://www.camada.app/frameworks). What this looks like for one attack at a time: [credential stuffing](https://www.camada.app/use-cases/credential-stuffing), [scraping](https://www.camada.app/use-cases/scraping), [AI agent abuse](https://www.camada.app/use-cases/ai-agents), [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits).

---

Source: https://www.camada.app/pricing

Pricing

# camada pricing, by events per month

You pay for events: one per request your SDK sees. Every plan runs Watchkeeper, the AI analyst, and shows you its verdicts. On Free they stay recommendations. Paid plans can also enforce: once you turn enforcement on, your app blocks the clients the analyst judges malicious. Going over your included events never blocks traffic.

Free needs no card. A 14-day trial of Starter or Growth needs a card. Nothing is charged today. Cancel before the trial ends (the date is shown in the app) and you pay nothing. Otherwise the plan's monthly price starts on day 15. There is one trial per person and per card, once your email is verified. Enforcement is on, and you get every feature of the plan you pick for the whole trial.

## Plans

### Free

$0/mo

100k events / month

- 1 project
- 7-day retention of analysis rows
- Visibility and learning only
- Alerts: Email
- No chat assistant
- Overage: None

[Start on Free](https://my.camada.app/start?plan=free)

14-day trial

### Starter

$59/mo

1M events / month

- 3 projects
- 30-day retention of analysis rows
- Enforcement on
- Alerts: Email, Slack
- No chat assistant
- Overage: $5 per extra 1M events

[Start the 14-day trial](https://my.camada.app/start?plan=starter)

14-day trial

### Growth

$249/mo

10M events / month

- Unlimited projects
- 90-day retention of analysis rows
- Enforcement on
- Alerts: Email, Slack, webhooks
- Chat assistant, 2M tokens / month
- Overage: $3 per extra 1M events

[Start the 14-day trial](https://my.camada.app/start?plan=growth)

### Enterprise

Custom

Custom events / month

- Unlimited projects
- 365-day retention of analysis rows
- Enforcement on
- Alerts: Email, Slack, webhooks
- Chat assistant, unlimited tokens
- Overage: None
- Audit log of every change

[Talk to us](mailto:hello@camada.app?subject=camada%20Enterprise)

Or [start on Free, no card](https://my.camada.app/start?plan=free).

Raw events are kept 7 days on every plan. Retention above applies to verdicts, blocks, greylist and run reports.

Chat budgets count input and output tokens together, per calendar month (UTC), across the organization. Each user can send 30 messages an hour. [What the agent can do](https://www.camada.app/docs/chat).

Enterprise is for volume past Growth's 10M events. It adds a year of retention, chat with no monthly token budget, the audit log of every change in your organization, and a price we set with you, with no overage. SAML single sign-on and EU-only data residency are not offered yet, and no plan has a published uptime commitment yet.

Questions

## How billing works

**What is an event?**

One request your SDK saw. Every request ships one event; beacon posts ride along with the request they belong to. Snapshot polls and bytes are shown on your usage page but never billed.

**How does the 14-day trial work?**

Free needs no card. A 14-day trial of Starter or Growth needs a card. Nothing is charged today. Cancel before the trial ends (the date is shown in the app) and you pay nothing. Otherwise the plan's monthly price starts on day 15. Prepaid cards can't start a trial, and there is one trial per person and per card, once your email is verified. Enforcement is on, and you get every feature of the plan you pick for the whole trial. If you cancel or switch plan during the trial, the end date stays the same. A cancelled trial ends on that date with no charge and the organization moves to Free. If the day-15 charge fails, the organization has Free features until an invoice is paid.

**What happens when I go over the included events?**

Traffic is never blocked and your app is never slowed. On Free, camada lowers the sampling rate after a 10% grace so the analyst keeps working within budget. On paid plans sampling stays at 1 and the extra events are billed per million at your plan rate. You are alerted at 80% and at 100%.

**How is overage calculated?**

Per million events over the included amount, per month, on the events actually ingested. Starter is $5 per extra 1m events, Growth $3 per extra 1m events. It appears as its own line on the Stripe invoice.

**How is chat metered?**

The agent is included on Growth and Enterprise. Growth comes with 2M input and output tokens across the whole organization, counted per calendar month (UTC); Enterprise is unlimited. Every user is also limited to 30 messages an hour, counted over a rolling window. When the monthly budget runs out the agent answers with a short upgrade notice instead of calling the model. Nothing else in camada changes.

**Why is enforcement off on Free?**

Free is for seeing what camada sees and running the learning window. Verdicts still appear as recommendations; the SDK does not enforce them.

**Can I change plans later?**

Yes. An upgrade takes effect at once and is invoiced prorated. A downgrade, and cancelling, take effect at the end of the period you already paid for. Nothing changes until then.

More detail on the trial, overage, downgrades and cancelling: [how billing works](https://www.camada.app/docs/billing).

---

Source: https://www.camada.app/security

Security

# Security and privacy: fail open, every time

A camada outage or a camada bug must never return a 5xx from your app. That rule shapes every part of the SDK.

[Data](https://www.camada.app/security#data) [Client IP](https://www.camada.app/security#proxies) [Retention](https://www.camada.app/security#retention) [Reputation](https://www.camada.app/security#reputation) [Location](https://www.camada.app/security#location) [Chat agent](https://www.camada.app/security#chat) [Staff access](https://www.camada.app/security#access) [Platform](https://www.camada.app/security#platform)

**camada is unreachable**

The SDK keeps serving with the snapshot it already has. Events that cannot ship are dropped, never retried on your request path.

**The SDK throws**

Errors inside the SDK are caught and logged. Your handler runs as if camada were not installed.

**Cold serverless instance**

No snapshot is loaded yet, so the first request passes. The snapshot loads asynchronously and enforcement starts on the next request.

**You want it off now**

Set CAMADA_DISABLED=1. It is checked per request; no redeploy needed if your platform reloads env.

**A rule needs a signal your position lacks**

ASN, country and TLS fingerprint cannot be evaluated inside a Node or Next app, so blocks keyed on them are skipped there. TLS fingerprint entries are enforced in your app only on Cloudflare Workers, by @camada/hono and by @camada/sveltekit with adapter-cloudflare. Path entries enforce in every SDK. IP entries enforce once the client IP resolves.

Data

## What leaves your app

One event per request. This is the whole list.

| Request line | method, host, path and query string; query values that look like tokens, keys or passwords are replaced before shipping |
| --- | --- |
| Response | status code and latency (Node SDK), content type and length |
| Headers | names, sizes and order; User-Agent, Accept, Accept-Language, client hints, Sec-Fetch-*, Referer and Origin; the Authorization scheme name only |
| Network | client IP resolved through your trusted-proxy setting, plus ASN, country and TLS fingerprint where the position exposes them |
| Session | the first-party _sfp cookie value and a per-request id |
| Beacon | screen and window size, timezone, languages, platform, WebGL renderer, canvas hash, automation flags, input event counts, timing |
| App outcomes | the event name you pass to track() and an HMAC of the identifier, computed in your process |

### What never leaves your app

- Authorization and Cookie header values
- Request and response bodies (field names and sizes only)
- Query values matching token, key or password patterns
- Raw user ids, emails or anything you pass to track() before hashing

Redaction runs inside the SDK against a fixed allowlist. You can add fields to capture; there is no option to capture less carefully. The SDKs are open source so the allowlist can be audited. The Worker adds a second guard: it accepts an Authorization scheme name only, and a user id only when it is hash-shaped.

Trust boundary

## Client IP and proxies

ASN and country rules apply where the collecting position exposes them. A Cloudflare Worker running `@camada/hono`, or `@camada/sveltekit` with adapter-cloudflare, sees both, and a TLS fingerprint besides; the Node and Next.js SDKs see neither, so those rules stay off inside your app. Next.js on Vercel sends the JA4 TLS digest in its events, where it is used for scoring, not for enforcement, so a fingerprint entry never blocks a request in a Next.js or Node app. Which key types your own project can enforce is reported per project in the app; what each one is for is on the [rules](https://www.camada.app/docs/rules) page.

The SDK never trusts a raw `X-Forwarded-For`. It resolves the client IP from your project's trusted-proxy setting (a hop count, a CIDR list, or the Vercel preset). Without one, the socket peer is used in Node. Next.js middleware has no socket peer, so off Vercel it needs the `CAMADA_TRUSTED_PROXY` setting (or one set in the app) before IP entries enforce there; on Vercel it defaults to the Vercel preset. A spoofed header can never put an address on your blocklist.

Retention

## How long data is kept

- Raw events: 7 days on every plan, then deleted.
- Verdicts, blocks, greylist rows and run reports: 7, 30, 90 or 365 days by plan.
- Audit log entries: at least one year.
- Deleting a project removes all of its data within 30 days. You can request an export of a project's data as JSON.

IP addresses are personal data. The [privacy policy](https://www.camada.app/legal/privacy) and [DPA](https://www.camada.app/legal/dpa) state the purposes: detecting and blocking abusive traffic against your project, and reputation as described below.

Disclosure

## Cross-tenant reputation

An IP address that gets a malicious verdict is remembered for seven days. Once three or more other paying organizations have flagged it, it scores higher at your projects. Trial projects, projects still in their learning period and other projects in your own organization do not count, and an address you allowed, cleared or ignored is not raised. Only IP addresses are scored this way. For a TLS fingerprint, the investigation agent can read the same kind of record as context, but it does not change the score. The reputation store holds the key, the verdict and counts. It never holds which tenant saw it, and no project can see another project's traffic. camada never shows you who flagged an address.

Where

## Data location and sub-processors

camada runs on Cloudflare's global network; storage is Cloudflare R2, D1 and KV. EU-only residency is not offered yet. The full list of sub-processors, with what each one does, is on the [sub-processors page](https://www.camada.app/legal/subprocessors).

Chat

## Where the agent runs

The in-app agent runs on Cloudflare Workers AI (glm-5.3-flash) through Cloudflare AI Gateway: your question, the tool results it read to answer it and the conversation so far never leave Cloudflare, and no third-party model provider is involved. It is available on the plans that include chat; when the primary model or the gateway is unavailable a second Workers AI model answers instead. The agent is scoped to one project by your session, never by the model, and traffic text reaches the model as delimited data rather than as instructions. The whole picture is on the [chat](https://www.camada.app/docs/chat) page, and every provider is listed on the [sub-processors](https://www.camada.app/legal/subprocessors) page.

Access

## How camada staff can reach your organization

camada staff are not members of your organization. They sign in with a separate camada staff account, and having one grants no access to your data by itself.

- To open your organization at all, a staff member has to start an impersonation session and write down a reason. There is no other way in.
- The session is time-boxed: it ends by itself after 60 minutes, and can be stopped sooner.
- While it runs, that person acts as an administrator of your organization and of no other.
- Your audit log records the start and the end of the session with the reason, and every change made during it carries the staff member's identity and that reason — never one of your own accounts.
- Anyone in your organization who can read the audit log can read all of that afterwards, without asking us.

Platform

## The app and this site

- Sign-in runs inside camada on Cloudflare with Better Auth, which is open source, by email code or Google; the app holds a signed session cookie and keeps only display preferences in browser storage.
- Every app route checks the session and your membership in the organization. Ids that belong to another organization return 404.
- Every change in the app writes an audit row: who, what, before, after.
- The app and this site ship a content security policy, HSTS and `frame-ancestors 'none'`.
- This site sets no cookies and uses cookieless analytics when enabled.

Found a vulnerability? Write to [security@camada.app](mailto:security@camada.app). We acknowledge every report.

---

Source: https://www.camada.app/docs

Docs

# camada docs

## Quickstarts

- [Express](https://www.camada.app/docs/quickstart/express) `@camada/node`
- [Fastify](https://www.camada.app/docs/quickstart/fastify) `@camada/node`
- [NestJS](https://www.camada.app/docs/quickstart/nest) `@camada/node`
- [Koa](https://www.camada.app/docs/quickstart/koa) `@camada/node`
- [Next.js](https://www.camada.app/docs/quickstart/nextjs) `@camada/next`
- [FastAPI](https://www.camada.app/docs/quickstart/fastapi) `camada`
- [Django](https://www.camada.app/docs/quickstart/django) `camada`
- [Flask](https://www.camada.app/docs/quickstart/flask) `camada`
- [Go](https://www.camada.app/docs/quickstart/go) `github.com/camada-app/camada-go`
- [Rails](https://www.camada.app/docs/quickstart/rails) `camada`
- [PHP](https://www.camada.app/docs/quickstart/php) `camada/camada`
- [Laravel](https://www.camada.app/docs/quickstart/laravel) `camada/camada`
- [Spring Boot](https://www.camada.app/docs/quickstart/spring) `dev.camada:camada`
- [ASP.NET Core](https://www.camada.app/docs/quickstart/aspnet) `Camada`
- [Hono on Workers](https://www.camada.app/docs/hono) `@camada/hono`
- [Python (ASGI/WSGI)](https://www.camada.app/docs/python) `camada`
- [Go (net/http)](https://www.camada.app/docs/go) `github.com/camada-app/camada-go`
- [PHP (front controller, Laravel)](https://www.camada.app/docs/php) `camada/camada`
- [Ruby (Rack, Rails)](https://www.camada.app/docs/ruby) `camada`
- [Java (servlet, Spring Boot)](https://www.camada.app/docs/java) `dev.camada:camada`
- [.NET (ASP.NET Core)](https://www.camada.app/docs/dotnet) `Camada`

## Reference

- [Webhook payload](https://www.camada.app/docs/webhooks) catalog, signature, retries
- [API reference](https://my.camada.app/api/openapi.json) OpenAPI 3.1, served by the app
- [How billing works](https://www.camada.app/docs/billing) plans, trial, overage
- [Chat with your agent](https://www.camada.app/docs/chat) tools, change cards, workflows
- [Memory](https://www.camada.app/docs/memory) facts, index, retention
- [Rules and list entries](https://www.camada.app/docs/rules) IP, CIDR, path, ASN, country
- [Challenge](https://www.camada.app/docs/challenge) proof of work, cookie, SDK support
- [Signals and rules](https://www.camada.app/how-it-works)

## Operate

- [Fail-open behaviour and data handling](https://www.camada.app/security)
- [Service status](https://www.camada.app/status)
- [Contact](https://www.camada.app/contact)

Env

## Environment variables the SDKs read

| Variable | Meaning |
| --- | --- |
| `CAMADA_KEY` | Required. `<ingest_token>.<snap_token>`, shown once when a project is created. Unset, the SDK is inert and logs one rate-limited error. |
| `CAMADA_INGEST_URL` | Ingest origin. Defaults to production. Local dev: `http://localhost:8787`. |
| `CAMADA_SNAPSHOT_URL` | Blocklist snapshot URL. Defaults to ingest + `/snapshot`. |
| `CAMADA_TRUSTED_PROXY` | `none \| vercel \| hops:N \| cidrs:a,b`. Overrides the project setting locally. Raw X-Forwarded-For is never trusted without it. |
| `CAMADA_DISABLED` | `1` switches the SDK off. Checked per request. |
| `CAMADA_SERVERLESS` | `1` uses lazy snapshot refresh with no interval timer (in-app SDKs). Cold invocations fail open and catch up. |
| `CAMADA_CHALLENGE` | `0` passes challenge verdicts instead of serving the proof-of-work page (in-app SDKs). |

Agents

## For AI agents and coding assistants

- [llms.txt](https://www.camada.app/llms.txt) lists every page with a one-line summary. [llms-full.txt](https://www.camada.app/llms-full.txt) is the whole site in one file.
- Every page has a Markdown version at its URL plus `.md`, for this page [/docs.md](https://www.camada.app/docs.md). The page's own URL returns the same Markdown when the request sends `Accept: text/markdown`.
- An [agent skill](https://www.camada.app/.well-known/agent-skills/add-camada/SKILL.md) holds the install steps for every framework, listed in the [skills index](https://www.camada.app/.well-known/agent-skills/index.json).
- The app's API is described in [OpenAPI 3.1](https://my.camada.app/api/openapi.json) and listed in the [API catalog](https://www.camada.app/.well-known/api-catalog).
- [robots.txt](https://www.camada.app/robots.txt) lets in search engines, AI answer engines and AI training crawlers that say who they are.

---

Source: https://www.camada.app/docs/billing

Docs

# How billing works

## The unit is one event

One event is one request your SDK saw. Beacon posts ride along with the request they belong to, so they are not counted twice. Snapshot polls and ingest bytes appear on your usage page for capacity planning, and are never billed. Billing is per events ingested per month.

## Plans

| Plan | Price | Included | Projects | Retention | Enforcement | Alerts | Overage |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Free | $0/mo | 100k / month | 1 project | 7 days | Off | Email | None |
| Starter | $59/mo | 1M / month | 3 projects | 30 days | On | Email, Slack | $5 per extra 1M events |
| Growth | $249/mo | 10M / month | Unlimited projects | 90 days | On | Email, Slack, webhooks | $3 per extra 1M events |
| Enterprise | Custom | Custom / month | Unlimited projects | 365 days | On | Email, Slack, webhooks | None |

Side-by-side with the feature lists: [pricing](https://www.camada.app/pricing).

## The 14-day trial

Free needs no card. A 14-day trial of Starter or Growth needs a card. Nothing is charged today. Cancel before the trial ends (the date is shown in the app) and you pay nothing. Otherwise the plan's monthly price starts on day 15. There is one trial per person and per card, once your email is verified, and prepaid cards can't start a trial. Enforcement is on, and you get every feature of the plan you pick for the whole trial.

If the day-15 charge fails, the organization has Free features until an invoice is paid. Moving to Free deletes no data beyond what Free's 7-day retention ages out.

## Going over the included events

Going over **never blocks or slows your traffic**, and never turns protection off. What changes is how much camada analyses and what you are charged:

- On Free, after a 10% grace the analyst lowers its sampling rate to a plan floor, so it keeps working inside the budget instead of stopping. Enforcement of blocks you already have is unaffected.
- On paid plans sampling stays at 1 and the extra events are billed per million at your plan rate: Starter $5 per extra 1m events, Growth $3 per extra 1m events.
- You are alerted at 80% and at 100% of the included events, once each per period, in the app and on your alert channels.

## The numbers you see are the numbers you are billed

Usage is summed per UTC day per project from the same rollups the analyst writes, and that single set of rows is what the billing page shows, what the usage page charts, and what is reported to Stripe. There is no second meter.

## Upgrades, downgrades, cancelling

- **During the trial:** cancel or switch plan any time. The trial end date does not move. A cancelled trial is never charged and the organization moves to Free on that date.
- **Upgrade:** takes effect immediately and is invoiced at once, prorated for the rest of the period.
- **Downgrade,** including to Free: scheduled for the end of the period you already paid for. Nothing changes until then, and you can undo it before it lands.
- **Cancel:** the same shape — the subscription ends at the end of the period, and the organization is then on Free. You can resume before it takes effect.

## What changes on Free

- Retention of analysis rows drops to 7 days. Raw events are kept 7 days on every plan.
- Enforcement is off: verdicts stay, as recommendations, and the SDK stops enforcing them.
- Alert channels narrow to email.
- 1 project; extra projects stay readable but cannot be created.
- Above 100k events a month, sampling drops to the plan floor.

## Invoices and receipts

Stripe renders them; camada does not build its own. Overage is its own invoice line ("Events over included: N × rate"). Stripe emails a reminder before the trial ends, and camada emails a confirmation when it starts. Receipts and failed-payment mail come from Stripe, to the billing address on the account. Payment methods, tax ids and the billing address are managed in the Stripe customer portal, linked from the app's billing settings.

Questions about the Enterprise plan or an invoice: [hello@camada.app](mailto:hello@camada.app).

---

Source: https://www.camada.app/docs/challenge

Docs

# Challenge

A challenge is the verdict between letting a request through and blocking it: make the client prove it is a browser. Where your SDK can serve one, a suspicious request gets a small first-party page instead of your app. A real browser passes it in well under a second and carries on; a headless client that does not run JavaScript does not.

## The flow

1. The snapshot your SDK polls marks the key as challenge.
2. The request arrives without a valid `_cch` cookie, and the SDK could resolve a client IP for it, so the SDK answers a page load with a **403** and a self-contained HTML page: inline JavaScript, **no external assets**, `Cache-Control: no-store`. Nothing is fetched from camada or from anyone else to display it.
3. The page computes a SHA-256 proof of work at **16 bits** of difficulty over a server nonce. The nonce is an HMAC-SHA256 of your project key, the client IP and the UTC day, so a proof done for one address is worthless from another. Yesterday's nonce is still accepted, so a solve begun just before midnight UTC is not thrown away.
4. It posts the answer back to the SDK's own verify route, on your own origin.
5. The SDK checks the work, sets the `_cch` cookie and answers **302** back to the URL that was asked for.
6. The retried request carries the cookie and passes straight through.

## The cookie

`_cch` is an HMAC token your SDK issues and verifies itself, valid **one hour**, set `HttpOnly; SameSite=Lax`. No third party is involved and nothing is stored outside your app. The cookie carries no identity beyond the address it was issued to — only the fact that this client did the work.

## Requests that are not browsers

A challenge needs a client IP: the nonce and the cookie are both bound to one, so when the SDK cannot resolve an address it lets the request through rather than minting a cookie anyone could present. That is the same fail-open stance IP rules take.

A request that does not accept HTML, or whose `sec-fetch-dest` is not `document`, is not shown a page it could never solve. It passes to your app, and the response carries this header so your frontend can challenge it, for example by loading a page:

response header

```http
x-camada-challenge: 1
```

SDK releases that serve the challenge but predate this header answer such a request with a 403 instead. Upgrade to a release that sends the header to let it through.

The one exception to passing through is a client-side navigation's data request (React Router `.data`, SvelteKit `__data.json`, Next Pages Router `/_next/data`): it is challenged like a page, and the router turns the 403 into a full page load that meets the challenge. Next App Router soft navigations are not in that list: they pass with the header like any other fetch, and the next full page load meets the challenge.

When a request passes to your app with the header, its response carries `no-store` on `Cache-Control`, `CDN-Cache-Control`, `Surrogate-Control` and the Cloudflare, Vercel and Netlify CDN cache headers, replacing whatever your app set, because the signal is about one client and no cache should hand it to another. If your API responses are normally cacheable, they are not cached while that client is under a challenge.

## What it reports

Each outcome ships as an ordinary event, so the activity pages show how many challenges were served, how many were passed, and how many API calls were signalled with the header. A signalled event's `st` is the status your app actually answered, not always 200.

events

```text
served    { "st": 403, "blk": "challenge" }
passed    { "st": 200, "ch": 1 }
signalled { "st": 200, "chs": 1 }
```

## Which SDKs enforce it

| Package | From | Verifies at | Covers |
| --- | --- | --- | --- |
| `@camada/node` | `0.1.0` | `POST /__camada/challenge` | Express, Fastify, NestJS and Koa. |
| `@camada/next` | `0.1.0` | `POST /api/camada/challenge` | Next.js middleware and the route handler it installs. |
| `@camada/hono` | `0.1.0` | `POST /__camada/challenge` | Hono on Cloudflare Workers. |
| `@camada/sveltekit` | `0.1.0` | `POST /__camada/challenge` | SvelteKit handle hook. |
| `@camada/nuxt` | `0.1.0` | `POST /__camada/challenge` | Nuxt server middleware (h3). |
| `@camada/remix` | `0.1.0` | `POST /_cam/challenge` | React Router framework mode (Remix) middleware. |
| `@camada/bun` | `0.1.0` | `POST /__camada/challenge` | Bun.serve fetch handler. |
| `@camada/deno` | `0.1.0` | `POST /__camada/challenge` | Deno.serve handler. |
| `@camada/python` | `0.2.0` | `POST /__camada/challenge` | Python: Django, Flask, FastAPI, any ASGI or WSGI app. |
| `@camada/go` | `0.1.0` | `POST /__camada/challenge` | Go: net/http, any router built on http.Handler. |
| `@camada/php` | `0.1.0` | `POST /__camada/challenge` | PHP: any front controller, Laravel. |
| `@camada/ruby` | `0.1.0` | `POST /__camada/challenge` | Ruby: Rails, Sinatra, any Rack app. |
| `@camada/java` | `0.1.0` | `POST /__camada/challenge` | Java: Spring Boot, any servlet container. |
| `@camada/dotnet` | `0.1.0` | `POST /__camada/challenge` | .NET: ASP.NET Core. |

Challenge rows only reach an SDK that asks for snapshot version 4, by sending `x-camada-snapshot: 4`. camada keeps serving version 3 to everyone else, and version 3 has no challenge section at all — so **older SDKs** treat a challenge verdict as a recommendation: it is recorded and alerted, and nothing is enforced. Upgrading the package is what turns it on.

Inside the SDK the match order is **allow, then block, then challenge**: an allow-list entry always wins, and a key that is blocked is blocked rather than challenged.

## Turning it off

Pass `challenge: false` in the middleware options (the default is `true`) and the SDK treats challenge verdicts as recommendations without giving up the rest of snapshot v4.

What a challenge verdict means next to a block, and what else a list entry can key on: [rules and list entries](https://www.camada.app/docs/rules). Serving one from a Cloudflare Worker: [@camada/hono](https://www.camada.app/docs/hono).

---

Source: https://www.camada.app/docs/chat

Docs

# Chat with your agent

A streaming chat inside the app, scoped to one project. It reads your traffic through tools, cites what it found, and proposes changes you confirm. It is included on Growth and Enterprise.

## It answers only from tools

The agent has no prior knowledge of your traffic. Every claim it makes comes from one of these calls, made live against your project while it answers:

| Tool | What it reads |
| --- | --- |
| `get_overview` | Requests, blocked, investigated, active blocks and recommendations for a range, plus the open actions and the learning-window state. |
| `query_findings` | Findings filtered by time, verdict, category, action or key, sorted, up to 50 at a time. |
| `get_entity` | One IP, CIDR, session, TLS fingerprint, ASN, country or path, with its verdicts, counts and current state. |
| `get_run` | One analysis run and the report it produced. |
| `get_rules` | The rule catalog, the action set per verdict category, and the sensitivity preset. |
| `get_lists` | The allow-list and the manual blocks, with their reasons and TTLs. |
| `get_config` | Project settings, health, setup progress and the limits of your plan. |
| `search_memory` | The facts stored for this project. See memory. |
| `remember` | Stores a new fact. You see it as "remembered: …" with an Undo. |
| `search_docs` | These documentation pages. |
| `propose_change` | Drafts a change for you to confirm. It never applies one. |

Every answer about a finding carries its evidence: verdict ids, run ids and entity links you can click straight through to. If an answer names a verdict or a run without citing it, the app asks the model once more for the citations, and failing that attaches the ids from the tool results the answer was built on.

## Change cards: the agent never writes

When the agent wants to change something it draws a change card instead of acting: what kind of change it is, the before and after, and why. **Nothing is applied until you confirm it.** On confirm the change runs through exactly the same code path as the equivalent button in the app, under your own role, and the audit row records you as the actor with the conversation and proposal attached — so an agent-assisted change is as traceable as a hand-made one.

- Kinds it can propose: allow, block, unblock, rule, category, sensitivity, config and alert route.
- Confirming needs member or admin. A viewer can read and ask, and sees "ask an admin" on the card.
- A card you neither confirm nor reject expires after 24 hours.

## Guided workflows

Type `/` for the workflow menu. Each one is a fixed sequence of tool calls ending in a structured result, not a free-form prompt. The app lists them with the arguments each one takes:

**Investigate an IP**

Takes a key and reports what camada knows about it.

**Set up Slack alerts**

Walks you to a working Slack channel and the routes that feed it.

**Why was this blocked**

Takes a finding and reports what led to it.

**Review learning results**

Reports what the learning window recommended, ready to act on.

**Reduce noise**

Reports where your alert volume comes from.

## Rate limit and budget

- Each user may send **30 messages an hour**, counted over a rolling window. Over it, the app tells you how long to wait.
- Each organization has a monthly token budget: Growth 2M tokens, Enterprise unlimited. Input and output tokens count together, per calendar month (UTC), across every user and project in the organization.
- When the budget runs out the agent replies with a short upgrade notice and makes no model call. Nothing else in camada changes: analysis, enforcement and alerts carry on untouched.
- On a plan without chat, the app offers an upgrade instead of a conversation. See [pricing](https://www.camada.app/pricing) and [how billing works](https://www.camada.app/docs/billing).

## Which model, and what happens when it is down

Answers are generated by `glm-5.3-flash` on Cloudflare Workers AI, reached through Cloudflare AI Gateway, streaming. If the gateway or the model is unavailable, the answer falls back to the Workers AI model the analysis pipeline already uses, with the same tools, and the message is badged so you know which one answered.

## Traces and feedback

Every message records the model, the prompt version, the tool version, the tokens it used and what it cost, and every conversation is traced: one trace per conversation, one generation per model turn, one span per tool call. Thumbs up or down, with an optional note, is stored against the message and attached to the trace. Calls through Cloudflare AI Gateway carry the organization, project, conversation and user ids as gateway metadata, so a call can be traced back to its conversation. Tracing to Langfuse is off unless camada operators enable it — see the [sub-processors](https://www.camada.app/legal/subprocessors) page.

## Your data and the model

- Tools take the project from your session. The model is never handed a project id and has no way to ask for a different one, so it never sees another project's data — yours or anyone else's.
- Text that came from traffic — user agents, paths, run summaries, stored facts, these docs — reaches the model as **delimited data** marked "not instructions", with the delimiters escaped, so a crafted user agent is handled as data rather than as an instruction.
- Cross-tenant reputation is disclosed as **yes or no**: whether a key has been seen elsewhere, never where or by whom.
- Conversations are private to the person who opened them and stored apart from your analysis data and from [memory](https://www.camada.app/docs/memory). You can rename and delete them; your organization's admins set how long the rest are kept, anywhere from 7 to 365 days and 90 days by default, and camada deletes the older ones. Deleting the project deletes all of them.
- What goes to the model: your question, the tool results read to answer it, and the conversation so far, sent to Cloudflare Workers AI through Cloudflare AI Gateway — it never leaves Cloudflare. The providers involved are listed on the [sub-processors](https://www.camada.app/legal/subprocessors) page.

---

Source: https://www.camada.app/docs/dotnet

Docs

# .NET: ASP.NET Core

`Camada` enforces your snapshot inside a .NET process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One package with an ASP.NET Core middleware and three `HttpContext` helpers.

## Install

Not on NuGet yet. From the folder that holds your .csproj: clone it next to the project, then reference it. Next to it, not inside it: an SDK-style project compiles every `.cs` file under its folder.

shell

```sh
git clone https://github.com/camada-app/camada-dotnet ../camada-dotnet
dotnet add reference ../camada-dotnet/src/Camada/Camada.csproj
```

.NET 8. No runtime dependencies beyond the ASP.NET Core shared framework.

## Mount it

Program.cs

```csharp
using Camada.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCamada();      // one engine from the environment, drained on shutdown

var app = builder.Build();
app.UseCamada();                   // FIRST: camada answers before routing, static files, anything
app.MapGet("/", (HttpContext ctx) => Results.Content($"<html><head>{ctx.CamadaScriptTag()}</head>…", "text/html"));
app.Run();
```

`AddCamada()` builds the engine when the container first resolves it — on the first request through the middleware — from the environment:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that runs dotnet run, add them to "environmentVariables" in Properties/launchSettings.json, or set them in your host's settings. camada reads only the environment, and ASP.NET does not pass appsettings.json, user-secrets or a .env file to it.

That build starts the snapshot poll on a background task and never blocks, so the request that triggered it is answered cold: it passes (fail open), and so does anything that arrives before the first poll lands. To enforce from request 1, resolve the engine at startup and wait for the boot poll:

warm-up

```csharp
// beside using Camada.AspNetCore; at the top of Program.cs
using Camada;
using Camada.Snapshot;

// after var app = builder.Build();
var engine = app.Services.GetRequiredService<CamadaEngine>();   // builds it; the boot poll is already running
if (engine.Snap != null)                                       // null when CAMADA_KEY is unset or CAMADA_DISABLED=1
{
    var deadline = Environment.TickCount64 + 5000;
    while (engine.Snap.Verdict(new MatchInput { Ip = "0.0.0.0" }).Reason == "cold" && Environment.TickCount64 < deadline)
    {
        Thread.Sleep(10);   // bounded: an unreachable analyst leaves it cold, and the app still fails open
    }
}
```

An app that reads its own configuration hands the values in through the options — credentials still travel as an environment map, never as constructor arguments. Outside the generic host, `UseCamada()` alone falls back to `CamadaEngine.Default`, a lazy singleton wired from the process environment; `CamadaEngine.Configure(options)` replaces it.

explicit config

```csharp
using Camada.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCamada(o =>   // instead of AddCamada(); myKey, myIngest: read from your own configuration
{
    o.Env = new Dictionary<string, string?> { ["CAMADA_KEY"] = myKey, ["CAMADA_INGEST_URL"] = myIngest };
    o.ChallengePath = "/api/__camada/challenge";
});
```

Quickstart: [ASP.NET Core](https://www.camada.app/docs/quickstart/aspnet).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `Env` | `the process environment` | Where CAMADA_KEY and friends are read from (the process one is read per request, for the kill switch). Pass a dictionary to configure in code. |
| `Transport` | `HttpClient` | The delegate that reaches the analyst; tests hand in an in-process fake. |
| `RefreshS` | `server-steered` | Poll cadence in seconds. Unset, the tenant config's poll_seconds steers it; set, it is pinned. |
| `Challenge` | `true` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `ChallengePath` | `/__camada/challenge` | Where that page posts its solution. |
| `SnapshotVersion` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `ScriptPath` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `FpPath` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as ScriptPath: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_SERVERLESS=1` (a per-request staleness check, no timer), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request (set at boot, no timer starts at all). The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

1. Keeps the snapshot fresh off the request path: a background task on a `PeriodicTimer` at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. `CAMADA_SERVERLESS=1` checks staleness per request instead.
2. Resolves the client from the socket peer (`Connection.RemoteIpAddress`), combined with `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one. The SDK never reads the peer through the forwarded-headers middleware: if you add `UseForwardedHeaders()`, keep `UseCamada()` before it, so camada judges the raw header itself.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints, then runs your app with `x-rid` and the `_sfp` session cookie on its response (stamped from `Response.OnStarting`, so a handler that clears headers still carries them), the context in `HttpContext.Items["camada"]`, and when the response is done ships one batched, redacted event with its real status, latency and the matched route pattern. An exception in your app ships as `st: 500` and propagates unchanged.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the middleware does the rest:

beacon

```csharp
// Program.cs, above app.Run(): Mount it already maps this route
app.MapGet("/", (HttpContext ctx) =>
    Results.Content($"<html><head>{ctx.CamadaScriptTag()}</head><body>…</body></html>", "text/html"));
```

`ctx.CamadaScriptTag()` returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at `GET /_cam/b.js` (an embedded resource, cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```csharp
// Program.cs, above app.Run(); LoginForm (with an Email) and SignIn are your own form type and sign-in check
app.MapPost("/login", async (HttpContext ctx, LoginForm form) =>
{
    var ok = await SignIn(form);
    if (!ok) ctx.CamadaTrack("login_failed", user: form.Email);   // hashed in-process; never throws
    return ok ? Results.Redirect("/") : Results.Json(new { error = "invalid" }, statusCode: 401);
});
```

`ctx.CamadaTrack(event, user: …)` ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never throws; on a request the middleware did not run for it still ships the event, with no rid, sid or ip to join it to. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand; the answer is an `IResult` to return from the handler:

gating a route

```csharp
// Program.cs, above app.Run(): the proof-of-work page (or 403 JSON) until this browser holds a valid _cch, then null
app.MapGet("/export", (HttpContext ctx) => ctx.CamadaServeChallenge() ?? BigFile());   // BigFile(): your response, an IResult
```

## What this position sees

The same position as `@camada/node`, in a .NET process: the final status and latency, the session, the route pattern, the beacon's browser signals and your app's outcomes. The event carries the header order as `IHeaderDictionary` reports it, which is not the wire's order under Kestrel — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches the middleware, so those conditions fail open in-app and the analyst resolves ASN and country itself. `matches` patterns are JS regexes run on `Regex` in ECMAScript mode (retried on the default engine when that mode refuses a spelling; one neither accepts never matches here while it does at the edge), each under a 50 ms timeout that reads as no match. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- Every process polls its own snapshot (about 5 MB resident) and flushes its own batches; the tenant's `poll_seconds` keeps the cadence honest across a fleet.
- Pending events drain on the host's `ApplicationStopping` within half a second, and every engine also drains on `ProcessExit` (what a bare `CamadaEngine.Default` relies on). No signal handlers are installed — an app owns its own shutdown — so a process killed outright may drop its last batch.
- Serverless hosts: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
- The poll is a plain background task, not an `IHostedService`: it needs no host to run under and starts with the engine.

## It fails open

Without a key the middleware is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute, through `ILogger` under `AddCamada()` or stderr otherwise — the message only, never a stack trace), a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/go

Docs

# Go: net/http

`github.com/camada-app/camada-go` enforces your snapshot inside a Go process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One module, one public package, a `net/http` middleware that any router built on `http.Handler` sits behind.

## Install

shell

```sh
go get github.com/camada-app/camada-go
```

Go 1.23 or newer. No dependencies outside the standard library. Tagged releases are on the Go module proxy ([pkg.go.dev](https://pkg.go.dev/github.com/camada-app/camada-go)).

## Mount it

main.go

```go
import "github.com/camada-app/camada-go"

mux := http.NewServeMux()
mux.HandleFunc("GET /{$}", home)
http.ListenAndServe(":8080", camada.Handler(mux))   // outermost, so camada answers before routing
```

`camada.Handler` shares one lazy engine, built from the environment on the first request:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Go reads no .env file.

That build starts the snapshot poll on a goroutine and never blocks, so the request that triggered it is answered cold: it passes (fail open), and so does anything that arrives before the first poll lands. To enforce from request 1, build the engine eagerly at startup and wait for the boot poll:

warm-up

```go
import "github.com/camada-app/camada-go/snapshot"

cam := camada.Default()   // builds the engine; the boot poll is already running on its goroutine
if cam.Snap != nil {      // nil when CAMADA_KEY is unset or CAMADA_DISABLED=1
	deadline := time.Now().Add(5 * time.Second)
	for cam.Snap.Verdict(snapshot.MatchInput{IP: "0.0.0.0"}).Reason == "cold" && time.Now().Before(deadline) {
		time.Sleep(10 * time.Millisecond)   // bounded: an unreachable analyst leaves it cold, and the app still fails open
	}
}
defer cam.Stop(context.Background())   // drains the last event batch, at most 500 ms
```

An app that reads its own configuration can build the engine itself and hand it in:

explicit config

```go
cam := camada.New(camada.Options{
	Env:           map[string]string{"CAMADA_KEY": myKey, "CAMADA_INGEST_URL": myIngest},
	ChallengePath: "/api/__camada/challenge",
})
http.ListenAndServe(":8080", cam.Handler(mux))
```

Quickstart: [Go](https://www.camada.app/docs/quickstart/go).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `Env` | `the process environment` | Where CAMADA_KEY and friends are read from (a map[string]string). Pass one to configure in code. |
| `Transport` | `net/http` | The func(HTTPRequest) HTTPResponse that reaches the analyst; tests hand in an in-process fake. |
| `Refresh` | `server-steered` | Poll cadence (a time.Duration). Zero, the tenant config's poll_seconds steers it; set, it is pinned. |
| `Challenge` | `nil (= true)` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `ChallengePath` | `/__camada/challenge` | Where that page posts its solution. |
| `SnapshotVersion` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `ScriptPath` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `FPPath` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as ScriptPath: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_SERVERLESS=1` (no poll goroutine; each stale request kicks one refresh off the request path), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request (set at boot, no goroutines start at all). The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

1. Keeps the snapshot fresh off the request path: one poll goroutine at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. `CAMADA_SERVERLESS=1` drops the goroutine: each request checks staleness, and a stale one kicks one refresh off the request path.
2. Resolves the client from the socket peer (`r.RemoteAddr`), combined with `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one; `net/http` never rewrites the peer, so a reverse proxy is declared, not inferred.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints, then runs your app with `X-Rid` and the `_sfp` session cookie on its response, and ships one batched, redacted event with its real status, latency and route pattern (`r.Pattern`) when the response is done. A panic in your handler ships as `st: 500` and propagates unchanged; a hijacked connection ships as `st: 101`.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the middleware does the rest:

beacon

```go
func home(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "<html><head>%s</head><body>…</body></html>", camada.ScriptTag(r))
}
```

`camada.ScriptTag(r)` returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at `GET /_cam/b.js` (cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```go
func login(w http.ResponseWriter, r *http.Request) {
	if !signIn(r) {
		camada.Track(r, "login_failed", r.FormValue("email"))   // hashed in-process; never panics
		http.Error(w, "invalid", http.StatusUnauthorized)
		return
	}
	http.Redirect(w, r, "/", http.StatusSeeOther)
}
```

`camada.Track(r, event, user)` (an empty user when there is no identifier) ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never panics; outside the middleware (a request it did not run for) the outcome still ships, with no rid, sid or ip to join on. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand; `camada.FromRequest(r)` exposes the request's `RID`, `SID` and resolved `IP`:

gating a route

```go
func export(w http.ResponseWriter, r *http.Request) {
	if camada.ServeChallenge(w, r) {
		return   // the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
	}
	bigFile(w)
}
```

## What this position sees

The same position as `@camada/node`, in a Go process: the final status and latency, the session, the route pattern, the beacon's browser signals and your app's outcomes. `net/http` parses headers into a map, so the event's header order is the sorted name list, not the wire's — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a Go process (a server terminating TLS itself could read the ClientHello, and the event already carries the empty field until that lands), so those conditions fail open in-app and the analyst resolves ASN and country itself. `matches` patterns are JS regexes read by Go's RE2: named groups are native, `[^]` and `\cX` are translated, and a spelling RE2 rejects — lookaround, backreferences — never matches here while it does at the edge. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- Every process polls its own snapshot (about 5 MB resident) and flushes its own batches; the tenant's `poll_seconds` keeps the cadence honest across a fleet.
- Pending events drain when you call `cam.Stop(ctx)` (`defer` it in `main`), within half a second. No signal handlers are installed — an app owns its own shutdown — so a process killed without one drops its last batch.
- Serverless hosts: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
- Behind a reverse proxy or load balancer, declare it: `CAMADA_TRUSTED_PROXY=hops:1` (or the tenant config) is what makes `X-Forwarded-For` count.

## It fails open

Without a key the engine is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute, through `log.Default()` or the logger you pass to `camada.SetLogger`), a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/hono

Docs

# Hono on Cloudflare Workers

`@camada/hono` enforces your snapshot inside a Cloudflare Worker: block, allow and challenge, decided in-process, with events shipped off the response path.

## Install

shell

```sh
npm i @camada/hono
```

## Mount it

src/index.ts

```ts
import { Hono } from 'hono';
import { camada } from '@camada/hono';

const app = new Hono();

app.use('*', camada());        // key, ingest and snapshot URLs come from the Worker env
app.get('/', (c) => c.text('hello'));

export default app;
```

Workers hand environment variables to the request rather than to a process, so the middleware builds its engine from `c.env` on the first request it sees:

.dev.vars / wrangler secret

```dotenv
CAMADA_KEY=<ingest_token>.<snap_token>
CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Put `CAMADA_KEY` in with `wrangler secret put CAMADA_KEY`, not in `wrangler.toml`. An app that reads its own configuration can pass the values in code instead:

explicit config

```ts
app.use('*', camada({ key: MY_KEY, ingestUrl: MY_INGEST }));
```

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `key` | `env.CAMADA_KEY` | The <ingest_token>.<snap_token> pair, printed once when the project is created. Without it the middleware is inert. |
| `ingestUrl` | `env.CAMADA_INGEST_URL` | Ingest base. Batches go to <ingestUrl>/e. |
| `snapshotUrl` | `env.CAMADA_SNAPSHOT_URL` | Where the blocklist snapshot is polled from. Defaults to <ingestUrl>/snapshot. |
| `trustedProxy` | `your project setting` | hops:N or cidrs:a,b when something else sits in front of the Worker; none to trust nothing. |
| `challenge` | `true` | Serve the proof-of-work page for challenge verdicts. |
| `challengePath` | `/__camada/challenge` | Where that page posts its solution. |
| `snapshotVersion` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `scriptPath` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `fpPath` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as scriptPath: the script derives one from the other. |

`CAMADA_DISABLED=1` in the Worker environment switches everything off, and is checked per request.

## What it does per request

1. Refreshes the snapshot off the response path through `waitUntil` — lazily, with no interval timers, which an edge runtime does not keep alive anyway.
2. Resolves the client from `cf-connecting-ip`, falling back to `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one.
3. A blocked key gets **403** with `x-block-reason` before your handler runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. An allow-list entry wins over a wider block: an allow-listed address inside a blocked CIDR or ASN goes through.
5. A challenged key gets the proof-of-work page on a page load; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
6. Otherwise your handler runs, and the settled response ships one batched, redacted event with its real status.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the middleware does the rest:

beacon

```ts
import { camada, scriptTag } from '@camada/hono';

app.use('*', camada());
app.get('/', (c) => c.html(`<html><head>${scriptTag(c)}</head><body>…</body></html>`));
```

`scriptTag(c)` returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at `GET /_cam/b.js` (cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and the endpoints stand down with it.

Mounted on a prefix rather than `'*'`, the middleware never sees `/_cam/*`. Move both paths under it with `camada({ scriptPath: '/api/_cam/b.js', fpPath: '/api/_cam/fp' })`— the script derives the post path from its own URL, so the two must share a directory.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```ts
import { camada, track } from '@camada/hono';

app.post('/login', async (c) => {
  const ok = await signIn(c);
  if (!ok) track(c, 'login_failed', { user: email });   // await is optional: the flush rides waitUntil
  return ok ? c.redirect('/') : c.text('Invalid credentials', 401);
});
```

`track(c, event, { user })` ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the Worker. It never throws, and it is a no-op on a request the middleware did not run for. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

## What this position sees

`request.cf` gives a Worker the client's ASN, country and TLS fingerprint, so ASN, country and TLS-fingerprint rules genuinely enforce here — unlike a bare Node app, which sees none of them. With the beacon and `track()` this is the full in-app position: status, session, browser signals and outcomes alike. The one thing missing is raw header order, which Workers normalise away; camada knows that from the position itself and never scores its absence as evidence against a request.

## Routes to leave alone

Mount it on the paths you want covered, and keep health checks and webhook receivers out: they have no browser to challenge and must answer whatever the snapshot says.

excluding routes

```ts
const guard = camada();                 // call once and reuse: the engine is a singleton
const OPEN = new Set(['/api/health', '/api/stripe/webhook']);

app.use('/api/*', (c, next) => (OPEN.has(c.req.path) ? next() : guard(c, next)));
```

One catch when you mount on a prefix rather than on `'*'`: the middleware answers the challenge itself, on `challengePath`, so that path has to reach it. Either keep the mount at `'*'` and skip the routes you want inside the handler, or move the path under your prefix with `camada({ challengePath: '/api/__camada/challenge' })`. Otherwise a challenged browser has nowhere to post its answer and can never get through.

## It fails open

Without a key the middleware is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest, a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page, and what a list entry can key on is on [rules and list entries](https://www.camada.app/docs/rules).

---

Source: https://www.camada.app/docs/java

Docs

# Java: Spring Boot, any servlet container

`dev.camada:camada` enforces your snapshot inside a JVM: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One artifact with a plain `jakarta.servlet.Filter` that Spring Boot, Tomcat, Jetty and Undertow all take as is.

## Install

Not on Maven Central yet. From your project's folder: clone it next to the project, build it into your local Maven repository, then add the dependency.

shell, then pom.xml

```text
git clone https://github.com/camada-app/camada-java ../camada-java
mvn -q -f ../camada-java install -DskipTests

<!-- then, in pom.xml -->
<dependency>
  <groupId>dev.camada</groupId>
  <artifactId>camada</artifactId>
  <version>0.2.0</version>
</dependency>
```

Java 17 or newer; the only runtime dependency is the servlet API your container already provides.

## Mount it

Spring Boot

```java
// CamadaConfig.java, beside your @SpringBootApplication class
package com.example.demo;   // your application's package

import dev.camada.servlet.CamadaFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
class CamadaConfig {
  @Bean
  FilterRegistrationBean<CamadaFilter> camadaFilter() {
    var reg = new FilterRegistrationBean<>(new CamadaFilter());
    reg.setOrder(Ordered.HIGHEST_PRECEDENCE);   // first, so camada answers before routing
    return reg;
  }
}
```

any servlet container

```java
// CamadaListener.java: any servlet container (or declare the filter first in web.xml)
import dev.camada.servlet.CamadaFilter;
import jakarta.servlet.ServletContextEvent;
import jakarta.servlet.ServletContextListener;
import jakarta.servlet.annotation.WebListener;

@WebListener
public class CamadaListener implements ServletContextListener {
  @Override
  public void contextInitialized(ServletContextEvent event) {
    event.getServletContext()
        .addFilter("camada", new CamadaFilter())
        .addMappingForUrlPatterns(null, false, "/*");   // false: ahead of the filters web.xml declares
  }
}
```

The filter shares one lazy engine (`Camada.getDefault()`), built from the environment on the first request:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. camada reads only the environment, and Spring Boot does not pass application.properties or a .env file to it.

That build starts the snapshot poll on a daemon thread and never blocks, so the request that triggered it is answered cold: it passes (fail open), and so does anything that arrives before the first poll lands. To enforce from request 1, warm the engine at startup; `warmUp(ms)` polls until the snapshot is no longer cold or the budget is spent, returns false rather than throwing, and is a no-op on an inert engine:

warm-up

```java
// CamadaConfig.java: two more imports…
import dev.camada.Camada;
import org.springframework.boot.ApplicationRunner;

// …and one more @Bean in the class, run once the app has started
@Bean
ApplicationRunner camadaWarmUp() {
  // builds the engine (its boot poll is already running on its thread), then waits for that poll:
  // bounded, so an unreachable analyst leaves it cold, and the app still fails open
  return args -> Camada.getDefault().warmUp(5000);
}
```

The default is built once, by the first caller, with that caller's options: when the filter was handed `Options`, warm through `camadaFilter.engine()` rather than a bare `Camada.getDefault()`. The static helpers (`Camada.scriptTag`, `track`, `serveChallenge`) never build it: before the filter's first request they are silent no-ops.

An app that reads its own configuration can build the engine itself and hand it in — or hand the filter the options it should build the default engine with:

explicit config

```java
// CamadaConfig.java, for an app that reads its own configuration: these imports too…
import dev.camada.Camada;
import dev.camada.Options;
import java.util.Map;
import org.springframework.beans.factory.annotation.Value;

// …and this filter bean in place of the one above
@Bean
FilterRegistrationBean<CamadaFilter> camadaFilter(
    @Value("${camada.key}") String key, @Value("${camada.ingest-url}") String ingest) {
  Camada engine = new Camada(new Options()
      .env(Map.of("CAMADA_KEY", key, "CAMADA_INGEST_URL", ingest))
      .challengePath("/api/__camada/challenge"));
  var reg = new FilterRegistrationBean<>(new CamadaFilter(engine));   // this engine, not the default
  // or new CamadaFilter(new Options().env(...)): the default engine, built with these options on the first request
  reg.setOrder(Ordered.HIGHEST_PRECEDENCE);
  return reg;
}
```

Quickstart: [Spring Boot](https://www.camada.app/docs/quickstart/spring).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `env` | `System.getenv()` | Where CAMADA_KEY and friends are read from. Pass a Map to configure in code. |
| `transport` | `java.net.http` | The HTTP seam that reaches the analyst; tests hand in an in-process fake. |
| `refreshS` | `server-steered` | Poll cadence in seconds. Unset, the tenant config's poll_seconds steers it; set, it is pinned. |
| `challenge` | `true` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `challengePath` | `/__camada/challenge` | Where that page posts its solution. |
| `snapshotVersion` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `scriptPath` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `fpPath` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as scriptPath: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_SERVERLESS=1` (a per-request staleness check that hands the refresh to the daemon thread), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request (set at boot, no threads start at all). The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

1. Keeps the snapshot fresh off the request path: a daemon poll thread at the cadence your tenant config sets (at least 5 s; gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. The request path never waits on the network.
2. Resolves the client from the socket peer (`getRemoteAddr()`), combined with `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one. Keep the container's own forwarded-header handling off (Spring Boot: `server.forward-headers-strategy=none`, the default) — a `RemoteIpValve` would rewrite the peer before camada judges the header.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints (a body camada already read is replayed to the app whole), then runs your app with `x-rid` and the `_sfp` session cookie on its response — stamped before the chain runs, so your handlers see them too — and when the response is done, or in `AsyncListener.onComplete` when the app went async, ships one batched, redacted event with its real status, latency and the Spring MVC route pattern. An exception in your app ships as `st: 500` and propagates unchanged. The filter handles the original `REQUEST` dispatch only; `ASYNC`, `ERROR`, `FORWARD` and `INCLUDE` pass through.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the filter does the rest:

beacon

```java
// PageController.java, beside CamadaConfig.java: the tag goes in the <head> of the pages you render
package com.example.demo;   // your application's package

import dev.camada.Camada;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
class PageController {
  @GetMapping(value = "/", produces = "text/html")
  String home(HttpServletRequest request) {
    return "<html><head>" + Camada.scriptTag(request) + "</head><body>…</body></html>";
  }
}
```

`Camada.scriptTag(request)` (the `HttpServletRequest`) returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The filter serves the script at `GET /_cam/b.js` (vendored into the jar, cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```java
// PageController.java: these imports too…
import java.net.URI;
import java.util.Map;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

// …and this handler in the class
@PostMapping("/login")
ResponseEntity<?> login(HttpServletRequest request, @RequestParam String email, @RequestParam String password) {
  if (!signIn(email, password)) {
    Camada.track(request, "login_failed", email);   // hashed in-process; never throws
    return ResponseEntity.status(401).body(Map.of("error", "invalid"));
  }
  return ResponseEntity.status(303).location(URI.create("/")).build();
}

private boolean signIn(String email, String password) {
  return false;   // your own check
}
```

`Camada.track(request, event, user)` ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never throws and is a no-op on a request the filter did not run for. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand; the per-request `Context` (`rid`, `sid`, `ip`) is the `"camada"` request attribute:

gating a route

```java
// PageController.java: these imports too…
import jakarta.servlet.http.HttpServletResponse;
import java.io.IOException;

// …and this handler in the class
@GetMapping("/export")
void export(HttpServletRequest request, HttpServletResponse response) throws IOException {
  if (Camada.serveChallenge(request, response)) {
    return;   // the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
  }
  response.getWriter().write("…");   // your export
}
```

## What this position sees

The same position as `@camada/node`, in a JVM: the final status and latency, the session, the beacon's browser signals, your app's outcomes, and the header order as the container hands it over. No ASN, country or TLS fingerprint reaches a servlet — camada knows what this tap can see from the position itself and never scores their absence as evidence against a request — so those conditions fail open in-app and the analyst resolves ASN and country itself. `matches` patterns are JS regexes read by `java.util.regex`: named groups are translated (a plain group, `\k<name>` its number), `[^]` and a bare `$` too, and a spelling the engine still rejects never matches here while it does at the edge. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- Every JVM polls its own snapshot (about 5 MB resident) and flushes its own batches; the tenant's `poll_seconds` keeps the cadence honest across a fleet. Both threads are daemons: they never keep a JVM alive.
- Pending events drain at exit within half a second, from a JVM shutdown hook — which runs on SIGTERM as well as on a normal exit, so a container stopped by its orchestrator keeps its last batch. No signal handlers are installed; a JVM does not fork, so there is no fork handling to speak of.
- Serverless hosts: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
- Not in this release: a Spring Boot starter (the filter is plain `jakarta.servlet`, registered by hand as above) and container-specific suites — Jetty and Undertow take the same filter but are not exercised.

## It fails open

Without a key the filter is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute on the `camada` `java.util.logging` logger, message only, never a stack trace), a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/memory

Docs

# Memory

Memory is what camada knows about your setup, kept per project, so you stop explaining the same thing twice. It is a list of plain facts, and none of them is hidden from you: every one is on the Memory page in the app, where anyone in the organization can read them and members and admins can add, edit and delete them.

## What a fact is

| Field | Meaning |
| --- | --- |
| `kind` | One of preference, infrastructure, decision, contact or note. |
| `text` | The fact itself, up to 500 characters. Write it the way you would tell a colleague. |
| `source` | user when you typed it, agent when the chat agent stored it, system when camada wrote it for you. |
| `author` | The person who wrote it, for a fact with source user. |
| `entity` | Optional. An IP, CIDR, ASN, path or country the fact is about, so it can be matched to traffic. |
| `created` | When it was written. Editing a fact updates it in place and re-indexes it. |
| `expires` | Optional. After it passes, the fact stops being used and stops being sent to the analyst. |

The database row is the source of truth. When the agent stores one during a conversation you see it at once as "remembered: …", with an Undo that deletes it.

## Facts camada writes for you

Adding an allow-list entry writes an `infrastructure` fact from the reason you gave — "Allow-listed asn 12345: our SEO crawler" — because that reason is exactly the kind of thing the analyst should know. Removing the entry retires the fact: it stops being sent to the analyst and stops appearing in search, rather than being silently rewritten behind you.

## How facts are indexed

Every fact, every conversation summary and every run report summary is embedded with Cloudflare Workers AI (`@cf/baai/bge-m3`) into a Cloudflare Vectorize index, tagged with the project and the kind. Every query is filtered by project id, so a search can only ever return this project's rows. The embeddings are an index, not the store: delete the fact and its vector goes with it.

## Summaries camada writes into the index

Besides your facts, camada writes short model-written summaries into the same index: one per conversation, so the agent can recall what you discussed before, and one per analysis run report. They are searchable on the Memory page and included in the export, so you can always read what was written. They are not facts: they are never pushed to the analyst, and they go when the conversation or the project goes.

## How facts reach the investigation agent

This is the part that pays for itself. After every change, camada pushes the project's live facts — up to 200 facts that have not expired, as a full replacement — to the analyst that investigates your traffic.

- While investigating an entity, the analyst can call `get_tenant_context`, which returns up to 20 of your facts: the ones that match the entity first (an IP inside one of your CIDRs, the same ASN, a path prefix, the same country), then general ones.
- A fact it used is quoted in the verdict's evidence as `context: <the fact>`, so you can see which piece of your own knowledge changed the answer.
- "Our SEO crawler runs from ASN 12345" stops being a false positive on every run that reads it, instead of being re-litigated each time.
- Facts are handed to that agent as delimited customer data, never as instructions — a fact cannot rewrite how the analyst reasons.

## Export, retention and deletion

- **Export:** the Memory page hands you the whole project's memory as JSON — the facts and the indexed documents — with one button.
- **Transcripts are separate.** Chat conversations are stored in their own tables, apart from memory and apart from your analysis data, under their own retention: an organization setting between 7 and 365 days, **90 days** by default. Conversations older than that are deleted; memory is untouched.
- **Deletion:** deleting the project deletes its facts, its vectors and its transcripts.

What the [agent](https://www.camada.app/docs/chat) can read and change, and what is sent to the model, is on the chat page; retention of everything else is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/php

Docs

# PHP: front controllers, Laravel

`camada/camada` enforces your snapshot inside a PHP process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped after the response has left. One package with a front-controller adapter that needs nothing but `$_SERVER`, `php://input` and `header()` — FPM, `php -S`, mod_php — and a Laravel middleware.

## Install

Not on Packagist yet. Run these in your project's folder: Composer installs it straight from GitHub, composer.lock pins the commit, and composer update camada/camada moves it.

shell

```sh
composer config repositories.camada vcs https://github.com/camada-app/camada-php
composer require camada/camada:dev-main
```

PHP 8.1 or newer, `ext-json` and `ext-zlib` (the snapshot travels gzipped), `allow_url_fopen=On` (the transport is an http stream), no runtime dependencies.

## Mount it

front controller

```php
<?php
// public/index.php — any front controller
require __DIR__ . '/../vendor/autoload.php';

use Camada\Camada;
use Camada\Http\Sapi;

$cam = Camada::default();      // built lazily from the environment, once per request
$ctx = Sapi::run($cam);        // null: camada answered (block, challenge, beacon) and the script must stop
if ($ctx === null) {
    return;
}
// your app: x-rid and the _sfp cookie are already on the response; $ctx->rid, $ctx->sid, $ctx->ip are yours
```

Laravel

```php
// bootstrap/app.php (Laravel 11+), inside the existing ->withMiddleware(function (Middleware $middleware) { … })
$middleware->prepend(\Camada\Laravel\Middleware::class);   // first in the global stack

// or app/Http/Kernel.php (Laravel 10): the first entry of protected $middleware = [ … ]
\Camada\Laravel\Middleware::class,

// the context rides $request->attributes->get('camada')
```

The engine is built from the environment, once per request:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that runs php -S; under PHP-FPM, which clears the environment, add env[CAMADA_KEY] = … to the pool config. PHP reads no .env file. Laravel loads .env into the environment, except once php artisan config:cache has run: there, set them as real environment variables.

An app that reads its own configuration can build the engine itself and hand it in:

explicit config

```php
$cam = new Camada(env: ['CAMADA_KEY' => $key, 'CAMADA_INGEST_URL' => $ingest], challengePath: '/api/__camada/challenge');
$ctx = Sapi::run($cam);                       // Laravel: Camada::setDefault($cam) in a service provider — the kernel builds the middleware itself
```

Quickstarts: [PHP](https://www.camada.app/docs/quickstart/php), [Laravel](https://www.camada.app/docs/quickstart/laravel).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `env` | `the process environment` | Where CAMADA_KEY and friends are read from. Pass an array to configure in code. |
| `transport` | `StreamTransport` | The HTTP seam that reaches the analyst; tests hand in an in-process fake. |
| `refreshS` | `server-steered` | Poll cadence in seconds. Unset, the tenant config's poll_seconds steers it; set, it is pinned. |
| `challenge` | `true` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `challengePath` | `/__camada/challenge` | Where that page posts its solution. |
| `snapshotVersion` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `scriptPath` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `fpPath` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as scriptPath: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_CACHE_DIR` (the runtime's directory, below), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request (set at boot, no files are touched and no request is ever made). The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

A PHP process lives for one request, so the poll thread and the flush thread the other SDKs run become one file-backed runtime on disk that every worker of every SAPI shares: the raw snapshot container (seeked into per request, never parsed whole), its state, and an event spool, under `CAMADA_CACHE_DIR` (default: the system temp dir, keyed by your snapshot token). Every write is `tmp + rename()`, so a reader never sees a torn file, and the request path never opens a socket.

1. Keeps the snapshot fresh in the **post-response** phase, after the client has its bytes: a stale snapshot (0.9 × the cadence your tenant config sets) is fetched under a lock (gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. A busy lock means another worker is on it.
2. Resolves the client from the socket peer (`REMOTE_ADDR`), combined with `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one. nginx's `real_ip` module rewrites the peer before PHP sees it; behind it the trusted-proxy setting should say `none`.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints, then runs your app with `x-rid` and the `_sfp` session cookie on its response. Under FPM and FrankenPHP `fastcgi_finish_request()` ends the response; under `php -S` and mod_php the adapter's output buffer is flushed with a `Content-Length`. Then one redacted event with its real status and latency is appended to the spool, and a due spool (500 rows, or 15 s since the last flush) ships in slices. An uncaught exception ships as `st: 500` and stays PHP's (or Laravel's) own 500.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the adapter does the rest:

beacon

```php
echo '<html><head>', $cam->scriptTag($ctx), '</head><body>…</body></html>';
```

`$cam->scriptTag($ctx)` (Laravel: the context is `$request->attributes->get('camada')`) returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The adapter serves the script at `GET /_cam/b.js` (from opcache, cacheable for an hour) and relays `POST /_cam/fp` onto the event spool, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```php
if (!sign_in($email, $password)) {
    $cam->track($ctx, 'login_failed', $email);   // hashed in-process; never throws
    http_response_code(401);
    return;
}
header('Location: /', true, 303);
```

`$cam->track($ctx, $event, $user)` ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is spooled — the raw value never leaves the process. It never throws and is a no-op on a request the adapter did not run for. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand:

gating a route

```php
if ($answer = $cam->serveChallenge($ctx)) {
    Sapi::send($answer);   // the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
    return;
}
big_file();
```

## What this position sees

The same position as `@camada/node`, in a PHP process: the final status and latency, the session, the beacon's browser signals and your app's outcomes. Header order is whatever `getallheaders()` yields — a hash under FastCGI — so the analyst reads no header-order signal from this tap; camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a PHP process, so those conditions fail open in-app and the analyst resolves ASN and country itself. `matches` patterns are JS regexes read by PCRE without the `u` flag: named groups are native, `[^]` is translated, and a spelling PCRE still rejects never matches here while it does at the edge. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- FPM, FrankenPHP (classic mode), LiteSpeed: the response ends with `fastcgi_finish_request()` and the post-response work runs in the same worker afterwards — a slow analyst costs that worker's availability for the poll's duration (3 s timeout), never the client's latency.
- `php -S`, mod_php: the fallback flushes the adapter's buffer with a `Content-Length`; a client that honours it stops reading before the deferred work runs. Run the CLI server with `PHP_CLI_SERVER_WORKERS=4` or more, or a refresh in one request delays the next.
- The cache dir must be a local, writable directory (`flock()` and `rename()` are the concurrency model; a network mount is not). It is per host: a fleet polls once per host per cadence, and each host ships its own spool.
- The first request after a deploy (or an emptied cache) is answered cold — it passes and arms the refresh; the next request enforces. To enforce from request 1, warm the cache in a deploy step. It must warm the directory the workers read: set `CAMADA_CACHE_DIR` explicitly for both (the default lives under the system temp dir, which is per-service under systemd's `PrivateTmp`, and is created `0700`), and run the step as the FPM pool's user:

warm-up

```php
$cam = Camada::default();
if ($cam->snap !== null) {                    // null when CAMADA_KEY is unset or CAMADA_DISABLED=1
    $deadline = microtime(true) + 5;
    while ($cam->snap->verdict(new \Camada\Snapshot\MatchInput(ip: '0.0.0.0'))->reason === 'cold' && microtime(true) < $deadline) {
        $cam->snap->refresh();                // bounded: an unreachable analyst leaves it cold, and the app still fails open
        usleep(10_000);
    }
}
```

- Events ship when the spool is due, in the post-response phase of the request that finds it due, so a quiet site ships its last events on its next hit, not on a timer. A failed POST drops that batch (logged at most once a minute); over 2000 spooled rows the oldest half is dropped. Nothing runs at process exit and no signal handlers are installed.
- Under Laravel the middleware's `terminate()` is the post-response phase. Worker-mode SAPIs (FrankenPHP worker mode, Octane), a PSR-15 middleware and an APCu-backed runtime are not in this release.

## It fails open

Without a key the engine is **inert**: one log line, no files, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute, across workers), a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/python

Docs

# Python: FastAPI, Django, Flask

`camada` on PyPI enforces your snapshot inside a Python process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One package, with an ASGI middleware, a WSGI middleware, and integrations for FastAPI, Django and Flask.

## Install

shell

```sh
pip install camada
```

Python 3.10 or newer. No runtime dependencies.

## Mount it

FastAPI / Starlette

```python
from fastapi import FastAPI
from camada.fastapi import CamadaMiddleware

app = FastAPI()
app.add_middleware(CamadaMiddleware)   # key, ingest and snapshot URLs come from the environment
```

Django

```python
# settings.py
MIDDLEWARE = [
    "camada.django.CamadaMiddleware",   # first, so it answers before anything else runs
    *MIDDLEWARE,
]
```

Flask

```python
from flask import Flask
from camada.flask import init_app

app = Flask(__name__)
init_app(app)   # wraps app.wsgi_app, so camada answers before routing
```

any ASGI or WSGI app

```python
from camada.asgi import CamadaASGI   # any ASGI 3 app
from camada.wsgi import CamadaWSGI   # any WSGI app

application = CamadaASGI(application)
```

The engine is built from the environment on the first request it sees:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Python reads no .env file on its own.

An app that reads its own configuration can build the engine itself and hand it to the integration:

explicit config

```python
from camada import Camada
from camada.fastapi import CamadaMiddleware

engine = Camada(env={"CAMADA_KEY": MY_KEY, "CAMADA_INGEST_URL": MY_INGEST}, challenge_path="/api/__camada/challenge")
app.add_middleware(CamadaMiddleware, engine=engine)
```

Quickstarts: [FastAPI](https://www.camada.app/docs/quickstart/fastapi), [Django](https://www.camada.app/docs/quickstart/django), [Flask](https://www.camada.app/docs/quickstart/flask).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `env` | `os.environ` | Where CAMADA_KEY and friends are read from. Pass a mapping to configure in code. |
| `transport` | `urllib` | The HTTP callable that reaches the analyst; tests hand in an in-process fake. |
| `refresh_s` | `server-steered` | Snapshot poll cadence in seconds. Unset, the tenant config's poll_seconds steers it; set, it is pinned. |
| `challenge` | `True` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `challenge_path` | `/__camada/challenge` | Where that page posts its solution. |
| `snapshot_version` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `script_path` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `fp_path` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as script_path: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_SERVERLESS=1` (lazy refresh, no poll thread), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request. The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

1. Keeps the snapshot fresh off the request path: a daemon thread polls at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), and asks for snapshot v5, the container that carries your ordered custom rules. `CAMADA_SERVERLESS=1` refreshes lazily instead.
2. Resolves the client from the socket peer, combined with `X-Forwarded-For` only under your trusted-proxy setting. A raw forwarded header is never trusted without one.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints, then runs your app with `x-rid` and the `_sfp` session cookie on its response, and ships one batched, redacted event with its real status and latency when the response is done. An exception in your app ships as `st: 500` and propagates unchanged.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the middleware does the rest:

beacon

```python
from camada.fastapi import script_tag

@app.get("/", response_class=HTMLResponse)
async def home(request: Request):
    return f"<html><head>{script_tag(request)}</head><body>…</body></html>"
```

`script_tag(request)` (Flask: `script_tag()`) returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at `GET /_cam/b.js` (cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```python
from camada.fastapi import track

@app.post("/login")
async def login(request: Request, form: LoginForm):
    ok = await sign_in(form)
    if not ok:
        track(request, "login_failed", user=form.email)   # hashed in-process; never raises
    return RedirectResponse("/") if ok else JSONResponse({"error": "invalid"}, 401)
```

`track(request, event, user=…)` (Django the same; Flask `track(event, user=…)`) ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never raises. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand:

gating a route

```python
from camada.fastapi import serve_challenge   # Django: camada.django, Flask: camada.flask

@app.get("/export")
async def export(request: Request):
    if answer := serve_challenge(request):
        return answer          # the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
    return big_file()
```

## What this position sees

The same position as `@camada/node`, in a Python process: the final status and latency, the session, the beacon's browser signals and your app's outcomes. Under ASGI (FastAPI, Starlette, async Django) the event also carries the wire's header order; WSGI (Flask, sync Django) loses it, which is why the plan calls ASGI the first-class tier — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a Python process, so those conditions fail open in-app and the analyst resolves ASN and country itself. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- Every worker process polls its own snapshot (about 5 MB resident each) and ships its own batches; the tenant's `poll_seconds` keeps the cadence honest across a fleet.
- Threads do not survive a fork. Under gunicorn `--preload` or uWSGI the SDK notices the fork and restarts its poll and flush threads in each worker.
- Pending events drain at interpreter exit within half a second. The SDK installs no signal handlers — an app owns its own shutdown — so a worker killed by SIGTERM without one may drop its last batch.
- Serverless hosts: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next request.

## It fails open

Without a key the middleware is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest, a corrupt snapshot or a bug in the package costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/ruby

Docs

# Ruby: Rails, Sinatra, any Rack app

The `camada` gem enforces your snapshot inside a Ruby process: your ordered custom rules, then allow, block and challenge, decided in-process, with events shipped off the request path. One gem with a Rack middleware that any Rack app mounts and a Railtie that mounts it for Rails — the `sentry-ruby` model.

## Install

shell

```sh
bundle add camada
```

Ruby 3.1 or newer. No runtime dependencies (stdlib only); it never requires `rack` itself. On [RubyGems](https://rubygems.org/gems/camada) as `camada`.

## Mount it

Rack

```ruby
# config.ru — Sinatra, Hanami, or any Rack app
require "camada"
use Camada::Rack      # first, so camada answers before routing
run App
```

Rails (Gemfile)

```ruby
# Rails — nothing to add: the Railtie inserts Camada::Rack at the top of the middleware stack
gem "camada"
```

The middleware shares one lazy engine, built from the environment on the first request:

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Rack and Rails read no .env file (Rails needs the dotenv-rails gem for that).

That build starts the snapshot poll on a thread and never blocks, so the request that triggered it is answered cold: it passes (fail open), and so does anything that arrives before the first poll lands. To enforce from request 1, warm the engine at boot by waiting for the boot poll:

warm-up

```ruby
# config/initializers/camada.rb, or config.ru before `run`
engine = Camada.default          # builds the engine; the boot poll is already running on its thread
if engine.snap                   # nil when CAMADA_KEY is unset or CAMADA_DISABLED=1
  probe = Camada::Snapshot::MatchInput.new(ip: "0.0.0.0")
  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 5
  while engine.snap.verdict(probe).reason == "cold" && Process.clock_gettime(Process::CLOCK_MONOTONIC) < deadline
    sleep 0.01                   # bounded: an unreachable analyst leaves it cold, and the app still fails open
  end
end
```

An app that reads its own configuration can build the engine itself and hand it in:

explicit config

```ruby
# my_key, my_ingest: read from your own configuration
engine = Camada::Engine.new(env: { "CAMADA_KEY" => my_key, "CAMADA_INGEST_URL" => my_ingest }, challenge_path: "/api/__camada/challenge")
use Camada::Rack, engine
```

Quickstart: [Rails and Rack](https://www.camada.app/docs/quickstart/rails).

## The options you will use

| Option | Default | Meaning |
| --- | --- | --- |
| `env` | `ENV` | Where CAMADA_KEY and friends are read from. Pass a Hash to configure in code. |
| `transport` | `Net::HTTP` | Anything responding to #call(HttpRequest) that reaches the analyst; tests hand in an in-process fake. |
| `refresh_s` | `server-steered` | Poll cadence in seconds. Unset, the tenant config's poll_seconds steers it; set, it is pinned. |
| `challenge` | `true` | Serve the proof-of-work page for challenge verdicts (CAMADA_CHALLENGE=0 switches it off too). |
| `challenge_path` | `/__camada/challenge` | Where that page posts its solution. |
| `snapshot_version` | `5` | 4 drops your ordered custom rules; 3 the allow and challenge sections too. |
| `script_path` | `/_cam/b.js` | Where the first-party beacon script is served. |
| `fp_path` | `/_cam/fp` | Where that script posts the beacon. Keep it in the same directory as script_path: the script derives one from the other. |

Environment: `CAMADA_KEY`, `CAMADA_INGEST_URL`, `CAMADA_SNAPSHOT_URL`, `CAMADA_TRUSTED_PROXY`, `CAMADA_SERVERLESS=1` (a per-request staleness check, no poll thread), `CAMADA_CHALLENGE=0`, and the kill switch `CAMADA_DISABLED=1`, checked per request (set at boot, no threads start at all). The [docs index](https://www.camada.app/docs) lists what each one means.

## What it does per request

1. Keeps the snapshot fresh off the request path: a poll thread at the cadence your tenant config sets (gzip on the wire, 304 when nothing changed), asking for snapshot v5, the container that carries your ordered custom rules. `CAMADA_SERVERLESS=1` checks staleness per request instead.
2. Resolves the client from the socket peer (`REMOTE_ADDR`), combined with `X-Forwarded-For` only under your trusted-proxy setting. Never `request.ip`: `Rack::Request#ip` trusts a forwarded header from anyone, which is exactly the spoof camada refuses.
3. Runs your ordered custom rules, then the allow, block and challenge lists. A blocked request gets **403** with `x-block-reason` (and `x-block-rule` when a rule decided) before your app runs. The event still ships, marked as an SDK block so it is not confused with your own 403s.
4. A challenged browser gets the proof-of-work page; an API call reaches your app, and its response carries `x-camada-challenge: 1` for your frontend to act on. A request whose IP cannot be resolved is let through. See [challenge](https://www.camada.app/docs/challenge).
5. Serves the beacon endpoints, then runs your app with `x-rid` and the `_sfp` session cookie on its response, and when the server closes the response body ships one batched, redacted event with its real status, latency and the matched route pattern when the framework names it (`sinatra.route`, Rails' `route_uri_pattern`). An exception in your app ships as `st: 500` and propagates unchanged.

## Add the beacon

Bots that never run JavaScript are the cheapest to catch. Put the tag in the `<head>` of the pages you render and the middleware does the rest:

beacon

```ruby
# Sinatra: `env` is the Rack env; Rails: request.env
get "/" do
  "<html><head>#{Camada.script_tag(env)}</head><body>…</body></html>"
end
```

`Camada.script_tag(env)` (Rails: `request.env`) returns a `<script src="/_cam/b.js?r=…" async>` tag carrying this request's event id, so the beacon is joined to the page view it came from. The middleware serves the script at `GET /_cam/b.js` (cacheable for an hour) and relays `POST /_cam/fp` onto the event batch, stamped with the client address camada resolved — never the one the body claims. Both endpoints sit behind the verdict, so a blocked client gets 403 there too. Turn the beacon off in the project's settings and the tag becomes empty and both endpoints fall through to your app.

## Report what your app knows

The wire shows a `POST /login`; only your handler knows whether it failed. Tell camada from the handler:

outcomes

```ruby
post "/login" do
  ok = sign_in(params)   # your own check
  Camada.track(env, "login_failed", user: params[:email]) unless ok   # hashed in-process; never raises
  ok ? redirect("/") : halt(401, { error: "invalid" }.to_json)
end
```

`Camada.track(env, event, user: …)` ships the outcome joined to this request's event and session. The user identifier is hashed in-process with your ingest token before it is queued — the raw value never leaves the process. It never raises and is a no-op on a request the middleware did not run for. The event name is free-form; the analyst's rules read this vocabulary:

| Event | When |
| --- | --- |
| `login_failed / login_succeeded` | a credential check settled |
| `signup` | an account was created |
| `password_reset` | a reset was requested |
| `mfa_failed` | a second factor was rejected |
| `payment_failed / payment_succeeded` | a charge settled |
| `coupon_failed` | a promo code was rejected |

A route you want to gate yourself can serve the challenge on demand; the answer is a Rack triple:

gating a route

```ruby
get "/export" do
  if (answer = Camada.serve_challenge(env))
    halt(*answer)   # the proof-of-work page (or 403 JSON) until this browser holds a valid _cch
  end
  big_file   # your response
end
```

## What this position sees

The same position as `@camada/node`, in a Ruby process: the final status and latency, the session, the beacon's browser signals and your app's outcomes. The Rack env carries no wire header order, so the analyst reads no header-order signal from this tap — camada knows what this tap can see from the position itself and never scores the absence of header order as evidence against a request. No ASN, country or TLS fingerprint reaches a Ruby process, so those conditions fail open in-app and the analyst resolves ASN and country itself. `matches` patterns are JS regexes read by Ruby's Onigmo: named groups are native, `^` and `$` become `\A` and `\z`, and a spelling Ruby still rejects never matches here (and never raises) while it does at the edge. What a rule can key on is on [rules and list entries](https://www.camada.app/docs/rules).

## Deploying it

- Every worker process polls its own snapshot (about 5 MB resident, read a word at a time) and flushes its own batches; the tenant's `poll_seconds` keeps the cadence honest across a fleet.
- Threads do not survive a fork. Ruby has no fork hook, so the SDK compares `Process.pid` on every call and starts over in a forked worker: new locks, an empty queue, its poll and flush threads restarted. Puma cluster mode with `preload_app!`, Unicorn and Passenger need nothing added.
- Pending events drain at interpreter exit within half a second (`at_exit`). No signal handlers are installed — an app owns its own shutdown — so a worker killed by SIGKILL, or by SIGTERM without a handler, may drop its last batch.
- Serverless hosts: `CAMADA_SERVERLESS=1`. A cold invocation fails open and catches up on the next one.
- The middleware writes lower-case header names; it appends `set-cookie` as an Array under Rack 3 and joins cookies with `"\n"` under Rack 2.

## It fails open

Without a key the middleware is **inert**: one log line, no requests, no enforcement, so an unprovisioned environment behaves exactly as if camada were not installed. Beyond that, a dead ingest (logged at most once a minute, one line, no backtrace), a corrupt snapshot or a bug in the gem costs you the telemetry, never the request — camada can never turn one of your responses into a 5xx. The whole stance is on the [security](https://www.camada.app/security) page.

---

Source: https://www.camada.app/docs/rules

Docs

# Rules and list entries

An allow-list entry or a manual block names one key. Every entry takes a reason and an optional expiry. An allow-list entry always wins over a block, wherever the two overlap.

## What you can key an entry on

These five key types are the ones you can write by hand, on the allow-list and on manual blocks alike.

| Key type | What it is | Enforced where |
| --- | --- | --- |
| `ip` | A single address, v4 or v6. | Any SDK or proxy in the request path. |
| `cidr` | A range. Nothing wider than a /8 is accepted. | Any SDK or proxy in the request path. |
| `path` | A path, in any case. Ending it in a slash makes a prefix. See below. | Any SDK or proxy in the request path. |
| `asn` | The autonomous system number as a decimal string, 1 to 4294967295. | Positions that see the IP-derived ASN. See below. |
| `country` | ISO 3166-1 alpha-2, uppercase, e.g. BR. | Positions that see the IP-derived country. See below. |

camada's own analysis blocks a wider set: a verdict can also name a session or a TLS fingerprint. Those are not key types you can write an entry for; they appear on findings and on the entity pages like any other key.

## How paths match

Paths match without regard to case, a trailing slash or percent-encoding, so `/admin` also covers `/Admin`, `/admin/` and `/%61dmin`.

- A key ending in a slash is a prefix and covers the directory itself: `/admin/` covers `/admin` and `/admin/users`.
- `.` and `..` are resolved, doubled slashes collapse and `;` parameters are dropped, so `/public/../admin` is `/admin`. An encoded slash, `%2F`, never counts as a separator.
- A block matches any of those spellings. An allow-list entry or a skip rule has to match the path both before and after `..` is resolved, so `/public/../admin` never borrows the exemption for `/public/`.
- A rule's path conditions work the same way: *is*, *starts with* and *matches regex* all ignore case.

## Country and ASN need a position that sees them

ASN and country are derived from the client IP by the position that collects the request. A Cloudflare Worker running [@camada/hono](https://www.camada.app/docs/hono) has them, because the platform puts `request.cf` in front of your handler with the ASN and the country on it; so do camada's own proxy and edge module, and CDN log sources.

`@camada/node` and `@camada/next` **do not see** them: inside your app the SDK has the forwarded request, not the connection. Where the position cannot see the signal, a country or ASN entry is stored and shown but never matches, and a challenge or block verdict on one of those keys is recorded and alerted rather than enforced. Nothing is guessed at. Each project's rules page in the app reports which key types it can actually enforce, worked out from the positions camada has really received traffic from; until a project has seen traffic the page says so instead of guessing. That report, not this table, is the answer for your project.

## Actions per verdict category

| Action | What happens |
| --- | --- |
| `block` | The SDK answers 403 before your handler runs. |
| `challenge` | The SDK serves a proof-of-work page, where it can. See below. |
| `alert` | Recorded and alerted, never enforced. |
| `ignore` | Recorded and nothing else. |

**Challenge is enforced by SDKs on snapshot v4 (@camada/node ≥ 0.1.0, @camada/next ≥ 0.1.0, @camada/hono ≥ 0.1.0, @camada/sveltekit ≥ 0.1.0, @camada/nuxt ≥ 0.1.0, @camada/remix ≥ 0.1.0, @camada/bun ≥ 0.1.0, @camada/deno ≥ 0.1.0, @camada/python ≥ 0.2.0, @camada/go ≥ 0.1.0, @camada/php ≥ 0.1.0, @camada/ruby ≥ 0.1.0, @camada/java ≥ 0.1.0, @camada/dotnet ≥ 0.1.0); older SDKs treat it as recommend.**

On an older SDK a challenge verdict therefore behaves exactly like alert-only: the row appears in your activity and in your alerts, and no traffic is stopped. The flow, the cookie and the version table are on the [challenge](https://www.camada.app/docs/challenge) page.

What camada scores before it ever reaches a rule: [how it works](https://www.camada.app/how-it-works).

---

Source: https://www.camada.app/docs/webhooks

Reference

# Webhook payload

A webhook channel is one HTTPS URL per project, added under `Alerts → Channels` in the app. camada sends one `POST` per alert event, JSON body, signed. Any 2xx response counts as delivered; anything else is retried. Times in the body are ISO 8601 UTC.

## Request headers

| Header | Value |
| --- | --- |
| `content-type` | Always application/json. |
| `x-camada-event` | The event id, e.g. block.applied. Route on this without parsing the body. |
| `x-camada-delivery` | Delivery id, the same value as delivery_id in the body. Use it to deduplicate. |
| `x-camada-signature` | t=<unix seconds>,v1=<hex HMAC-SHA256>. Can carry more than one v1; accept the request if any one matches. See below. |

## Payload

Every event uses the same envelope. `entity` is null for events that are not about one address or session (quota, payment, learning); each link in `links` is absolute or null. `data` carries the fields specific to the event. `schema_version` is 1.

POST body

```json
{
  "schema_version": 1,
  "event": "block.applied",
  "severity": "warning",
  "occurred_at": "2026-09-03T14:22:07.311Z",
  "delivery_id": "dlv_7f3c1a9e2b40",
  "org": { "id": "org_2ZKq", "name": "Acme" },
  "project": { "id": "prj_8Ha2", "name": "Production", "slug": "acme-production", "env": "production" },
  "entity": { "key_type": "ip", "key": "203.0.113.66" },
  "verdict": "malicious",
  "category": "scraping",
  "confidence": 0.94,
  "action": "blocked",
  "summary": "1,284 requests in 4 minutes across 37 product pages, no beacon, headless fingerprint.",
  "evidence": [
    "no beacon post on any of 37 page views",
    "TLS fingerprint matches a known headless client",
    "request interval standard deviation 41 ms"
  ],
  "links": {
    "entity": "https://my.camada.app/activity/entities/ip/203.0.113.66",
    "run": "https://my.camada.app/activity/runs/run_5512",
    "allow": "https://my.camada.app/lists?allow=203.0.113.66",
    "block": "https://my.camada.app/lists?tab=blocks&block=203.0.113.66",
    "project": "https://my.camada.app/"
  },
  "data": { "ttl_hours": 24, "source": "verdict" }
}
```

## Compatibility

Inside `schema_version: 1` fields are **only added**, never removed or renamed — so parse leniently and ignore what you do not know. A breaking change bumps `schema_version`, and the old version keeps being delivered for **90 days** after the new one ships, which is your window to migrate.

## Event catalog v1

| Event | Default severity | Meaning |
| --- | --- | --- |
| `block.applied` | warning | A block was written and published to your snapshot. |
| `block.recommended` | info | A block was recommended during the learning window, not enforced. |
| `verdict.suspicious` | info | The analyst wrote a suspicious or malicious verdict that was not blocked. |
| `attack.spike` | critical | Blocked plus recommended activity in five minutes went far over the trailing hour. |
| `learning.ended` | info | The learning window closed and is waiting for your review. |
| `list.changed` | info | Someone changed the allow-list or a manual block. |
| `key.rotated` | warning | A project key was rotated; the previous pair is in its grace period. |
| `key.old_still_in_use` | warning | The previous key is still being used after a rotation. |
| `quota.threshold` | warning | The organization passed 80% of its included events for the period. |
| `quota.exceeded` | warning | The organization passed 100% of its included events. Traffic is never blocked. |
| `run.failed` | critical | An analysis run failed after its last retry. |
| `payment.failed` | critical | Stripe could not charge the card on file. |
| `test` | info | Sent by "Send test" on a channel. Same shape, no real entity. |

Severity is a default: you set it per event per channel when you route it, and you choose immediate, hourly or daily delivery there too.

## Verifying the signature

Each webhook channel has a secret, shown once when you create it and rotatable at any time. Every request carries:

header

```http
x-camada-signature: t=1788393727,v1=9f2c...c41d
```

`v1` is the hex HMAC-SHA256 of the string `<t>.<raw body>` under your channel secret, where `t` is the Unix timestamp in seconds from the same header. Reject the request when `|now − t|` is more than **300 seconds**, and compare the digests in constant time. Sign over the bytes you received, before any JSON parse or re-serialisation.

The header can carry more than one `v1`: for 24 hours after you rotate a secret, camada signs with both the old and the new one (`t=…,v1=…,v1=…`), so you can deploy the new secret without dropping deliveries. The order is not promised. Accept the request if any one `v1` matches, as the sample does.

Node 20+ / Express

```js
import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = process.env.CAMADA_WEBHOOK_SECRET;

// Verify over the RAW body, before any JSON parsing.
app.post('/camada', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('x-camada-signature') ?? '';
  const pairs = header.split(',').map((kv) => kv.split('='));
  const t = Number(pairs.find(([k]) => k === 't')?.[1]);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);

  const expected = createHmac('sha256', SECRET).update(t + '.' + req.body).digest('hex');
  const want = Buffer.from(expected, 'hex');
  // The header can carry more than one v1 (see below): accept the request if any one matches.
  const ok = pairs
    .filter(([k]) => k === 'v1')
    .some(([, v]) => {
      const got = Buffer.from(v ?? '', 'hex');
      return got.length === want.length && timingSafeEqual(got, want);
    });
  if (!ok) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  console.log(event.event, event.delivery_id);
  res.sendStatus(200); // any 2xx counts as delivered
});
```

## Retries

A non-2xx response, a timeout or a transport error is retried up to five times with a growing delay: 30 seconds, 1 minute, 5 minutes, 15 minutes, 60 minutes. Deliveries are idempotent per event and channel, but a retry can still arrive after your first response was lost — deduplicate on `delivery_id`. A channel that has been failing for 24 hours is disabled automatically and the organization's admins get an email.

## Noise control

- The same event for the same entity is sent once per 60 minutes; repeats are recorded without a delivery.
- Each channel takes a limited number of immediate deliveries an hour, **20 by default** and editable per channel between 1 and 1,000 under `Alerts → Channels`; anything over the cap rolls into that channel's digest instead of being dropped.
- A route can be hourly or daily instead of immediate: one summary per channel per window, with counts by event and the top entities.
- Mute silences a project until a time you pick. Critical events still deliver.

## Slack and email channels

A Slack channel takes an incoming webhook URL and receives Block Kit, not this JSON: a header, a section with the entity, verdict, confidence and project as fields, a context line, and Allow / Block buttons linking into the app. An email channel goes to named addresses or to every member of the organization, sent through Postmark from `alerts@camada.app`, subject `[camada] <severity> <event>`. Both carry the same facts as the JSON above.

Webhook channels are on Growth and above, Slack from Starter, email on every plan — see [pricing](https://www.camada.app/pricing). The Channels tab has a "Send test" button that pushes the `test` event through the real path and shows you the response code.

---

Source: https://www.camada.app/docs/quickstart/aspnet

Quickstart

# ASP.NET Core quickstart

Installed from GitHub ([camada-app/camada-dotnet](https://github.com/camada-app/camada-dotnet)).

## 1. Install

Not on NuGet yet. From the folder that holds your .csproj: clone it next to the project, then reference it.

```sh
git clone https://github.com/camada-app/camada-dotnet ../camada-dotnet
dotnet add reference ../camada-dotnet/src/Camada/Camada.csproj
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that runs dotnet run, add them to "environmentVariables" in Properties/launchSettings.json, or set them in your host's settings. camada reads only the environment, and ASP.NET does not pass appsettings.json, user-secrets or a .env file to it.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```csharp
// Program.cs
using Camada.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddCamada();      // one engine from the environment, drained on shutdown

var app = builder.Build();
app.UseCamada();                   // FIRST: camada answers before routing, static files, anything
// your routes go here, the beacon one below included: app.Run() blocks, so nothing after it is mapped
app.Run();
```

- Put UseCamada() before UseForwardedHeaders(), if you use it, so camada judges the raw header itself.
- .NET 8; nothing beyond the ASP.NET Core shared framework.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```csharp
// Program.cs, above app.Run(): the tag goes in the <head> of the pages you render
app.MapGet("/", (HttpContext ctx) => Results.Content($"<html><head>{ctx.CamadaScriptTag()}</head><body>…</body></html>", "text/html"));
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```csharp
// in a handler that takes HttpContext ctx, once your own sign-in check fails (email: the account it was for)
ctx.CamadaTrack("login_failed", user: email);
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a background PeriodicTimer task at the cadence your tenant config sets (ETag/304, gzip on the wire). A cold start fails open.
2. Resolves the client IP from Connection.RemoteIpAddress per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie from Response.OnStarting, puts the context in HttpContext.Items["camada"], and when the response is done ships one batched, redacted event carrying the matched route pattern.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- The header order is what IHeaderDictionary reports, not the wire's under Kestrel; the analyst knows and never scores its absence.
- The request that builds the engine is answered cold. Resolve CamadaEngine from app.Services at startup and wait for the boot poll (the README shows the bounded loop).
- Keep UseCamada() before UseForwardedHeaders() so camada judges the raw header itself.
- Pending events drain on ApplicationStopping and ProcessExit. CAMADA_SERVERLESS=1 switches to a per-request staleness check with no timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [.NET page](https://www.camada.app/docs/dotnet).

---

Source: https://www.camada.app/docs/quickstart/django

Quickstart

# Django quickstart

Package `camada`, on PyPI.

## 1. Install

```sh
pip install camada
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Python reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```python
# settings.py
MIDDLEWARE = ["camada.django.CamadaMiddleware", *MIDDLEWARE]
```

- Put it first, so blocked requests never reach the rest of the stack.
- Sync and async stacks alike; the matched route pattern rides the event.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```python
from camada.django import script_tag
return f"<head>{script_tag(request)}</head>…"
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```python
from camada.django import track
track(request, "login_failed", user=email)
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a daemon thread (30 s poll with ETag, gzip on the wire). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and when the response is done ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- WSGI loses the wire's header order; the analyst knows this tap cannot see it and never scores its absence.
- Every worker process polls its own snapshot (about 5 MB each) — the server's poll_seconds keeps the cadence honest. Under gunicorn --preload the threads restart after the fork.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no poll thread.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Python page](https://www.camada.app/docs/python).

---

Source: https://www.camada.app/docs/quickstart/express

Quickstart

# Express quickstart

Package `@camada/node`, on npm.

## 1. Install

```sh
npm i @camada/node
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or keep them in .env and start it with node --env-file=.env (Node 20.6+). Node reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```js
import camada from '@camada/node';
app.use(camada.express());
```

- Works for Connect-style stacks too.
- Register it before your routes so blocked requests never reach them.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper, or `<CamadaBeacon/>` from @camada/react.

```js
import camada from '@camada/node';
res.send(`<head>${camada.scriptTag(req)}</head>…`);
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```js
import camada from '@camada/node';
camada.track(req, 'login_failed', { user: email });
```

Runtime

## What it does per request

1. Refreshes the blocklist snapshot off-path (30 s poll with ETag). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. A blocked IP or path gets a 403 with x-block-reason before your app runs. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts to ingest with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and on response finish ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP and path entries. ASN and TLS-fingerprint entries fail open in-app.
- Memory: about 5 MB per loaded snapshot.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no interval timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs).

---

Source: https://www.camada.app/docs/quickstart/fastapi

Quickstart

# FastAPI quickstart

Package `camada`, on PyPI.

## 1. Install

```sh
pip install camada
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Python reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```python
from camada.fastapi import CamadaMiddleware
app.add_middleware(CamadaMiddleware)   # any Starlette app too
```

- A pure ASGI middleware: streaming responses and lifespan are untouched.
- Add it last, so it runs outermost and answers before anything else.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```python
from camada.fastapi import script_tag
return f"<head>{script_tag(request)}</head>…"
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```python
from camada.fastapi import track
track(request, "login_failed", user=email)
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a daemon thread (30 s poll with ETag, gzip on the wire). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and when the response is done ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- ASGI keeps the wire's header order, so the event carries it.
- Every worker process polls its own snapshot (about 5 MB each) — the server's poll_seconds keeps the cadence honest. Under gunicorn --preload the threads restart after the fork.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no poll thread.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Python page](https://www.camada.app/docs/python).

---

Source: https://www.camada.app/docs/quickstart/fastify

Quickstart

# Fastify quickstart

Package `@camada/node`, on npm.

## 1. Install

```sh
npm i @camada/node
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or keep them in .env and start it with node --env-file=.env (Node 20.6+). Node reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```js
import { camadaFastify } from '@camada/node/fastify';
await app.register(camadaFastify);
```

- Register the plugin at the root instance so every route is covered.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper, or `<CamadaBeacon/>` from @camada/react.

```js
import camada from '@camada/node';
reply.type('text/html').send(`<head>${camada.scriptTag(request.raw)}</head>…`);
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```js
import camada from '@camada/node';
camada.track(request.raw, 'login_failed', { user: email });
```

Runtime

## What it does per request

1. Refreshes the blocklist snapshot off-path (30 s poll with ETag). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. A blocked IP or path gets a 403 with x-block-reason before your app runs. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts to ingest with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and on response finish ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP and path entries. ASN and TLS-fingerprint entries fail open in-app.
- Memory: about 5 MB per loaded snapshot.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no interval timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs).

---

Source: https://www.camada.app/docs/quickstart/flask

Quickstart

# Flask quickstart

Package `camada`, on PyPI.

## 1. Install

```sh
pip install camada
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Python reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```python
from camada.flask import init_app
init_app(app)   # wraps app.wsgi_app, so camada answers before routing
```

- Wraps the WSGI app rather than registering a before_request hook: the beacon and challenge endpoints answer before routing.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```python
from camada.flask import script_tag
return f"<head>{script_tag()}</head>…"
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```python
from camada.flask import track
track("login_failed", user=email)
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a daemon thread (30 s poll with ETag, gzip on the wire). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and when the response is done ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- WSGI loses the wire's header order; the analyst knows this tap cannot see it and never scores its absence.
- Every worker process polls its own snapshot (about 5 MB each) — the server's poll_seconds keeps the cadence honest. Under gunicorn --preload the threads restart after the fork.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no poll thread.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Python page](https://www.camada.app/docs/python).

---

Source: https://www.camada.app/docs/quickstart/go

Quickstart

# Go quickstart

Module `github.com/camada-app/camada-go`, on the Go module proxy.

## 1. Install

```sh
go get github.com/camada-app/camada-go
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Go reads no .env file.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```go
import "github.com/camada-app/camada-go"

mux := http.NewServeMux()
mux.HandleFunc("GET /{$}", home)
http.ListenAndServe(":8080", camada.Handler(mux))   // outermost, so camada answers before routing
```

- net/http: any router built on http.Handler sits behind it.
- The first request builds the engine and is answered cold; camada.Default().Stop(ctx) before main returns drains the last batch.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```go
fmt.Fprintf(w, "<html><head>%s</head>…", camada.ScriptTag(r))
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```go
camada.Track(r, "login_failed", email)   // "" when there is no identifier
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a goroutine at the cadence your tenant config sets (ETag/304, gzip on the wire). A cold start fails open.
2. Resolves the client IP from r.RemoteAddr per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets X-Rid and the _sfp session cookie, and when the response is done ships one batched, redacted event carrying the route pattern (r.Pattern).

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- net/http parses headers into a map, so the event carries the sorted header names, not the wire order; the analyst knows and never scores its absence.
- The request that builds the engine is answered cold. To enforce from request 1, build it eagerly with camada.Default() at startup and wait for the boot poll (the README shows the bounded loop).
- camada.Default().Stop(ctx) before main returns drains the last batch within half a second; no signal handlers are installed.
- CAMADA_SERVERLESS=1 drops the poll goroutine: each request checks staleness, and a stale one kicks one refresh off the request path.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Go page](https://www.camada.app/docs/go).

---

Source: https://www.camada.app/docs/quickstart/koa

Quickstart

# Koa quickstart

Package `@camada/node`, on npm.

## 1. Install

```sh
npm i @camada/node
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or keep them in .env and start it with node --env-file=.env (Node 20.6+). Node reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```js
import { camadaKoa } from '@camada/node/koa';
app.use(camadaKoa());
```

- Mount it first in the middleware chain.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper, or `<CamadaBeacon/>` from @camada/react.

```js
import camada from '@camada/node';
ctx.type = 'html';
ctx.body = `<head>${camada.scriptTag(ctx.req)}</head>…`;
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```js
import camada from '@camada/node';
camada.track(ctx.req, 'login_failed', { user: email });
```

Runtime

## What it does per request

1. Refreshes the blocklist snapshot off-path (30 s poll with ETag). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. A blocked IP or path gets a 403 with x-block-reason before your app runs. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts to ingest with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and on response finish ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP and path entries. ASN and TLS-fingerprint entries fail open in-app.
- Memory: about 5 MB per loaded snapshot.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no interval timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs).

---

Source: https://www.camada.app/docs/quickstart/laravel

Quickstart

# Laravel quickstart

Installed from GitHub ([camada-app/camada-php](https://github.com/camada-app/camada-php)).

## 1. Install

Not on Packagist yet. Run these in your project's folder: Composer installs it straight from GitHub, composer.lock pins the commit, and composer update camada/camada moves it.

```sh
composer config repositories.camada vcs https://github.com/camada-app/camada-php
composer require camada/camada:dev-main
```

## 2. Environment

The key is printed once when you create a project in the app. Laravel loads .env into the environment, except once php artisan config:cache has run: there, set them as real environment variables.

.env

```dotenv
CAMADA_KEY=<ingest_token>.<snap_token>
CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```php
// bootstrap/app.php (Laravel 11+), inside the existing ->withMiddleware(function (Middleware $middleware) { … })
$middleware->prepend(\Camada\Laravel\Middleware::class);   // first in the global stack

// or app/Http/Kernel.php (Laravel 10): the first entry of protected $middleware = [ … ]
\Camada\Laravel\Middleware::class,
```

- Prepend it so blocked requests never reach the rest of the stack.
- terminate() is the post-response phase: the spool ships and the snapshot refreshes after the kernel has sent the response.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```php
// routes/web.php
use Camada\Camada;
use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    $ctx = $request->attributes->get('camada');   // the middleware put it there
    return '<html><head>' . Camada::default()->scriptTag($ctx) . '</head><body>…</body></html>';
});
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```php
// in a route or controller, once your own sign-in check fails ($email: the account it was for)
\Camada\Camada::default()->track($request->attributes->get('camada'), 'login_failed', $email);
```

Runtime

## What it does per request

1. Keeps the snapshot in a file-backed cache every worker shares (CAMADA_CACHE_DIR) and refreshes it in the post-response phase, after the client has its bytes. An empty cache answers the first request open.
2. Resolves the client IP from REMOTE_ADDR per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it; behind nginx real_ip the peer is already the client, so say none.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party, from opcache) and relays /_cam/fp posts onto the event spool with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and after the response has ended appends one redacted event to the spool; a due spool ships in that same post-response phase.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- Header order is whatever getallheaders() yields, so the analyst reads no HEADER_ORDER signal from this tap and never scores its absence.
- Under FPM and FrankenPHP the post-response work runs after fastcgi_finish_request(); under php -S and mod_php the buffer is flushed with a Content-Length first. Run the CLI server with PHP_CLI_SERVER_WORKERS=4 or more.
- The cache dir must be a local, writable directory (flock and rename are the concurrency model). Each host keeps its own copy and ships its own spool.
- Events ship when the spool is due, on the next request that finds it due: a quiet site ships its last events on its next hit, not on a timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [PHP page](https://www.camada.app/docs/php).

---

Source: https://www.camada.app/docs/quickstart/nest

Quickstart

# NestJS quickstart

Package `@camada/node`, on npm.

## 1. Install

```sh
npm i @camada/node
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or keep them in .env and start it with node --env-file=.env (Node 20.6+). Node reads no .env file on its own.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```ts
import { CamadaModule } from '@camada/node/nest';

@Module({ imports: [CamadaModule.forRoot()] })   // Nest ≤10: CamadaModule.forRoot({ routes: '*' })
export class AppModule {}
```

- Default Express platform. On the Fastify platform register the Fastify plugin instead.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper, or `<CamadaBeacon/>` from @camada/react.

```ts
import camada from '@camada/node';
res.send(`<head>${camada.scriptTag(req)}</head>…`);
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```ts
import camada from '@camada/node';
camada.track(req, 'login_failed', { user: email });
```

Runtime

## What it does per request

1. Refreshes the blocklist snapshot off-path (30 s poll with ETag). A cold start fails open.
2. Resolves the client IP per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it.
3. A blocked IP or path gets a 403 with x-block-reason before your app runs. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts to ingest with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and on response finish ships one batched, redacted event.

Limits

## Caveats at this position

- Enforcement at this position covers IP and path entries. ASN and TLS-fingerprint entries fail open in-app.
- Memory: about 5 MB per loaded snapshot.
- CAMADA_SERVERLESS=1 switches to lazy refresh with no interval timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs).

---

Source: https://www.camada.app/docs/quickstart/nextjs

Quickstart

# Next.js quickstart

Package `@camada/next`, on npm.

## 1. Install

```sh
npm i @camada/next
```

## 2. Environment

The key is printed once when you create a project in the app.

.env

```dotenv
CAMADA_KEY=<ingest_token>.<snap_token>
CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```ts
// middleware.ts (Next ≤15) or proxy.ts (Next 16) at the project root
import { camada } from '@camada/next';
export default camada();
export const config = { matcher: ['/((?!_next/|favicon.ico).*)'] };

// app/api/camada/[...camada]/route.ts
import { camadaRoute } from '@camada/next';
export const { GET, POST } = camadaRoute();

// app/layout.tsx, inside <head>
import { CamadaBeacon } from '@camada/next';
<CamadaBeacon />
```

- App router. Three files, one env var.
- On Vercel the middleware sees x-vercel-ja4-digest, a real TLS fingerprint, and Vercel's X-Forwarded-For is trusted by default.
- Events ship before the response, so status is unknown at this position. Blocked requests ship with 403.
- Keep the matcher as broad as the example. Every route it excludes is invisible to camada.

## 4. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```ts
import { track } from '@camada/next';
// server action, route handler or server component
await track('login_failed', { user: email });
```

Runtime

## What it does per request

1. Refreshes the blocklist snapshot off-path in event.waitUntil.
2. Enforces it inline: a matching IP or path gets a 403 with x-block-reason and x-block-version. Blocked requests always ship as events.
3. Stamps x-camada-rid on the forwarded request and x-rid on the response.
4. Ships the wire event before the response, so status is unknown (except 403 on blocks). On Vercel the JA4 digest rides along.
5. The route handler serves /api/camada/b.js first-party and relays /api/camada/fp beacon posts to ingest with the trusted-proxy-resolved IP.

Limits

## Caveats at this position

- Client IP needs a trusted-proxy setting. Middleware has no socket peer, so without one the IP is null and IP rules do not enforce. On Vercel the default is the Vercel preset.
- Header order is alphabetical at this position; the scorer knows and does not apply order rules here.
- Serverless cold start fails open: the first request on a cold instance passes, then enforcement begins.
- track() works from request scope only and must not be called from middleware.
- Every route your matcher excludes is invisible to camada: no blocking, no events. Keep it as broad as the example.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs).

---

Source: https://www.camada.app/docs/quickstart/php

Quickstart

# PHP quickstart

Installed from GitHub ([camada-app/camada-php](https://github.com/camada-app/camada-php)).

## 1. Install

Not on Packagist yet. Run these in your project's folder: Composer installs it straight from GitHub, composer.lock pins the commit, and composer update camada/camada moves it.

```sh
composer config repositories.camada vcs https://github.com/camada-app/camada-php
composer require camada/camada:dev-main
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that runs php -S; under PHP-FPM, which clears the environment, add env[CAMADA_KEY] = … to the pool config. PHP reads no .env file.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```php
<?php
// public/index.php — any front controller
require __DIR__ . '/../vendor/autoload.php';

use Camada\Camada;
use Camada\Http\Sapi;

$cam = Camada::default();      // built lazily from the environment, once per request
$ctx = Sapi::run($cam);        // null: camada answered (block, challenge, beacon) and the script must stop
if ($ctx === null) {
    return;
}
// your app: x-rid and the _sfp cookie are already on the response
```

- Needs nothing but $_SERVER, php://input and header(): FPM, php -S, mod_php.
- The snapshot and event spool live in a file-backed cache every worker shares; both refresh after the response has left.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```php
echo '<html><head>', $cam->scriptTag($ctx), '</head>…';
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```php
$cam->track($ctx, 'login_failed', $email);
```

Runtime

## What it does per request

1. Keeps the snapshot in a file-backed cache every worker shares (CAMADA_CACHE_DIR) and refreshes it in the post-response phase, after the client has its bytes. An empty cache answers the first request open.
2. Resolves the client IP from REMOTE_ADDR per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it; behind nginx real_ip the peer is already the client, so say none.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party, from opcache) and relays /_cam/fp posts onto the event spool with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and after the response has ended appends one redacted event to the spool; a due spool ships in that same post-response phase.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- Header order is whatever getallheaders() yields, so the analyst reads no HEADER_ORDER signal from this tap and never scores its absence.
- Under FPM and FrankenPHP the post-response work runs after fastcgi_finish_request(); under php -S and mod_php the buffer is flushed with a Content-Length first. Run the CLI server with PHP_CLI_SERVER_WORKERS=4 or more.
- The cache dir must be a local, writable directory (flock and rename are the concurrency model). Each host keeps its own copy and ships its own spool.
- Events ship when the spool is due, on the next request that finds it due: a quiet site ships its last events on its next hit, not on a timer.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [PHP page](https://www.camada.app/docs/php).

---

Source: https://www.camada.app/docs/quickstart/rails

Quickstart

# Rails quickstart

Package `camada`, on RubyGems.

## 1. Install

```sh
bundle add camada
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. Rack and Rails read no .env file (Rails needs the dotenv-rails gem for that).

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```ruby
# config.ru — Sinatra, Hanami, or any Rack app
require "camada"
use Camada::Rack      # first, so camada answers before routing
run App

# Rails — nothing to add: the Railtie inserts Camada::Rack at the top of the middleware stack
```

- One gem, one Rack middleware; the Railtie mounts it for Rails.
- Never request.ip: the middleware reads REMOTE_ADDR and applies your trusted-proxy rules itself.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```ruby
"<html><head>#{Camada.script_tag(env)}</head>…"   # Sinatra: env; Rails: request.env
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```ruby
Camada.track(env, "login_failed", user: email)   # Sinatra: env; Rails: request.env
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a thread at the cadence your tenant config sets (ETag/304, gzip on the wire). A cold start fails open.
2. Resolves the client IP from REMOTE_ADDR per your trusted-proxy setting — never request.ip, which trusts X-Forwarded-For from anyone.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie, and when the server closes the body ships one batched, redacted event carrying the matched route pattern (sinatra.route, Rails route_uri_pattern).

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- The Rack env carries no wire header order, so the analyst reads no HEADER_ORDER signal from this tap and never scores its absence.
- The request that builds the engine is answered cold. Warm it in an initializer by waiting for the boot poll (the README shows the bounded loop).
- Threads do not survive a fork: the SDK compares Process.pid on every call and starts over in a forked worker. Puma cluster mode, Unicorn and Passenger need nothing added.
- CAMADA_SERVERLESS=1 switches to a per-request staleness check with no poll thread.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Ruby page](https://www.camada.app/docs/ruby).

---

Source: https://www.camada.app/docs/quickstart/spring

Quickstart

# Spring Boot quickstart

Installed from GitHub ([camada-app/camada-java](https://github.com/camada-app/camada-java)).

## 1. Install

Not on Maven Central yet. From your project's folder: clone it next to the project, build it into your local Maven repository, then add the dependency.

```sh
git clone https://github.com/camada-app/camada-java ../camada-java
mvn -q -f ../camada-java install -DskipTests

<!-- then, in pom.xml -->
<dependency>
  <groupId>dev.camada</groupId>
  <artifactId>camada</artifactId>
  <version>0.2.0</version>
</dependency>
```

## 2. Environment

The key is printed once when you create a project in the app. Set these as environment variables: export them in the shell that starts your app, or add them in your host's settings. camada reads only the environment, and Spring Boot does not pass application.properties or a .env file to it.

shell

```sh
export CAMADA_KEY=<ingest_token>.<snap_token>
export CAMADA_INGEST_URL=http://localhost:8787   # dev only; defaults to production ingest
```

## 3. Wire it in

```java
// CamadaConfig.java, beside your @SpringBootApplication class
package com.example.demo;   // your application's package

import dev.camada.servlet.CamadaFilter;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;

@Configuration
class CamadaConfig {
  @Bean
  FilterRegistrationBean<CamadaFilter> camadaFilter() {
    var reg = new FilterRegistrationBean<>(new CamadaFilter());
    reg.setOrder(Ordered.HIGHEST_PRECEDENCE);   // first, so camada answers before routing
    return reg;
  }
}
```

- A plain jakarta.servlet.Filter: Tomcat, Jetty and Undertow take it as is, from web.xml or addFilter at the front of the chain.
- Keep server.forward-headers-strategy=none (the default) so camada judges X-Forwarded-For itself.

## 4. Add the beacon to HTML pages

Optional but recommended. The beacon cuts false positives by showing which sessions are real browsers. Use the helper.

```java
// PageController.java, beside CamadaConfig.java: the tag goes in the <head> of the pages you render
package com.example.demo;   // your application's package

import dev.camada.Camada;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
class PageController {
  @GetMapping(value = "/", produces = "text/html")
  String home(HttpServletRequest request) {
    return "<html><head>" + Camada.scriptTag(request) + "</head><body>…</body></html>";
  }
}
```

## 5. Send app outcomes

Login failures, signups and checkout declines are the signals no edge position sees. The identifier is HMAC-hashed in your process. How they catch [credential stuffing](https://www.camada.app/use-cases/credential-stuffing).

```java
// in a PageController handler, once your own sign-in check fails (email: the account it was for)
Camada.track(request, "login_failed", email);
```

Runtime

## What it does per request

1. Refreshes the snapshot off-path on a daemon thread at the cadence your tenant config sets (ETag/304, gzip on the wire). A cold start fails open.
2. Resolves the client IP from getRemoteAddr() per your trusted-proxy setting. Raw X-Forwarded-For is never trusted without it; keep server.forward-headers-strategy=none.
3. Your ordered custom rules first, then allow, block, challenge. A block gets a 403 with x-block-reason before your app runs; a challenge serves the proof-of-work page on a page load, and an API call reaches your app with an x-camada-challenge: 1 response header. The event still ships.
4. Serves /_cam/b.js (the beacon, first-party) and relays /_cam/fp posts onto the event batch with the resolved client IP.
5. Sets x-rid and the _sfp session cookie before the chain runs, and when the response is done (or in AsyncListener.onComplete) ships one batched, redacted event carrying the Spring MVC route pattern.

Limits

## Caveats at this position

- Enforcement at this position covers IP, path, user-agent and request-header conditions. ASN, country and TLS-fingerprint entries fail open in-app.
- The event carries the header order as the container hands it over.
- The request that builds the engine is answered cold. Camada.getDefault().warmUp(5000) at startup waits for the boot poll, bounded, and never throws.
- Both threads are daemons; pending events drain from a JVM shutdown hook, on SIGTERM as well as a normal exit.
- CamadaFilter handles the original REQUEST dispatch only; ASYNC, ERROR, FORWARD and INCLUDE pass through. CAMADA_SERVERLESS=1 hands refreshes to the daemon thread from a per-request staleness check.

Kill switch: `CAMADA_DISABLED=1`, checked per request. All other variables are listed in the [docs index](https://www.camada.app/docs); the package's options and deployment notes are on the [Java page](https://www.camada.app/docs/java).

---

Source: https://www.camada.app/use-cases/ai-agents

Use case

# Keep rogue AI agents and AI-driven attackers out

Attackers use language models to scan your app, write exploits and try stolen passwords faster than any team could. Some AI agents scrape what they should not and abuse signups. Others are your customers' assistants doing a job. camada judges each one by what it does.

[Get started free](https://my.camada.app/) [How camada works →](https://www.camada.app/how-it-works)

The pattern

## What it looks like in your traffic

- Automation in the browser: webdriver set, headless signs, no input events across a session.
- Probes for secrets and admin panels: /.env, /.git, wp-config.php, /phpmyadmin.
- Injection payloads in query strings, many families from one client.
- Signups and logins in bursts from fresh sessions on cloud networks.

Detection

## How camada scores it

| What camada looks for | Score |
| --- | --- |
| webdriver true or automation globals present | `+60` |
| Browser beacon user agent differs from the header user agent | `+40` |
| Secret or config file probe (/.env, /.git, wp-config.php, *.sql) | `+30 per path, up to 60` |
| Web shell or exploit-kit path | `+60` |
| Injection payloads, per distinct family | `+15, up to 45` |
| Beacon with real input events within 10 seconds | `-30` |

The triage model and the investigation agent read the requests behind a score, plus the facts you recorded about your site, before anything is blocked. Each verdict says why.

A sample of the rules, with their default weights. The full pipeline and more rules are on [how it works](https://www.camada.app/how-it-works).

Setup

## Set it up

1. Install the SDK for your framework, and add the beacon to your HTML pages. [Framework quickstarts →](https://www.camada.app/frameworks)
2. Allow-list the agents you trust, and choose what each category does. [Rules and list entries →](https://www.camada.app/docs/rules)
3. Record facts about your site, such as a partner that calls your API from a cloud network, so the agent does not flag it. [Memory →](https://www.camada.app/docs/memory)

Limits

## What camada does not do

- camada does not check cryptographic signatures from AI agents today, so it cannot vouch for an agent you want to let in. Your allow-list does that.
- An agent that behaves like one careful human may not stand out. camada acts on behaviour, not on who sent the agent.
- API clients cannot solve a challenge. On API calls camada can only signal your app with a response header.

Questions

## Common questions

### Does camada block all AI agents?

No. camada keeps bad actors out, not bots. Customers, verified search engines and allow-listed agents get in. A rogue agent is judged by the same evidence as any other attacker: what it requests and how.

### Can attackers using AI look exactly like customers?

Per request, often yes: real browsers, home IPs, valid requests. Across a session they still probe paths customers never visit, fail logins on many accounts or never run JavaScript. camada scores the whole session, the IP and the TLS fingerprint where it is visible.

### Is an AI model deciding to block my traffic?

Models write verdicts, with guardrails. A block needs a malicious verdict at 80% confidence or more by default, each new project starts in a learning window that only recommends, and a person on your team turns enforcement on.

Other attacks camada handles: [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing) · [Scraping](https://www.camada.app/use-cases/scraping) · [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits). Plans and the 14-day trial: [pricing](https://www.camada.app/pricing).

---

Source: https://www.camada.app/use-cases/credential-stuffing

Use case

# Credential stuffing protection that knows which logins failed

Credential stuffers replay leaked email and password pairs against your login. Each request looks like a customer who mistyped. camada sees the pattern because your app tells it which logins failed, for which account, as a hash.

[Get started free](https://my.camada.app/) [How camada works →](https://www.camada.app/how-it-works)

The pattern

## What it looks like in your traffic

- Many login POSTs from one client and almost no page views.
- Failed logins spread across many of your accounts, one or two tries each: a password spray.
- Logins from hosting and cloud networks, where your customers rarely sit.
- The same client build spread over many IPs, each one staying under a per-IP limit.

Detection

## How camada scores it

| What camada looks for | Score |
| --- | --- |
| Failed logins on 10+ of your accounts, at most 2 tries each (password spray, from track()) | `+50` |
| 20+ failed logins across 3+ accounts (from track()) | `+40` |
| 10+ login POSTs, over 80% POSTs, at most one page view | `+35` |
| 10+ POSTs answered 401 or 403 | `+35` |
| A hosting or cloud network on a login, signup or checkout path | `+30` |
| One client build failing logins from 10+ IPs, each under the per-IP bar | `+50, +65 at 20+ IPs` |
| Flagged malicious by 3 or more other paying organizations in the last 7 days | `+40` |

At the default sensitivity, a client at 60 goes to the investigation agent, which reads its requests and writes a verdict with evidence. A block needs a malicious verdict at 80% confidence or more.

A sample of the rules, with their default weights. The full pipeline and more rules are on [how it works](https://www.camada.app/how-it-works).

Setup

## Set it up

1. Install the SDK for your framework. [Framework quickstarts →](https://www.camada.app/frameworks)
2. Call track() with login_failed and login_succeeded where your sign-in code knows the outcome. The account id is HMAC-hashed in your process. [track() in the Express quickstart →](https://www.camada.app/docs/quickstart/express)
3. Turn on challenge for suspect browsers if you would rather ask than block. [How a challenge works →](https://www.camada.app/docs/challenge)

Limits

## What camada does not do

- camada judges clients every few minutes, not on each request. The first tries from a new client reach your login until a run flags it and your app pulls the new blocklist.
- Without track(), camada only sees status codes and paths. Rules that count failed logins per account need it.
- camada does not check passwords against breach lists and does not replace rate limits or MFA on your login.

Questions

## Common questions

### How is credential stuffing different from brute force?

Brute force tries many passwords on one account. Credential stuffing tries leaked email and password pairs, usually one or two per account, across many accounts. Per-account lockouts rarely trip, which is why camada counts failures across accounts and across IPs.

### Does camada see my users' passwords or emails?

No. Request and response bodies never leave your app. track() sends an event name and an HMAC of the identifier you pass, computed in your process.

### Will a customer who forgot their password get blocked?

A few failed logins from one person do not reach the thresholds above. Rules that count a real person's signs, like input events in the browser beacon, lower the score. New projects start in a learning window that only recommends, so you see what would be blocked first.

Other attacks camada handles: [Scraping](https://www.camada.app/use-cases/scraping) · [AI agent abuse](https://www.camada.app/use-cases/ai-agents) · [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits). Plans and the 14-day trial: [pricing](https://www.camada.app/pricing).

---

Source: https://www.camada.app/use-cases/cve-exploits

Use case

# Find the clients probing your app for known CVEs

When a CVE is published, scanners try it on every app they can reach within hours. camada checks your traffic against exploit signatures refreshed every day, and when a new CVE appears it looks back over the last 7 days to tell you who probed for it before anyone had a signature.

[Get started free](https://my.camada.app/) [How camada works →](https://www.camada.app/how-it-works)

The pattern

## What it looks like in your traffic

- Requests for exploit paths of products you may not even run.
- Payloads in the query string or headers that match a published exploit template.
- One client trying several CVEs in a row, then moving on.

Detection

## How camada scores it

| What camada looks for | Score |
| --- | --- |
| A request matched a CVE that CISA lists as actively exploited (KEV) | `+60` |
| A request matched a CVE signature that is not on the KEV list | `+30` |
| Web shell or exploit-kit path (shell.php, /vendor/phpunit, /boaform) | `+60` |
| Secret or config file probe | `+30 per path, up to 60` |

Signatures are compiled every day from CISA Known Exploited Vulnerabilities, CrowdSec virtual-patching rules, the Emerging Threats Open rule set and nuclei templates. A finding names the CVE and, when camada knows your stack, says whether you run the affected product.

A sample of the rules, with their default weights. The full pipeline and more rules are on [how it works](https://www.camada.app/how-it-works).

Setup

## Set it up

1. Install the SDK for your framework. Nothing else to configure: every project gets the signature feed. [Framework quickstarts →](https://www.camada.app/frameworks)
2. Tell camada what you run, so a finding says "you run Confluence" or "not your stack". [Memory →](https://www.camada.app/docs/memory)
3. Send alerts to email, Slack or a signed webhook, depending on your plan. [Webhook payload →](https://www.camada.app/docs/webhooks)

Limits

## What camada does not do

- camada does not patch your code. Patch the CVE; camada finds and blocks the clients probing for it.
- A single exploit request reaches your app. camada blocks the client from the next run, once enforcement is on.
- Signatures match the path, the query and some request headers. Request bodies, cookies and Authorization values never leave your app, so signatures on them cannot match.

Questions

## Common questions

### What does the 7-day look-back do?

Every day camada claims the CVEs its feed listed for the first time. It then re-scans each project's last 7 days of raw events for requests that matched those CVEs before they were listed, and sends one alert per project when it finds any.

### Where do the signatures come from?

CISA Known Exploited Vulnerabilities (for the actively exploited flag), CrowdSec hub virtual-patching rules, the Emerging Threats Open rule set and nuclei templates. They are refreshed once a day.

### Is this a WAF?

No. A WAF inspects each request before your app answers. camada scores clients over a window, then your app blocks the ones judged malicious. You can keep a WAF or CDN in front of your app and run camada inside it.

Other attacks camada handles: [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing) · [Scraping](https://www.camada.app/use-cases/scraping) · [AI agent abuse](https://www.camada.app/use-cases/ai-agents). Plans and the 14-day trial: [pricing](https://www.camada.app/pricing).

---

Source: https://www.camada.app/use-cases/scraping

Use case

# Scraping protection that keeps search engines in

Scrapers copy your prices, listings and content, and run up your compute bill. Search engines and partners you trust crawl you too. camada tells them apart by behaviour and by published crawler IP ranges, not by user agent alone.

[Get started free](https://my.camada.app/) [How camada works →](https://www.camada.app/how-it-works)

The pattern

## What it looks like in your traffic

- Hundreds of pages an hour from one client, with no JavaScript running in the browser.
- A new session on every request because the client drops cookies.
- A Chrome user agent without the client hints real Chrome sends.
- A user agent that claims to be Googlebot from outside Google's published IP ranges.

Detection

## How camada scores it

| What camada looks for | Score |
| --- | --- |
| 150+ pages an hour; 400+ pages an hour | `+25; +50` |
| 3+ HTML pages served and the beacon never ran (no JavaScript) | `+25` |
| Claims Googlebot, bingbot or Applebot from outside their published IP ranges | `+60` |
| Chrome or Edge user agent without Sec-CH-UA client hints | `+25` |
| Known AI crawler (GPTBot, CCBot and others); agents known to ignore robots.txt | `+20; +35` |
| The real Googlebot, bingbot or Applebot, from inside the published ranges | `-40` |

A crawler you invited goes on your allow-list and stays off the blocklist. The AI-crawler rule names the bot in its reason, so you can allow one you want.

A sample of the rules, with their default weights. The full pipeline and more rules are on [how it works](https://www.camada.app/how-it-works).

Setup

## Set it up

1. Install the SDK for your framework. [Framework quickstarts →](https://www.camada.app/frameworks)
2. Add the beacon to your HTML pages. It is first-party, served from your own origin, and it is what shows a real browser ran. [Beacon setup in the Express quickstart →](https://www.camada.app/docs/quickstart/express)
3. Allow-list the partners and crawlers you want by IP or CIDR range. [Rules and list entries →](https://www.camada.app/docs/rules)

Limits

## What camada does not do

- A slow scraper that behaves like one reader can stay under every threshold. camada catches volume and automation, not intent.
- Blocks apply from the analyst's next run, so a scraper's first pages are served.
- camada does not watermark content or charge crawlers per request.

Questions

## Common questions

### Will camada hurt my SEO?

Verified Googlebot, bingbot and Applebot are checked against the IP ranges those companies publish, and the real ones score lower, not higher. Fakes using their names are caught. The guardrails also say never to block on a user agent alone.

### Can I let some AI crawlers in and keep others out?

Yes. Each AI-crawler finding names the bot. Allow-list the address ranges of the ones you want, or turn the AI-crawler rule off for your project. You also choose what each verdict category does: block, challenge, alert or ignore.

### What about scrapers using residential proxies?

Rotating IPs does not hide a session that drops cookies, runs no JavaScript or shares one client build across many addresses. camada groups those requests by session and by client shape, not only by IP.

Other attacks camada handles: [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing) · [AI agent abuse](https://www.camada.app/use-cases/ai-agents) · [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits). Plans and the 14-day trial: [pricing](https://www.camada.app/pricing).

---

Source: https://www.camada.app/compare/arcjet

Compare

# camada vs Arcjet

Both run as an SDK inside your app, with no proxy and no DNS change, and both fail open by default. They differ in when and how they decide. Arcjet evaluates rules you configure on each request. camada reviews whole sessions every few minutes with an AI analyst, and your app enforces the blocklist it writes.

Arcjet facts come from its own docs and pricing pages, linked beside each row and listed at the end, as checked on 2026-10-26. Spot an error? Write to [us](https://www.camada.app/contact) and we will fix it.

Side by side

## How camada and Arcjet differ

| Topic | camada | Arcjet |
| --- | --- | --- |
| Where it runs | An SDK in your app. Each request is checked against a blocklist held in memory; nothing calls camada on the request path. | An SDK in your app with a WebAssembly module that analyzes requests locally. When a rule needs it, the SDK makes one call to the Arcjet Cloud API per request. [[1]](https://docs.arcjet.com/architecture) |
| When it decides | Every 10 minutes by default (5 at the fastest), over sessions, IPs and TLS fingerprints. A new client's first requests reach your app until a run flags it. | On each request, as it arrives. Arcjet states under 1 ms of local overhead, and typically 20 to 30 ms when the Cloud API is called. [[1]](https://docs.arcjet.com/architecture) |
| Who writes the rules | camada scores every client against its own rules, and an AI triage model and investigation agent write a verdict with evidence. You can turn rules off and choose what each category does. | You configure rules in code: bot protection, rate limiting, Shield WAF, email validation, signup form protection, sensitive information, filters and prompt injection detection. [[2]](https://docs.arcjet.com/get-started) |
| Languages | Node, Next.js, Hono, SvelteKit, Nuxt, React Router, Bun, Deno, Python, Go, Ruby, PHP, Java and .NET. | JavaScript and TypeScript, Python and Go, with framework guides for Next.js, Node.js, Express, NestJS, SvelteKit, Nuxt, Remix, Bun, Deno, FastAPI and Flask among others. [[2]](https://docs.arcjet.com/get-started) |
| Good bots | Googlebot, bingbot and Applebot are checked against their published IP ranges. Fakes using those names score +60. | Bots are identified from the user agent, and authenticity is verified using IP data and reverse DNS lookups. [[3]](https://docs.arcjet.com/bot-protection) |
| Rate limiting | No per-request rate limiter. Page and request rates are scored over the analysis window. | Rate limiting rules, tracked across requests by the Cloud API. [[1]](https://docs.arcjet.com/architecture) |
| If the service is down | Fails open: an outage or a bug in camada never returns a 5xx from your app. | Fails open by default, with an option to fail closed. Default API timeout 2000 ms. [[1]](https://docs.arcjet.com/architecture) |
| Price | Free (100k events a month, no enforcement), Starter $59/mo (1M events), Growth $249/mo (10M events), Enterprise priced with you. | Free plan limited to 10,000 requests a month after a 15-day trial; Individual $25/mo; Startup $299/mo; web requests $5 per 1M. [[4]](https://arcjet.com/pricing) |

Choosing

## Which one fits

### Arcjet fits better when

- You want each request decided on the spot, with rules you write in code.
- You need rate limiting, email validation or signup form checks in the same SDK.
- You are protecting an AI app and want prompt injection detection.

### camada fits better when

- You want attackers found for you, with a written verdict for each, instead of writing and tuning rules.
- Your backend is Ruby, PHP, Java or .NET.
- You want failed logins per account (hashed) and CVE exploit probes to count as evidence.

### Running both

They do different jobs and can run side by side in one app: Arcjet for per-request rules such as rate limits, camada for judging clients across sessions and keeping the ones it finds out.

[Get started free](https://my.camada.app/) [Framework quickstarts →](https://www.camada.app/frameworks) [Pricing →](https://www.camada.app/pricing)

Sources

## Sources

1. [Arcjet docs: Architecture](https://docs.arcjet.com/architecture), checked 2026-10-26
2. [Arcjet docs: Get started](https://docs.arcjet.com/get-started), checked 2026-10-26
3. [Arcjet docs: Bot protection](https://docs.arcjet.com/bot-protection), checked 2026-10-26
4. [Arcjet pricing](https://arcjet.com/pricing), checked 2026-10-26

More comparisons: [camada vs Cloudflare Bot Management](https://www.camada.app/compare/cloudflare-bot-management). What camada catches: [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing) · [Scraping](https://www.camada.app/use-cases/scraping) · [AI agent abuse](https://www.camada.app/use-cases/ai-agents) · [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits).

---

Source: https://www.camada.app/compare/cloudflare-bot-management

Compare

# camada vs Cloudflare Bot Management

Cloudflare scores each request at its network, in front of your app, once your traffic is proxied through it. camada runs inside your app, where it also sees what your login and checkout code knows. Many teams can run both: camada keeps your CDN in front of your app as it is.

Cloudflare Bot Management facts come from its own docs and pricing pages, linked beside each row and listed at the end, as checked on 2026-10-26. Spot an error? Write to [us](https://www.camada.app/contact) and we will fix it.

Side by side

## How camada and Cloudflare Bot Management differ

| Topic | camada | Cloudflare Bot Management |
| --- | --- | --- |
| Setup | A package and a middleware in your app, plus one env var. No DNS change. | Traffic must reach your origin through Cloudflare's proxy, set per DNS record. [[1]](https://developers.cloudflare.com/dns/proxy-status/) |
| When it decides | Every few minutes, over sessions, IPs and TLS fingerprints. Each request only checks a blocklist your app already holds. | On each request, with a bot score from 1 to 99 built from heuristics, machine learning and JavaScript detections. [[2]](https://developers.cloudflare.com/bots/concepts/bot-score/) |
| Availability | Every plan runs the AI analyst. Enforcement on Starter and above. | Bot Management for Enterprise is a paid add-on. Business and Enterprise customers without it get Super Bot Fight Mode; Free plans get Bot Fight Mode. [[8]](https://developers.cloudflare.com/bots/plans/biz-and-ent/) |
| TLS fingerprints | Used where the position sees them: @camada/hono on Cloudflare Workers, and the JA4 digest on Vercel. | JA3 and JA4 fingerprints, for Enterprise customers who have purchased Bot Management. [[4]](https://developers.cloudflare.com/bots/additional-configurations/ja3-ja4-fingerprint/) |
| Good bots and agents | Googlebot, bingbot and Applebot checked against published IP ranges; your allow-list for the rest. camada does not check agent signatures today. | A verified bots list, verified by IP validation or Web Bot Auth signatures; signed agents are now part of it. [[5]](https://developers.cloudflare.com/bots/concepts/bot/verified-bots/) |
| AI crawlers | An AI-crawler rule names the bot in its reason, so you can allow the ones you invited. | AI Crawl Control monitors and controls how AI services access your content, on all plans. [[6]](https://developers.cloudflare.com/ai-crawl-control/) |
| App outcomes | track() reports failed logins, signups and declined payments from your code, tied to a hashed account id. | Sees requests and responses as they pass through its network. [[1]](https://developers.cloudflare.com/dns/proxy-status/) |
| Challenges | Your own SDK serves a proof-of-work page to suspect browsers. API calls get a response header your app can act on. | Turnstile, which verifies visitors are human without a CAPTCHA. [[7]](https://developers.cloudflare.com/turnstile/) |
| Price | Published: Free, Starter $59/mo, Growth $249/mo, Enterprise priced with you. | Bot Management is sold as an Enterprise add-on; Cloudflare does not publish its price. [[3]](https://developers.cloudflare.com/bots/get-started/bot-management/) |

Choosing

## Which one fits

### Cloudflare Bot Management fits better when

- You want bad traffic stopped at the edge, before it reaches your origin at all.
- You already run Cloudflare Enterprise and want bot scores and JA3/JA4 in your WAF rules.
- You want signed AI agents verified for you.

### camada fits better when

- You do not want to move DNS or put a proxy in front of your app.
- You want your app's own outcomes, such as failed logins per account, to count as evidence.
- You want a published price, and a written verdict for every client that gets blocked.

### Running both

camada runs inside your app, so Cloudflare can stay in front of it. Cloudflare handles volume at the edge; camada judges the clients that still reach your app and blocks the ones it finds malicious.

[Get started free](https://my.camada.app/) [Framework quickstarts →](https://www.camada.app/frameworks) [Pricing →](https://www.camada.app/pricing)

Sources

## Sources

1. [Cloudflare docs: Proxy status](https://developers.cloudflare.com/dns/proxy-status/), checked 2026-10-26
2. [Cloudflare docs: Bot scores](https://developers.cloudflare.com/bots/concepts/bot-score/), checked 2026-10-26
3. [Cloudflare docs: Get started with Bot Management](https://developers.cloudflare.com/bots/get-started/bot-management/), checked 2026-10-26
4. [Cloudflare docs: JA3/JA4 fingerprint](https://developers.cloudflare.com/bots/additional-configurations/ja3-ja4-fingerprint/), checked 2026-10-26
5. [Cloudflare docs: Verified bots](https://developers.cloudflare.com/bots/concepts/bot/verified-bots/), checked 2026-10-26
6. [Cloudflare docs: AI Crawl Control](https://developers.cloudflare.com/ai-crawl-control/), checked 2026-10-26
7. [Cloudflare docs: Turnstile](https://developers.cloudflare.com/turnstile/), checked 2026-10-26
8. [Cloudflare docs: Super Bot Fight Mode plans](https://developers.cloudflare.com/bots/plans/biz-and-ent/), checked 2026-10-26

More comparisons: [camada vs Arcjet](https://www.camada.app/compare/arcjet). What camada catches: [Credential stuffing](https://www.camada.app/use-cases/credential-stuffing) · [Scraping](https://www.camada.app/use-cases/scraping) · [AI agent abuse](https://www.camada.app/use-cases/ai-agents) · [CVE exploit scans](https://www.camada.app/use-cases/cve-exploits).

---

Source: https://www.camada.app/contact

Contact

# Contact camada

**General and sales**

Plans, the Enterprise tier, partnerships.

[hello@camada.app](mailto:hello@camada.app)

**Security**

Vulnerability reports.

[security@camada.app](mailto:security@camada.app)

**Privacy**

Data requests, DPA questions, sub-processor objections.

[privacy@camada.app](mailto:privacy@camada.app)

Is something down? Check the [status page](https://www.camada.app/status) first; incidents are posted there before we answer email.

---

Source: https://www.camada.app/status

Status

# Service status

- Marketing site

  www.camada.app

  Checking…

  24 h —

  p95 —
- App and API

  my.camada.app

  Checking…

  24 h —

  p95 —
- Ingest and snapshots

  in.camada.app

  Checking…

  24 h —

  p95 —

Checks run every five minutes from the app. **24 h** is the share of those checks that succeeded in the last 24 hours; **p95** is the 95th percentile latency of the same checks. Numbers are read live from the app's public status endpoint, so this page shows nothing cached.

`status.camada.app` points here; both addresses show the same checks. For an incident that is not visible in these numbers, write to [hello@camada.app](mailto:hello@camada.app).