---
type: explanation
title: Instrumentation
summary: How Caputchin checks that a challenge was solved by a real browser, not a script pretending to be one.
---

Proof of work proves that *effort* was spent. It does not prove *what* spent it. A determined attacker with a farm of real browsers can grind through puzzles cheaply. Instrumentation is the second layer that closes that gap: it proves the work happened inside a genuine browser.

## How it works

On every request, Caputchin generates a fresh, one-off JavaScript program and runs it in the visitor's browser. The program exercises machinery that only a real browser has, and reports back what it observed:

- **Browser API probes** that check genuine browser functionality is present and behaves correctly.
- **Computation chains** of bitwise integer operations.
- **DOM arithmetic** that builds trees of elements, reads the values the layout engine computes for them, and tears them back down.

The trick is an asymmetry: a real rendering engine produces the right answers almost for free, while a headless or scripted runtime stubs these operations out, implements them incorrectly, or skips them for speed. The mismatch gives the visitor away.

## Content-Security-Policy

Because the program runs `eval` in the visitor's browser, the page that embeds your widget must allow `'unsafe-eval'` in its `script-src` Content-Security-Policy. There is no fallback for this: if `'unsafe-eval'` is blocked, the program cannot run and verification fails. If your policy cannot allow it, turn instrumentation off for the key on its [Security](/docs/site-keys/security) page, which drops the requirement at the cost of automated-browser detection (proof of work and any required game still run). See [game sandboxing](/docs/understanding-caputchin/game-sandboxing#the-csp-you-set-on-your-own-page) for the complete host-page policy.

## Why it pairs with proof of work

The two layers cover each other's blind spots. Proof of work alone can be mined cheaply by real browsers; instrumentation alone could be faked by a script that never does the work. Together they raise the cost on two independent axes: proof of work proves effort, instrumentation proves environment.

## Obfuscation

Because the program ships to the visitor, a motivated attacker could study it and try to pre-compute the answers. To make that harder, the program is obfuscated. A key's [Security](/docs/site-keys/security) page exposes an **Obfuscation level**: turning it up makes the program harder to reverse-engineer, at the cost of more server-side CPU. The same signals back the **Block automated browsers** option, which rejects detected headless and WebDriver clients outright.

## An honest limit

Instrumentation is not foolproof. Stealth browsers patch the tells it looks for, and the checks themselves note they can be beaten. It is one layer among several, strongest when stacked with [proof of work](/docs/understanding-caputchin/proof-of-work) and the rest of a key's [security](/docs/site-keys/security) settings.