How to Use Canary Tokens to Catch Unauthorized Access

October 30, 2026

A canary token — also called a honeytoken — is a fake credential deployed inside your real systems. It has no legitimate use, so any use is by definition unauthorized. GitGuardian Honeytoken generates AWS keys, GitLab tokens, Okta tokens and generic ones that fire an alert when accessed.

Secret scanning tells you a key leaked. Honeytokens tell you someone is retrying old attempts against live infrastructure. That is the signal a scanner cannot give you, because the key is working and valid.

How does GitGuardian Honeytoken work?

You create the token in the GitGuardian dashboard under Honeytoken, choose a provider type, and place it where an attacker would look: a .aws/credentials file on an EC2 instance, a .env in a shared dev server, a wiki page, a config repo.

GitGuardian monitors for usage and alerts you with the source IP, the API call attempted and the token that fired. It can also trigger a webhook into Slack or a SOAR playbook.

The critical property: the token is not a real IAM user with permissions. It is a decoy credential that only exists in monitoring. Using it changes nothing in your infrastructure.

Where should you actually place them?

The useful placements are the ones an attacker reaches after initial access:

Location Catches
~/.aws/credentials on a prod instance A human on a compromised shell
Repo .env-template files Developers copying templates
Internal wiki / Notion page Insider data access
CI secrets marked “unused” Enumeration of the pipeline
S3 bucket prefixes Lateral movement

Only put one in a location you would notice being extracted. A token buried in a 400-file config repo where nobody looks is a token you will never see fire.

What does a hit actually tell you?

Not much by default, which is the part vendors skip. The alert gives you source IP and the API call. You have to do the triage:

  1. Is the IP in your known ranges? Compare against your cloud egress IPs first — if it is your own CI, you have a misconfiguration, not an attack.
  2. What was the call? GetCallerIdentity alone is reconnaissance. Anything that attempts a write is a person who did not check permissions first.
  3. When? A hit at 3am in your timezone on a Sunday is a script.

The most common false positive is a developer’s local tooling with a stale config directory. Timestamp your deployment notes so you can correlate.

Why does this catch things secret scanning misses?

Because secret scanning only finds secrets it can pattern-match. A valid token that leaked outside Git — through a Slack message, a screenshot, a contractor’s laptop — never appears in a commit.

Honeytokens are the only control that catches a key you do not know is exposed. They also catch the case where a leaked key was rotated in Git but the old value still exists in someone’s shell history.

What are the limits?

  • Nobody looks at alerts. This is the main reason honeytokens fail. If your alert lands in a Slack channel nobody monitors at night, you paid for a log entry.
  • Coverage is thin. A token only fires if the attacker finds that specific location. Three tokens in a 200-instance fleet catch maybe one in five intrusions.
  • Legal framing. Do not place honeytokens on an employee’s personal device or in a way that monitors an individual. Place them in systems only, and put it in your acceptable-use policy.

GitGuardian Honeytoken is available on paid plans; the free tier is limited. If you are on free, a much cruder version works: an AWS IAM user with Deny * that fires a CloudWatch alarm on GetCallerIdentity. It is five minutes of setup and catches the same thing.

Key Takeaways

  • A honeytoken is a valid-looking credential that should never be used; any use is unauthorized.
  • Place them where an attacker goes after initial access — ~/.aws/credentials, CI secrets, internal wikis.
  • Triage with IP range, API call type and timestamp; a GetCallerIdentity call is reconnaissance, not yet damage.
  • They catch leaks that never touch Git, which is exactly what scanners cannot see.
  • Without a monitored alert channel and a response owner, honeytokens are decoration.