Skip to main content

Respond to a triggered honeytoken

GitGuardian helps you by providing as much contextual information as possible about the events and some guidelines.


The lifecycle of a honeytoken

The lifecycle of a honeytoken and the possible actions are shown in the following schema:

graph LR Active -...->|Event happens!| Triggered Triggered -->|Reset| Active Triggered -->|Revoke| Revoked Active -->|Revoke| Revoked

Investigate the events

An event is a recorded usage of a honeytoken.

Events data

For AWS key pairs, you get the following information:

  • Timestamp (when the honeytoken was used)
  • IP address and country
  • User-agent (may be empty)
  • Action performed (GetCallerIdentity, ListBuckets…)

Event tags

The purpose of event tags is to provide additional context for a particular event based on its IP address.

Some tags are added automatically by GitGuardian:

  • GitGuardian Public Monitoring IP: the event originates from an IP address used by GitGuardian to monitor public GitHub. This indicates that the honeytoken itself has been leaked and is publicly exposed on GitHub.
  • AWS internal IP: the event originates from AWS itself. This typically happens when the honeytoken leaks publicly on GitHub. Note that for this particular case there is no actual IP address attached to the event.

It is possible to create custom rules for IP tags, which can be managed from the Honeytoken settings page.

Managing custom rules for IP tags

To manage custom IP tagging rules, go to Settings > Honeytoken > IP tags.

This section displays all IP tagging rules that apply to Honeytoken events.

While some rules are managed by GitGuardian and cannot be edited or removed, it is possible to create and manage your own custom rules using valid CIDRs to define the IP ranges.

Create IP tagging rule IP tagging rules

Future events with an IP matching the defined rules will receive the appropriate tag: Event tag

No retroactive application of the tags on existing events

Whenever an IP tagging rule is added, modified or deleted, there is no effect on any of the honeytoken events that already existed. Only future events will be impacted.

Open vs. archived events

Resetting and revoking a honeytoken archives all the associated events. The archived events remain present, but they are hidden/greyed out. Use the status filter in the Events section to see them.

Reset a triggered honeytoken

If your investigation has determined that the trigger alert was a false alarm, such as when one of your developers genuinely tested the honeytoken, you should reset the honeytoken.

Resetting the honeytoken changes its status back to Active, allowing it to be triggered again on future attempts.

After resetting, your honeytoken is as good as new!


Revoke a triggered honeytoken

If your investigation has confirmed a real security incident, and you have taken the necessary steps to remediate the incident and ensure that your environment is protected, it is important to revoke the triggered honeytoken. This honeytoken is now compromised and thus useless.

Revoking the honeytoken will deactivate it entirely by deleting the associated AWS key pair. Events will no longer be logged on this honeytoken.


Remember to create a new honeytoken to replace the compromised one in order to be alerted of new incidents in the same environment!