git-secretsPrevents you from committing passwords and other sensitive information to a git repository.git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<files>...]git secrets --scan-historygit secrets --install [-f|--force] [<target-directory>]git secrets --list [--global]git secrets --add [-a|--allowed] [-l|--literal] [--global] <pattern>git secrets --add-provider [--global] <command> [arguments...]git secrets --register-aws [--global]git secrets --aws-provider [<credentials-file>] git-secrets scans commits, commit messages, and --no-ff merges toprevent adding secrets into your git repositories. If a commit,commit message, or any commit in a --no-ff merge history matches one ofyour configured prohibited regular expression patterns, then the commit isrejected.
git-secrets must be placed somewhere in your PATH so that it is picked upby git when running git secrets .
You can use the install target of the provided Makefile to install git secrets and the man page.You can customize the install path using the PREFIX and MANPREFIX variables. make install Run the provided install.ps1 powershell script. This will copy the needed filesto an installation directory (%USERPROFILE%/.git-secrets by default) and addthe directory to the current user PATH . PS > ./install.ps1 brew install git-secrets Warning You're not done yet! You MUST install the git hooks for every repo thatyou wish to use with git secrets --install . Here's a quick example of how to ensure a git repository is scanned for secretson each commit: cd /path/to/my/repogit secrets --installgit secrets --register-aws Add a configuration template if you want to add hooks to all repositories youinitialize or clone in the future. git secrets --register-aws --global Add hooks to all your local repositories. git secrets --install ~/.git-templates/git-secretsgit config --global init.templateDir ~/.git-templates/git-secrets Add custom providers to scan for security credentials. git secrets --add-provider -- cat /path/to/secret/file/patterns With git-secrets is also possible to scan a repository including all revisions: git secrets --scan-history Each of these options must appear first on the command line. --install - Installs git hooks for a repository. Once the hooks are installed for a gitrepository, commits and non-fast-forward merges for that repository will be preventedfrom committing secrets.
--scan - Scans one or more files for secrets. When a file contains a secret, thematched text from the file being scanned will be written to stdout and thescript will exit with a non-zero status. Each matched line will be written withthe name of the file that matched, a colon, the line number that matched,a colon, and then the line of text that matched. If no files are provided,all files returned by
git ls-files are scanned. --scan-history - Scans repository including all revisions. When a file contains a secret, thematched text from the file being scanned will be written to stdout and thescript will exit with a non-zero status. Each matched line will be written withthe name of the file that matched, a colon, the line number that matched,a colon, and then the line of text that matched.
--list - Lists the
git-secrets configuration for the current repo or in the globalgit config. --add - Adds a prohibited or allowed pattern.
--add-provider - Registers a secret provider. Secret providers are executables that wheninvoked output prohibited patterns that
git-secrets should treat asprohibited. --register-aws Adds common AWS patterns to the git config and ensures that keys presentin ~/.aws/credentials are not found in any commit. The followingchecks are added: - AWS Access Key IDs via
(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16} - AWS Secret Access Key assignments via ":" or "=" surrounded by optionalquotes
- AWS account ID assignments via ":" or "=" surrounded by optional quotes
- Allowed patterns for example AWS keys (
AKIAIOSFODNN7EXAMPLE andwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ) - Known credentials from
~/.aws/credentials
Note While the patterns registered by this command should catch mostinstances of AWS credentials, these patterns are not guaranteed tocatch them all. git-secrets should be used as an extra means ofinsurance -- you still need to do your due diligence to ensure that youdo not commit credentials to a repository. --aws-provider - Secret provider that outputs credentials found in an INI file. You canoptionally provide the path to an INI file.
-f, --force - Overwrites existing hooks if present.
<target-directory> When provided, installs git hooks to the given directory. The currentdirectory is assumed if <target-directory> is not provided. If the provided <target-directory> is not in a git repository, thedirectory will be created and hooks will be placed in<target-directory>/hooks . This can be useful for creating git templatedirectories using with git init --template <target-directory> . You can run git init on a repository that has already been initialized.From the git init documentation: From the git documentation: Running git init in an existing repositoryis safe. It will not overwrite things that are already there. Theprimary reason for rerunning git init is to pick up newly addedtemplates (or to move the repository to another place if--separate-git-dir is given). The following git hooks are installed: pre-commit : Used to check if any of the files changed in the commituse prohibited patterns.commit-msg : Used to determine if a commit message contains aprohibited patterns.prepare-commit-msg : Used to determine if a merge commit willintroduce a history that contains a prohibited pattern at any point.Please note that this hook is only invoked for non fast-forward merges.
Note Git only allows a single script to be executed per hook. If therepository contains Debian-style subdirectories like pre-commit.d and commit-msg.d , then the git hooks will be installed into thesedirectories, which assumes that you've configured the correspondinghooks to execute all of the scripts found in these directories. Ifthese git subdirectories are not present, then the git hooks will beinstalled to the git repo's .git/hooks directory.
ExamplesInstall git hooks to the current directory: cd /path/to/my/repositorygit secrets --install Install git hooks to a repository other than the current directory: git secrets --install /path/to/my/repository Create a git template that has git-secrets installed, and then copy thattemplate into a git repository: git secrets --install ~/.git-templates/git-secretsgit init --template ~/.git-templates/git-secrets Overwrite existing hooks if present: git secrets --install -f -r, --recursive Scans the given files recursively. If a directory is encountered, thedirectory will be scanned. If -r is not provided, directories will beignored. -r cannot be used alongside --cached , --no-index , or--untracked .
--cached - Searches blobs registered in the index file.
--no-index - Searches files in the current directory that is not managed by git.
--untracked - In addition to searching in the tracked files in the working tree,
--scan also in untracked files. <files>... The path to one or more files on disk to scan for secrets. If no files are provided, all files returned by git ls-files arescanned.
ExamplesScan all files in the repo: git secrets --scan Scans a single file for secrets: git secrets --scan /path/to/file Scans a directory recursively for secrets: git secrets --scan -r /path/to/directory Scans multiple files for secrets: git secrets --scan /path/to/file /path/to/other/file You can scan by globbing: git secrets --scan /path/to/directory/* Scan from stdin: echo 'hello!' | git secrets --scan - --global - Lists only git-secrets configuration in the global git config.
--global - Adds patterns to the global git config
-l, --literal - Escapes special regular expression characters in the provided pattern sothat the pattern is searched for literally.
-a, --allowed - Mark the pattern as allowed instead of prohibited. Allowed patterns areused to filter our false positives.
<pattern> - The regex pattern to search.
ExamplesAdds a prohibited pattern to the current repo: git secrets --add '[A-Z0-9]{20}' Adds a prohibited pattern to the global git config: git secrets --add --global '[A-Z0-9]{20}' Adds a string that is scanned for literally (+ is escaped): git secrets --add --literal 'foo+bar' Add an allowed pattern: git secrets --add -a 'allowed pattern' --global - Adds AWS specific configuration variables to the global git config.
[<credentials-file>] - If provided, specifies the custom path to an INI file to scan. If notprovided,
~/.aws/credentials is assumed.
--global - Adds the provider to the global git config.
<command> - Provider command to invoke. When invoked the command is expected to writeprohibited patterns separated by new lines to stdout. Any extra argumentsprovided are passed on to the command.
ExamplesRegisters a secret provider with arguments: git secrets --add-provider -- git secrets --aws-provider Cats secrets out of a file: git secrets --add-provider -- cat /path/to/secret/file/patterns egrep -compatible regular expressions are used to determine if a commit orcommit message contains any prohibited patterns. These regular expressions aredefined using the git config command. It is important to note thatdifferent systems use different versions of egrep. For example, when running onmacOS, you will use a different version of egrep than when running on somethinglike Ubuntu (BSD vs GNU).
You can add prohibited regular expression patterns to your git config usinggit secrets --add <pattern> . Sometimes a regular expression might match false positives. For example, gitcommit SHAs look a lot like AWS access keys. You can specify many differentregular expression patterns as false positives using the following command: git secrets --add --allowed 'my regex pattern' You can also add regular expressions patterns to filter false positives to a.gitallowed file located in the repository's root directory. Lines startingwith # are skipped (comment line) and empty lines are also skipped. First, git-secrets will extract all lines from a file that contain a prohibitedmatch. Included in the matched results will be the full path to the name ofthe file that was matched, followed by ':', followed by the line number that wasmatched, followed by the entire line from the file that was matched by a secretpattern. Then, if you've defined allowed regular expressions, git-secrets willcheck to see if all of the matched lines match at least one of your registeredallowed regular expressions. If all of the lines that were flagged as secretare canceled out by an allowed match, then the subject text does not containany secrets. If any of the matched lines are not matched by an allowed regularexpression, then git-secrets will fail the commit/merge/message. Important Just as it is a bad practice to add prohibited patterns that are toogreedy, it is also a bad practice to add allowed patterns that are tooforgiving. Be sure to test out your patterns using ad-hoc calls togit secrets --scan $filename to ensure they are working as intended. Sometimes you want to check for an exact pattern match against a set of knownsecrets. For example, you might want to ensure that no credentials present in~/.aws/credentials ever show up in a commit. In these cases, it's better toleave these secrets in one location rather than spread them out across gitrepositories in git configs. You can use "secret providers" to fetch thesetypes of credentials. A secret provider is an executable that when invokedoutputs prohibited patterns separated by new lines. You can add secret providers using the --add-provider command: git secrets --add-provider -- git secrets --aws-provider Notice the use of -- . This ensures that any arguments associated with theprovider are passed to the provider each time it is invoked when scanningfor secrets. Let's take a look at an example. Given the following subject text (stored in/tmp/example ): This is a test!password=ex@mplepasswordpassword=******More test... And the following registered patterns: git secrets --add 'password\s*=\s*.+'git secrets --add --allowed --literal 'ex@mplepassword' Running git secrets --scan /tmp/example , the result willresult in the following error output: /tmp/example:3:password=******[ERROR] Matched prohibited patternPossible mitigations:- Mark false positives as allowed using: git config --add secrets.allowed ...- List your configured patterns: git config --get-all secrets.patterns- List your configured allowed patterns: git config --get-all secrets.allowed- Use --no-verify if this is a one-time false positive Breaking this down, the prohibited pattern value of password\s*=\s*.+ willmatch the following lines: /tmp/example:2:password=ex@mplepassword/tmp/example:3:password=****** ...But the first match will be filtered out due to the fact that it matches theallowed regular expression of ex@mplepassword . Because there is still aremaining line that did not match, it is considered a secret. Because that matching lines are placed on lines that start with the filenameand line number (e.g., /tmp/example:3:... ), you can create allowedpatterns that take filenames and line numbers into account in the regularexpression. For example, you could whitelist an entire file using somethinglike: git secrets --add --allowed '/tmp/example:.*'git secrets --scan /tmp/example && echo $?# Outputs: 0 Alternatively, you could allow a specific line number of a file if thatline is unlikely to change using something like the following: git secrets --add --allowed '/tmp/example:3:.*'git secrets --scan /tmp/example && echo $?# Outputs: 0 Keep this in mind when creating allowed patterns to ensure that your allowedpatterns are not inadvertently matched due to the fact that the filename isincluded in the subject text that allowed patterns are matched against. Use the --no-verify option in the event of a false positive match in acommit, merge, or commit message. This will skip the execution of thegit hook and allow you to make the commit or merge. Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
请发表评论