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>]

你可以使用提供的 Makefile 中的 ``install`` 目标来安装 ``git secrets`` 及其手册页。你可以通过 PREFIX 和 MANPREFIX 变量自定义安装路径。

::

    make install

Windows
~~~~~~~

运行提供的 ``install.ps1`` PowerShell 脚本。该脚本会将所需文件复制到安装目录（默认为 ``%USERPROFILE%/.git-secrets``），并将该目录添加到当前用户的 ``PATH`` 中。

::

    PS > ./install.ps1

Homebrew（macOS 用户）

brew install git-secrets

**你还没有完成！你必须为每个你想使用** ``git secrets --install`` **的仓库安装 git 钩子**。

cd /path/to/my/repo
git secrets --install
git secrets --register-aws

git secrets --register-aws --global

git secrets --install ~/.git-templates/git-secrets
git config --global init.templateDir ~/.git-templates/git-secrets

git secrets --add-provider -- cat /path/to/secret/file/patterns

git secrets --scan-history

每个选项必须出现在命令行首位。

``--install``
    为仓库安装 git 钩子。一旦为某个 git 仓库安装了钩子，该仓库的提交和非快进合并操作将被阻止提交机密信息。

``--scan``
    扫描一个或多个文件中的机密信息。当某个文件包含机密信息时，被扫描文件中匹配的文本将输出到 stdout，脚本将以非零状态退出。每个匹配行会输出文件名、冒号、行号、冒号以及匹配的文本行。如果未提供任何文件，则扫描 ``git ls-files`` 返回的所有文件。

``--scan-history``
    扫描仓库的所有修订版本。当某个文件包含机密信息时，被扫描文件中匹配的文本将输出到 stdout，脚本将以非零状态退出。每个匹配行会输出文件名、冒号、行号、冒号以及匹配的文本行。

``--list``
    列出当前仓库或全局 git 配置中的 ``git-secrets`` 配置。

``--add``
    添加一个禁止或允许的模式。

``--add-provider``
    注册一个机密提供程序。机密提供程序是可执行文件，调用时会输出 ``git-secrets`` 应视为禁止的模式。

``--register-aws``
    将常见的 AWS 模式添加到 git 配置，并确保 ``~/.aws/credentials`` 中的密钥不会出现在任何提交中。会添加以下检查：

    - 通过 ``(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}`` 匹配 AWS 访问密钥 ID
    - Amazon Bedrock API 密钥。长寿命：``ABSK[A-Za-z0-9+/]{109,}=*``，短寿命：``bedrock-api-key-YmVkcm9jay5hbWF6b25hd3MuY29t``
    - 通过“:”或“=”以及可选引号包围的 AWS 秘密访问密钥赋值
    - 通过“:”或“=”以及可选引号包围的 AWS 账户 ID 赋值
    - 允许的示例 AWS 密钥模式（``AKIAIOSFODNN7EXAMPLE`` 和 ``wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY``）
    - 来自 ``~/.aws/credentials`` 的已知凭证

    .. note::

        虽然此命令注册的模式应该能捕获大多数 AWS 凭证实例，但这些模式 **不能** 保证捕获 **所有** 实例。``git-secrets`` 应作为额外保险手段——你仍需尽职尽责，确保不会将凭证提交到仓库中。

``--aws-provider``
    输出 INI 文件中找到的凭证的机密提供程序。你可以选择提供 INI 文件的路径。


``--install`` 的选项

如果提供的 ``<target-directory>`` 不在 git 仓库中，该目录将被创建，钩子将放在 ``<target-directory>/hooks`` 中。这对于创建 git 模板目录很有用，可与 ``git init --template <target-directory>`` 一起使用。

你可以在已初始化的仓库上再次运行 ``git init``。来自 `git init 文档 <https://git-scm.com/docs/git-init>`_：

    根据 git 文档：在现有仓库中运行 ``git init`` 是安全的。它不会覆盖已有的内容。重新运行 ``git init`` 的主要原因是应用新添加的模板（或者如果指定了 ``--separate-git-dir``，则将仓库移动到其他位置）。

将安装以下 git 钩子：

1. ``pre-commit``：用于检查提交中更改的文件是否使用了禁止模式。
2. ``commit-msg``：用于判断提交消息是否包含禁止模式。
3. ``prepare-commit-msg``：用于判断合并提交是否会引入包含禁止模式的历史记录。请注意，此钩子仅在非快进合并时调用。

.. note::

    Git 每个钩子只允许执行一个脚本。如果仓库包含 Debian 风格的子目录，如 ``pre-commit.d`` 和 ``commit-msg.d``，则 git 钩子将安装到这些目录中，这假定你已经配置了相应的钩子来执行这些目录中的所有脚本。如果这些 git 子目录不存在，则 git 钩子将安装到 git 仓库的 ``.git/hooks`` 目录。

cd /path/to/my/repository
git secrets --install

git secrets --install /path/to/my/repository

git secrets --install ~/.git-templates/git-secrets
git init --template ~/.git-templates/git-secrets

git secrets --install -f

``-r, --recursive``
    递归扫描给定文件。如果遇到目录，将扫描该目录。如果未提供 ``-r``，目录将被忽略。

    ``-r`` 不能与 ``--cached``、``--no-index`` 或 ``--untracked`` 同时使用。

``--cached``
    搜索索引文件中注册的 blob。

``--no-index``
    搜索当前目录中未由 git 管理的文件。

``--untracked``
    除了搜索工作树中已跟踪的文件外，``--scan`` 还会搜索未跟踪的文件。

``<files>...``
    要扫描的磁盘上一个或多个文件的路径。

    如果未提供文件，则扫描 ``git ls-files`` 返回的所有文件。


示例
^^^^^^^^

扫描仓库中的所有文件：::

    git secrets --scan

扫描单个文件中的机密信息：::

    git secrets --scan /path/to/file

递归扫描目录中的机密信息：::

    git secrets --scan -r /path/to/directory

扫描多个文件中的机密信息：::

    git secrets --scan /path/to/file /path/to/other/file

你可以使用通配符扫描：::

    git secrets --scan /path/to/directory/*

从 stdin 扫描：::

    echo 'hello!' | git secrets --scan -


``--list`` 的选项

``--global``
    将模式添加到全局 git 配置

``-l, --literal``
    转义提供模式中的特殊正则表达式字符，以便字面搜索该模式。

``-a, --allowed``
    将模式标记为允许而不是禁止。允许的模式用于过滤误报。

``<pattern>``
    要搜索的正则表达式模式。


示例
^^^^^^^^

向当前仓库添加一个禁止模式：::

    git secrets --add '[A-Z0-9]{20}'

向全局 git 配置添加一个禁止模式：::

    git secrets --add --global '[A-Z0-9]{20}'

添加一个进行字面扫描的字符串（``+`` 被转义）：::

    git secrets --add --literal 'foo+bar'

添加一个允许模式：::

    git secrets --add -a 'allowed pattern'


``--register-aws`` 的选项

``[<credentials-file>]``
    如果提供，则指定要扫描的 INI 文件的自定义路径。如果未提供，则假定为 ``~/.aws/credentials``。


``--add-provider`` 的选项

git secrets --add-provider -- git secrets --aws-provider

git secrets --add-provider -- cat /path/to/secret/file/patterns

git secrets --add --allowed 'my regex pattern'

就像添加过于贪婪的禁止模式是不好的做法一样，添加过于宽松的允许模式也是不好的做法。请务必使用对 ``git secrets --scan $filename`` 的临时调用来测试你的模式，确保它们按预期工作。

git secrets --add-provider -- git secrets --aws-provider

This is a test!
password=ex@mplepassword
password=******
More test...

git secrets --add 'password\s*=\s*.+'
git secrets --add --allowed --literal 'ex@mplepassword'

/tmp/example:3:password=******

[ERROR] Matched prohibited pattern

Possible 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

/tmp/example:2:password=ex@mplepassword
/tmp/example:3:password=******

git secrets --add --allowed '/tmp/example:.*'
git secrets --scan /tmp/example && echo $?
# 输出: 0

git secrets --add --allowed '/tmp/example:3:.*'
git secrets --scan /tmp/example && echo $?
# 输出: 0