Honeytoken types

GitGuardian offers two types of honeytokens. Both are real-looking credentials that grant access to nothing, and both raise the same alerts, events and tags when used. They differ in what the decoy is, where it is believable, and how you create it.

	AWS key	Kubeconfig
What the decoy is	An AWS access key ID and secret access key	A kubeconfig file with a cluster, a user holding a bearer token, and a context
Where it is believable	Source code, CI/CD variables, ~/.aws/credentials, wikis and tickets	~/.kube/config on developer machines, CI runners, deployment tooling
How to create it	Dashboard, API, Deployment jobs, ggshield	ggshield on an endpoint
What triggers it	Any AWS API call signed with the key	Any request sent to the API server address in the kubeconfig, for example a kubectl command
Availability	SaaS and self-hosted	SaaS only

AWS key honeytokens

An AWS key honeytoken is a real IAM access key pair, created in an AWS organization that GitGuardian operates. The key has no permissions. When someone uses it, AWS records the call and GitGuardian turns it into an event within minutes, carrying the IP address, user agent and the AWS action attempted.

AWS keys are the type to use for most placements: scanners and credential harvesters look for them first, and they are plausible in almost any file. Create one from the dashboard by following Getting started, or at scale with Deployment jobs.

Kubeconfig honeytokens

A kubeconfig honeytoken is a kubeconfig file: a cluster entry pointing at an API server address that GitGuardian operates, a user entry holding an opaque bearer token, and a context binding the two. It looks like the file kubectl writes for any cluster, and secret scanners, including GitGuardian's own Kubernetes Kubeconfig Bearer Token detector, pick it up as a live cluster credential.

The decoy cluster does not exist. Any request made with the file, whether kubectl get pods from an attacker's shell or a scanner checking the token, reaches GitGuardian and is recorded as an event on the honeytoken.

Progressive rollout

Kubeconfig honeytokens are rolling out progressively on SaaS workspaces. If ggshield honeytoken plant --type kubeconfig fails with You don't have access to this type of honeytoken, contact your GitGuardian account manager or support@gitguardian.com to enable it. The type is not available on self-hosted installations.

Create and deploy a kubeconfig honeytoken

Kubeconfig honeytokens are created when you plant them on an endpoint. ggshield asks GitGuardian for a honeytoken for this machine and user, GitGuardian mints one, and ggshield merges it into ~/.kube/config:

ggshield honeytoken plant --type kubeconfig

The decoy context, cluster and user are added next to the entries the developer already has, which keep working as before. On a machine with no kubeconfig yet, the decoy becomes the current context so that a stolen file works out of the box. On a machine that already has one, the current context is left alone: the owner's own kubectl must never trip the decoy.

The honeytoken then appears in Honeytoken > Honeytokens with the type Kubeconfig, and its detail page shows the full kubeconfig and the endpoint it was planted on. Deployment, verification and removal follow the same process as AWS keys on endpoints: see Protect endpoints with Honeytokens.

remarque

The dashboard and the POST /honeytokens API create AWS key honeytokens only. To place a kubeconfig honeytoken somewhere else than an endpoint, plant it on a machine first, then copy the kubeconfig from the honeytoken detail page. Give the honeytoken a description that says where you put it.

Test a kubeconfig honeytoken

Copy the kubeconfig from the honeytoken detail page into a file, then run any kubectl command against it:

kubectl --kubeconfig ./honeytoken-kubeconfig.yaml get namespaces

There is no cluster behind the address, so ignore what kubectl prints. Shortly after, an event appears on the honeytoken and its status switches to Triggered. Reset it afterwards, as for any test, so that you are alerted on the next real use. See Respond to a triggered honeytoken.

What a kubeconfig event tells you

For kubeconfig honeytokens, each event carries:

• Timestamp: when the request reached GitGuardian.
• IP address and country: where the request came from.
• User agent: the client that sent it, for example kubectl/v1.29.0.
• Action: the HTTP method and path requested on the decoy API server, for example GET /api. A single kubectl command can produce several events in a row, one per request it sends.

IP rules, the GitGuardian Public Monitoring IP tag and the public exposure detection apply to kubeconfig honeytokens exactly as they do to AWS keys.

Revoke a kubeconfig honeytoken

Revoking a kubeconfig honeytoken invalidates its bearer token: from then on, every request made with it is rejected. On the next ggshield honeytoken plant run, the decoy context is removed from the machine it was planted on.

Requests made with a revoked kubeconfig are still recorded as archived events, so you can see when a copy of the file is tried after the revocation. They do not trigger the honeytoken and do not send alerts.