Keshav Malik

Keshav is a full-time Security Engineer who loves to build and break stuff.
He is constantly looking for new and exciting technologies
and enjoys working with diverse technologies in his spare time.
He loves music and plays badminton whenever the opportunity presents itself.

In today's digital world, protecting our code is more important than ever. Whether we're dealing with GitHub, GitLab, or Bitbucket, we need to ensure that our Source Code Management (SCM) repositories are only accessed by trusted people and services.

Why? Because these repositories are like treasure troves, filled with valuable code that makes our software tick. If someone with bad intentions gets in, they could steal that code, tamper with it, or even bring our operations to a halt.

That's where honeytokens come into the picture. These clever security tools act like tripwires in our code. They look like valuable targets to intruders, but in reality, they are traps. When touched, they send us an alert, letting us know someone is trying to sneak around where they shouldn't be.

In this guide, we'll explore how honeytokens can help protect our SCM repositories. We'll walk through how to create a Honeytoken with GitGuardian and how to add it to our GitHub, GitLab, and Bitbucket repositories. So, let's dive in and learn how to turn the tables on any potential intruders

Cracking the Code: What Are Honeytokens?

Honeytokens are essentially digital traps. These traps are set to lure cyber attackers who, believing they've discovered valuable data like a password or an API key, attempt to use it. However, the honeytoken isn't a real credential. Instead, it's a decoy designed to alert you to the intruder's presence as soon as they try to use it. Think of it as a silent alarm system for your repositories.

How Honeytokens Catch Intruders

A honeytoken's primary job is to sit quietly and wait. They're placed strategically in areas that might attract unauthorized access, such as code repositories or CI/CD pipelines. If an attacker stumbles upon the honeytoken and tries to use it, that's when it springs into action.

The use of the honeytoken instantly alerts the security team, providing crucial information about the breach, including the intruder's IP address and the time of the attempted access. In a nutshell, honeytokens help turns the tables on cybercriminals, turning their attempted intrusion into an opportunity for you to spot a security gap.

The Advantages of Using Honeytokens

Whether it's a GitHub, GitLab, or Bitbucket repository, a honeytoken can offer several significant benefits. One of the primary benefits is the early detection of data breaches. By alerting the security team the moment an intruder attempts to use the honeytoken, you can respond quickly to potential threats.

How to Create a Honeytoken Using GitGuardian

Honeytokens can be created and managed entirely through the GitGuardian dashboard. Follow the guide to get started creating your first honeytoken!

How to Create and Use Honeytokens: Step-by-Step Instructions
Learn how to create, test and deploy GitGuardian honeytokens to detect security breaches, strengthen supply chain security, and prevent code leakage. Find out where to place honeytokens to effectively deceive attackers and protect your assets.

Adding a Honeytoken to Your SCM Repositories

When it comes to adding honeytokens to your repositories, strategic placement is crucial. You'll want to choose files or locations that may typically contain sensitive data, encouraging any potential intruders to take the bait.

Make sure each honeytoken is unique to each repository. This allows you to determine the exact breach point if a Honeytoken is triggered. With this approach, you’ll gain comprehensive insights into potential system vulnerabilities.

GitHub Honeytokens: Adding a Layer of Defense

To deploy a Honeytoken in a GitHub repository, follow these steps:

  • Go to the GitGuardian dashboard, and create a honeytoken.
  • Once created, copy your honeytoken.
  • Navigate to your GitHub repository, and choose a location to place the honeytoken. A sample location might be within a .env or config.yml file where sensitive data could typically be found.
  • Paste the honeytoken into the chosen location and save the changes.

GitLab Honeytokens: A Step Towards Greater Security

Here's how you can add a Honeytoken to your GitLab repository:

  • Start by creating a honeytoken in the GitGuardian dashboard.
  • Once your honeytoken is ready, copy it.
  • Open your GitLab repository and pick a location where you'd like to place the honeytoken. A potential location could be inside a Dockerfile or ci.yml file that an attacker might typically scrutinize.
  • Paste your honeytoken in the selected location and save your changes.

Bitbucket Honeytokens: Secure Your Code Base

Follow these steps to implement a Honeytoken in a Bitbucket repository:

  • Create a honeytoken from your GitGuardian dashboard.
  • Copy your newly minted honeytoken.
  • Head over to your Bitbucket repository, and identify a suitable location for the honeytoken. You might consider placing it in a secrets.json or credentials.xml file, where sensitive data is typically stored.
  • Insert the honeytoken at your chosen spot, and remember to save your changes.

Adding a Security Boost to Azure Repos with Honeytokens

Adding a honeytoken to your Azure Repositories can add a layer of extra protection. Here's a simplified process of how to do it:

  • Head over to your GitGuardian dashboard, and create a Honeytoken. Once your Honeytoken is ready, go ahead and copy it.
  • Go to your Azure Repos and select the repository where you want to place your Honeytoken.
  • Find a suitable place to put your Honeytoken. A good example could be an appsettings.json or a Web.config file, where sensitive information often resides.
  • Paste the honeytoken: Now, all you need to do is paste the honeytoken into your chosen spot and save your changes.

Staying Alert and Ready with GitGuardian

When it comes to safeguarding your SCM repositories, staying ahead of potential threats is crucial. And that's exactly what honeytokens help you do. But, these decoy secrets are only half the battle. The real strength lies in effective monitoring and the ability to react quickly when these honeytokens are triggered.

The Power of Prompt Notifications

So, what happens when a mischievous intruder stumbles upon one of your honeytokens and tries to use it? As soon as this occurs, an event is created in your GitGuardian dashboard. This event isn't just a bland alert; it's a treasure trove of valuable information.

The event details include the IP address, action, timestamp, and user agent associated with the attempted intrusion.

In addition, in the case of honeytokens deployed in Git repositories integrated with GitGuardian, the source file and repository where the honeytoken is placed is automatically detected and displayed.

On the Perimeter page, the number of deployed honeytokens is displayed for each source along with their status (active or triggered) and also if any have been found “Publicly exposed,” which means the honeytoken was detected on a publicly exposed repository.

This information could provide key insights into who the intruder might be and how they're attempting to gain unauthorized access. It could also help you and your security team uncover their modus operandi.

Real-time Updates via Email

But what if you're not constantly monitoring your GitGuardian dashboard? Don't worry, we've got you covered. In addition to the dashboard alert, GitGuardian promptly emails you about the triggered honeytoken. This means that even if you're not actively monitoring your dashboard, you'll be immediately alerted about the intrusion attempt.

Seamless Integration: Honeytoken Alerts and Custom Webhooks

Along with these prompt notifications, GitGuardian also allows the configuration of custom webhooks to receive alerts when honeytokens are triggered or when a new event is recorded. This makes it possible to integrate the information directly into your Security Information and Event Management (SIEM) system or other security systems, ensuring seamless communication and response.

You can create dedicated webhooks or use the same ones for secrets detection events, refining the "Event Subscription" scopes as needed. The available event subscriptions are:

  • Honeytoken > Triggers: Receive a webhook event whenever the status of a Honeytoken changes to 'Triggered.'
  • Honeytoken > Events: Receive a webhook event whenever a new Honeytoken event is recorded.

Whether it's a triggered honeytoken or a new event, the payload structure for webhooks is consistent and easy to understand, making it simpler for you to manage your security response.

Concluding Thoughts

Remember, the beauty of honeytokens lies in their ability to be silent watchdogs in your SCM repositories. When placed strategically, they allow you to identify security breaches in real time. Coupled with the robust monitoring and alert system of GitGuardian, you'll always be one step ahead, ready to act swiftly and decisively to secure your repositories.

In the next section, we'll discuss some best practices to ensure you're making the most of Honeytoken in your SCM repositories.

Getting the Most Out of Your Honeytokens

Adding honeytokens to your SCM repositories is a fantastic way to boost your security game. But to get the most out of them, there are a few best practices you should keep in mind:

1. Make Honeytokens Part of Your Overall Security Strategy

Honeytokens are a powerful tool, but they work best when used as part of a broader security strategy. So, while you're laying these traps for potential intruders, remember to keep up with other security practices, like regularly updating and patching your software, implementing strong access controls, and educating your team about security threats.

2. Work Closely with Your Security Team

When a Honeytoken is triggered, quick action is crucial. Ensure your security team is prepared to respond swiftly to these alerts. They should know exactly what steps to take to lock down your system and investigate the breach.

3. Use Unique Honeytokens for Each Repository

Using a unique Honeytoken for each repository helps you quickly identify which repository may have been compromised when an alert is triggered. If the same Honeytoken is used in multiple locations, it becomes harder to pinpoint exactly where the breach occurred.

4. Carefully Choose Your Honeytoken Locations

Place your honeytokens in locations where they will be attractive to an attacker but will not disrupt the workflow of your team. Remember, you want the Honeytoken to be found by a potential intruder but not accidentally stumbled upon or used by a member of your team.


We've taken a deep dive into the world of honeytokens and learned just how valuable they can be in protecting your SCM repositories. But the most crucial takeaway from all of this is that in the realm of cybersecurity, being proactive is key. And that's precisely what honeytokens help us do.

Using honeytokens, we set up a safety net, luring potential intruders into traps that not only alert us to their presence but also give us valuable information about them. It's like having a security camera that not only catches thieves in the act but also calls the police for you!

But as fantastic as honeytokens are, remember, they're just one piece of the puzzle. To truly secure your SCM repositories, it's essential to have a robust and comprehensive security strategy. Regularly review your practices, keep your team educated about the latest threats, and always be ready to adapt and evolve. You can read more about securing GitHub repositories in this guide (with actionable insights for other SCMs as well):

GitHub Security 101: Best Practices for Securing your Repository
DevSecOps expert and GitHub Star Sonya Moisset shared with us her tips to improve your open-source repository’s security in a few simple steps.

Now that you're well-versed in the world of honeytokens, it's time to put this knowledge into action. If you haven't already, sign up for GitGuardian and start setting up your own honeytokens. And remember, the GitGuardian team is always here to help you along the way.

Join us for a 20-minute live demo of GitGuardian Honeytoken with our in-house experts Dwayne McDaniel and Jason Miller. Come and see how GitGuardian can help you safeguard your software supply chain with Honeytoken!

See upcoming sessions