Setting up canary tokens

Place canary tokens that prove exfiltration when they appear in outbound traffic.

A canary token is a fake credential placed somewhere an attacker might look. When it shows up in outbound traffic, grith denies the call and alarms loudly. See Canary tokens for the concept; this page is the practical deployment.

Step 1 — choose placements

Good canary placements are plausibly attractive:

Path	Why
`~/.aws/credentials_backup`	Looks like sloppy ops hygiene.
`~/secrets.txt`	Same.
`~/.env.backup`	Same.
`repo/test/fixtures/.env`	Looks like a careless test fixture.
`~/Downloads/aws-keys.txt`	Looks like a saved Slack message.
`repo/.env.production.bak`	Looks like a leftover from a deploy.

Bad placements:

Inside ~/.config/grith/ — agents don't read grith's config.
Read-only system paths the agent will skip.
Anywhere the agent has zero plausible reason to look.

Aim for 3–5 canaries, each in a different "category" of likely target. More than that and you get diminishing returns; fewer and an attacker might miss them.

Step 2 — add them

grith canary add --label "aws-prod-decoy" --generate
grith canary add --label "ssh-honey" --generate
grith canary add --label "gh-test-fixture" --generate

Each command registers a token and prints its value — grith canary add does not create files. Copy each printed value into the matching decoy path from Step 1 (for example, paste the aws-prod-decoy value into ~/.aws/credentials_backup). To plant a specific, convincingly shaped string instead of a random one, use --value "<literal>" in place of --generate.

Step 3 — verify

grith canary list

Should show your three canaries. Each is now monitored.

Step 4 — set up notifications

Canary fires are the highest-severity event grith produces. Make sure at least one notification channel handles them:

[notifications.channels.slack]
enabled = true
webhook_url = "..."
severity_map = { canary = "critical" }

[notifications.channels.pagerduty]
enabled = true
service_key = "..."
severity_map = { canary = "critical" }

See per-channel guides for the specific setup steps.

Step 5 — test (carefully)

To verify the canary detection works without actually firing a real one:

# Read the file (this is a sensitive-path-heuristic read, will probably quarantine)
cat ~/.aws/credentials_backup

# Approve in the digest
grith digest approve <id>

# Now simulate a network call with the canary token as payload
grith proxy test '{
    "operation": "network",
    "target": "https://example.com/test",
    "args": ["<paste-the-canary-value-here>"]
  }'

The proxy test should return decision: deny, with filter: canary firing. (The test is dry-run — it doesn't actually send the canary anywhere.)

When a canary fires

Investigate the originating session immediately:

grith audit --decision deny --limit 10
grith digest show <canary-event-id>

Terminate the session if it's still running:
```
grith supervisor kill <session-id>
```
Rotate the canary (and any nearby canaries — same attacker, same scan):
```
grith canary rotate <id>
```
Investigate what else the session touched. The audit log captures everything.