awslabs/git-secretsPrevents you from committing secrets and credentials into git repositories
.. contents:: :depth: 2
::
git secrets --scan [-r|--recursive] [--cached] [--no-index] [--untracked] [<files>...]
git secrets --scan-history
git 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 to
prevent adding secrets into your git repositories. If a commit,
commit message, or any commit in a --no-ff merge history matches one of
your configured prohibited regular expression patterns, then the commit is
rejected.
git-secrets must be placed somewhere in your PATH so that it is picked up
by git when running git secrets.
*nix (Linux/macOS)
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
Windows
~~~~~~~
Run the provided ``install.ps1`` powershell script. This will copy the needed files
to an installation directory (``%USERPROFILE%/.git-secrets`` by default) and add
the directory to the current user ``PATH``.
::
PS > ./install.ps1
Homebrew (for macOS users)
::
brew install git-secrets
.. warning::
**You're not done yet! You MUST install the git hooks for every repo that
you wish to use with** ``git secrets --install``.
Here's a quick example of how to ensure a git repository is scanned for secrets on each commit::
cd /path/to/my/repo
git secrets --install
git secrets --register-aws
Add a configuration template if you want to add hooks to all repositories you initialize or clone in the future.
::
git secrets --register-aws --global
Add hooks to all your local repositories.
::
git secrets --install ~/.git-templates/git-secrets
git 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
Operation Modes
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 git
repository, commits and non-fast-forward merges for that repository will be prevented
from committing secrets.
``--scan``
Scans one or more files for secrets. When a file contains a secret, the
matched text from the file being scanned will be written to stdout and the
script will exit with a non-zero status. Each matched line will be written with
the 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, the
matched text from the file being scanned will be written to stdout and the
script will exit with a non-zero status. Each matched line will be written with
the 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 global
git config.
``--add``
Adds a prohibited or allowed pattern.
``--add-provider``
Registers a secret provider. Secret providers are executables that when
invoked output prohibited patterns that ``git-secrets`` should treat as
prohibited.
``--register-aws``
Adds common AWS patterns to the git config and ensures that keys present
in ``~/.aws/credentials`` are not found in any commit. The following
checks are added:
- AWS Access Key IDs via ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}``
- Amazon Bedrock API keys. Long-lived via ``ABSK[A-Za-z0-9+/]{109,}=*`` and short-lived via ``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
- AWS Secret Access Key assignments via ":" or "=" surrounded by optional
quotes
- AWS account ID assignments via ":" or "=" surrounded by optional quotes
- Allowed patterns for example AWS keys (``AKIAIOSFODNN7EXAMPLE`` and
``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``)
- Known credentials from ``~/.aws/credentials``
.. note::
While the patterns registered by this command should catch most
instances of AWS credentials, these patterns are **not** guaranteed to
catch them **all**. ``git-secrets`` should be used as an extra means of
insurance -- you still need to do your due diligence to ensure that you
do not commit credentials to a repository.
``--aws-provider``
Secret provider that outputs credentials found in an INI file. You can
optionally provide the path to an INI file.
Options for ``--install``
-f, --force
Overwrites existing hooks if present.
<target-directory>
When provided, installs git hooks to the given directory. The current
directory is assumed if <target-directory> is not provided.
If the provided ``<target-directory>`` is not in a git repository, the
directory will be created and hooks will be placed in
``<target-directory>/hooks``. This can be useful for creating git template
directories 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 <https://git-scm.com/docs/git-init>`_:
From the git documentation: Running ``git init`` in an existing repository
is safe. It will not overwrite things that are already there. The
primary reason for rerunning ``git init`` is to pick up newly added
templates (or to move the repository to another place if
``--separate-git-dir`` is given).
The following git hooks are installed:
1. ``pre-commit``: Used to check if any of the files changed in the commit
use prohibited patterns.
2. ``commit-msg``: Used to determine if a commit message contains a
prohibited patterns.
3. ``prepare-commit-msg``: Used to determine if a merge commit will
introduce 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 the
repository contains Debian-style subdirectories like ``pre-commit.d``
and ``commit-msg.d``, then the git hooks will be installed into these
directories, which assumes that you've configured the corresponding
hooks to execute all of the scripts found in these directories. If
these git subdirectories are not present, then the git hooks will be
installed to the git repo's ``.git/hooks`` directory.
Examples ^^^^^^^^
Install git hooks to the current directory::
cd /path/to/my/repository
git secrets --install