@mapbox/secret-shield

secret-shield

1. 🚨 Are you being blocked from committing? 🚨
2. About secret-shield
3. Install
4. Requirements
   1. Quick Install and setup
   2. Manual Install
   3. Uninstalling
5. Using secret-shield
   1. Setting up automated searching
   2. Manually searching
   3. Additional functionality
6. FAQ:
   1. Does secret-shield auto-update?
   2. Why secret-shield?
   3. What does it search for, exactly?
   4. It says it found a secret but it’s not, what do I do?
   5. It says it found a secret and it actually is a secret, what do I do?
   6. Does it work with my git client?
   7. I already have pre-commit hooks for something else, will secret-shield work with them?
      1. Husky + lint-staged integration

🚨 Are you being blocked from committing? 🚨

Some repositories require secret-shield to commit to them. If you don't have secret-shield you'll be blocked from committing to those repos

If secret-shield is installed on your machine, read this for common issues with secret-shield and how to fix them.

About secret-shield

secret-shield is a convenient way to protect against inadvertently committing potential secrets to GitHub. It can be set up to automatically run before each commit (if it catches something, it will stop the commit and ask you to review the findings), or you can manually run it from the command line.

Please note: secret-shield will now be required when working with certain repositories. Learn more.

If you want to add secret-shield to your repository, take a look here.

Install

Requirements

secret-shield is a Node project tested with Node 10 & 12

secret-shield requires npm >= 6 to install globally. Previous versions of npm will not correcly install the required dependencies.

Quick Install and setup

npm install -g @mapbox/secret-shield

You still need to set it up. Easiest way: secret-shield --add-hooks global.

Manual Install

Clone this repository, then from inside it, run:

npm install
npm link

Tests are available using npm test.

You still need to set it up. Easiest way: secret-shield --add-hooks global.

Uninstalling

To uninstall secret-shield:

1. make sure that you don't have any global hooks configured for secret-shield: secret-shield --remove-hooks global
2. uninstall secret-shield normally (if you installed using npm, you can run npm remove -g @mapbox/secret-shield)

Using secret-shield

You can set up secret-shield to automatically search for secrets before each commit, or manually run it from anywhere.

Setting up automated searching

secret-shield uses pre-commit hooks to run before each commit and check for secrets only in whatever changes you've made. You can create these hooks either globally or on a per-repository basis.

• To create a global pre-commit hook that will run on all repositories, run secret-shield --add-hooks global (to remove, use --remove-hooks global)
• To create pre-commit hooks only for your current repository, run secret-shield --add-hooks local (to remove, use --remove-hooks local). Note that, if working with others, it's almost always a better idea to install secret-shield directly in your repository so that everyone who works on it uses secret-shield.

If a potential secret is found, secret-shield will abort the commit and provide you with its findings. After reviewing the findings, you can either go back and change your files or force the commit through without any checks by running git commit with the --no-verify flag.

Manually searching

You can manually use secret-shield to search through:

• Files: secret-shield <--file|-f> <file>
• Directories: secret-shield <--directory|-d> <directory>
• Repositories: secret-shield <--repository|-r> <repository> [branch]
• Strings: secret-shield <--string|-s> <string>
• CloudFormation template files: automatically detected

Use <--redact|-R> [number] if you need to redact potentially sensitive information: output will be truncated to the specified number of characters.

Additional functionality

• You can change the rules used by secret-shield and also write your own rules.
• You can specify advanced output (such as JSON output) and redaction rules.
• Secret-shield also supports some basic batch processing. (Work in progress)

FAQ:

Does secret-shield auto-update?

Yes, secret-shield will automatically check for updates on average once in every 20 runs as a pre-commit hook.

Why secret-shield?

Credential leaks are frequently a problem in any organization or team. Secret-shield aims to nullify the impact of a credential leak by blocking it before the secret has a chance to get out in the first place.

When combined with documented best practices for handling secrets, secret-shield can dramatically reduce the probability of a leaked secret. Secret-shield can find already-leaked secrets much faster than searching by hand -- when combined with a robust incident response framework, this can significantly reduce the impact of a credential leak.

Security researchers can use secret-shield to find and report leaked secrets to affected teams or organizations.

What does it search for, exactly?

By default, secret-shield performs a minimal search: AWS client IDs, Mapbox secure keys, Slack tokens, and GitHub tokens.

If you perform more advanced searches, secret-shield can look for more things, such as AWS secret IDs, “don’t commit” messages, and high-entropy strings.

It says it found a secret but it’s not, what do I do?

If it ran automatically before a commit, simply commit with the --no-verify flag. It won’t prompt you about those findings again, unless you change something in those lines.

If you ran it manually, you can ignore the findings.

It says it found a secret and it actually is a secret, what do I do?

If it ran automatically before a commit and the secret wasn’t there before, simply go back and remove the secret: it didn’t commit it, so you’re safe.

If the secret was there before (so it’s already been committed), or if you ran it manually and it found a secret that’s already been committed, the secret should be considered compromised -- follow your company or project's procedures for handling leaked secrets.

Does it work with my git client?

Secret-shield uses pre-commit hooks; some clients support them, others just force commits through regardless. You should check your client’s documentation on whether it supports pre-commit hooks.

I already have pre-commit hooks for something else, will secret-shield work with them?

Yes! Secret-shield will automatically detect any local hooks that you have, e.g. husky, and run them instead. If you want to run secret-shield on that repository, you should add it to those local hooks. Take a look here.

Husky + lint-staged integration

You can use secret-shield with husky and lint-staged by adding secret-shield as an npm dependency in your package.json and using the following configuration

  "husky": {
    "hooks": {
      "pre-commit": "lint-staged && secret-shield --check-and-run"
    }
  },
  "lint-staged": {
    "*": [
      "command2",
      "command2"
    ]
  }

If you are using an old version of husky

  "scripts": {
    "precommit": "lint-staged && secret-shield --check-and-run"
  },
  "lint-staged": {
    "*": [
      "command2",
      "command2"
    ]
  }