# how to set up canary tokens in your AWS account

## TL;DR
Plant fake credentials that no legitimate process should ever touch: an AWS key canary, a fake S3 object, or a DNS token from a canary-token service, each wired to alert you the moment it is used. Place them where an attacker poking around would trip them, like in an old config file or a tempting S3 bucket. A canary firing is high signal because false positives are nearly zero.

## The query
```text
how to set up canary tokens in your AWS account
```

## Use this when
- you want early warning that someone is poking around your AWS environment
- someone asks "how do canary tokens work" or "how do I detect intruders in AWS"
- you are building a deception layer alongside real monitoring
- you need a demo-friendly intrusion detection story for an audit

## Not for this skill when
- you need to detect the initial compromise vector (canaries catch lateral movement, not the first click)
- you have no alerting pipeline (a canary nobody hears is decoration)
- you want production data protection (canaries detect, they dont prevent)

## Steps
1. Pick a canary type: an AWS API key token, a fake S3 bucket object, or a DNS token, from a canary-token service or your own setup.
   Expected output: you have a token value and a unique alert destination for it.
2. Plant it believably: drop the fake key in an old-looking config file on a bastion host, or put the tempting document in an S3 bucket named like your backups.
   Expected output: the token sits where recon would find it but no legitimate job reads it.
3. Wire the alert: confirm the service notifies your alert channel when the token fires, and test it once yourself from a sandbox.
   Expected output: your test trip produces an alert within minutes.
4. Document each canary: where it lives, what type, who owns it, and the date planted.
   Expected output: a short registry so future you does not mistake your own canary for a breach.
5. Tell the incident team the canaries exist (but not the exact values or spots, beyond need-to-know).
   Expected output: responders treat a canary firing as a real intrusion signal, not a mystery.
6. Rotate periodically: replace tokens every few months and after any firing.
   Expected output: fresh tokens with the old ones retired in the registry.

### Variant: AWS key canary with CloudTrail
Use a real IAM user with zero permissions and a key you never use. Alert on any CloudTrail event mentioning that key. Any usage at all is the signal.

### Variant: S3 object canary
Put a file named like "backup-credentials.txt" in a bucket with access logging. Reads of that object fire the alert. Name it tempting but keep real secrets far away.

### Variant: DNS canary
A unique hostname that resolves through the canary service. Drop it in config files or internal docs; any lookup of it means someone read that file and tried the host.

## Why this happens
Attackers enumerate: they list buckets, read config files, and try credentials they find. A canary is a tripwire in exactly those paths. Because no legitimate workflow touches it, the signal-to-noise ratio beats almost any other detection.

## Edge cases and pitfalls
- Your own vulnerability scanners and asset inventory will trip canaries. Allowlist your scanners or place canaries off their paths.
- A canary in code that gets committed to a public repo fires constantly from scanners. Keep canaries out of public repos.
- One canary per account is not coverage. Plant several across the paths attackers actually walk.
- After a real firing, assume the attacker knows the trick and rotate all canary placements, not just the tripped one.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_jPfLswoCqohfZDjlvH1K4Q