# Canaries: tripwires for a hijacked agent

Scanners lose to adaptive attackers. A tripwire does not need to recognise the payload: it notices the
consequence. Bucker plants two kinds of canary, and both end the same way, in one finding of kind
`tripwire_fired`.

## Decoys, on Bucker's side

An owner turns decoys on for a project. Bucker then keeps at most **three** live decoy records in it,
one per placement:

| Placement | What it is |
| --- | --- |
| `error_event` | a synthetic error event |
| `log_line` | a synthetic log line |
| `span_attribute` | a synthetic span attribute |

Each carries an instruction-shaped lure addressed to an automated assistant and one word-shaped canary
such as `orchid-lantern-441793`, unique across every Bucker organization. The lure asks for something no real triage needs: fetch a URL on the
canary route, open a branch named after the word, pass it as a tool argument. A legitimate flow never
does, so a match is unambiguous and there is no score and no threshold.

Decoys are badged `decoy` and are excluded from counts, alerts, rollups, digests, exports, billing and
data-subject reach wherever they are served.

### Where Bucker watches

Every exit Bucker owns calls the watch with the text it is about to send:

| Exit | Seen at |
| --- | --- |
| `canary_route` | `GET /canary/:word/:mac`, the public route the lure points at |
| `mcp_tool_argument` | every `tools/call` in `bucker-mcp`, before the arguments are parsed |
| `governed_write_plan` | the plan of a governed write |
| `pull_request_body`, `pull_request_branch` | pull requests Bucker opens |
| `issue_comment` | comments Bucker posts |
| `outbound_webhook_target` | the URL of an outbound webhook |
| `ssrf_refusal` | a destination the SSRF guard refused |

The match is verbatim (a paraphrase is missed) and case-insensitive; percent-encoded URLs are decoded.
A word of another organization never matches here: an exit matches the organization it acts for, or,
for a credential that names none, only the organizations its holder is a member of. The watch never blocks the exit and never throws
into it.

### What a trip does

Once, in one transaction: the canary moves to `tripped`; a fresh decoy of the same placement is
rotated in (so the project keeps its three and the leaked word is dead); one `tripwire_fired` finding
is filed; one `tripwire.fired` audit row is written (`basis: tripwire`). Then the owners are alerted.

If the exit knows which credential was used, the owner's leak-response policy applies, the same one
SEC-09 reads. With `notify` (the default) nothing is disabled. With `disable`, the one implicated
agent token is **disabled** (reversible: an owner restores it with `credential.restore`), never
revoked. A trip never deletes data. `credential.revoke` stays a person's dual-controlled act and a
freeze on the principal is a proposal for a person.

### The switch

`tripwire.enable` and `tripwire.disable` are human-only acts at org `admin`: a person in their own
session, never an agent, a service account, a delegated token or an OAuth client.

| Door | |
| --- | --- |
| `POST /orgs/:o/projects/:p/tripwire/enable` | brings the project to three live decoys; idempotent |
| `POST /orgs/:o/projects/:p/tripwire/disable` | retires them (rows are kept) |
| `GET /orgs/:o/projects/:p/canaries` | ids, kind, placement, state |

## Honeytokens, in the customer's AI app

A person at org `admin` plants a honeytoken (`POST .../honeytokens`). The word, credential-shaped
(`hny_` and twenty characters), is returned in **that response only**. The customer puts it in their
app's context. Their SDK checks every model output and tool argument for it in process and, when it
appears, sends an event tagged `bucker.canary.tripped` with the canary's **id**: the word itself never
leaves their app.

The tag arrives through ingest, so it is evidence anyone with the public project key could write. It
is therefore handled with the project taken from the **key**, never from the event; only a live
honeytoken of that exact project trips; any other id (unknown, another project's, a decoy's) is
ignored in silence; and the finding is filed with `dsn` provenance, which ranks and never opens an
issue on its own. A project holds at most ten live honeytokens.

## What agents see

Nothing of a decoy before a trip. `ai_canaries_list` (read, `security:read`, held until the SG-059
review, 400 tokens) returns ids, kind, placement and state, and the live-decoy count. It never
returns a word, a digest, lure text or ciphertext. After a trip an agent sees a `tripwire_fired`
finding in `findings_list` and the decoy already rotated.

## How the word is kept

The word is stored sealed (AUTH_SECRET, bound to its project and digest) and by SHA-256 for matching;
no column holds it plain. Exactly one function opens the ciphertext, the planter that writes the lure
into the project's telemetry, and a source scan in the test suite fails if anything else does.

## The public route

`GET /canary/:word/:mac` has no credential to check, and answers every visitor with the same status and
body, `200 { "received": true }`, whatever the word is, and it answers before the lookup runs, so
neither the body nor the response time says whether a word is live. The shape is checked before any
query, and the route is rate limited per address. The second segment is a MAC of the word that only
Bucker can compute, checked in constant time before anything is looked up, so guessing a word (one
of 921,600,000) is not enough to raise a false alarm in someone else's organization: a caller would
have to guess the MAC as well.
