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, the information we get are the following:

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

Event tags#

For some of the events, GitGuardian will automatically add a tag to the record whenever we can identify the origin of the event.

The existing tags are the following:

  • AWS internal IP: events triggered by AWS themselves. That happens when the honeytoken leaks publicly on GitHub.
  • Publicly exposed: events triggered by GitGuardian Monitoring of public GitHub, which indicates that the honeytoken itself has been leaked and is publicly exposed on GitHub.

After investigation, if it is a false alarm, the honeytoken can be reset. However, if it is a real incident, the honeytoken can be revoked.

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!