Honeytokens with ggshield: plant tripwires that alert on secret use

In this video, we introduce ggshield honeytoken and why it’s one of the most powerful tools in the GitGuardian toolbox.

https://docs.gitguardian.com/ggshield-docs/home

https://docs.gitguardian.com/honeytoken/home

A honeytoken is a decoy secret that alerts you the moment someone tries to use it or validate it. Think of it like a digital tripwire. In GitGuardian, honeytokens can be created through the dashboard or API, and they look like real AWS keys because they are valid credentials. The difference is they grant zero access and are isolated to an AWS account GitGuardian maintains specifically for this purpose.

You’ll manage honeytokens in the GitGuardian workspace or via API, but ggshield lets you generate and plant honeytokens directly into your local files to make them realistic and trackable.

Before we create one, we cover permissions and limits. As of the making of this video, ggshield honeytoken is restricted to users with Manager or Owner permissions. If you’re on the Starter plan for personal work, you can create and manage up to 5 honeytokens.

We’ll also fix a common gotcha: if you authenticated earlier via browser login, your token was likely scoped for scan only. To create honeytokens, you need additional scopes: honeytokens:write (which also includes honeytokens:read).

You can do this in two ways:
Create a new personal access token with scan + honeytoken permissions, then log in using:
ggshield auth login --method token
Or re-run browser login with expanded scopes using:
ggshield auth login --scopes honeytokens:write
If you’re already logged in, you’ll need to log out first:
ggshield auth logout

Once permissions are set, we’ll create honeytokens locally using the two options in the help menu:
create generates the decoy credentials and prints them to your terminal along with metadata and a link back to the honeytoken in your GitGuardian workspace
create-with-context generates a realistic file containing the honeytoken so it blends into code more credibly

We’ll run both so you can see the difference, including naming your honeytokens to keep them organized:
ggshield honeytoken create --name DemoVid1 --type AWS
ggshield honeytoken create-with-context --name ExampleForVideo --type AWS

For create-with-context, the output won’t print the honeytoken itself. Instead, it confirms placement and shows you where it was written, plus the dashboard link so you can track it.

We’ll also cover optional flags like adding a short description, choosing a language for the generated file, and setting a custom output filename.

Final reminder: honeytokens are meant for private environments only, like private repos and internal systems. If you expose one publicly, it won’t take long before the tripwire fires and you start getting alerts.