Talisman

A tool to detect and prevent secrets from getting checked in

[](https://opensource.org/licenses/MIT) [](https://goreportcard.com/report/thoughtworks/talisman) [](https://github.com/thoughtworks/talisman/issues) [](https://github.com/thoughtworks/talisman/actions/workflows/test-and-coverage.yml) ## 目录 - [什么是 Talisman？](#what-is-talisman) - [安装](#installation) - [安装到 path（推荐方式）](#install-onto-path-recommended-approach) - [作为全局 hook 模板安装](#installation-as-a-global-hook-template) - [配置项目](#configuring-a-project) - [与 hook 框架一起使用](#using-with-hook-frameworks) - [Pre-commit](#pre-commit) - [Husky](#husky) - [直接调用 talisman](#directly-invoking-talisman) - [升级](#upgrading) - [Talisman 实战](#talisman-in-action) - [验证](#validations) - [忽略文件](#ignoring-files) - [交互模式](#interactive-mode) - [忽略特定的检测器](#ignoring-specific-detectors) - [忽略特定的关键字](#ignoring-specific-keywords) - [忽略同类型的多个文件（使用通配符）](#ignoring-multiple-files-of-same-type-with-wildcards) - [通过指定语言范围忽略文件](#ignoring-files-by-specifying-language-scope) - [自定义搜索模式](#custom-search-patterns) - [配置严重性阈值](#configuring-severity-threshold) - [Talisman 作为命令行工具](#talisman-as-a-cli-utility) - [交互模式](#interactive-mode-1) - [Git 历史扫描器](#git-history-scanner) - [校验和计算器](#checksum-calculator) - [Talisman HTML 报告](#talisman-html-reporting) - [示例截图](#sample-screenshots) - [卸载](#uninstallation) - [从全局 hook 模板卸载](#uninstallation-from-a-global-hook-template) - [从单个仓库卸载](#uninstallation-from-a-single-repository) - [为 Talisman 做贡献](#contributing-to-talisman) # 什么是 Talisman？ Talisman 是一个扫描 git 变更集的工具，用于确保潜在的秘密 或敏感信息不会离开开发者的工作站。 它会验证发往远程的变更集中是否包含可疑内容——例如 潜在的 SSH 密钥、授权 token、私钥等。 # 安装 Talisman 支持 MAC OSX、Linux 和 Windows。 Talisman 可以通过以下方式之一进行安装和使用： 1. 作为独立的可执行文件 2. 作为全局 [git hook 模板](https://git-scm.com/docs/git-init#_template_directory) 的 git hook 和命令行工具（用于 git 仓库扫描） 3. 作为单个 git 仓库中的 git hook Talisman 可以被设置为 git 仓库上的 pre-commit 或 pre-push hook。 请参阅下面的说明。 *免责声明：Talisman 无法检测通过 git 仓库中的强制推送混入的秘密。强制推送本身就具有高风险，我们建议 git 仓库管理员采取适当的措施来授权此类活动。* ## 安装到 path（推荐方式） 我们建议将 `talisman` 安装到您的 path 中，以便它能够被 git hook 框架和脚本调用。从我们的 [发布页面](https://github.com/thoughtworks/talisman/releases) 中为您的系统选择正确的二进制文件，或者运行 我们的 [安装脚本](https://github.com/thoughtworks/talisman/blob/main/install.sh)： ``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)" ``` 或者设置环境变量 `INSTALL_LOCATION` 来为 二进制文件指定自定义位置： ``` INSTALL_LOCATION=/usr/local/bin bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)" ``` 或者设置环境变量 `VERSION` 为已发布的标签来安装特定版本： ``` VERSION=v1.36.0 bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/install.sh)" ``` 或者在 Linux 上使用 linuxbrew，在 macOS 上使用 homebrew，在终端中运行以下 命令： ``` brew install talisman ``` ## 作为全局 hook 模板安装 我们提供的脚本会将 Talisman 安装为 **pre-commit git hook 模板**，因为这会使 Talisman 不仅存在于您现有的 git 仓库中，还会存在于您 'init' 或 'clone' 的任何新仓库中。 1. 在您的终端上运行以下命令，将二进制文件下载并安装到 $HOME/.talisman/bin 作为 pre-commit hook： ``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/install.bash)" ``` 或者 作为 pre-push hook： ``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/install.bash)" -- pre-push ``` 2. 如果您的 `$PATH` 中没有设置 TALISMAN\_HOME，系统会提示您一个合适的位置来设置它。请选择您机器上配置环境变量来源的选项编号。 请记住对路径文件执行 *source* 命令或重启您的终端。 如果您选择稍后再设置 `$PATH`，请将 TALISMAN\_HOME=$HOME/.talisman/bin 导出到路径中。 3. 选择一个基本目录，让 Talisman 能够扫描其中的所有 git 仓库，并设置一个 git hook（pre-commit 或 pre-push，如步骤 1 中所选择的）作为符号链接。 此脚本不会覆盖已有的 hooks。如果您有现存的 hooks，可以通过 [hook 框架](#using-with-hook-frameworks) 来添加 talisman。 - 您可以在执行安装之前设置 SEARCH_ROOT 环境变量为基础目录的路径，这样在安装过程中就不需要手动输入了。 # 配置项目 ## 与 hook 框架一起使用 全局安装 talisman 作为 hook 不会覆盖任何现有的 hooks。如果 安装脚本发现任何现有的 hooks，它只会在控制台上进行提示。要运行多个 hooks，我们建议使用诸如 pre-commit 或 husky 这样的 hook 框架。这些说明假定 talisman 可执行文件已 安装在您系统路径中的某个位置。 ### Pre-commit 使用 [pre-commit](https://pre-commit.com) 来管理现有 hooks 以及 Talisman。在您的 `.pre-commit-config.yaml` 中引用我们的 [pre-commit-hooks](.pre-commit-hooks.yaml)： ``` - repo: https://github.com/thoughtworks/talisman rev: 'v1.32.2' # Update me! hooks: # both pre-commit and pre-push supported # - id: talisman-push - id: talisman-commit ``` ### Husky [husky](https://typicode.github.io/husky) 是一个用于管理 hooks 的 npm 模块。 将以下行添加到您的 `package.json` 中的 husky pre-commit 配置里： ``` talisman --githook pre-commit ``` ## 直接调用 talisman 一旦 talisman 可执行文件[安装](#install-onto-path-recommended-approach)完成， 您就可以为 git 仓库配置一个独立的 pre-commit hook： ``` cd my-git-project echo "talisman -g pre-commit" >> .git/hooks/pre-commit chmod +x .git/hooks/pre-commit ``` # 升级 自 v0.4.4 版本发布以来，Talisman 会自动更新 二进制文件到最新发布版，这是在调用 hook（根据您的设置，在 pre-commit/pre-push 时）进行的。所以，您只需放松一下，无需任何额外努力即可持续使用最新的 Talisman。 可以设置以下环境变量： 1. TALISMAN_SKIP_UPGRADE：如果您想跳过自动升级检查，请设置为 true。默认为 false。 2. TALISMAN_UPGRADE_CONNECT_TIMEOUT：升级取消前的最大连接超时时间（以秒为单位）。默认为 10 秒。 如果您确实需要手动升级，请按以下步骤操作：
[推荐] 更新 Talisman 二进制文件和 hook 脚本至最新版本： ``` curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/update_talisman.bash > /tmp/update_talisman.bash && /bin/bash /tmp/update_talisman.bash ``` 通过执行以下命令仅更新 Talisman 二进制文件： ``` curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/update_talisman.bash > /tmp/update_talisman.bash && /bin/bash /tmp/update_talisman.bash talisman-binary ``` # Talisman 实战 安装成功后，Talisman 会在每次 commit 或 push（根据安装时的选择）之前自动运行对明显秘密的检查。如果检测到任何安全违规，talisman 将显示详细的错误报告： ``` $ git push Talisman Report: +-----------------+-------------------------------------------------------------------------------+ | FILE | ERRORS | +-----------------+-------------------------------------------------------------------------------+ | danger.pem | The file name "danger.pem" | | | failed checks against the | | | pattern ^.+\.pem$ | +-----------------+-------------------------------------------------------------------------------+ | danger.pem | Expected file to not contain hex encoded texts such as: | | | awsSecretKey=c64e8c79aacf5ddb02f1274db2d973f363f4f553ab1692d8d203b4cc09692f79 | +-----------------+-------------------------------------------------------------------------------+ ``` 在上面的例子中，文件 *danger.pem* 被标记为安全违规，原因如下： * 文件名与预设的模式之一匹配。 * 文件包含一个 awsSecretKey，被 Talisman 扫描并标记。 如果您将 Talisman 安装为 pre-commit hook，它将仅扫描每次 commit 中的 _diff_。这意味着它只会报告文件中被更改部分的错误。 如果您将 Talisman 安装为 pre-push hook，它将扫描发生更改的完整文件。如上所述，建议您将 Talisman 作为 **pre-commit hook** 使用。 ## 验证 以下检测器会针对变更集执行，以检测秘密/敏感信息： * **Encoded values** - 扫描 Base64、十六进制等编码的秘密。 * **File content** - 扫描文件中可能是潜在秘密或密码的可疑内容。 * **File size** - 扫描可能包含密钥或其他秘密的大文件。 * **Entropy** - 扫描可能包含密码的高熵内容。 * **Credit card numbers** - 扫描可能是潜在信用卡号的内容。 * **File names** - 扫描可能表明其包含秘密（如密钥、凭证等）的文件名和扩展名。 ## 忽略文件 如果您*真的*确定要推送该文件，您可以将其配置到项目根目录的 `.talismanrc` 文件中。忽略失败文件所需的内容将在 Talisman 错误报告之后立即由 Talisman 打印在控制台上： ``` If you are absolutely sure that you want to ignore the above files from talisman detectors, consider pasting the following format in .talismanrc file in the project root fileignoreconfig: - filename: danger.pem checksum: cf97abd34cebe895417eb4d97fbd7374aa138dcb65b1fe7f6b6cc1238aaf4d48 ignore_detectors: [] ``` 在 `.talismanrc` 文件中输入此项，只要校验和与 `checksum` 字段中提到的值一致，Talisman 就会忽略 `danger.pem` 文件。 ### 交互模式 **仅适用于非 Windows 用户** 如果每次遇到 Talisman 报错时都要将内容复制到 .talismanrc 显得过于麻烦，您可以启用交互模式，让 Talisman 协助您提示添加要忽略的文件。 只需遵循以下简单步骤： 1. 打开设置环境变量的 bash 配置文件（.bashrc、.bash_profile、.profile 或其他位置） 2. 您会在 `# >>> talisman >>>` 下看到 `TALISMAN_INTERACTIVE` 变量 3. 如果尚未设置为 true，请添加 `export TALISMAN_INTERACTIVE=true` 4. 不要忘记保存并对该文件执行 source 命令 就是这样！每次 Talisman hook 在 pre-push/pre-commit 期间发现错误时，只需按照 Talisman 的指示操作即可。 请注意，在没有验证内容的情况下不要盲目忽略文件。您必须确信没有秘密被泄露出去。 ### 忽略特定的检测器 下面是可以在 `.talismanrc` 文件中配置的各种字段的详细说明： * `filename`：此字段应填写完全限定的文件名。 * `checksum`：此字段应始终使用上面显示的消息中 Talisman 指定的值。如果在任何时候对文件进行了新的更改，将产生新的校验和，Talisman 将再次扫描该文件以查找任何潜在的安全威胁。 * `ignore_detectors`：此字段将禁用特定文件的某些检测器。 例如，如果您的 `init-env.sh` 文件名触发了警告，您可以仅禁用 此警告，同时在出现其他问题时（例如文件内容）仍然收到提醒： ``` fileignoreconfig: - filename: init-env.sh checksum: cf97abd34cebe895417eb4d97fbd7374aa138dcb65b1fe7f6b6cc1238aaf4d48 ignore_detectors: [filename, filesize] ``` 注意：在这里，init-env.sh 的 filename 和 filesize 检测器都被忽略了，但 filecontent 检测器仍然会在 `init-env.sh` 上激活。 目前，您可以忽略 * `filecontent` * `filename` * `filesize` ### 忽略特定的关键字 由于您的某些文件可能包含诸如 `key` 或 `pass` 之类的关键字，而这些关键字不一定与秘密相关，您可能希望忽略这些关键字以减少误报。 这可以通过在文件级别和/或仓库级别使用 `allowed_patterns` 字段来实现： ``` fileignoreconfig: - filename: test allowed_patterns: [key] allowed_patterns: - keyword - pass ``` 在前面的例子中，`test` 文件中允许出现 `key`，而在仓库级别允许出现 `keyword` 和 `pass`。 `allowed_patterns` 字段也支持 Golang 正则表达式。下面是一个简单的代码示例，展示了 Golang RegExp 的用处： ``` export AWS_ACCESS_KEY_ID = AKIAIO5FODNN7EXAMPLE export AWS_ACCESS_KEY_ID=$(vault read -field=value path/to/aws-access-key-id) ``` 默认情况下，Talisman 会对这两行都发出警报。在第二行中，我们从 Hashicorp Vault 中提取 AWS Access Key ID，这并没有将秘密暴露给代码。如果这种用法在您的代码中很常见，您可能希望告诉 Talisman 在您使用 Vault 时不要发出警报。这可以通过如下配置来实现： ``` allowed_patterns: - export\ AWS[ \w]*KEY[ \w]*=.*vault\ read.* ``` ### 忽略同类型的多个文件（使用通配符） 您可以选择忽略特定类型的所有文件，因为您知道它们总是安全的，并且不希望 Talisman 扫描它们。 步骤： 1. 为您想要忽略的文件格式化一个通配符模式。例如，`*.lock` 2. 使用[校验和计算器](#checksum-calculator)输入该模式并获取一个集合校验和。例如，`talisman --checksum="*.lock" ` 3. 将控制台上打印的 fileconfig 块复制到 .talismanrc 文件中。 如果其中任何一个文件被修改，talisman 将再次扫描这些文件，除非您重新计算新的校验和并替换 .talismanrc 文件中的内容。 ### 通过指定语言范围忽略文件 您可以在 talismanrc 中为项目指定语言范围，从而选择忽略文件。 ``` scopeconfig: - scope: go - scope: node - scope: images - scope: php - scope: python ``` Talisman 被配置为基于指定的范围忽略某些文件。例如，在 scopeconfig 中指定 node 范围将阻止 talisman 扫描诸如 yarn.lock 或 package-lock.json 等文件。 您可以指定多个范围。 目前 .talismanrc 仅支持针对 go、node、php 和 images 的 scopeconfig。其他范围将很快添加。 ### 自定义搜索模式 您可以指定自定义的正则表达式模式，以在当前仓库中查找内容 ``` custom_patterns: - pattern1 - pattern2 ```
**注意**：.talismanignore 的使用已被弃用。.talismanrc 文件取代了它，因为： * .talismanrc 具有更易读的 yaml 格式 * 它还引入了更安全的做法，每次修改带有潜在敏感值的文件时都需要进行审查 * 新格式还带来了可扩展性，以引入新的可用功能。敬请期待更多更新 ## 配置严重性阈值 每次验证都会关联一个严重性级别 1. Low 2. Medium 3. High 您可以在您的 .talismanrc 中指定阈值： ``` threshold: medium ``` 这将报告所有 Medium 严重性级别及以上的问题（低于阈值的潜在风险将被报告为警告） 1. 可以在[配置文件](detector/severity/severity_config.go)中找到包含其严重性级别的所有风险列表。 2. 默认情况下，阈值设置为 low。 3. 您添加的任何自定义搜索模式都将被视为 high 严重性。 ## 配置自定义严重性 您可以在 .talismanrc 文件中自定义 Talisman 提供的检测器的[安全级别](detector/severity/severity_config.go)： ``` custom_severities: - detector: Base64Content severity: medium - detector: HexContent severity: low ``` 通过使用自定义严重性和严重性阈值，可以将 Talisman 配置为仅根据您的上下文对重要内容发出警报。这对于减少误报非常有用。 ## Talisman 作为命令行工具 如果您在命令行中执行 `talisman`，您将能够看到所有可以传递的参数选项。 ``` -c, --checksum string checksum calculator calculates checksum and suggests .talismanrc format -d, --debug enable debug mode (warning: very verbose) -g, --githook string either pre-push or pre-commit (default "pre-push") --ignoreHistory scanner scans all files on current head, will not scan through git commit history -i, --interactive interactively update talismanrc (only makes sense with -g/--githook) -p, --pattern string pattern (glob-like) of files to scan (ignores githooks) -r, --reportdirectory string directory where the scan reports will be stored -s, --scan scanner scans the git commit history for potential secrets -w, --scanWithHtml generate html report (**Make sure you have installed talisman_html_report to use this, as mentioned in Readme**) -v, --version show current version of talisman ``` ### 交互模式 当您经常遇到许多被 talisman hook 标记的文件，而您知道它们可以安全提交时，您可以使用此功能让 talisman 简化您的操作过程。交互模式将允许 Talisman 提示您直接从命令提示符将想要忽略的文件添加到 .talismanrc 中。 要启用此功能，您需要在 bash 文件中将 TALISMAN_INTERACTIVE 变量设置为 true。 您可以通过以下两种方式之一在交互模式下调用 talisman： 1. 打开您的 bash 文件，并添加 ```export TALISMAN_INTERACTIVE=true``` 不要忘记对该 bash 文件执行 source 命令以使变量生效！ 2. 或者，您也可以使用命令行工具调用交互模式 （用于 pre-commit hook） ```talisman -i -g pre-commit``` *注意*：如果您使用 IDE 的版本控制集成来进行 git 操作，此功能将无法工作。您仍然可以手动将建议的文件名和校验和输入到 .talismanrc 文件中。 ### Git 历史扫描器 您现在可以从命令行执行 Talisman，并将其潜在地添加到您的 CI/CD 流水线中，以扫描您仓库的 git 历史记录，从而发现任何敏感内容。 这也包括扫描 .talismanrc 文件中列出的文件。 **步骤**： 1. 进入要扫描的 git 目录路径 `cd ` 2. 运行扫描命令 `talisman --scan` * 运行此命令将在当前目录的根目录下创建一个名为 talisman_reports 的文件夹，并将报告文件存储在那里。 * 您还可以通过提供附加参数 --reportdirectory 或 --rd 来指定报告的位置
例如，`talisman --scan --reportdirectory=/Users/username/Desktop` 您可以使用上面给出的其他选项进行扫描。 Talisman 目前不支持在扫描时忽略文件。 ### 校验和计算器 Talisman 校验和计算器会输出 yaml 格式，您可以直接复制并粘贴到 .talismanrc 文件中，以便从 talisman 检测器中忽略特定的文件格式。 要运行校验和，请 "cd" 进入仓库的根目录并运行以下命令 例如： `talisman --checksum="*.pem *.txt"` 1. 此命令会查找仓库中的所有 .pem 文件，并计算所有这些文件的集合校验和，然后输出用于 .talismanrc 的 yaml 格式。它以相同的方式处理 .txt 文件。 2. 可以用空格分隔提供多个文件名/模式。 示例输出： ``` .talismanrc format for given file names / patterns fileignoreconfig: - filename: '*.pem' checksum: f731b26be086fd2647c40801630e2219ef207cb1aacc02f9bf0559a75c0855a4 ignore_detectors: [] - filename: '*.txt' checksum: d9e9e94868d7de5b2a0706b8d38d0f79730839e0eb4de4e9a2a5a014c7c43f35 ignore_detectors: [] ``` 注意：校验和计算器在计算文件的集合校验和时会考虑暂存的文件。 # Talisman HTML 报告 Powered by Talisman 命令行工具 `talisman` 还具有提供详细且可共享的 HTML 报告的功能。安装 Talisman 后，请按照 [talisman-html-report](https://github.com/jaydeepc/talisman-html-report) 中提到的步骤，在 `.talisman` 文件夹中安装报告包。要生成 html 报告，请运行： * `talisman --scanWithHtml` 这将扫描仓库并在被扫描的仓库下创建一个 `talisman_html_report` 文件夹。我们需要在此仓库中启动一个 HTTP 服务器来访问报告。以下是启动 HTTP 服务器的推荐方法： * `python -m SimpleHTTPServer (eg: 8000)` 您现在可以通过导航到以下地址来访问报告： `http://localhost:8000` ## 示例截图 * 欢迎 * 概要 * 详细报告 * 错误报告 **注意**：如果您在 CI 或任何其他托管环境中运行 Talisman，则无需启动服务器 # 卸载 卸载过程取决于您当初是如何安装 Talisman 的。 您可能选择了作为全局 hook 模板安装，或者安装在单个仓库中。 请根据您在安装时选择的选项，遵循以下步骤操作。 ## 从全局 hook 模板卸载 在终端上运行以下命令，从您的机器上全局卸载 talisman。 对于 pre-commit hook： ``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/uninstall.bash)" ``` 对于 pre-push hook： ``` bash -c "$(curl --silent https://raw.githubusercontent.com/thoughtworks/talisman/main/global_install_scripts/uninstall.bash)" -- pre-push ``` 这将会 1. 询问您所有仓库的基础目录，找到其中的所有 git 仓库并移除 talisman hooks 2. 从 .git-template 中移除 talisman hook 3. 从中央安装位置（$HOME/.talisman/bin）移除 talisman。
您需要手动从环境变量中移除 TALISMAN_HOME ## 从单个仓库卸载 当您安装 Talisman 时，它必须在安装过程中于您的仓库中创建了一个 pre-commit 或 pre-push hook（根据您的选择）。 您可以通过从仓库的 .git/hooks 文件夹中删除 Talisman pre-commit 或 pre-push hook 来手动移除该 hook。 # 为 Talisman 做贡献 要为 Talisman 做贡献，请查看我们的[贡献指南](contributing.md)。

标签：CI/CD安全, DevSecOps, EVTX分析, Go语言, Husky, Llama, LLM应用, Pre-commit Hook, SolidJS, Thoughtworks, Token检测, 上游代理, 代码安全, 代码提交检查, 凭证扫描, 安全助手, 密码防护, 开源安全工具, 日志审计, 漏洞枚举, 程序破解, 逆向工程平台, 错误基检测, 静态代码分析