Skip to main content

Honeypot Canaries

Belay plants decoy credential files — honeypot canaries — that no legitimate workflow should ever touch. Because they are fake and unused, any read or egress of their sentinel bytes is unambiguous evidence that something is sweeping for secrets or trying to exfiltrate them. A canary hit trips a Critical verdict immediately.

When this matters​

Pattern rules catch known dangerous shapes. Canaries catch the intent behind credential theft without needing to enumerate every way an agent might discover or ship a secret: the moment a decoy's distinctive bytes appear in a tool call, the game is up.

What gets planted​

Belay seeds two kinds of decoy under its data directory (~/.belay/honeypot/ on Linux and macOS, %ProgramData%\Belay\honeypot\ on Windows):

  • A fake AWS credentials file — a decoy access key that is not real and grants nothing; its only purpose is to be recognisable if something reads or ships it.
  • A .env sentinel — a decoy environment file carrying a fixed canary token, placed where an agent hunting for environment secrets would stumble on it. The token value is not user-configurable — it is a known constant baked into the daemon, which is what makes it a reliable, well-tested tripwire.

Both use distinctive, unused sentinel byte-runs that will not collide with real project data. (The exact sentinel values are defined in the open-source daemon; we intentionally do not reprint them here so they stay effective as tripwires.)

How a trip is detected​

The daemon watches for the sentinel bytes on two paths:

  1. On read — a tool call that reads a canary file (or otherwise pulls its sentinel bytes into view).
  2. On egress — the sentinel bytes appearing in an outbound command (uploading, posting, or otherwise shipping the decoy off the host).

Either path raises a Critical finding. Combined with session correlation, a canary read that arms the session and a later outbound sink is exactly the arm→sink pattern the engine is built to stop.

tip

A canary hit is one of the highest-confidence signals Belay produces. Unlike a heuristic pattern match, there is essentially no benign reason for a decoy credential to be read or transmitted — treat these findings as real.

Relationship to the audit trail​

Canary findings are written to the hash-chained audit log (~/.belay/audit.ndjson) like any other verdict and surface in the desktop app's Activity and Live Feed views. Because the audit log is tamper-evident, a recorded canary trip cannot be quietly scrubbed after the fact.