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
| Canary | How to build it | Signal source | Typical placement |
|---|---|---|---|
| AWS access key | IAM user with no policies (or an explicit deny-all) in a dedicated account; generate a key pair | CloudTrail 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 secret | App registration with a client secret and no role assignments or API permissions | Entra ID service principal sign-in logs | Config files, pipeline variables, automation scripts |
| Google Cloud service account key | Service account with no IAM bindings; JSON key file | Cloud Audit Logs and service account key usage | Build agents, notebooks, shared drives. See the Google Cloud Service Account Keys Security Guide |
| Source control or package token | A token on a bot account with access only to an empty repository or scope | Organisation audit log and token usage events | CI secrets, .npmrc, .git-credentials |
| SaaS API key | Key issued to an unused integration user with read-only access to nothing | SaaS admin audit log | Wikis, tickets, integration configs |
| Database login | Login with CONNECT only, or a fake connection string to a monitored listener | Database authentication logs | Application config, backup scripts, connection string files |
| Kubernetes credential | Service account with no RoleBindings, token in a Secret or kubeconfig | API server audit log (user.username matches the canary) | Namespaces, jump hosts, CI runners. See the Kubernetes Service Account Token Guide |
| Directory service account | Disabled-looking but enabled account, plausible name, never used, tagged as honeytoken | Domain controller authentication events, ITDR alerts | Scripts, scheduled task arguments, LDAP descriptions |
| Vault entry | A fake secret in the secrets manager under an attractive path | Secrets manager read audit events | Paths 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.
- 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.
- 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.
- Images and artefacts: a canary in base images and in build artefacts, which catches anyone mining your public or private registry.
- Collaboration tools: a canary credential in a wiki page titled like a runbook, and in a ticket.
- 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.
- 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-prodnext to real deployment config is convincing; a user calledhoneytoken1is 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
| Canary | Detection logic | Key fields to capture |
|---|---|---|
| AWS key | Any CloudTrail event where userIdentity.accessKeyId is in the canary list | eventName, errorCode, sourceIPAddress, userAgent, region |
| Entra service principal | Any service principal sign-in for the canary application ID | IP address, result, resource requested |
| Kubernetes | Any audit event for the canary service account username | verb, resource, sourceIPs, userAgent |
| Directory account | Any authentication or ticket request for the account; Defender for Identity honeytoken alert where used | source host, protocol, time |
| Vault path | Any read of the canary path | caller identity, client IP, auth method |
- Route to the SOC as high severity with the placement location in the alert, taken from the decoy register.
- 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.
- Find the reader: who and what can access the placement (endpoint, runner, repository, backup), and what else that identity touched.
- 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.
- 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
| Framework | Reference | Relevance |
|---|---|---|
| MITRE D3FEND | D3-DUC Decoy User Credential; D3-DST Decoy Session Token; D3-DF Decoy File | The defensive techniques this guide implements |
| MITRE Engage | Lures | Adversary engagement activity |
| NIST SP 800-53 Rev. 5 | SC-26 Decoys; SI-4 System Monitoring | Control basis for decoys and their monitoring |
| NIST CSF 2.0 | DE.CM-09, DE.AE-02, DE.AE-06 | Monitoring, analysis and sharing of adverse events |
| ISO/IEC 27001:2022 Annex A | A.8.16 Monitoring activities | Detection 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
- MITRE D3FEND: Decoy User Credential
- MITRE D3FEND: Decoy Session Token
- NIST: SP 800-53 Rev. 5 (SC-26 Decoys)
- MITRE Engage: Matrix
- Microsoft Learn: Defender for Identity entity tags
- AWS: STS GetAccessKeyInfo
- AWS: CloudTrail record contents
- Thinkst Canarytokens: AWS API Keys token
Related NHI Mgmt Group resources: Deception Technology Guide · ITDR Guide · Secrets Management Guide · Git Secret Scanning Guide