grith canary
Create and manage canary tokens for exfiltration trap detection.
grith canary [list | add | remove | rotate]Manage canary tokens — fake credentials placed in your filesystem that trigger a hard DENY if they ever appear in an outbound payload.
Subcommands
grith canary list
List all registered canaries.
$ grith canary list
Registered canary tokens (3):
6f1e... | aws-prod-decoy | 9c2f8a1b7d3e...
9c2a... | gh-org-trap | 4b7c1e9f2a8d...
3e8b... | ssh-honey | e21a7f0c94bd...Each row is the token id, its label, and the registered value. list takes no
flags — there is no --format json.
grith canary add
Register a new canary value in the detection set.
grith canary add --label <LABEL> (--generate | --value <VALUE>)| Option | Required | Description |
|---|---|---|
--label <LABEL> | yes | Human-readable name for alerts. |
--generate | one of these | Register a random 48-character hex token value. |
--value <VALUE> | one of these | Register a literal token value you supply. Cannot be combined with --generate. |
Example:
grith canary add --label "aws-prod-decoy" --generateThis registers the token and prints its id, label, and value. grith canary add
does not write any file — copy the printed value into whatever decoy file you
want an attacker to find (see Setting up canary tokens).
To make a convincingly shaped decoy, pass the shaped string yourself with
--value "<literal>".
grith canary remove <id>
Unregister a canary from the detection set. If you placed the value in a decoy file, delete that file yourself — the registry does not track file placements.
grith canary remove 6f1e...grith canary rotate <id>
Replace a canary's value while keeping its label, then update the registration. Use
after a suspected leak. Supply the new value the same way as add — --generate
for a random value or --value <VALUE> for a literal one (one is required).
grith canary rotate 6f1e... --generateRotation updates the detection set only; if you placed the old value in a decoy file, replace that file's contents with the new value it prints.
When a canary fires
The canary filter (11) returns DENY for any outbound payload containing a registered canary value. The audit log records:
- The canary id and label
- The session and process that tried to send it
- The destination
- The other filter contributions (for context)
Notification channels page on canary fires by default, regardless of the channel's normal rate-limit budget.
See also
- Canary tokens — concept
- Setting up canary tokens — placement strategy
- Canaries API — REST routes