A canary is a decoy secret. It sits among your real secrets and looks like any other, but nothing of yours should ever read it. Its value is generated for you and you never set it, so a read is a sign that something is going through your secrets that should not be.
Plant a canary#
In an environment, select the
+at the top right of the secrets table and choose Canary.Give it a name a stray reader would reach for, such as
AWS_SECRET_ACCESS_KEY, and create.
That is all it needs — the value is generated for you, and the canary is armed the moment it is created.
What happens when it is read#
When one of your machines reads an armed canary, that machine is disabled at once and loses access to your Burrow on its next request. It keeps its identity and its grants, so once you have looked into what happened you can turn it back on from the Machines page. The machine is still handed a value, so whoever is going through your secrets has no sign they tripped anything.
The read and the disable both land in your audit log, naming the machine, so you can see which one it was and shut down whatever is using its credentials.
Arm and disarm#
A canary is armed by default. Disarm it from its row to record reads without disabling anything, and Arm it again whenever you want. Its row shows whether it is armed and how many times it has been tripped.
Revealing a canary yourself never trips it — only a machine read does. Its value is fixed when the canary is created and cannot be changed.