Join our Newsletter — 33% off our NHI Course
Home› Guides› Honeytokens and Canary Credentials Guide: Designing Fake Keys…
Guide SOC & Detection Engineering

Honeytokens and Canary Credentials Guide: Designing Fake Keys and Accounts That Catch Real Attackers

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 13 min read
On this page

Most secret leaks are discovered weeks after the attacker used the credential, because nothing alerts when a stolen key is first tried. A honeytoken is a credential, account or data item that has no legitimate use, so any use of it is a high-confidence signal of compromise. Planted where real machine credentials live (a .env file, a CI variable, a developer's ~/.aws/credentials, a Kubernetes namespace, a password vault), canary credentials tell you that someone has read that location and is acting on what they found. This guide covers how to design, place, monitor and respond to canary credentials for non-human identities: cloud access keys, service principals, API and SaaS tokens, database logins, Kubernetes tokens and directory accounts. It is for detection engineers, cloud security and NHI programme owners. The wider deception toolset, including honeypots and canary files, is covered in the Deception Technology Guide; this page goes deeper on credentials.

Key takeaways

  • Use by anyone is the alert. A canary credential has no legitimate user, so detection needs no baseline and produces few false positives when it is registered and documented.
  • Place canaries where attackers harvest secrets, not where they are convenient: CI runners, developer laptops, build images, backups, wikis and secrets stores.
  • A canary must look real and be powerless. It should match your naming and key formats but hold no permissions, so an attacker gains nothing by using it.
  • The alert is the start of an incident, because it proves the location was read; every real secret stored alongside the canary is compromised.
  • Keep a decoy register so secret scanners, auditors and responders can tell a tripped canary from a real leak, and test each canary on a schedule.

What honeytokens and canary credentials are

MITRE D3FEND classes these as deceptive techniques: D3-DUC Decoy User Credential, D3-DST Decoy Session Token and D3-DF Decoy File. NIST SP 800-53 Rev. 5 control SC-26 Decoys covers the practice of components that attract and divert attackers, and MITRE Engage lists Lures among its adversary engagement activities. In practice, three properties define a useful canary credential:

  • Authentic format: it is a genuine credential issued by the real provider (a real AWS access key for a real IAM user, a real Entra service principal secret), so it passes any format check an attacker or a tool applies.
  • Zero privilege: the identity behind it has no permissions, or explicit denies, so use cannot cause harm.
  • Observable use: the provider logs every authentication attempt or API call, including failures, and those logs reach your detection pipeline.

Honeytoken accounts in a directory differ slightly: they are dormant user or service accounts whose sign-in, or even lookup, should never occur. Microsoft Defender for Identity supports a Honeytoken tag for users and devices, and any sign-in from a tagged account raises an alert.

Canary types for non-human identities

CanaryHow to build itSignal sourceTypical placement
AWS access keyIAM user with no policies (or an explicit deny-all) in a dedicated account; generate a key pairCloudTrail events for the access key ID, including failed calls (errorCode such as AccessDenied)~/.aws/credentials on developer and admin machines, .env files, CI variables, AMIs and container images
Azure service principal secretApp registration with a client secret and no role assignments or API permissionsEntra ID service principal sign-in logsConfig files, pipeline variables, automation scripts
Google Cloud service account keyService account with no IAM bindings; JSON key fileCloud Audit Logs and service account key usageBuild agents, notebooks, shared drives. See the Google Cloud Service Account Keys Security Guide
Source control or package tokenA token on a bot account with access only to an empty repository or scopeOrganisation audit log and token usage eventsCI secrets, .npmrc, .git-credentials
SaaS API keyKey issued to an unused integration user with read-only access to nothingSaaS admin audit logWikis, tickets, integration configs
Database loginLogin with CONNECT only, or a fake connection string to a monitored listenerDatabase authentication logsApplication config, backup scripts, connection string files
Kubernetes credentialService account with no RoleBindings, token in a Secret or kubeconfigAPI server audit log (user.username matches the canary)Namespaces, jump hosts, CI runners. See the Kubernetes Service Account Token Guide
Directory service accountDisabled-looking but enabled account, plausible name, never used, tagged as honeytokenDomain controller authentication events, ITDR alertsScripts, scheduled task arguments, LDAP descriptions
Vault entryA fake secret in the secrets manager under an attractive pathSecrets manager read audit eventsPaths named like production database or payment credentials

Managed services such as Thinkst Canarytokens issue AWS key canaries for you and send the alert; their documentation notes alerts can take 2 to 30 minutes because they flow through Amazon's logging. The open-source Canarytokens server can be self-hosted, but its AWS key token relies on separate AWS-side infrastructure that the project has moved to a private repository, so self-hosters must provide that themselves or build their own.

Placement strategy: think like a credential harvester

Attackers and infostealers go to predictable places. In the Shai-Hulud npm worm, malicious install scripts harvested credentials from developer machines and CI runners. In the .env cloud extortion campaign, attackers took AWS keys from exposed .env files and immediately called GetCallerIdentity, ListUsers and ListBuckets. A canary key in either location would have fired on that first call.

  1. Developer and administrator endpoints: a canary profile in the cloud CLI credentials file, a canary token in the Git credential store and shell history-style files.
  2. CI/CD: a canary secret in every pipeline's secret store and on self-hosted runners, named like a deployment key. See the CI/CD Pipeline Identity Security Guide.
  3. Images and artefacts: a canary in base images and in build artefacts, which catches anyone mining your public or private registry.
  4. Collaboration tools: a canary credential in a wiki page titled like a runbook, and in a ticket.
  5. Secrets stores and backups: a canary path in the vault and a canary file in backup sets, which detects insiders and attackers with storage access.
  6. Code repositories: canaries in private repositories detect repository theft; avoid public repositories unless you intend it, because public exposure triggers provider scanning (AWS may attach the AWSCompromisedKeyQuarantineV3 policy to an IAM user whose keys are found exposed) and noise from opportunistic scanners.

Designing canaries attackers will not spot

  • Match conventions: use your real naming scheme for users, roles and secret paths. A key for svc-deploy-prod next to real deployment config is convincing; a user called honeytoken1 is not.
  • Beware account attribution: AWS STS GetAccessKeyInfo returns the account ID that owns any access key. If all your canaries sit in a single dedicated account, or in an account known to belong to a canary service, a careful attacker can recognise them. Consider canary accounts that look like part of your organisation's estate.
  • Match age and context: place canaries in the same files as real secrets and update their surroundings when real configs change.
  • No real permissions, ever: attach explicit denies where the provider supports them, and review canaries in access reviews like any other identity so they never acquire rights.
  • Unique per location: issue a distinct canary for each placement so the alert tells you exactly which location was read.

Rolling out a canary programme

  1. Agree scope and rules (week 1): get written approval from the security leadership and the platform owners whose systems will hold canaries. Decide who may know placements (normally the detection team and incident managers only) and record the rule that canaries never hold real data or permissions.
  2. Build the canary identities (week 1 to 2): create zero-privilege identities in each provider, ideally by infrastructure as code so they can be recreated quickly. Confirm in each provider that failed calls by the identity are logged, and that those logs reach the SIEM.
  3. Pilot in one location type (week 2 to 4): start with CI secret stores or admin laptops. Trigger each canary yourself from an unrelated network and measure time to alert. Expect benign triggers from secret scanners, backup verification jobs or engineers testing what a "stray" key does; tune by documenting, not by suppressing the canary.
  4. Expand by risk: add runner images, vault paths, backups, wikis and repositories, highest-value locations first. Generate each canary uniquely and record it in the register at creation time.
  5. Integrate with operations: add canaries to the secret scanning allow-list by identifier (not by pattern), to the NHI inventory as decoys, and to the incident playbooks.
  6. Roll back cleanly: if a canary causes operational problems (for example a tool fails on a credential it cannot use), remove it from that location, delete the identity and update the register, rather than granting it permissions to keep the tool happy.

Detection, alert routing and response

Write one detection per canary type that matches the canary identifier and fires on any event, success or failure.

CanaryDetection logicKey fields to capture
AWS keyAny CloudTrail event where userIdentity.accessKeyId is in the canary listeventName, errorCode, sourceIPAddress, userAgent, region
Entra service principalAny service principal sign-in for the canary application IDIP address, result, resource requested
KubernetesAny audit event for the canary service account usernameverb, resource, sourceIPs, userAgent
Directory accountAny authentication or ticket request for the account; Defender for Identity honeytoken alert where usedsource host, protocol, time
Vault pathAny read of the canary pathcaller identity, client IP, auth method
  1. Route to the SOC as high severity with the placement location in the alert, taken from the decoy register.
  2. Treat the location as breached. The canary proves that whoever read the file also read every real secret in it. Rotate those secrets using the Leaked Credential Response Playbook.
  3. Find the reader: who and what can access the placement (endpoint, runner, repository, backup), and what else that identity touched.
  4. Use the attacker's metadata: source IP, user agent and the API calls attempted show tooling and intent; feed them into hunting across real identities.
  5. Replace the canary with a fresh one after the incident, because the tripped one is now known to the attacker.

Where identity fits: canaries as NHI detection

Canary credentials are the cheapest high-fidelity detection an NHI programme can deploy, because they need no behavioural baseline. They complement baselining of real machine identities, described in the Detection Engineering for Non-Human Identities Guide, and the identity threat detection covered in the ITDR Guide. Register every canary in your NHI inventory with an owner and a "decoy" classification so it is not cleaned up as an orphaned identity, and so secret scanning results that find it are closed correctly.

Decision guidance and measurement

Managed service or build your own? A managed canary service is quickest for small teams: it issues credentials, receives provider logs and alerts with no pipeline work. Build your own when you need canaries in many clouds and SaaS platforms, need to avoid a third party knowing your placements, or want canaries in accounts that look like your own estate. Large organisations usually combine both: managed tokens for breadth, home-built canaries in high-value locations wired straight into the SIEM.

Canaries or behavioural detection? Both. Behavioural analytics on real service accounts catch misuse of credentials the attacker actually stole, but need baselines and tuning, and can miss slow or careful use. Canaries catch the act of harvesting itself, with almost no tuning, but only where you placed them and only if the attacker tries the decoy. Use canaries to cover the locations where real secrets accumulate and behavioural detection to cover the real identities, and correlate the two: a canary trigger from an IP address is a strong lead for hunting real-identity activity from the same source.

Small vs large organisations. Start with three canaries: one cloud key on admin laptops, one secret in CI and one in the main secrets store. Larger estates should aim for a canary in every pipeline secret store, every base image and every privileged jump host, generated and rotated by automation.

Metrics:

  • Coverage: percentage of high-value secret locations (CI stores, runner images, admin endpoints, vault paths) holding a canary.
  • Health: percentage of canaries tested in the last 90 days with an alert received end to end.
  • Time to alert: median minutes from a test trigger to a SOC ticket.
  • Time to rotate co-located secrets after a real trigger.
  • False trigger rate, with cause (scanner, tool, staff curiosity), which should fall as the register is used.

Framework mapping

FrameworkReferenceRelevance
MITRE D3FENDD3-DUC Decoy User Credential; D3-DST Decoy Session Token; D3-DF Decoy FileThe defensive techniques this guide implements
MITRE EngageLuresAdversary engagement activity
NIST SP 800-53 Rev. 5SC-26 Decoys; SI-4 System MonitoringControl basis for decoys and their monitoring
NIST CSF 2.0DE.CM-09, DE.AE-02, DE.AE-06Monitoring, analysis and sharing of adverse events
ISO/IEC 27001:2022 Annex AA.8.16 Monitoring activitiesDetection of anomalous behaviour
MITRE ATT&CK (detected)T1552.001 Credentials In Files; T1552.004 Private Keys; T1078.004 Cloud Accounts; T1087.004 Cloud Account discovery; T1580 Cloud Infrastructure Discovery; T1558.003 Kerberoasting (honey service principal names)Attacker behaviours a tripped canary reveals

Common failure patterns

  • Canaries with real permissions: a "decoy" key that can list buckets helps the attacker.
  • Alerts that go nowhere: a canary wired to a mailbox nobody reads, or a logging pipeline that drops failed calls.
  • Treating a trigger as a curiosity: rotating only the canary and not the real secrets beside it.
  • Obvious decoys: generic names, wrong key formats or every canary in one identifiable account.
  • No register: secret scanners raise canaries as leaks, engineers delete them, or responders waste hours confirming they are fake.
  • Never testing: provider log changes or a broken integration silently disable alerting for months.

Practitioner checklist

  • Create a decoy register: canary ID, type, placement, owner, creation date, last test.
  • Build zero-privilege canary identities in each cloud and key SaaS platform you use.
  • Place unique canaries in CI secret stores, runner images, admin endpoints, vault paths and backups.
  • Write one detection per canary type that fires on any use, including failed calls.
  • Route alerts to the SOC with the placement location and a link to the response runbook.
  • On trigger, rotate every real secret in the same location and investigate who could read it.
  • Test every canary at least every 90 days and replace tripped ones.
  • Exclude registered canaries from secret scanning remediation and orphaned-identity clean-up.

Standards and references

Related NHI Mgmt Group resources: Deception Technology Guide · ITDR Guide · Secrets Management Guide · Git Secret Scanning Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.