Protect endpoints with Honeytokens

Honeytoken protection places a decoy AWS credential on each developer machine. The credential grants no access to anything, so nobody has a legitimate reason to use it. The moment someone does, GitGuardian raises an alert that tells you which machine was compromised.

Why plant honeytokens on developer machines

Endpoint scanning inventories the credentials that are already on a machine. Honeytoken protection adds intrusion detection to that same deployment, so you also learn the moment someone tries to steal them.

Credential harvesters are programs that search a machine for saved credentials and send them to an attacker. They reach developer machines through malicious packages, trojanized tools, and rogue browser extensions. Their behavior is predictable: read the well-known credential locations (.env, .gitconfig, .npmrc, etc.), and exfiltrate whatever is there. Planting a decoy in exactly those locations means the attacker's first move is what gives them away.

This gives you a few things that are hard to get from any other detection layer:

• A signal with no ambiguity. The decoy has no legitimate use, so any use of it is unauthorized by definition. There is no baseline to learn, no tuning, and no signature list to keep current.
• A last line of defense. If malware has already slipped past your EDR and other endpoint controls, using the decoy still exposes it.
• A named machine to investigate. The event carries the IP address, user agent, and timestamp, and the honeytoken resolves to a specific endpoint and its owner, which is where an investigation actually starts.
• Coverage you can measure. The dashboard reports the share of your fleet that is protected and lists the endpoints that are not, so this is a program you can drive to completion rather than a best effort. See Monitor coverage.
• No extra agent to deploy. Planting reuses the ggshield binary you already install for scanning and writes a file rather than running a resident process, so there is nothing new to certify and no ongoing cost on the machine.

For developers, planting is unobtrusive. It only ever touches its own profile and leaves every other AWS profile on the machine untouched.

How planting works

The ggshield honeytoken plant command reconciles the machine against GitGuardian on every run. It asks GitGuardian what the desired state is for this endpoint, then applies it to disk:

• For an active honeytoken, it writes or refreshes the decoy AWS credential profile.
• For a honeytoken you revoked in GitGuardian, it removes that profile from the machine.
• Any other profile in the file is preserved.

ggshield never revokes a honeytoken by itself. It applies the desired state and reports back where the honeytoken landed. Revoking stays a deliberate action you take in GitGuardian, which means a cleanup on one machine can never disable a tripwire you still rely on.

Because the command reconciles rather than appends, running it repeatedly is safe. A machine that has already been planted stays as it is.

remarque

Planting requires the honeytokens:write scope on the token that ggshield uses. This is not the same as honeytokens:check, which exists so that endpoint scanning does not trigger your own honeytokens when it encounters them. A fleet doing both needs both scopes.

Deploy honeytoken protection

Honeytoken protection is deployed the same way as scanning, through your MDM, and the two are independent. An endpoint can be scanned without being planted, and the dashboard reports each separately.

You have two options for scheduling, and both are valid:

• Add the plant command to the job that already runs your daily inventory scan.
• Run it as its own MDM job on a lower frequency, since the desired state changes far less often than scan results.

For the token setup, the MDM job patterns, and the scheduling detail, follow Deploy ggshield at scale with a service account token.

To plant on a single machine:

export GITGUARDIAN_API_KEY="<SAT_FROM_SECRET_STORE>"
export GITGUARDIAN_INSTANCE="<GITGUARDIAN_INSTANCE_URL>"

ggshield honeytoken plant

To see which targets would be written without contacting GitGuardian or touching the disk, use a dry run first:

ggshield honeytoken plant --list-targets

For the full option list, including how to override the profile name and target a specific user, see the ggshield honeytoken plant reference.

Verify that a machine is protected

Open the endpoint in Endpoint protection > Endpoints and check the Honeytoken protection card, which shows the latest sync, how many honeytokens are deployed, and how long the machine has been protected. The Honeytokens tab lists each one with its placement method, status, and when it was planted and last synced.

A machine that shows no recent sync is a machine whose plant job is not running. Because the command reconciles on every run, a stale sync also means a honeytoken you revoked may still be sitting on that disk.

Audit your endpoint honeytokens at scale

To review every honeytoken planted across the fleet, go to Honeytoken > Honeytokens and filter on Source type is Endpoints.

Opening one shows where it lives. The Sources card resolves the honeytoken to a machine and its owner, names the on-disk profile it was written to, and marks it as Planted.

For everything else you can do from this view, such as tagging and filtering, see Manage your population of honeytokens.

Remove a honeytoken from a machine

Removal is a two-step process, by design:

1. Revoke the honeytoken in GitGuardian, which is what stops it from being a live tripwire. See Respond to a triggered honeytoken.
2. Let the next plant run remove it from disk. To run a cleanup pass that only applies removals and writes nothing new, use ggshield honeytoken plant --remove-only.

This is also the rollback path. Disabling the plant job stops new placements, and a --remove-only pass clears what is already there.

When a honeytoken is triggered

A triggered honeytoken on an endpoint means someone used a credential that only exists on that machine as a decoy. Treat the machine as compromised and investigate from there.

Honeytoken alerting and response work the same way regardless of where the honeytoken was planted:

• Configure your alerts to route events to email, Slack, Microsoft Teams, or a webhook.
• Understand honeytoken events and trigger mechanism for what each event tells you.
• Respond to a triggered honeytoken for the reset and revoke workflow.