Skip to main content

Canary tripwires

Three private files each hide a fake secret. Nothing real uses it. If that fake secret ever shows up somewhere it shouldn't, like a saved change or an outgoing email, the box refuses and writes an alarm.

Where you see it​

Only in the daily checkup, and only if something went wrong. A clean day shows nothing. A tripped day shows CANARY TRIPPED.

The idea​

Coal miners once carried a canary. If the bird got sick, the air was bad. The bird didn't clean the air. It just warned the miners.

These tripwires work the same way. Three private files, the kind an attacker would want most, each hold a token that looks like a secret: CANARY- followed by 16 random characters. No real system uses it. So there is only one way it could show up in an email or a saved change. Something copied it out of a private file.

What happens, step by step​

Say an agent is tricked into gathering private notes and sending them to a stranger.

  1. At send time. Before anything else, the send guard scans the whole message and every attached file for the known tokens.
  2. It finds one. The send is refused outright. No yes can override it.
  3. At save time. Every change saved to git is checked too. A new line that adds a known token to any file other than its own home file is refused.
  4. Either way, an alarm is written to a private log that only the agent's account can read.
  5. The next daily checkup sees the alarm and reports CANARY TRIPPED to the owner.

What powers it​

PartWhat it does
canary.pyKnows the tokens, scans for them, and writes the alarm.
The pre-commit checkRuns the scan on every change before git saves it.
send-guard.pyRuns the scan on every outgoing message and attachment.
canary-alarm.jsonlThe private alarm log.
healthcheck.pyThe daily checkup. Reports any alarm to the owner.

Why it works this way​

It is a detector, not a wall. Every other layer tries to stop an attack. This one assumes an attack might get through, and makes sure it can't happen quietly. If a leak ever gets past the quarantine and the send guard's other checks, the canary is the thing that catches it.

It fails open, except on a hit. If the scan itself breaks, it lets the save or send go on. A broken scanner should not freeze the whole company. But when it finds a real token, it always refuses. As the code puts it, a canary "refuses only after it finds a known positive token hit."

It only knows its own tokens. The canary does not scan for real passwords or keys. It watches for the three planted fakes. That keeps it simple, and it means it almost never cries wolf.

A real limit

A token split across two lines slips past the scan. See Known limits.

Connected to​