ripsecrets

ripsecrets is a command-line tool to prevent committing secret keys into your source code. ripsecrets has a few features that distinguish it from other secret scanning tools:

What makes ripsecrets different

ripsecrets has a few features that distinguish it from other secret scanning tools:

1. Focused on pre-commit. It's a lot cheaper to prevent secrets from getting committed in the first place than dealing with the consequences once a secret that has been committed to your repository has been detected.

2. Extremely fast. Using a secret scanner shouldn't slow down your development workflow, so ripsecrets is 95 times faster or more than other tools. Learn more about how it's designed for performance.

3. Always local operation. Many other secret scanners try to verify that the secrets are valid, which in practice means sending strings from your source code to 3rd party services automatically. There's a security versus convenience tradeoff in that decision, but ripsecrets is designed to be the best "local only" tool and will never send data off of your computer.

4. Low rate of false positives. While local-only tools are always going to have more false positives than one that verifies secrets, ripsecrets uses a probability theory based approach in order to detect keys more accurately than other tools.

5. Single binary with no dependencies. Installing ripsecrets is as easy as copying the binary into your bin directory.

Usage

By default, running ripsecrets will recursively search source files in your current directory for secrets.

$ ripsecrets

For every secret it finds, it will print out the file, line number, and the secret that was found. If it finds any secrets, it will exit with a non-zero status code.

You can optionally pass a list of files and directories to search as arguments.

$ ripsecrets file1 file2 dir1

This is most commonly used to search files that are about to be committed to source control for accidentally included secrets.

Installing ripsecrets as a pre-commit hook

You can install ripsecrets as a pre-commit hook automatically in your current git repository using the following command:

$ ripsecrets --install-pre-commit

If you would like to install ripsecrets manually, you can add the following command to your pre-commit script:

ripsecrets --strict-ignore `git diff --cached --name-only --diff-filter=ACM`

Passing --strict-ignore ensures that your .secretsignore file is respected when running secrets as a pre-commit.

Installation

Homebrew

ripsecrets is available in Homebrew for macOS and Linux:

$ brew install ripsecrets

Pre-built

You can download a prebuilt binary for the latest release from the releases page.

Cargo

Alternatively, if you have Rust and Cargo installed, you can run:

$ cargo install --git https://github.com/sirwart/ripsecrets --branch main

Nix Flake

Assuming you have enabled Flakes in your Nix configuration, you can build the ripsecrets binary and make it available in your default Nix profile by running:

$ nix profile install github:sirwart/ripsecrets

Using pre-commit

ripsecrets works as a hook for the pre-commit framework. Add the following to your .pre-commit-config.yaml file:

repos:
-   repo: https://github.com/sirwart/ripsecrets
    rev: v0.1.8  # Use latest tag on GitHub
    hooks:
    -   id: ripsecrets
        # uncomment to check additional patterns 
        # args:
        # - --additional-pattern 'mytoken*'
        # - --additional-pattern 'mykey*'

There are two hooks available:

• ripsecrets (Recommended)

  pre-commit will set up a Rust environment from scratch to compile and run ripsecrets. See the pre-commit rust plugin docs for more information.

• ripsecrets-system

  pre-commit will look for ripsecrets on your PATH. This hook requires you to install ripsecrets separately, e.g., with your package manager or a prebuilt binary release. It is only recommended if you are happy making all repository users install ripsecrets manually.

Ignoring secrets

ripsecrets will respect your .gitignore files by default, but there might still be files you want to exclude from being scanned for secrets. To do that, you can create a .secretsignore file, which supports similar syntax to a .gitignore file for ignoring files. In addition to excluding files, it also supports a [secrets] section that allows ignoring individual secrets.

test/*
dummy

[secrets]
pAznMW3DsrnVJ5TDWwBVCA

In addition to the .secretsignore file, ripsecrets is compatible with detect-secrets style allowlist comments on the same line as the detected secret:

test_secret = "pAznMW3DsrnVJ5TDWwBVCA" # pragma: allowlist secret

Finding custom secrets

In some cases, you may have a custom secret that's not recognized by ripsecrets. To detect these, call ripsecrets with the --additional-pattern argument:

ripsecrets --additional-pattern my-secret-\*

Any matching groups in the regex will be tested for randomness before being reported as a secret. If you do not want this behavior, use non-matching groups in your regex. For example instead of (foo|bar) use (?:foo|bar).

If the secret pattern you're trying to detect is a publicly documented secret pattern, please open an issue.

How it works

ripsecrets has 2 types of secrets that it can find in code:

1. Secrets with known patterns that can be matched. API keys from services like Stripe and Slack have a predefined prefix that identifies them as API keys and can be found via regular expressions very reliably. You can see the current list of known secrets matched by ripsecrets here.

2. Random strings assigned to secret variables. Some secrets, like AWS's secret access keys, don't have a known pattern that can be unambiguously matched. To detect these, ripsecrets looks for variables or properties that are being assigned with words like "token", "secret", and "password", and checks if a random string is assigned to it.

To determine if a string is random or not ripsecrets looks at a few properties of a string, like how many distinct characters it has, and calculates how likely it is to have occurred by random chance. If the probability that it happened by chance is less than 1 in 10,000 then it's determined to not be a secret. You can learn more about how the probability is calculated here.

If you find either a false negative (a secret that wasn't found by ripsecrets) or a false positive (a non-secret that was flagged as such), please open an issue or a pull request.

Performance

The slowest part of secret scanning is looking for potential secrets in a large number of files. To do this quickly, ripsecrets does a couple of things:

1. All the secret patterns are compiled into a single regex, so each file only needs to be processed once.

2. This regex is fed to ripgrep, which is specially optimized for running a regex against a large number of files quickly.

Additionally, ripsecrets is written in Rust, which means there's no interpreter startup time. To compare real-world performance, here's the runtime of a few different scanning tools to search for secrets in the Sentry repo on an M1 air laptop:

tool	avg. runtime	vs. baseline
ripsecrets	0.32s	1x
trufflehog	31.2s	95x
detect-secrets	73.5s	226x

Most of the time, your pre-commit will be running on a small number of files, so the runtimes above are not typical, but when working with large commits that touch a lot of files, the runtime can become noticeable.

Running benchmarks

$ cargo bench

The results will then be viewable at target/criterion/report/index.html.

Alternative tools

Even if ripsecrets is not the right tool for you, if you're working on a service that deals with user data you should strongly consider using a secret scanner. Here are some alternative tools worth considering:

• detect-secrets
• trufflehog
• gitleaks