@osqd/bothandlerjs 0.6.0 → 0.7.0

package/docs/detection/detectors.md

@@ -165,6 +165,55 @@ query string.
 probeSignatureDetector({ extraPaths: ["/internal/admin"] })
 ```
 
+### `target-integrity`
+
+**cheap · always · ceiling `strong`**
+
+How was this target *spelled*?
+
+`probe-signature` above reads what a request asked for. This one reads how it asked, and it
+exists because the two are not the same question — and because the answer to the second is
+normally destroyed before any detector sees it.
+
+Every detector reads `facts.path`, which is normalised: decoded once, backslashes and
+doubled slashes collapsed, `.` and `..` resolved. That is not optional — a rule scoped to
+`/admin` has to hold against `/%61dmin` and `/./admin` or it is not a rule. It is also
+exactly what makes an evasive target arrive looking ordinary:
+
+```
+GET /%2e%2e%2f%2e%2e%2fapp/config.yml      →  facts.path = "/app/config.yml"
+```
+
+Which is a page nobody has, on no wordlist, indistinguishable from a broken link. So the
+target as it arrived is kept in `facts.rawPath` — and only when it differs from the
+normalised form, which on ordinary traffic it does not — and this reads it.
+
+| Spelling | Tier |
+| --- | ---: |
+| Encoded its own encoding, so one decoding pass leaves it still encoded | `strong` |
+| Wrote a traversal with its dots and slashes percent-encoded | `strong` |
+| Carried a control character, raw or encoded | `strong` |
+| Addressed the target to a proxy — `GET http://elsewhere/` at an origin server | `strong` |
+| Hid a path separator inside a segment | `moderate` |
+| Walked up out of the site root, written plainly | `moderate` |
+
+**Nothing here is `certain`, and the closest call says why.** A path segment that carries a
+URL as *data* — `/redirect/https%3A%2F%2Fexample.com%2Fa` — is encoded once to sit in a
+path and encoded again by whatever built the link around it. That is a real pattern on real
+sites and it produces `%252e` honestly. A deliberate act with no ordinary cause is not the
+same thing as one admitting no benign explanation, and only the second may close a door.
+
+The plain-traversal row is the one a *broken* client produces as readily as a hostile one,
+so it has a switch:
+
+```ts
+targetIntegrityDetector({ reportPlainTraversal: false })
+```
+
+All of these share the family `evasive-target`. One target usually trips several — a
+traversal is normally encoded and an encoded traversal is often double-encoded — and that
+is one act seen three ways, not three reasons.
+
 ### `tls-fingerprint`
 
 **cheap · always · ceiling `strong`**
@@ -243,6 +292,9 @@ would echo. Reaching one requires reading the page as data rather than as a page
 import { renderTrapLink, trapRobotsEntries, DEFAULT_TRAP_PATHS } from "@osqd/bothandlerjs";
 
 app.get("/", (_req, res) => res.send(page + renderTrapLink()));
+
+// And publish the same paths, so a crawler that obeys robots.txt never sees them.
+app.get("/robots.txt", (_req, res) => res.type("text/plain").send(trapRobotsEntries(DEFAULT_TRAP_PATHS)));
 ```
 
 The trap paths belong in your `robots.txt` as `Disallow`, which is what makes the evidence
@@ -297,6 +349,39 @@ walking a sitemap almost never revisits, so its ratio sits near one.
 `weak`, because a *welcome* crawler produces exactly this shape and so does a person on a
 first visit to a documentation site.
 
+### `blended-identity`
+
+**cheap · always · ceiling `strong`**
+
+What a *series* of claims says, as opposed to what one claim says.
+
+Every other identity check here reads a single request: this User-Agent names this bot, and
+that claim is either confirmable or it is not. The set of identities an actor has claimed
+over time is a different object, and some sets are self-contradictory in a way no member of
+them is.
+
+Three readings:
+
+- **Several security tools.** One address arriving as two or more named scanners is a scan,
+  not a coincidence.
+- **Several verifiable crawlers.** At most one of Googlebot, Bingbot and Yandex can be true
+  of an address, because each publishes a proof tied to addresses it controls. The
+  contradiction is visible from the claims alone — which matters most when DNS is
+  unreachable and neither claim can be refuted on its own.
+- **A crawler that also probes.** An actor that sent a scanner payload *and* claimed to be
+  a search crawler has told you which of the two is the lie.
+
+**These hold under the default address-based actor key**, which is why they are on by
+default and [`identity-rotation`](#identity-rotation) is not. A NAT gateway presents many
+browsers — that is exactly what makes counting User-Agents useless there — but it does not
+present sqlmap *and* nikto, and it does not claim to be Googlebot *and* Bingbot. The
+innocent explanation for a hundred browsers behind one address is an office; there is no
+corresponding one for these.
+
+`strong`, not `certain`. Trusting the wrong forwarded header collapses every client onto
+one address, and then two genuinely different crawlers produce this exact set — so it may
+contribute to a denial and may not be the whole of one.
+
 ### `id-enumeration`
 
 **cheap · always · ceiling `moderate`**
@@ -339,8 +424,11 @@ const { outcome } = await handler.handle(facts);
 handler.recordOutcome(facts, response.statusCode);
 ```
 
-The bundled Node adapter does this for you. Nothing else depends on it: every other
-detector works unchanged if you never call it, and this one is simply absent.
+Every bundled adapter does this for you — Node and Express on the response's `finish`,
+Fastify on the reply's, Koa from the status the middleware chain settled on, and the Fetch
+wrapper from the `Response` it returns. You only need the call above if you drive the
+engine yourself. Nothing else depends on it: every other detector works unchanged if you
+never call it, and this one is simply absent.
 
 Counts **404 and 410 only**. A 403 is usually this library's own doing, and counting it
 would let a rule that challenges an actor manufacture the evidence for having challenged
@@ -375,6 +463,14 @@ request looks like this — which is what `transportCoherenceDetector({ legacyHt
 is for. An all-HEAD visit is a stronger shape, but a link checker is a real and mostly
 harmless thing to be.
 
+**It cannot simply be made NAT-safe, and it is worth saying why.** A rotator changes the
+User-Agent and nothing else, so "several User-Agents behind a single header shape" looks
+like a clean way to separate it from a gateway. Measured, it is not: ten real browser
+profiles collapse to six stable header shapes, and Chrome, Edge, Opera and Chromium on
+Linux share one — they are the same engine sending the same headers in the same order. An
+office running Chrome and Edge produces that signature exactly. The narrower actor key is
+the fix; there is no header trick that substitutes for it.
+
 ### `parameter-sweep`
 
 **cheap · always · ceiling `weak`**
@@ -407,7 +503,9 @@ mid-session; something that does is cycling through a spoofing list.
 
 **Off by default, and think before enabling it.** With the default address-based actor
 key, a corporate NAT presents a hundred people's browsers as one actor with a hundred
-User-Agents — which is this detector's exact signature and is entirely innocent. Enable it
+User-Agents — which is this detector's exact signature and is entirely innocent. Switching
+it on without also narrowing `actorKey` raises a startup warning, because it is a decision
+whose consequences are invisible until real visitors are being challenged. Enable it
 when your `actorKey` identifies a session rather than a network.
 
 ### `session-integrity`
@@ -491,8 +589,46 @@ A resolver that is merely *unhappy* must reach a different verdict from one that
 
 ---
 
+## Detectors that arrive with something else
+
+Ten more exist and are not in the catalogue above, because none of them is installed by
+default: each reads a source that has to be configured before it exists at all, and a
+detector with nothing to read is a permanently silent entry in `describeDetectors()`.
+They are documented together in
+[correlating a client's own requests](correlation.md), which is also where the reasoning
+about what each is worth lives.
+
+**With `probe`** — a signed marker cookie this server issues and reads back, which
+identifies a *client* across requests rather than an address:
+
+| Detector | Ceiling |
+| --- | --- |
+| `identity-drift` | `strong` |
+| `marker-integrity` | `strong` |
+| `marker-fanout` | `moderate` |
+| `marker-persistence` | `moderate` |
+
+**With `challenge`** — reactions to a question this server chose to ask:
+
+| Detector | Ceiling |
+| --- | --- |
+| `challenge-reaction` | `strong` |
+| `challenge-integrity` | `moderate` |
+
+**With `site`** — a warmed-up baseline of what the rest of your traffic looks like:
+
+| Detector | Ceiling |
+| --- | --- |
+| `distributed-walk` | `moderate` |
+| `path-novelty` | `moderate` |
+| `miss-baseline` | `moderate` |
+| `path-campaign` | `moderate` |
+
+---
+
 ## Related
 
 - [How detection works](index.md) — the pipeline these run in
+- [Correlating a client's own requests](correlation.md) — the ten above, in detail
 - [Writing a detector](writing-a-detector.md) — the contract, and the rules on certainty
 - [Evidence and certainty](../concepts/evidence.md) — what the tiers mean

package/docs/detection/index.md

@@ -129,6 +129,7 @@ time goes, and turn it off afterwards — it is two clock reads per detector per
 
 ## Related
 
-- [The detectors](detectors.md) — all twenty in detail
+- [The detectors](detectors.md) — the default set, in detail
+- [Correlating a client's own requests](correlation.md) — the marker cookie, and reading a series rather than a request
 - [Writing a detector](writing-a-detector.md)
 - [Policy](../policy/index.md) — what happens to an assessment next

package/docs/detection/shadow-mode.md

@@ -0,0 +1,147 @@
+# Shadow mode
+
+Run a detector on every request and let it decide nothing. Then read what it would have
+done, from your own traffic, before it does it.
+
+← [Documentation](../index.md) · [Detection](index.md)
+
+---
+
+## The problem it solves
+
+Every detector ships with thresholds somebody chose. They were chosen against a corpus of
+real traffic and they are defensible — and they were not chosen against *your* traffic,
+which is the only traffic that matters when the question is whether a threshold is about
+to start challenging your customers.
+
+The [correlation detectors](correlation.md) make this sharp, because several of them fire
+at `moderate` on real people **by design**:
+
+- a phone moving between wifi and cellular presents one marker from many networks, which
+  is what `marker-fanout` counts;
+- a crowd arriving on a link somebody posted wrong all request the same missing page,
+  which is what `path-campaign` counts;
+- tapping "Request desktop site" changes the platform a client claims, which is what
+  `identity-drift` counts.
+
+None of those is a bug. Each is a real observation with a real innocent explanation, and
+whether the threshold separating them is right *here* is not a thing this library can
+know. Shadow mode is how you find out without anybody being turned away while you do.
+
+```js
+const handler = new BotHandler({
+  preset: "protect-content",
+  site: {},
+  probe: { secrets: [process.env.MARKER_SECRET] },
+  shadowDetectors: ["path-novelty", "marker-fanout", "path-campaign"],
+});
+```
+
+Those three now run on every request exactly as they otherwise would. Their findings are
+counted, charted, and readable in the dashboard next to the evidence that did decide.
+And they decided nothing.
+
+## What "decided nothing" means, precisely
+
+A shadowed detector cannot affect:
+
+| | |
+| --- | --- |
+| the verdict | including via `certain` evidence, which does not go through scoring at all |
+| the score and the confidence | its findings are not in the arithmetic |
+| the bot class and the identity | the class is picked from evidence that counted |
+| any rule | a rule matching `detector: "path-novelty"` does not match a shadowed one |
+| anything downstream of a verdict | the guard, the action, the challenge, `recordOutcome` |
+
+This is not a weight of zero, and the difference is the whole design. A weight is
+consulted on the **probabilistic** path; `certain` evidence never reaches that path,
+because it short-circuits scoring and returns `confirmed-bot` on its own — which is what
+makes a terminal action permissible. A shadowed detector emitting `certain` would have
+blocked people with its weight sitting at zero the entire time.
+
+So the evidence is kept out of the arithmetic rather than weighted inside it. It lands in
+`assessment.shadowEvidence`, which nothing that decides anything reads:
+
+```js
+const assessment = await handler.assess(facts);
+
+assessment.evidence;        // what decided this request
+assessment.shadowEvidence;  // what the shadowed detectors said, flagged with `shadow: true`
+assessment.shadowVerdict;   // what the verdict would have been if they had counted
+```
+
+## The number that actually answers the question
+
+`shadowVerdict` is the point. "It fired 312 times" is not a thing anybody can act on; what
+you need to know is what turning it on would *do*, and the honest form of that is the
+verdict each request would have received.
+
+It is computed only when a shadowed detector found something, so a well-behaved one costs
+nothing on the requests it is silent about — and a badly-behaved one is the case you
+wanted to hear about anyway.
+
+```js
+if (assessment.shadowVerdict?.verdict !== assessment.verdict) {
+  log.info({ was: assessment.verdict, wouldBe: assessment.shadowVerdict?.verdict }, "shadow");
+}
+```
+
+## Reading it
+
+**In the dashboard.** Shadowed findings appear in the evidence list for each request,
+dimmed and labelled *"shadowed: counted, and part of no decision"*, with a line beneath
+saying what the verdict would have been. The Statistics tab counts them separately from
+real firings and reports how many verdicts they would have moved, by the verdict they
+would have produced.
+
+**In Prometheus**, only when something is shadowed:
+
+```
+bothandler_shadow_firings_total{detector="path-novelty"} 312
+bothandler_shadow_verdict_changes_total{verdict="suspected-bot"} 41
+```
+
+Forty-one against a `human` count that did not move is the shape of a detector about to
+start challenging people. That is the reading this exists to make possible.
+
+**In `detectors()`**, a shadowed detector is marked, so `describeDetectors()` and the
+dashboard's detector list both say so even before it has fired once.
+
+## How to use it
+
+1. Turn a detector on in shadow, alongside the policy you are already running.
+2. Leave it a week. A week, not a day: the traffic that catches a threshold out is the
+   Monday morning, the campaign, the outage, the release.
+3. Read `shadow_verdict_changes_total`. If it would have moved requests to
+   `suspected-bot` or `confirmed-bot`, find them in the dashboard and read them — one at
+   a time, as requests, not as a number.
+4. Either adjust the threshold and go back to step 2, or take it out of
+   `shadowDetectors`.
+
+This is the same shape as [`monitor-only`](../policy/presets.md#monitor-only) and
+[`replay`](../testing/replay.md), and it answers the question those two cannot: *what
+happens when I add something new to a policy that is already running*.
+
+## The honest limits
+
+**A shadowed detector still consumes its budget.** It runs, it is timed, and if it throws
+or times out that is recorded like any other failure. Shadowing is about influence, not
+about cost.
+
+**It still writes to actor state, if it writes to actor state.** Detectors are supposed to
+report rather than record — the recording that matters happens in the pipeline around them
+— but a custom detector that mutates `ctx.state` in `inspect` will do so shadowed or not.
+The bundled ones do not.
+
+**Naming a detector that is not installed is a warning, not an error.** The usual cause is
+a typo, and a typo here is otherwise invisible: nothing was going to run, so nothing looks
+any different either way. The warning is checked after the handler has finished installing
+detectors, because the marker, site and challenge detectors arrive with the source they
+read — and those are exactly the ones worth shadowing.
+
+## Related
+
+- [The detectors](detectors.md) — what each one reads, and its ceiling
+- [Correlation](correlation.md) — the sources whose thresholds this exists to check
+- [Metrics](../operations/metrics.md) — the counters, in full
+- [Choosing a policy](../start/choosing-a-policy.md) — the same caution, one level up

package/docs/detection/signatures.md

@@ -6,7 +6,7 @@ How a client is recognised by name, and what a name is worth.
 
 ---
 
-161 signatures, 389 tokens, matched in a single Aho–Corasick pass over the lower-cased
+205 signatures, 389 tokens, matched in a single Aho–Corasick pass over the lower-cased
 User-Agent. One pass regardless of how many signatures there are, which is why adding to
 this costs nothing measurable.
 

package/docs/index.md

@@ -38,10 +38,11 @@ Read these once and everything else follows from them. They are short.
 | | |
 | --- | --- |
 | [How detection works](detection/index.md) | The pipeline: stages, budgets, failure, and what an assessment contains. |
-| [The detectors](detection/detectors.md) | All twenty, each with what it reads, why it exists, and what it costs. |
+| [The detectors](detection/detectors.md) | All twenty-two, each with what it reads, why it exists, and what it costs. |
 | [The signature database](detection/signatures.md) | How a client is recognised by name, and what a name is worth. |
 | [Verifying a crawler](detection/verification.md) | Reverse DNS, published address ranges, and refuting a forgery. |
 | [Browser signals](detection/client-signals.md) | The optional page script, and the ceiling on anything it reports. |
+| [Shadow mode](detection/shadow-mode.md) | Run a detector without letting it decide anything, and read what it would have done. |
 | [Writing a detector](detection/writing-a-detector.md) | The contract, and the rules about certainty you have to keep. |
 
 ## Policy
@@ -89,7 +90,7 @@ Read these once and everything else follows from them. They are short.
 | --- | --- |
 | [Testing overview](testing/index.md) | The three ways to find out what a policy does before it does it. |
 | [The command line](testing/cli.md) | `replay`, `check`, `explain`, `robots`, `detectors`. |
-| [The traffic corpus](testing/corpus.md) | 526 shapes of real traffic, and how to run your own config against them. |
+| [The traffic corpus](testing/corpus.md) | 548 shapes of real traffic, and how to run your own config against them. |
 | [Replaying your own logs](testing/replay.md) | The most useful thing you can do before deploying anything. |
 | [Try it locally](testing/try-it.md) | A demo site, a live dashboard and eighteen scripted clients. |
 

package/docs/integration/client-ip.md

@@ -56,6 +56,22 @@ holds.
 Invalid CIDRs throw at construction rather than matching silently. A range that matches
 nothing is a control you believe you have and do not.
 
+## Ports in the forwarded header
+
+Most proxies write a bare address. Azure's Application Gateway and Front Door write
+`1.2.3.4:5678`, and RFC 7239 spells IPv6 as `[2001:db8::1]:5678`. Both are read correctly:
+the port is removed before the address is parsed.
+
+This matters more than it sounds. Every entry in such a chain carries a port, so an
+implementation that cannot read one reads *none* of them — the chain empties, and every
+client behind that proxy resolves to the proxy's own address. They then share one actor,
+one history and one rate-limit bucket, so a single bot is enough to lock out every real
+visitor, and nothing about it looks like a failure.
+
+A bare IPv6 address is made of colons, so only two shapes are treated as carrying a port:
+a bracketed host, and a single colon whose left side is an IPv4 address. `2001:db8::1` and
+`::1` are addresses, not hosts with ports.
+
 ## The peer is checked too
 
 The connecting peer counts as the first hop and is checked the same way.

package/docs/operations/dashboard.md

@@ -29,6 +29,13 @@ User-Agent, the verdict, the score, the action and the rule that chose it. Filte
 proven, suspected, human, guard stops, denied, mitigated or served; or type into the
 search box.
 
+**The window.** The **From** and **To** boxes above the feed take absolute instants, and
+either may be left empty — which is what makes one control answer all three of the
+questions people actually ask: from the moment an incident started until now, everything up
+to when it stopped, or between two moments. They read and write local time, the same clock
+the rows show. The charts keep showing their own rolling window; this narrows the feed, the
+counts and the export.
+
 The feed pages, fifty requests at a time. The newest page follows the stream; stepping
 back holds the list still while you read it — a feed that renumbers itself under somebody
 paging through it cannot be read — and says **held while you read** so the stillness is
@@ -46,6 +53,9 @@ score:>70 -certain                   probabilistic traffic close to the line
 "GET /api/v2/orders"                 a phrase, spaces and all
 ```
 
+The whole language, with every field and worked examples, is in [the filter
+reference](filters.md).
+
 Fields: `path` `actor` `ua` `verdict` `action` `rule` `detector` `identity` `method`
 `class` `id` `bypass` `outcome` `certain` `score`. Every term must match — narrowing
 means `AND` — and anything that is not a field term is matched against the whole
@@ -114,14 +124,43 @@ regularity (near zero is a metronome, which no person is), prior confirmations,
 whether they hold clearance. **In feed** sends one to the live feed as an `actor:` filter,
 which makes it a shareable URL like every other view.
 
+**Tracked, or shown in the feed.** The toggle above the table chooses which population
+you are looking at. *Tracked* is the registry — the default, and the one that answers "who
+is hitting me hardest". *Shown in the feed* lists only the clients that appear in the feed
+as you have currently filtered it, so once a filter is on it answers the other question:
+who is in *this*. It is derived from rows the page already holds, so it narrows with the
+search, the chips and the window without another request.
+
+Three columns go blank in that view rather than being filled in. Per minute, cadence and
+unsolved challenges are properties of a client's whole history as the engine sees it, and
+the feed's ring holds a few hundred requests rather than that history — computing them
+from the slice would put a confident number under a heading that means something else. A
+dash says "ask the registry", which is the other half of the toggle.
+
 This screen pages too, twenty-five at a time, busiest first. The registry holds far more
 clients than the feed's ring holds requests, and paging is what reaches them: the feed
 already shows you what is loudest, and the population behind it is the reason this screen
 exists. Ranking something that is still moving means a client can shift between pages
-while you read; the order is a snapshot of a live list, not a stable index.
+while you read; the order is a snapshot of a live list, not a stable index. Paging belongs
+to the registry: the feed-scoped view is built from what is already on screen, so there is
+nothing behind it to page to.
 
 The **Actors tracked** counter above the tab strip is the way in: it is a button, so
 pressing it — or reaching it with the keyboard and pressing Enter — opens this screen.
+
+**Labels.** An address is not a memory. Whoever works out that `198.51.100.4` is a
+partner's price feed can write that down with **Label**, and it shows wherever that actor
+appears — with the key still underneath it, because the key is what you search for. Labels
+can also be set from code, which is the better place for what a deployment already knows:
+
+```ts
+handler.labelActor("198.51.100.4", "partner price feed");
+handler.labelActor("198.51.100.4", undefined);   // and back again
+```
+
+**Detection never reads a label.** That separation is deliberate: the moment a note can
+change a verdict, writing notes becomes a way to be wrong about people at scale. A label
+lives exactly as long as the actor does.
 Where the `registry` section is switched off there is no Actors screen to open, and the
 counter stays an ordinary tile rather than offering to go somewhere that does not exist.
 

package/docs/operations/filters.md

@@ -0,0 +1,143 @@
+# The feed filter
+
+The search box above the live feed takes a small query language. It is the same language
+everywhere it appears — the feed, the export, a shared link — so a filter that finds
+something can be sent to somebody else and will find the same thing.
+
+An empty query matches everything. Adjacent terms mean `AND`, because that is what
+narrowing means — and `$or`, `$not` and set membership are there for when it is not.
+
+## Terms
+
+| Form | Means |
+| --- | --- |
+| `checkout` | the text appears anywhere in the request |
+| `path:/api` | the path contains `/api` |
+| `-path:/health` | the path does **not** contain `/health` |
+| `"GET /api/v2/orders"` | the phrase, spaces and all |
+| `score:>70` | a numeric comparison |
+
+Negation is `-` or `!`, and works on any term. Quoting keeps spaces together, which is the
+only way to search for a phrase.
+
+## Operators
+
+| Form | Means |
+| --- | --- |
+| `a $and b` | both — the same as writing them next to each other |
+| `a $or b` | either |
+| `$not a` | not — the same as `-a`, spelled out |
+| `path:$in(/health, /metrics)` | the path contains any of these |
+| `action:$notin(allow, tag)` | the action contains none of these |
+| `(a $or b) $and c` | grouping |
+
+`$not` binds tightest, then `$and`, then `$or` — the conventional precedence, so
+`a $or b $and c` reads as `a $or (b $and c)`. Brackets are there for the times that is not
+what you meant.
+
+**Operators carry a `$` for a reason.** A bare `or` is a word that appears in User-Agents
+and in paths — `header-order` contains one — and a language where an ordinary search word
+silently becomes an operator is a language that lies about what it matched. Typing `or`
+searches for the text `or`.
+
+Nothing you can type is an error. The box filters as you type, so half-written input is
+the normal state rather than a mistake: an unclosed bracket, a dangling `$or`, a `$in(`
+with nothing after it yet all parse to the best available reading of what is there.
+
+An empty set matches nothing rather than everything, for the same reason — `$in()` is a
+query somebody is halfway through, and a filter that widens while you are still typing it
+is a filter that lies.
+
+A colon with an unknown name in front of it is *not* a field term — a path can contain a
+colon and so can a User-Agent — so `foo:bar` searches for the text `foo:bar`.
+
+## Fields
+
+| Field | Also | Matches against |
+| --- | --- | --- |
+| `path` | `url` | the request path |
+| `actor` | `ip` | the actor key, usually the address |
+| `ua` | `useragent`, `agent` | the User-Agent string |
+| `verdict` | | `confirmed-bot`, `verified-bot`, `suspected-bot`, `human`, `unknown` |
+| `class` | `botclass` | `scanner`, `scraper`, `impersonator`, `http-client`, `automation`, … |
+| `action` | | what was decided: `allow`, `challenge`, `block`, `tag`, … |
+| `outcome` | | the coarse version: `deny`, `mitigate`, `allow`, `pending` |
+| `rule` | | the rule id that decided it |
+| `detector` | | any detector that produced evidence on this request |
+| `identity` | | the named bot, such as `googlebot` |
+| `method` | | `GET`, `POST`, … |
+| `certain` | | `true` or `false` — whether the verdict rests on proof |
+| `bypass` | | why detection was skipped, when it was |
+| `id` | `request` | the request id |
+| `score` | | 0–100. Takes `>` and `<` as well as `=` |
+
+`score` is the only numeric field. `score:>70`, `score:<20` and `score:60` all work;
+everything else matches a substring, case-insensitively.
+
+## Worked examples
+
+```text
+actor:203.0.113.4 -path:/health      that address, except its health checks
+rule:no-scrapers action:tag          the rule that fired, and what it settled on
+score:>70 -certain                   probabilistic traffic close to the line
+detector:trap                        everything that touched a trap
+class:impersonator verdict:confirmed-bot   proven forgeries
+outcome:deny -class:scanner          denials that were not scanners
+"GET /api/v2/orders"                 a phrase
+```
+
+## The chips
+
+The row of buttons — **All**, **Proven**, **Suspected**, **Human**, **Guard stops**,
+**Denied**, **Mitigated**, **Served** — is a separate filter that combines with the query
+rather than replacing it. Picking **Denied** and typing `path:/api` gives you denials on
+`/api`.
+
+## Saved filters
+
+Anything you can type can be saved by name and recalled from the dropdown beside the box.
+Saved filters live in **your browser**, not on the server: they are yours, they do not need
+a write endpoint, and clearing site data clears them. They record the query *and* the chip,
+because a filter is usually both.
+
+## Hiding traffic
+
+There is no separate exclusion list. `$not` does the job:
+
+```text
+$not path:/health                       everything except health checks
+path:$notin(/health, /metrics)          except either of two
+$not (path:/health $or ua:kube-probe)   except anything matching either
+```
+
+This used to be a button that kept its own hidden list in your browser. One mechanism is
+better than two, and this one is in the URL like every other narrowing — so a view with
+the noise taken out is a link you can send somebody rather than a setting only you have.
+
+Hidden traffic is still assessed, still counted in the metrics, and still acted on. A
+filter hides it from *your screen*; it does not stop the engine seeing it.
+
+## Completion
+
+The box completes as you type. Field names come from the parser's own list, so anything it
+offers is something the language accepts — and fields whose values are a closed set
+(`verdict`, `class`, `action`, `outcome`, `certain`, `method`) complete their values too.
+`rule`, `identity` and `path` take anything, so nothing is offered for them: guessing there
+would be inventing options rather than completing them.
+
+A token beginning with `$` completes to an operator, and a closed-set field offers `$in(`
+and `$notin(` alongside its values — because a field with a fixed set of values is exactly
+the field somebody wants two of.
+
+Arrow keys move, Enter or Tab accepts, Escape closes.
+
+## The window
+
+**From** and **To** take absolute instants and either may be left empty, which is what lets
+one control answer "from the incident until now", "everything up to when it stopped" and
+"between these two moments". They use local time, the same clock the rows show.
+
+## Related
+
+- [The dashboard](dashboard.md) — the screens, and what each one is for
+- [Embedding it](embedding.md) — the same dashboard inside your own page

package/docs/operations/index.md

@@ -99,4 +99,5 @@ want the raw event, take it here.
 
 - [Metrics](metrics.md) · [The audit](audit.md) · [Notifications](notifications.md)
 - [The dashboard](dashboard.md) — all of the above, rendered
+- [The feed filter](filters.md) — the query language, saved filters and exclusions
 - [Configuration reference](../reference/configuration.md)

package/docs/operations/metrics.md

@@ -67,8 +67,26 @@ nineteen together.
 
 Switch metrics off entirely with `metrics: false`.
 
+## The counters that appear only when something is shadowed
+
+A detector named in [`shadowDetectors`](../detection/shadow-mode.md) runs and decides
+nothing, so its firings are counted apart from the ones that decided something. Folding
+them together would put work into a chart of decisions that made none.
+
+```
+bothandler_shadow_firings_total{detector="path-novelty"} 312
+bothandler_shadow_verdict_changes_total{verdict="suspected-bot"} 41
+```
+
+The second is the one to read. It counts the assessments the shadowed detectors *would
+have moved*, keyed by the verdict they would have produced — so forty-one would-be
+`suspected-bot`s against a `human` count that did not move is the shape of a detector
+about to start challenging people. Both are absent from the output entirely while nothing
+is shadowed, rather than sitting at zero.
+
 ## Related
 
 - [The audit](audit.md) — because a counter cannot tell you a number is *unusual*
 - [The guard](../concepts/the-guard.md) — what `bothandler_downgrades_total` is counting
+- [Shadow mode](../detection/shadow-mode.md) — running a detector without letting it decide
 - [The dashboard](dashboard.md) — these numbers, drawn

package/docs/policy/presets.md

@@ -241,4 +241,4 @@ npx @osqd/bothandlerjs check --preset protect-auth
 - [Rules](rules.md) — the grammar these are written in
 - [Actions](actions.md) — what each rule can ask for
 - [Choosing a policy](../start/choosing-a-policy.md) — the decision, start to finish
-- [The corpus](../testing/corpus.md) — 526 cases, including the ones these presets get wrong
+- [The corpus](../testing/corpus.md) — 548 cases, including the ones these presets get wrong