Canary Tokens (Honeytokens): Plant a Tripwire in Your Own Files

Open canarytokens.org, pick the Web bug / URL token (the docs call it the HTTP token), enter the email address that should be alerted, and — the part people rush — write a memo. You get back a URL that looks ordinary and does nothing useful. Anyone who visits it fires an alert.

The memo is the only context the alert carries, so make it say which token and where you put it:

URL token — link in ~/.bashrc on jump-host — planted 2026-10-14

You should now have a token URL on your clipboard and a token listed under your email’s management link. Do not visit it yet.

Why this matters. A canary that fires at 2am is only useful if the alert tells you what tripped and where. “http token” as a memo is useless; “link in ~/.bashrc on jump-host” tells you, half asleep, exactly which machine someone is poking at. The docs say the same thing in gentler words: make the reminder “descriptive” and “self-describing”.

This is the whole game. A canary is only as good as its hiding place: it has to sit somewhere no honest process and no normal workflow ever touches, but somewhere a curious intruder would. Put the URL from step 1 in a spot like these, and add a token or two of the matching type from the table:

Why this matters. The honeypot idea only pays off if a trip means something. Bury a token in a folder your backup software crawls nightly and you have built a false-alarm machine. Bury it where only a human going somewhere they should not would find it, and every alert is worth getting out of bed for. Signal comes from placement, not from the token.

The best bait is the file an attacker hopes to find. Name it something boring and nobody bites. Name it passwords.xlsx and you are not setting a trap so much as answering a prayer. — Nyx

Back at the generator, create an MS Word or MS Excel token. Thinkst hands you a real document with an invisible beacon baked in. Save it with a name that begs to be opened, and put it on a share you own:

\\FILESRV\HR\2026\passwords.xlsx

When someone opens it in Word or Excel, the document quietly reaches out and your alert fires. The file still opens and looks like a dull, near-empty spreadsheet, so the person who tripped it never knows.

Why this matters. Document tokens catch the step before damage: the browsing. An intruder mapping a share, or an insider shopping for data to take to a new job, opens the tempting file first. That open is your early warning — and unlike a URL token it survives being copied off the share, because the beacon travels inside the file.

Two more token types close gaps a URL cannot. Create a DNS token and an AWS API Keys token from the same menu, and plant each where it belongs:

• DNS token — a hostname that alerts the instant anything looks it up. Drop it in a config file as a fake backup server or database host. It fires even on a locked-down segment with no outbound HTTP, because name resolution still leaves.
• AWS API Keys token — a fake access key and secret. Put them in a decoy ~/.aws/credentials, a script, or a rarely-touched S3 bucket. The alert fires when someone uses the keys against AWS — so it can catch a thief hours or days after they lifted them.

Record each one’s memo and where you hid it. You now have four tripwires of three kinds, on your own ground.

Why this matters. Real networks have blind spots — segments with no web egress, laptops that get stolen offline, keys that get copied and used later. A URL token is silent in all three. DNS and credential tokens are not: they report on channels an attacker cannot easily avoid using.

Fire your own URL token: paste it into a browser on your phone, or open your decoy document. Within seconds the email arrives. Thinkst’s docs put it plainly: “If an attacker ever trips on the Canarytoken somehow, you’ll get an email letting you know that it has happened.” Read what it gives you. Every alert answers four questions:

• Which? Your memo / token reminder — the line you wrote in step 1. This is why the memo mattered.
• When? The time of the trip.
• From where? The source IP that touched the token — and for web tokens, rough geolocation.
• How? The channel (HTTP, DNS, and so on) and, for an HTTP token, the user agent — the browser or tool that made the request.

That source IP and user agent are the thread you pull next. A trip from a datacentre IP with a scripted user agent reads very differently from one inside your own office range.

Why this matters. A canary does not just say “something happened”; it hands you the start of an investigation. The memo scopes it, the time anchors it, the source IP and user agent point at who. We cannot fire a real hosted token from inside this lab’s sandbox — the field names above come straight from Thinkst’s documentation, not a screenshot we faked.

If you want to see the mechanism with nothing hosted, run a one-file stand-in. It serves a decoy URL on 127.0.0.1 and logs an alert record for every request — the same four questions, on your own box. Save canary_server.py and run it:

$ python3 canary_server.py

In a second terminal, “trip” it the way a snoop would stumble onto it:

$ curl -A "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" http://127.0.0.1:8099/t/decoy-passwords.xlsx

The server prints the trip the instant it happens. This is real output from running exactly that on this lab’s machine:

Canary armed. Decoy URL: http://127.0.0.1:8099/t/decoy-passwords.xlsx
Any request to that URL fires an alert. Ctrl+C to stop.
[CANARY TRIPPED] {"time": "2026-10-15T01:29:55+00:00", "channel": "HTTP", "token_reminder": "DECOY passwords.xlsx on FILESRV share", "src_ip": "127.0.0.1", "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)", "path": "/t/decoy-passwords.xlsx"}

A request to any other path stays silent — only the token fires. Notice the record carries the same fields the hosted alert does: time, channel, reminder, source IP, user agent.

Why this matters. Seeing the trip land locally demystifies the hosted service: a canary is just a resource that tells you when it was touched. This stand-in is a teaching toy — it only sees requests you send it on loopback. The hosted tokens reach far further and alert you by email; use those for real.

“Any interaction is suspicious” is the rule, but machines interact with things too. Before you treat a trip as an intruder, rule out the honest culprits:

• Chat and mail link previews. Paste a URL token into Slack, Teams, or an email and the platform’s bot fetches it to make a preview — an instant trip from a cloud IP. Never put URL tokens where links get unfurled.
• Backup, antivirus and EDR. Agents that read every file can open a document token. Keep document tokens out of folders these tools crawl.
• Search indexers. Windows Search and Spotlight open files to index them. Same fix: placement away from indexed paths.
• You. Your own test in step 5, or a colleague tidying the share. Log the time of your own trips so you can discount them later.

The tells of a real trip: a source IP you do not recognise, a scripted or server user agent, a time outside working hours, or several tokens firing in sequence as someone moves through your files. Learn your environment’s normal background first, so the odd one stands out.

Why this matters. A tripwire you have learned to ignore is worse than none, because it taught you to ignore it. Spend ten minutes finding your false-positive sources up front and every alert that survives is one you will actually act on.

A genuine trip is an incident. Work it calmly and in order:

• Write down what you have. Memo, exact time, source IP, user agent. That is your first evidence; save the alert.
• Do not tip off the toucher. Resist deleting the token or confronting anyone yet. You want to learn what else they touched while they still think they are unseen.
• Pivot on the source. What else did that IP or host do around that time? A canary is the thread; your logs are the rest of the sweater. Our Purple Bridge covers catching the activity around a trip.
• Rotate anything real that lived nearby. The decoy is fake, but if a token sat next to genuine credentials or data, treat those as exposed and rotate them.

Run it yourself, or run it in-house. The hosted canarytokens.org is free and perfect for learning and for home use. Organisations that do not want their tripwires calling an outside service can run the open-source Canarytokens (GPL v3) on their own infrastructure — the Docker build is the documented way in. Same idea, tokens that report home to you.