ggshield — Create Honeytokens

Overview

A honeytoken is a decoy credential that does nothing useful but raises an alert the moment someone tries to authenticate with it. Plant them in places attackers look (example configs, abandoned repos, internal wikis, deploy scripts) so any unauthorized read of that location triggers a notification on the GitGuardian dashboard.

ggshield honeytoken generates these decoys. For now, only AWS honeytokens are supported — they look like real AWS access keys but route to GitGuardian's monitoring infrastructure.

Core rule: every honeytoken must be planted somewhere an attacker might actually find. A honeytoken sitting only on the user's laptop is wasted. Always confirm the planting location with the user before generating one.

Start Here — Read This Before Doing Anything

Do not skip this section. Before you call ggshield honeytoken create:

1. Confirm the planting surface with the user explicitly. Ask: "Where do you want me to plant this?" If the answer is vague ("just somewhere"), surface the candidate list from the When to Use section — .env.example, pre-publication open-source repo, internal wiki page, deploy script, archived repo, container image, public artifact. Do not generate first and ask later.
2. Double-check the planting surface is not in the production import graph. If a teammate can import { fn } from './services/Foo' on the default branch and call it, your own CI will fire the honeytoken from real code. Prefer non-importable file types (.env, .yaml, .json, .csv, runbook pages), isolated directories (tests/fixtures/, examples/, archived/), or a non-default branch. Full tactics — including the "real to attackers, decoy to defenders" dual-audience principle — in references/planting-strategy.md → "Avoiding self-triggering".
3. Keep the honeytoken values out of the conversation. Always pass -o so ggshield writes the values straight to disk, and never read, print, or retype them. Never overwrite data that is already in the planting file. See Planting without exposing the values.
4. Always pass a meaningful --description. The alert fires months later, often to a different on-call. "planted in repo X / file Y on 2026-MM-DD" beats "test" by a wide margin. If the user doesn't supply one, propose one before generating.
5. Run Onboarding first if the CLI isn't set up. If ggshield --version fails, follow references/ggshield-cli-setup.md. If ggshield api-status doesn't show honeytokens:write in the Token scopes: line, walk through Onboarding (first use) below before attempting honeytoken create. The agent can drive the scope upgrade on the user's behalf — see references/gitguardian-platform.md.

When to Use

Proactively suggest a honeytoken when:

• The user is creating an .env.example, config.sample, credentials.template, or any "fill in your own keys" example file — these get copied, forked, and occasionally pushed publicly with real credentials by accident
• The user mentions open-sourcing or publishing a previously-private repository — plant before publication, then audit the alert feed
• The user is writing a deploy script, Helm chart, CI/CD workflow, or Dockerfile with placeholder credentials — replace the placeholder with a honeytoken so any future leak is detected
• The user is auditing exposure surface (Docker images, public artifacts, archived repos) and wants forward-looking detection
• The user is preparing internal documentation (Confluence, Notion, internal wikis, README runbooks) that references credentials — plant decoys there to catch credential exfiltration from those systems
• The user explicitly says "honeytoken", "canary token", "decoy", "tripwire credentials", or asks how to detect future leaks

For where to plant (concrete placement strategy, naming conventions, monitoring) see references/planting-strategy.md. For shared ggshield install, authentication, headless setup, CI tokens, and hook-install commands, see references/ggshield-cli-setup.md. For auth/scope recovery, instance URLs, headless setup, and the GitGuardian public docs URL pattern, see references/gitguardian-platform.md.

When Not to Use

Do not use this skill when:

• The task is to detect or remediate real secrets that already exist in code, files, or history — use scan-secrets. Honeytokens are decoys you plant, not secrets you find.
• The user needs a decoy for a provider other than AWS. ggshield honeytoken currently issues AWS-shaped tokens only; do not fabricate a fake key for another provider.
• The only available planting spot is somewhere an attacker would never look (a private local file the user alone sees). A honeytoken that no one can stumble on raises no alert and is wasted — confirm a real planting surface first.

Quick Start (if ggshield is already installed and authorized)

ggshield api-status                                      # verify the PAT includes honeytokens:write
ggshield honeytoken create --type AWS \
  --name "<planting-surface>-<YYYY-MM>" \
  --description "<where it was planted and why>" \
  -o <planting-file>

If api-status shows honeytokens:write is missing from Token scopes:, run the scope-recovery flow from references/gitguardian-platform.md (you can drive it on the user's behalf). If ggshield --version fails, follow references/ggshield-cli-setup.md first.

Onboarding (first use)

Prerequisites

ggshield honeytoken requires more than the standard scan setup:

1. GitGuardian role: the user must have Manager access level (or higher) on their GitGuardian workspace. Free tier and lower-permission seats cannot create honeytokens. Check via Settings → Members on the GitGuardian dashboard.
2. Personal Access Token scope: the PAT used by ggshield must include the honeytokens:write scope. Verify with ggshield api-status (the response lists active scopes).

If either is missing, ggshield honeytoken create exits with 403 Forbidden or "Insufficient permissions" — see Troubleshooting.

Setup

If the standard ggshield setup is already complete but ggshield api-status does not show the honeytokens:write scope, run the scope-recovery flow from references/gitguardian-platform.md with <required-scope> = honeytokens:write.

If ggshield itself is not installed or not authenticated at all, follow references/ggshield-cli-setup.md first, then run the scope-recovery flow if honeytokens:write is still missing.

Commands

Two forms — pick based on context:

# Bare honeytoken — just the credentials, no surrounding code
ggshield honeytoken create --type AWS --name <name> --description "<purpose>" -o <path>

# Honeytoken wrapped in a realistic-looking file (preferred when planting in code)
ggshield honeytoken create-with-context --type AWS --name <name> --description "<purpose>" --language python -o <path>

Use create-with-context when the honeytoken will live inside a code file — ggshield wraps the credentials in a plausible, language-appropriate snippet (e.g., a Python boto3 client setup, a Node.js AWS SDK init). The context makes the decoy look like a real, copy-pasted credential, dramatically improving its chance of being used by an attacker.

Use the bare create form when you just need the credentials to drop into a non-code location (a Notion page, a Confluence runbook, an .env.example line).

Key flags:

Exit codes: 0 = honeytoken created, non-zero = error (most commonly auth / permissions, see Troubleshooting).

Planting without exposing the values

A honeytoken looks like a real AWS key. Keep its values out of the conversation, transcripts, and logs, where a reader could trigger the decoy:

• Always pass -o <planting-file>. ggshield honeytoken create appends aws_access_key_id=... and aws_secret_access_key=... lines to the file and prints only the ID, name, and dashboard URL.
• If the file already has empty placeholder lines for these keys (for example AWS_ACCESS_KEY_ID= with nothing after the =), delete them first, then run with -o. Never delete or overwrite a line that has a value, even one that looks like a placeholder.
• Do not plant with the GitGuardian MCP generate_honeytoken tool. Its response contains the values.
• Do not open, cat, or retype the planted file.
• Do not label the decoy in the file. A comment such as "GitGuardian honeytoken" tells an attacker the key is fake. The dashboard name and --description already record where it was planted.
• Use create-with-context -o only with a path that does not exist yet. It replaces the whole content of an existing file.
• If the planting surface is only reachable through a tool call (a wiki or Notion page), write the honeytoken to a temporary file with -o and ask the user to paste the values in.
• Tell the user that their ggshield pre-commit hook will flag the planted file when they commit it. This is expected.

Best Practices

• Always set a meaningful --description. The dashboard alert shows it months later when someone trips the wire. "planted in repo X / file Y on 2026-05-21 by mathieu" beats "test" by a wide margin.
• One honeytoken per planting location. Don't reuse the same token in multiple places — when it fires, you want to know exactly which surface was compromised.
• Prefer create-with-context for code files. A naked credential string in a Python file looks fake; a boto3.client() call with the credentials inline looks real. Real-looking decoys catch real attackers.
• Plant in the source of truth. A honeytoken in .env.example only helps if devs actually use that template. Walk through the user's deploy story to find the real attractive surfaces (internal wikis, abandoned repos, deploy scripts, container images).
• Never plant a honeytoken anywhere your production import graph can reach. If a teammate can legitimately import the honeytoken-containing module from production code, the next CI run fires your own decoy. ggshield honeytoken create-with-context -o services/Foo.ts is a classic foot-gun — the file looks real to attackers, but also gets imported by real code. Plant in non-importable file types (.env, .yaml, .json, .csv, runbook pages), isolated directories (tests/fixtures/, examples/, archived/), or a non-default branch instead. Full tactics in references/planting-strategy.md → "Avoiding self-triggering".

Troubleshooting

403 Forbidden / "Insufficient permissions" — the current PAT lacks honeytokens:write, or the user is below Manager role.

The fix is the standard scope-recovery flow: ggshield auth logout + ggshield auth login --scopes honeytokens:write. See references/gitguardian-platform.md for the full procedure — both commands are runnable on the user's behalf, the OAuth flow handles scope upgrade without any manual PAT creation, and the same file covers the Manager-role caveat and headless login (--method oob first, with --method token as fallback).

--type is required — pass --type AWS. No other types are supported yet (this will change).

Any other or unlisted error — before improvising a fix, consult GitGuardian's AI-agent docs index at https://docs.gitguardian.com/llms.txt to locate the relevant page, then append .md to that page's URL to read it as Markdown. Search there first rather than guessing.