We are very proud of the work we put into the GitGuardian dashboard UI, helping security teams find secrets and remediate incidents. However, we understand our users need a way to programmatically call the platform from their Python, Powershell, or Bash scripts.

This is why we built ggshield, the GitGuardian command line interface (CLI), to extend the power of our secrets detection platform to the terminal. Another goal was to empower development teams to "Shift Left" and introduce security scanning earlier in the software development lifecycle.

We have previously released a guide and cheat sheet for using ggshield, giving an overview of how commands are structured and the basics for using our CLI. It also covers authentication and leveraging Git hooks to automate secret detection. If you are new to ggshield, we highly recommend reading that article next.

Since we published that guide and cheat sheet, we have been hard at work to make ggshield easier to use and more powerful. Let's take a look at some recent updates to our command line tool and learn some tips and tricks along the way.

ggshield

Easier to get started with ggshield

Early versions of ggshield relied on Python's pip or Mac's homebrew to install the tool. While these options are still available, we listened to our customers, who asked us to make it simpler to install on Mac and Windows, especially in managed environments where those package managers might not be available.

Windows users can now download a standalone executable. Everything you need is already included. Just download the latest windows-msvc.zip and unzip it wherever you prefer. Then, find the ggshield.exe waiting for you. 

MacOS users can now install .ggshield using our new signed packages. Download the latest .pkg, file and use the official Mac Installer to get up and running in record time. It's that simple.

Customize pre-commit remediation messages

The best time to spot a hardcoded credential is while it is still on the developer's machine before that secret enters the Git history. That is also the least expensive step in the SDLC to remediate a plaintext secret. This is why we make it easy to scan at the pre-commit stage of the git workflow with ggshield secret scan pre-commit. 

Developers can set up either a global Git hook that works across all their repos or a local Git hook, isolating the script to a single repo using the ggshield install command. We can also automate scans at the pre-push and pre-receive events as well. You can read more about our Git hooks in the original ggshield guide.

We have always offered some helpful general remediation advice to all users if a secret was detected when using Git hooks. We are happy to report that workspace managers can now provide custom remediation messages specific to using automated secret scanning at the pre-commit, pre-push, and even pre-receive steps of the git workflow.  Now, at the exact moment that information is most valuable to the developer, it has never been easier to share internal resources, such as company guidelines, links to documentation, or even instructions on properly utilizing your secrets manager of choice. Read the full documentation for customizing your remediation messages here.

Note: If your team is using a version of ggshield earlier than version 1.30, everyone will need to update to the latest version to make use of custom remediation messages.

News about secret scan - our most popular command

Before talking about the latest updates, let's take a moment to celebrate how users interact with the most popular command, ggshield secret scan.  Every day, thousands of workflows and individual developers make this call to our platform via the CLI. This base command command lets you scan a variety of sources for over 400 types of secrets.

ggshield usage report

Automated guardrails 

We built a CLI, in part, to empower teams to build guardrails into their software development processes. We are happy to report that a full 83% of scans for secrets involve automation. We have also heard from some customers that since it is so easy to run ggshield commands programmatically, they have also added scanning into all sorts of custom local automation scripts.  

The most popular way by far that people invoke ggshield is with ggshield secret scan ci. This command is designed to run inside of your continuous integration (CI) system, such as GitLab Runners, GitHub Actions, Jenkins, and CircleCI, to name just a few. 

ggshield secret scan changes

One recently added option for calling GitGuardian is the ggshield secret scan changes command. This powerful new changes parameter allows you to scan for changes between the current state of a repository that has been checked out and the default branch, most commonly the main branch. It is now easier than ever to check for secrets in the branch you are about to merge or rebase into your default branch, which is most likely the branch headed toward production.

Honoring .gitignore with secret scan path

While ggshield can scan the entirety of a repo, including all commits and branches, a more popular command is  ggshield secret scan path, which only looks at the current state of any files you scan. However, not all files in a directory might tracked with Git. A good example is a local .env file. It is very common to tell Git to simply ignore these files by listing them in .gitignore.

Until recently, scanning an entire folder also meant scanning these ignored files, which might purposely contain API keys or passwords used for local development. Now, users can use the --use-gitignore option to honor .gitignoremore and skip scanning those related files. It is one moe way we are trying to empower users who embrace differing development workflows.

The help menu for ggshield secret scan path showing the --use-gitignore option

Creating Honeytokens

Once we added Honeytokens, the cyberdeception tool, to the GitGuardian platform, users wanted an easier way to generate them without opening a browser and logging into their GitGuardian dashboard. They also wanted a better way to leverage these decoy credentials in a more automated way. We listened. 

With ggshield honeytoken create, anyone can create a new AWS-based honeytoken with just a few keystrokes. Running the command returns the decoy credential, which is ready to be copied into your code, project management tooling, communications platform, or any other private environment. Don't worry; scanning a GitGuardian Honeytoken with ggshield won't set off any alarms, as the platform knows how these are safe, even if they appear to be real credentials. 

You can create a honeytoken inside a file with a name that might realistically appear in your project with  ggshield honeytoken create-with-context. Adding a honeytoken within a relevant context makes it look more credible, making an attacker less likely to catch on that there is any cyber deception at play. 

ggshield honeytoken help menu

HasMySecretLeaked

One of the most popular free tools we have created at GitGuardian is HasMySecretLeaked (HMSL). This tool lets you quickly and safely check if one of your credentials has been spotted in a public GitHub repo. You can read more about that tool in the HMSL announcement blog post. 

We are proud to say that GitGuardian CLI users can leverage this tool from their terminal thanks to the ggshield hmsl command. You can fingerprint any secret, creating a short snippet of an encrypted hash and then safely check it against our database of publicly exposed plaintext credentials. 

One of the most powerful options in this command is,check-secret-manager, which safely checks all the secrets stored in your secrets vault. Currently, this integration only supports Vault by Hashicorp. We would love to hear from you about which secrets manager we should support next.

HasMySecretLeaked

SARIF output

There is no one true path to reporting, triaging, and fixing security findings. The market offers many solutions to manage cybersecurity threats, and many teams also build custom software solutions that gather and use the data provided by all their security scanning tools. 

By default, the standard output format for any ggshield command is simple text delivered via stdout directly in the terminal. Given how many users rely on automation, they requested a more transportable format so that output could be ingested by another tool or process. We have offered the JSON format for some time, even offering a shorthand command option --json to achieve this.

Recently though, some of our more advanced customers began asking us to provide output in the Static Analysis Results Interchange Format (SARIF). Originally developed by cybersecurity professionals as a way to standardize the output of static analysis tools, SARIF makes it easier to aggregate, analyze, and compare results from many different scanning tools. SARIF's value lies in its ability to provide a unified, structured approach to managing security analysis results. It can help ensure that security vulnerabilities are efficiently identified, communicated, and remediated.

The command ggshield secret scan path <path-to-directory> --format sarif to get your results in this standardized way, which we hope helps you better leverage ggshield across your security practice. 

Example SARIF file

Shift left with ggshield

We are glad to be helping teams of all sizes embrace secrets detection throughout the software development lifecycle by empowering developers to scan for plaintext credentials directly from the command line. We are continually striving to improve the capabilities of our platform and make ggshield more functional and easier to use.

If you are not already scanning for secrets in places like log files or throughout your CI environments, we invite you to get started today by signing up for GitGuardian and downloading ggshield. Then, with just a couple of commands, you completely automate local secrets scanning just by authenticating your install to your GitGuardian workspace (ggshield auth login) and then setting a global Git pre-commit hook to automatically check for secrets before you make another commit (ggshield install --mode global). 

We would love to hear from you. What other advancements would you like to see us make to ggshield? Are any yet-to-be-added features preventing you and your team from embracing it?  We would also love to hear any stories about how you are incorporating ggshield into your Poweshell or Bash scripts, leveraging our tool in your larger security automation efforts.