Secretlint

Secretlint 是一款可插拔的 linting 工具，用于防止提交凭据。

特性

• 扫描器：在项目中查找凭据并报告这些凭据
• 项目友好：易于设置你的项目并集成 CI 服务
• 提交前钩子：防止提交凭据文件
• 可插拔：允许创建自定义规则和灵活的配置
• 文档：描述规则将其检测为机密的原因

快速演示

你可以在 https://secretlint.github.io/ 上查看 secretlint 的 linting 结果。

快速开始

你可以用一条命令在你的项目上试用 Secretlint。

如果你已经安装了 Docker：

docker run -v `pwd`:`pwd` -w `pwd` --rm -it secretlint/secretlint secretlint "**/*"

如果你已经安装了 Node.js：

npx @secretlint/quick-start "**/*"

运行之后， 如果你得到空结果且退出状态为 0，则你的项目是安全的。 否则，你会得到一些错误报告，说明你的项目包含以原始数据形式存在的凭据。

如果你想要获得持续的安全性，请参阅以下安装指南，并设置提交前钩子和 CI。

安装

使用 Docker

前提条件： 需要 Docker

使用我们的 Docker 容器，以最快的下载速度获得一个运行 Node.js 和 secretlint 的环境。

你可以通过以下命令使用 secretlint 检查当前目录下的所有文件：

docker run -v `pwd`:`pwd` -w `pwd` --rm -it secretlint/secretlint secretlint "**/*"

secretlint/secretlint Docker 容器 在设计上无需配置即可工作。

此 Docker 镜像内置了以下软件包：

• @secretlint/secretlint-rule-preset-recommend
• @secretlint/secretlint-rule-pattern
• @secretlint/secretlint-formatter-sarif

更多详情，请参阅 secretlint 的 Dockerfile。

使用 Node.js

前提条件： 需要 Node.js 22+。

Secretlint 使用 JavaScript 编写。 你可以使用 npm 安装 Secretlint：

npm install secretlint @secretlint/secretlint-rule-preset-recommend --save-dev

然后你应该设置一个配置文件：

npx secretlint --init

最后，你可以像这样对任意文件或目录运行 Secretlint：

npx secretlint "**/*"

📝 Secretlint 支持 glob 模式，glob 模式应使用双引号包裹。

也可以使用 npm install --global 全局安装 Secretlint。但我们不推荐这样做，某些规则在全局安装时可能会失效。

使用单可执行二进制文件

前置条件： 无

你可以通过单可执行二进制文件，在没有 Node.js 的情况下使用 secretlint 命令。

1. 从 Releases 页面 下载最新的二进制文件
2. 将文件权限更改为可执行：chmod +x ./secretlint
3. 运行 ./secretlint --init 创建配置文件
4. 运行 ./secretlint "**/*" 对项目进行 lint

更多详情，请参阅 publish/binary-compiler README。

用法

secretlint --help 显示用法。

Secretlint CLI that scan secret/credential data.

Usage
$ secretlint [file|glob*]

Note
supported glob syntax is based on picomatch (the engine used by micromatch)
https://github.com/micromatch/picomatch#globbing-features
https://github.com/micromatch/micromatch#matching-features

Options
--init             setup config file. Create .secretlintrc.json file from your package.json
--format           [String] formatter name. Default: "stylish". Available Formatter: checkstyle, compact, github, jslint-xml, junit, pretty-error, stylish, tap, unix, json, mask-result, table
--output           [path:String] output file path that is written of reported result.
--secretlintrc     [path:String] path to .secretlintrc config file. Default: .secretlintrc.*
--secretlintignore [path:String] path to .secretlintignore file. Default: .secretlintignore
--stdinFileName    [String] filename to process STDIN content. Some rules depend on filename to check content.
--no-color         disable ANSI-color of output.
--no-terminalLink  disable terminalLink of output.
--no-maskSecrets   disable masking of secret values; secrets are masked by default.
--no-glob          disable glob pattern interpretation; treat all inputs as literal file paths.
--no-gitignore     disable .gitignore cascade respect; .gitignore files are
                   respected by default (since v13).

Options for Developer
--profile          Enable performance profile.
--secretlintrcJSON [String] a JSON string of .secretlintrc. use JSON string instead of rc file.

Experimental Options
--locale            [String] locale tag for translating message. Default: en

Examples
# Scan a single file
$ secretlint ./README.md

# Scan all files (wrap glob in double quotes to avoid shell expansion)
$ secretlint "**/*"
$ secretlint "source/**/*.ini"

# Treat inputs as literal paths (for SvelteKit (group) / Next.js [param] etc.)
$ secretlint --no-glob "src/(auth)/login.ts"

# Lint STDIN content (filename hint affects which rules apply)
$ echo "SECRET" | secretlint --stdinFileName=secret.txt

# Use a custom config file
$ secretlint "**/*" --secretlintrc=.secretlintrc.custom.json

# Scan files ignored by .gitignore (e.g. to verify build artifacts)
$ secretlint --no-gitignore "dist/**/*"

# Mask secrets in a file in-place
$ secretlint .zsh_history --format=mask-result --output=.zsh_history

# Output JSON for programmatic parsing
$ secretlint "**/*" --format=json --output=secretlint-report.json

# Output GitHub Actions annotations in CI
$ secretlint "**/*" --format=github

Exit Status
Secretlint exits with the following values:

    - 0:
      - Linting succeeded, no errors found.
      - Found only "warning" or "info" severity messages.
      - Found lint error but --output is specified.
    - 1:
      - Linting failed, errors found.
    - 2:
      - Unexpected error occurred, fatal error.

配置

Secretlint 有一个配置文件 .secretlintrc.{json,yml,js}。

• 文档：配置 Secretlint

运行 secretlint --init 后，你的目录中会生成一个 .secretlintrc.json 文件。

在该文件中，你会看到一些规则配置如下：

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend"
    }
  ]
}

id 属性是 secretlint 规则包的名称。

Secretlint 没有内置规则。 你需要添加一些规则，并且应当安装该包并将规则添加到 .secretlintrc 文件中。

每条规则都有相同的配置模式：

• options：规则的选项定义。更多详情，请参阅每条规则的文档
• disabled：如果 disabled 为 true，则禁用该规则
• allowMessageIds：allowMessageIds 是一个消息 id 数组，用于抑制你希望屏蔽的错误报告
  • 消息 id 在每条规则中定义，请参阅规则文档

示例：options

例如，@secretlint/secretlint-rule-example 在 options 中具有 allows。 这个 allows 选项定义了一个你希望忽略的 RegExp-like String 列表。

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-example",
      "options": {
        "allows": [
          "/dummy_secret/i"
        ]
      }
    }
  ]
}

当你使用像 @secretlint/secretlint-rule-preset-recommend 这样的预设时，你需要将选项放在 rules 中。

例如，@secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-aws 的一个选项

{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend",
      "rules": [
        {
          "id": "@secretlint/secretlint-rule-aws",
            "options": {
              "allows": [
	            // it will be ignored
                "xxxx-xxxx-xxxx-xxxx-xxxx"
              ]
            }
        }
      ]
    }
  ]
}

示例：allowMessageIds

例如，你通过运行 secretlint 得到了以下错误报告：

$ secretlint "**/*"

SECRET.txt
  1:8  error  [EXAMPLE_MESSAGE] found secret: SECRET  @secretlint/secretlint-rule-example

✖ 1 problem (1 error, 0 warnings)

此错误的 message id 为 @secretlint/secretlint-rule-example 中的 EXAMPLE_MESSAGE。

如果你想忽略此错误，请使用 allowMessageIds。