- 🚨 Are you being blocked from committing? 🚨
- About secret-shield
- Install
- Requirements
- Using secret-shield
- FAQ:
- Does secret-shield auto-update?
- Why secret-shield?
- What does it search for, exactly?
- It says it found a secret but it’s not, what do I do?
- It says it found a secret and it actually is a secret, what do I do?
- Does it work with my git client?
- I already have pre-commit hooks for something else, will secret-shield work with them?
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.
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.
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.
npm install -g @mapbox/secret-shield
You still need to set it up. Easiest way: secret-shield --add-hooks global
.
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
.
To uninstall secret-shield:
- make sure that you don't have any global hooks configured for secret-shield:
secret-shield --remove-hooks global
- uninstall secret-shield normally (if you installed using npm, you can run
npm remove -g @mapbox/secret-shield
)
You can set up secret-shield
to automatically search for secrets before each commit, or manually run it from anywhere.
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.
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.
- 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)
Yes, secret-shield will automatically check for updates on average once in every 20 runs as a pre-commit hook.
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.
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.
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.
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.
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.
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.
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"
]
}