zricethezav/gitleaks

•Updated 6 months ago

Gitleaks provides a way to find secrets in git repositories

Image

10M+

zricethezav/gitleaks repository overview

○
│╲
│ ○
○ ░
░    gitleaks

⁠ ⁠ ⁠

Gitleaks is a SAST tool for detecting hardcoded secrets like passwords, api keys, and tokens in git repos. Gitleaks is an easy-to-use, all-in-one solution for detecting secrets, past or present, in your code.

⁠Getting Started

Gitleaks can be installed using Homebrew, Docker, or Go. Gitleaks is also available in binary form for many popular platforms and OS types on the releases page⁠. In addition, Gitleaks can be implemented as a pre-commit hook directly in your repo.

⁠MacOS

brew install gitleaks

⁠Docker

⁠DockerHub

docker pull zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]

⁠ghrc.io

docker pull ghcr.io/zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] --source="/path" [OPTIONS]

⁠From Source

Download and install Go from https://golang.org/dl/⁠
Clone the repo

git clone https://github.com/zricethezav/gitleaks.git

Build the binary

cd gitleaks
make build

⁠Usage

Usage:
  gitleaks [command]

Available Commands:
  completion  generate the autocompletion script for the specified shell
  detect      Detect secrets in code
  help        Help about any command
  protect     Protect secrets in code
  version     Display gitleaks version

Flags:
  -c, --config string          config file path
                               order of precedence:
                               1. --config/-c
                               2. (--source/-s)/.gitleaks.toml
                               if --config/-c is not set and no .gitleaks.toml/gitleaks.toml present
                               then .gitleaks.toml will be written to (--source/-s)/.gitleaks.toml for future use
      --exit-code string       exit code when leaks have been encountered (default: 1)
  -h, --help                   help for gitleaks
  -l, --log-level string       log level (debug, info, warn, error, fatal) (default "info")
      --redact                 redact secrets from logs and stdout
  -f, --report-format string   output format (json, csv, sarif)
  -r, --report-path string     report file
  -s, --source string          path to source (git repo, directory, file)
  -v, --verbose                show verbose output from scan

Use "gitleaks [command] --help" for more information about a command.

⁠Commands

There are two commands you will use to detect secrets; detect and protect.

⁠Detect

The detect command is used to scan repos, directories, and files. This comand can be used on developer machines and in CI environments.

When running detect on a git repository, gitleaks will parse the output of a git log -p command (you can see how this executed here⁠). git log -p generates patches⁠ which gitleaks will use to detect secrets. You can configure what commits git log will range over by using the --log-opts flag. --log-opts accepts any option for git log -p. For example, if you wanted to run gitleaks on a range of commits you could use the following command: gitleaks --source . --log-opts="--all commitA..commitB". See the git log documentation⁠ for more information.

You can scan files and directories by using the --no-git option.

⁠Protect

The protect command is used to uncommitted changes in a git repo. This command should be used on developer machines in accordance with shifting left on security⁠. When running detect on a git repository, gitleaks will parse the output of a git diff command (you can see how this executed here⁠). You can set the --staged flag to check for changes in commits that have been git added. The --staged flag should be used when running Gitleaks as a pre-commit.

NOTE: the protect command can only be used on git repos, running protect on files or directories will result in an error message.

⁠Verify Findings

You can verify a finding found by gitleaks using a git log command. Example output:

{
        "Description": "AWS",
        "StartLine": 37,
        "EndLine": 37,
        "StartColumn": 19,
        "EndColumn": 38,
        "Context": "\t\t\"aws_secret= \\\"AKIAIMNOJVGFDXXXE4OA\\\"\":          true,",
        "Secret": "AKIAIMNOJVGFDXXXE4OA",
        "File": "checks_test.go",
        "Commit": "ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29",
        "Entropy": 0,
        "Author": "zricethezav",
        "Email": "[email protected]",
        "Date": "2018-01-28 17:39:00 -0500 -0500",
        "Message": "[update] entropy check",
        "Tags": [],
        "RuleID": "aws-access-token"
}

We can use the following format to verify the leak:

git log -L {StartLine,EndLine}:{File} {Commit}

So in this example it would look like:

git log -L 37,37:checks_test.go ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29

Which gives us:

commit ec2fc9d6cb0954fb3b57201cf6133c48d8ca0d29
Author: zricethezav <[email protected]>
Date:   Sun Jan 28 17:39:00 2018 -0500

    [update] entropy check

diff --git a/checks_test.go b/checks_test.go
--- a/checks_test.go
+++ b/checks_test.go
@@ -28,0 +37,1 @@
+               "aws_secret= \"AKIAIMNOJVGFDXXXE4OA\"":          true,

⁠Pre-Commit hook

You can run Gitleaks as a pre-commit hook by copying the example pre-commit.py script into your .git/hooks/ directory.

⁠Configuration

Gitleaks offers a configuration format you can follow to write your own secret detection rules:

# Title for the gitleaks configuration file. 
title = "Gitleaks title"

# An array of tables that contain information that define instructions
# on how to detect secrets 
[[rules]]
# Unique identifier for this rule
id = "awesome-rule-1"
# Short human readable description of the rule.
description = "awsome rule 1" 
# Golang regular expression used to detect secrets. Note Golang's regex engine
# does not support lookaheads.
regex = '''one-go-style-regex-for-this-rule''' 
# Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
# in conjunction with a valid `regex` entry.
path = '''a-file-path-regex'''
# Array of strings used for metadata and reporting purposes.
tags = ["tag","another tag"]
# Int used to check shannon entropy of a specific group in a regex match. 
entropyGroup = 3
# Float representing the minimum shannon entropy a regex group must have to be considered a secret. 
entropy = 3.5
# You can include an allowlist table for a single rule to reduce false positives or ignore commits
# with known/rotated secrets
[rules.allowlist]
description = "ignore commit A"
commits = [ "commit-A", "commit-B"]
paths = ['''one-file-path-regex''']
regexes = ['''one-regex-within-the-already-matched-regex''']

# This is a global allowlist which has a higher order of precendence than rule-specific allowlists.
# If a commit listed in the `commits` field below is encountered then that commit will be skipped and no 
# secrets will be detected for said commit. The same logic applies for regexes and paths.
[allowlist]
description = "ignore commit A"
commits = [ "commit-A", "commit-B"]
paths = ['''one-file-path-regex''']
regexes = ['''one-regex-within-the-already-matched-regex''']

Refer to the default gitleaks config⁠ for examples and advice on writing regular expressions for secret detection.

⁠Exit Codes

You can always set the exit code when leaks are encountered with the --exit-code flag. Default exit codes below:

0 - no leaks present
1 - leaks or error encountered

Tag summary

Recent tags

Content type

Image

Digest

sha256:c00b6bd0a…

Size

23.9 MB

Last updated

6 months ago

docker pull zricethezav/gitleaks