CodeSecDays 2024 - Join GitGuardian for a full-day exploration of cutting-edge DevSecOps solutions!

Save my spot!

CodeSecDays 2024 - Join GitGuardian for a full-day exploration of cutting-edge DevSecOps solutions!

Save my spot!

Creating a pre-commit git hook & GitHub action with GitGuardian Shield to scan secrets

In this video, we will run through how to use GitGuardian Shield to create a pre-commit hook and GitHub action workflow to scan your commits for secrets. This tutorial aims not just to show the basics but explain what the tool is doing to help better understand where and how to implement secrets detection in other areas of the SDLC. GitGuardian Dashboard: https://dashboard.gitguardian.com GitGuardian Shield repository: https://github.com/GitGuardian/gg-shield0:00 Introduction 0:38 What is GitGuardian Shield 2:16 Getting set up with GitGuardian 5:01 Creating a pre-commit git hook 8:44 Ignoring secrets with GGShield 9:46 Creating a GitHub action workflow

Video Transcript

in this video i'm going to show you some of the features of GitGuardian Shield the open source cli tool to detect secrets from GitGuardian. We're going to go through how to set up a pre-commit hook into this and the different options that are involved with that and then we're going to take a look at how we can add the GitGuardian shield into our GitHub actions workflow. But first let's just take a tiny little bit of time and talk about exactly what is GitGuardian Shield and how it works and the pros and cons associated with adding this. Let's start by looking at exactly how GitGuardian Shield works.Well, GitGuardian Shield leverages the GitGuardian secret detection engine and it does this through the GitGuardian API. Now there's a couple of reasons why we choose to do it this way. Number one detecting secrets is very complicated. Yes you can detect high increased patterns or using regex to find prefix types of keys but being able to verify them as true positives and not false positives is quite difficult. You have to include a lot of weak signals and if possible you want to be able to verify this against the API provider, verify that the key is in fact valid and the best way to do this is to leverage the engine behind a powerful commercial tool. The other reason is that secrets detection is constantly evolving new types of secrets are being issued and we benefit from the massive amounts of data from GitHub to be able to update their detection patterns there are of course some cons of detecting secrets this way. Number one is that we need an internet connection. We're leveraging an API so we have to be able to send data externally but the end result is that you will be able to benefit from more powerful sequence detection than in other tools. But it's first important to understand and weigh up the pros and cons of different tools that are out there. But now we have that out the way and let's dive into what we can do with GitGuardian Shield. All right, let's start by getting our API key that will allow us to be able to send information to the GitGuardian detection engine. So to do this we need to go to dashboard.gitguardian.com. You can either log in with GitHub or create an account via email. I already have one so of course, so i'm just going to log in. Now I have no connected repositories to this. this is in the dashboard that you can connect your Github repositories to and scan them via this user interface but we're going to skip past all of that and go directly down to this button on the bottom that says API. Now down the bottom we're going to create a new API key. I'm just going to call this test key for video. Okay so now i'm just going to open up my directory and my terminal. I have here just a repository called "flash gordon". This is just a standard python project. Nothing special about it and i'm going to use this as the example for what we're going to do moving forward. So the first thing is i'm going to create is a .env file and this is where i'm going to paste our API key so we're going to name our API variable GitGuardian_api_key equals and what we just copied from the GitGuardian dashboard. One of the great things about GitGuardian Shield is that it's going to search for env file automatically to be able to try and find the API key within them but you can also set this up as an environment variable within your machine. However, you would do that normally but this is the simplest way so it's the way that I'm going to stick with. So now obviously the next step is we need to install GitGuardian Shield so I'm just going to quickly navigate to the GitGuardian Shield GitHub repository. Here in our readme, if you get stuck you can find helpful information and examples of cod. But what I'm interested is in the instruction installation guide and here we can see that it's using pip to install it. So you need to have python installed. To use pip I'm just going to quickly check that I have pip installed. So I can use the command pip3. Now the 3 verifier just refers to the version that we're up to at the moment and obviously as I do we're going to run the command pip3 install gg shield. And that's it, we're good to go. Now that we have GitGuardian Shield installed we're going to move on to the next step which is setting up a pre-commit git hook. Now a pre-commit git hook will prevent any commits from going through if that commit contains a secret. Now it's really important to know that if a secret makes into your git repository it needs to be considered compromised. A pre-commit hook prevents them getting there in the first place therefore the cost of remediation is nearly null. Now that we have GitGuardian Shield installed and our API key in a env file we can navigate over to the GitHub gg shield repository. Scroll down to install command and we'll see that we have some options for installing a pre-commit hook. Now the first option we need to decide on is whether or not we want to install a pre-commit hook locally or globally. The difference is that local means it's going to be installed on the repository that you're navigated within. So just a singular repository and globally means it's going to be installed throughout all of your repositories. We can very quickly see what this looks like if I navigate into my directory and I open up the hidden folder here: .git and go into hooks you'll see that some example git hooks that are in there. Now if i run the command ggshield install m for mode and local you'll see it successfully install the pre-commit hook and we can see that here this is the pre-commit hook that's going to be run. Now if I delete this and I instead run the command ggshield install dash m global, you'll see that it hasn't added anything into this folder and that is because if I navigate into the root directory of my computer of my machine you'll see another .git folder that's hidden here with again a folder that says hooks was decided and here we see the pre-commit hook. So this is where the global pre-commit hook lives as compared to the local pre-commit. So now we have everything installed let's check to see if it works as expected so I'm going to open up a file called python server and this is going to open up just an example a python observer file and in here we can see a variable contributed slack key. So at the moment this has a placeholder but we're going to remove this and put in an example slack key. Now this isn't a real key but it's close enough to trigger our detection engine so now what I'm going to do is I'm going to add this into a commit so git add python ui and then we're going to commit this and you'll immediately see that we get a report in our console. Iit says here that it has detected a slack user token and it told us that this is on line 10 and it's a change between this and this. And as we can confirm yet on line 10 we have our slack token so we can see that our pre-commit hook is working. but if this secret is false or we want to live dangerously and just commit into our repository anyway while we can ignore this with a simple command ggshield ignore last found Now what this command does is it actually creates a yaml file within our repository we can see right here .gitguardian.yaml. Now if I open this up you can see here this is not actually our secret it's our show token but this means that in the future GitGuardian is going to ignore this particular slack key so now if I want to commit this, we can see that this has been committed fine and I can then push this into my repository where I now have a select token and there we have it that is how to install a pre-commit hook. Now next we're going to use GitGuardian Shield to be able to set up a GitHub action or GitHub action workflow to scan our secrets on push. So to do this we can either navigate to GitHub itself and do it within the repository interface by clicking on actions and setup new workflow. But in this case, we're going to do it just on our local machine here so first we need to create a new directory called .github then we need to create a directory inside this called workflows and finally, I'm just going to create a file called main .yaml and we can open up this now if we navigate back over to the gg shield repository in GitHub. And we go down to GitHub actions you can see that there is already the code needed to be able to set up this action so we're just going to copy this and go backpaste it into a main.yaml. So now we're going to push these changes into our repositories which will update our actions workflow automatically. so now that we can see we have this folder .github workflows and our main.yaml file is within there and if we go over to actions we can see here that it's already added in this action but we have an area here so if we click on this and look at where this is failed you see this message error GitGuardian API key is needed. Now obviously we don't want to push our env file we've created into our git repository. There's a much more secure way to handle secrets within GitHub so we navigate over to settings, go down to secrets here we can create a new repository secret so GitGuardian now value is the same API key we used before. go ahead and add that secret. Now if we go back to our code we can check to see that this GitHub action is working. So now what you'll remember is that we added the secret to our GitGuardian ignore file by ignoring the last one but we're only ignoring it locally so that means that if I have GitHub actions installs it's like another layer of defense to ensure that the secrets get picked up. So let's go ahead and push this and see what happens. So git add, git commit. okay so now we've put this file with an active secret into git repository and if we go into here and we click over to actions we'll see that we're running an action on the commit we just made updating server. So let's go ahead and wait for this to finish it should take about a few seconds now what we can see now that it's finished running is that we get another error here. So if we click onto this, click on GitGuardian scan we can see that it's failed here but this time it hasn't failed because of the API key it's failed because of the slack user token so we can see this here. and we get basically the exact same response now obviously if you're the owner of the repository at this point you now can take action. You can decline the merge request if it's one you can see that it's failed, so you know that something's wrong. The next question you might be asking is that well if we ignore this file locally in our pre-commit hook then we obviously want to ignore it in our GitHub workflows and yes that's probably correct this was just for a demonstration and all we need to do to ignore this in in our GitHub actions workflow. Check as well is just to add in that GitGuardian yaml file that contains the ignore sha so we're going to do that right now I'm going to go gitadd.gitguardian.yaml and we're going to push this into our repository as well now if we push the same file again so we make an arbitrary edit resave this file and now make another adjustment gitadd server.py gitcommit and we push this into our remote repository. we can now go back to our GitHub actions we can see here that when we updated the ignore file the check run went through smooth and because I've updated the ignore file for GitGuardian we shouldn't get an error on this check run as well. But let's find out and as you can see this here has passed no problems because that secret is now in our ignore file. there we have it that's how you can add GitGuardian Shield into your GitHub action workflow.