DEV Community

yutianle
yutianle

Posted on

Canary tokens are a detection control, and detection controls can be measured

#detection #canarytokens #honeytokens #deception

Canary tokens are a detection control, and detection controls can be measured

Most breach narratives share a structural problem. The intruder is present for weeks or months, and nobody notices until a third party calls. Detection tooling that fires on anomalous behaviour helps, but it produces volume, and volume requires triage capacity that many teams do not have. Canary tokens run the other way: they generate almost no signal until something specific happens, and when they fire, the signal is usually worth reading.

The concept is old. Lance Spitzner described honeytokens in 2003, and Spafford & Kim raised the idea in 1994. What changed is deployment cost. The free generator at canarytokens.org exposes twenty-nine token types behind a browser form, and the implementation is published openly at github.com/thinkst/canarytokens, so an organisation that would rather not depend on a third-party domain can run its own.

What a canary token is, and what it is not

A canary token is an artefact placed where a legitimate user has no reason to go. It contains a reference to a unique endpoint. When something resolves the DNS name, opens the document, or tries to authenticate with the credential, the endpoint records the event and notifies the operator. The token blocks nothing and inspects no traffic. It answers one question: did something interact with an object it should not have?

That narrowness is the whole point. A triggered token is a high-fidelity event, because the expected rate of legitimate interaction sits at approximately zero. A token that never fires tells you one thing: nothing touched that object.

Deployment patterns that hold up

File-based tokens are the most common. A Word, Excel or PDF token embeds a remote resource reference, so the loader fetches it when the document is opened. The Thinkst engineering blog describes the same technique applied to video files and makes a broader point: many formats permit a URL fetch, and a signed executable will reach for a certificate revocation list at an embedded URL when it launches.

Credential tokens carry the most weight. A plausible-looking AWS access key sitting in a file such as ~/.aws/credentials has no legitimate consumer. An attacker sweeping the filesystem will find it, because that is the behaviour being optimised for, and the attempt to use it produces an alert. Database connection strings and API keys follow the same pattern.

Directory tokens scale cheapest. On Windows, a folder token works through a desktop.ini file:

[.ShellClassInfo]
IconResource=\\%USERNAME%.%COMPUTERNAME%.%USERDOMAIN%.INI.xxxxxxxx.canarytokens.com\resource.dll
Enter fullscreen mode Exit fullscreen mode

Two caveats deserve attention. On Windows 11 the token may fail to fire unless the policy at Computer Configuration > Administrative Templates > Windows Components > File Explorer > "Allow remote paths in file shortcut icons" is enabled. Antivirus scanning of the watched folder will also produce recurring false alerts, which in practice means adding an exclusion for the token directory.

A newer pattern targets machine learning artefacts. Because Pickle-backed model files can execute code on load, a beacon call can be prepended to a serialised model so that loading it emits a DNS query. Clever, but the ceiling is low: it detects unauthorised load only, and a team that has already banned Pickle in favour of safer formats gets little from it.

Making the control measurable

Treating canary tokens as a control rather than a trick means defining expectations and then checking them. Four numbers are worth tracking.

Coverage: how many of the asset classes that matter, whether credential stores, document shares, model registries or administrative endpoints, hold at least one token, and which hold none. Trigger latency: the interval between the artefact being touched and the alert landing in the on-call queue, measured end to end rather than assumed. False-positive rate: how often a token fires for a mundane reason, with endpoint scanning and backup indexing the usual suspects. Verification cadence: when the team last confirmed a token still fires. A token whose endpoint has been decommissioned, or whose domain the proxy now classifies as malicious, is no longer a control.

The honest limitation is that a triggered token remains a hypothesis until someone investigates. The public service reports the source IP, the timestamp and whatever memo the operator supplied, and little more. A token tripped by an internet-wide scanner is not evidence of a targeted intrusion, and a careful adversary who enumerates the environment and avoids anything shaped like a decoy will produce no alert at all. Canary tokens narrow the window between access and detection; they do not close it.

Defensive implications

Place tokens only where a benign user has no business going, and write down why each location qualifies. Exclude token paths from routine scanning and from backup indexing. Route alerts into the same queue as other detections, with a runbook that begins by checking the source and separating automated scanning from interactive access. Where the deployment depends on the public token domain, verify periodically that it is not blocked, and weigh self-hosting when the dependency becomes unacceptable. Then test the tokens on a schedule. An unverified tripwire is an assumption, not a control.

References

Top comments (0)