Understand honeytoken events and trigger mechanism

An event in the context of honeytokens represents the recorded use of a honeytoken. When a honeytoken is in Active status, any new event will immediately change its status to Triggered, initiating the corresponding alerts.

Exception

The trigger mechanism differs for allowed events. See the related section for more details.

Events data

Events can be seen in the honeytoken detail page. Each event carries the following information:

• Timestamp: The exact moment of honeytoken usage
• IP address and country: Location information linked to the honeytoken usage
• User-agent: The accessing software's identity (may be blank).
• Action: What was attempted with the honeytoken. For AWS keys, the AWS action, like GetCallerIdentity or ListBuckets. For kubeconfig honeytokens, the HTTP method and path requested on the decoy API server, like GET /api.

See Honeytoken types for the details specific to kubeconfig events.

Events tags

Event tags provide additional context based on the event's IP address.

You can create custom tags using the IP rules settings. Furthermore, GitGuardian manages some default tags:

• GitGuardian Public Monitoring IP: Implies 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: Signifies the event originates from within AWS, commonly occurring when an AWS key honeytoken is publicly exposed on GitHub. Note that for this particular case there is no actual IP address attached to the event.

Open vs. archived vs. allowed events

Events can be categorized into three states:

• Open: The default state of events.
• Archived: Resetting or revoking a honeytoken archives all its open events.
• Allowed: Events from IPs on the allow-list, ignored by the trigger mechanism.

Archived and allowed events are still stored but hidden by default. Use the status filter in the Events section to view them. They are displayed in grey, with allowed events marked by a green tick next to the IP address.

Pausing events reception

When a honeytoken accumulates 100 open events, the reception of new events will be paused. We pause event reception at this threshold because additional events beyond this number are unlikely to provide new information and could negatively impact performance.

This situation typically occurs in the following scenarios:

• The honeytoken becomes publicly exposed on GitHub, causing scanners to detect and test it. In this case, the honeytoken should definitely be considered compromised, and revoked.
• Some internal and known tools regularly call the honeytoken for legitimate reasons. In this case, you may want to allow these calls and then reset the honeytoken.

Note that events reception will resume if the honeytoken is reset, as this action resets the count of open events to zero.

Using IP rules to enrich and manage events

IP rules help in declaring known IP ranges for better identification and management of events, serving two purposes: IP tagging and IP allow-listing.

IP tagging

The feature enables you to attach custom tags to events based on IP addresses, useful for identifying events from familiar sources like your company's internal network.

IP allowlisting

Each tag and its associated IP range can be added to an allowlist. Events from these IPs are ignored and do not trigger the honeytoken.

caution

Handle this feature cautiously as it might lead to overlooking unauthorized attempts on your honeytokens.

Events from allowed IPs are recorded but greyed out and excluded by default. You can opt to display them using the “status” filter.

IP rules configuration

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

While GitGuardian sets some uneditable rules, you can create and manage your own using valid CIDRs for IP ranges.

No retroactive application of the IP rule on existing events

Adding, modifying, or deleting IP rules won't affect existing honeytoken events. Only future events will be impacted.

Behavior in case of several rules for same IP range

Multiple rules for the same IP range are allowed. Events matching these rules receive all associated tags. If any rule has "allow-list" selected, those events will be considered 'allowed', except for events from GitGuardian Public Monitoring IPs, which cannot be overridden.