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

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

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

然后您应该设置一个配置文件：```
npx secretlint --init

:memo: Secretlint 支持 [glob 模式](https://github.com/mrmlnc/fast-glob#basic-syntax)，glob 模式需用双引号包裹。

也可以使用 `npm install --global` 全局安装 Secretlint。但**不推荐**，因为某些规则可能在全局环境中失效。

### 使用独立可执行二进制文件

**前提条件：** 无

你可以通过独立可执行二进制文件在无需 Node.js 的情况下使用 `secretlint` 命令。

1. 从 [Releases 页面](https://github.com/secretlint/secretlint/releases) 下载最新二进制文件
2. 修改文件权限为可执行：`chmod +x ./secretlint`
3. 运行 `./secretlint --init` 创建配置文件
4. 运行 `./secretlint "**/*"` 对项目进行 lint

更多详情请参考 [publish/binary-compiler](https://github.com/secretlint/secretlint/blob/HEAD/publish/binary-compiler) 的 README。

## 使用方法

`secretlint --help` 显示用法信息。

    Secretlint CLI that scan secret/credential data.
    
    用法
    $ secretlint [file|glob*]
    
    注意
    支持的 glob 语法基于 picomatch（micromatch 使用的引擎）
    https://github.com/micromatch/picomatch#globbing-features
    https://github.com/micromatch/micromatch#matching-features
    
    选项
    --init             设置配置文件。根据你的 package.json 创建 .secretlintrc.json 文件
    --format           [字符串] 格式化工具名称。默认："stylish"。可用格式：checkstyle, compact, github, jslint-xml, junit, pretty-error, stylish, tap, unix, json, mask-result, table
    --output           [路径:字符串] 输出文件路径，用于写入报告结果。
    --secretlintrc     [路径:字符串] .secretlintrc 配置文件的路径。默认为 .secretlintrc.*
    --secretlintignore [路径:字符串] .secretlintignore 文件的路径。默认为 .secretlintignore
    --stdinFileName    [字符串] 处理 STDIN 内容时使用的文件名。某些规则依赖于文件名来检查内容。
    --no-color         禁用输出的 ANSI 颜色。
    --no-terminalLink  禁用输出的终端链接。
    --no-maskSecrets   禁用秘密值的遮蔽；默认情况下秘密会被遮蔽。
    --no-glob          禁用 glob 模式解释；将所有输入视为字面文件路径。
    --no-gitignore     禁用 .gitignore 级联遵守；默认（从 v13 开始）会遵守 .gitignore 文件。
    
    开发者选项
    --profile          启用性能分析。
    --secretlintrcJSON [字符串] .secretlintrc 的 JSON 字符串。使用 JSON 字符串替代 rc 文件。
    
    实验性选项
    --locale           [字符串] 消息翻译的语言标签。默认：en
    
    示例
    # 扫描单个文件
    $ secretlint ./README.md

    # 扫描所有文件（将 glob 用双引号包裹以避免 shell 展开）
    $ secretlint "**/*"
    $ secretlint "source/**/*.ini"

    # 将输入视为字面路径（适用于 SvelteKit (group) / Next.js [param] 等）
    $ secretlint --no-glob "src/(auth)/login.ts"

    # 对 STDIN 内容进行 lint（文件名提示会影响哪些规则生效）
    $ echo "SECRET" | secretlint --stdinFileName=secret.txt

    # 使用自定义配置文件
    $ secretlint "**/*" --secretlintrc=.secretlintrc.custom.json

    # 扫描被 .gitignore 忽略的文件（例如验证构建产物）
    $ secretlint --no-gitignore "dist/**/*"

    # 原地遮蔽文件中的秘密
    $ secretlint .zsh_history --format=mask-result --output=.zsh_history

    # 输出 JSON 以供编程解析
    $ secretlint "**/*" --format=json --output=secretlint-report.json

    # 在 CI 中输出 GitHub Actions 注解
    $ secretlint "**/*" --format=github
    
    退出状态
    Secretlint 退出时返回以下值：
    
        - 0：
          - Lint 成功，未发现错误。
          - 发现 lint 错误但指定了 --output。
        - 1：
          - Lint 失败，发现错误。
        - 2：
          - 发生意外错误，致命错误。

## 配置

Secretlint 使用配置文件 `.secretlintrc.{json,yml,js}`。

- 文档：[配置 Secretlint](https://github.com/secretlint/secretlint/blob/HEAD/docs/configuration.md)

运行 `secretlint --init` 后，你会在目录中得到一个 `.secretlintrc.json` 文件。

其中会配置一些规则，如下所示：```json
{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend"
    }
  ]
}

当您使用像 `@secretlint/secretlint-rule-preset-recommend` 这样的预设时，需要将选项放在 `rules` 中。例如，`@secretlint/secretlint-rule-preset-recommend > @secretlint/secretlint-rule-aws` 的选项。```json5
{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-preset-recommend",
      "rules": [
        {
          "id": "@secretlint/secretlint-rule-aws",
            "options": {
              "allows": [
	            // it will be ignored
                "xxxx-xxxx-xxxx-xxxx-xxxx"
              ]
            }
        }
      ]
    }
  ]
}

这个错误的 message id 是 `EXAMPLE_MESSAGE`，位于 `@secretlint/secretlint-rule-example`。

如果你想要忽略此错误，请使用 `allowMessageIds`。```json
{
  "rules": [
    {
      "id": "@secretlint/secretlint-rule-example",
      "allowMessageIds": ["EXAMPLE_MESSAGE"]
    }
  ]
}

### 通过 `.gitignore` 和 `.secretlintignore` 忽略文件

Secretlint 以与 Git 相同的方式遍历文件系统，遵循嵌套的 `.gitignore` 文件。任何从工作目录到文件的路径中被某个 `.gitignore` 匹配的文件或目录都会被跳过。

`.secretlintignore` 的工作方式与 `.gitignore` 相同，并且会额外被考虑。解析顺序如下：

1. 内置忽略项：`.git`、`node_modules` 和 `.secretlintrc*` 系列。
2. 由 `--secretlintignore` 指向的文件（默认：`.secretlintignore`）。
3. 每个目录的 `.gitignore`（级联）。

要扫描被 gitignore 忽略的文件——例如，在项目中的 `.env` 文件被 gitignore 忽略——请传递 `--no-gitignore`：```
secretlint --no-gitignore "**/*"

更多详情，请参见 [配置 Secretlint](https://github.com/secretlint/secretlint/blob/HEAD/docs/configuration.md)。

## 使用场景

### 在 lint 错误消息中屏蔽密钥（默认行为）

Secretlint 默认会在 lint 错误消息中屏蔽密钥。这有助于防止在 CI 日志、终端输出或使用 AI 代理工具时意外泄露密钥。```bash
# Secrets are masked by default
$ secretlint "**/*"

### 修复密钥

Secretlint 无法自动修复密钥。
然而，`--format=mask-result` 选项可以遮蔽输入文件中的密钥，这非常有用。

例如，你可以遮蔽 `.zsh_history` 文件中的密钥并覆盖它。```bash
$ secretlint .zsh_history --format=mask-result --output=.zsh_history

添加钩子到 `.husky/pre-commit`：```
npx husky add .husky/pre-commit "npx --no-install lint-staged"

> **注意：** 需要使用 `--no-glob` 标志，因为 lint-staged 会传递包含 glob 特殊字符（例如 Next.js、SvelteKit 等使用的 `(group)` 或 `[param]` 路由模式）的字面文件路径。

这意味着在提交前由 Secretlint 检查每个暂存的文件。

#### [pre-commit](https://github.com/pre-commit/pre-commit)

**用例：** 你有一个正在使用 Docker 开发的项目。易于集成到 Secretlint。

安装 [pre-commit](https://pre-commit.com/#install)

    # macOS. see also https://pre-commit.com/#install
    brew install pre-commit

创建 `.pre-commit-config.yaml`：```
-   repo: local
    hooks:
    -   id: secretlint
        name: secretlint
        language: docker_image
        entry: secretlint/secretlint:latest secretlint

### 全局的 Pre-commit 钩子

**使用场景：** 如果你想使用 secretlint 检查任何项目，你可以使用全局的 git 钩子。

[Git 2.9+](https://github.blog/2016-06-13-git-2-9-has-been-released/) 支持 [`core.hooksPath`](https://git-scm.com/docs/githooks)。
它允许全局集成 secretlint。

我们创建了一个使用 secretlint + Docker 的 git 钩子示例项目。

- [secretlint/git-hooks](https://github.com/secretlint/git-hooks)
    - 要求：Docker

你可以通过以下步骤进行设置：```shell script
# clone this repository
git clone https://github.com/secretlint/git-hooks git-hooks
cd git-hooks
# integrate secretlint to git hook globally
git config --global core.hooksPath $(pwd)/hooks

##### `--format github` 用于 Pull Request 注释

您可以使用 `--format github` 在 Pull Request 文件上显示 lint 错误注释。
此格式化程序输出 [GitHub Actions 工作流命令](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions)，这些命令直接在 Pull Request 中已更改的文件上显示错误注释。```yaml
      - name: Lint with Secretlint
        run: npx secretlint --format github "**/*"

#### Mega-Linter

[Mega-Linter](https://nvuillam.github.io/mega-linter/) 是一个本地化兼容任何 CI 工具的 linters 聚合器，内置 [80 多个 linting 应用](https://nvuillam.github.io/mega-linter/supported-linters/)，默认包含 [**secretlint**](https://nvuillam.github.io/mega-linter/descriptors/credentials_secretlint/)。

你可以使用以下命令在任意仓库项目中[安装](https://nvuillam.github.io/mega-linter/installation/)它（需预先安装 Node.js）：

```shell
$ npx mega-linter-runner --install
``````shell
npx mega-linter-runner --install

## 语义版本控制策略

Secretlint 项目遵循[语义化版本控制](https://semver.org/ "Semantic Versioning")([secretlint-rule-preset-canary](https://github.com/secretlint/secretlint/blob/HEAD/packages/@secretlint/secretlint-rule-preset-canary) 是个例外)。

- 补丁版本（预期不会破坏你的 lint 构建）
    - CLI 或核心（包括格式化程序）中的错误修复。
    - 文档改进。
    - 非面向用户的更改，例如重构。
    - 在失败的版本发布后重新发布（即，发布一个对任何人都无法正常工作的版本）。
- 次要版本（可能会破坏你的 lint 构建）
    - 新增选项。
    - 某个现有规则被弃用。
    - 创建了新的 CLI 功能。
    - 添加了新的公共 API（新类、新方法、现有方法的新参数等）。
        - 这可能会破坏 TypeScript 定义
    - 创建了新的格式化程序。
- 主要版本（会破坏你的 lint 构建）
    - 为现有规则添加新选项，导致 secretlint 默认报告更多错误。
    - 移除了某个现有格式化程序。
    - 向规则预设添加新的默认规则。
    - 移除了部分公共 API，或以不兼容的方式进行了更改。

## 动机

- [git-secrets](https://github.com/awslabs/git-secrets) 很有用，但它在每个项目中的设置很麻烦。
    - 其主要用例是全局安装。
    - Secretlint 希望为项目安装，并允许为每个项目自定义设置。
- [repo-security-scanner](https://github.com/UKHomeOffice/repo-security-scanner)、[Gitleaks](https://github.com/zricethezav/gitleaks) 和 [truffleHog](https://github.com/dxa4481/truffleHog) 是不错的扫描工具。
    - Secretlint 需要灵活的自定义功能，包括忽略定义和自定义规则。
- [detect-secrets](https://github.com/Yelp/detect-secrets) 是类似的工具，但它采用 opt-out 方法。
    - Secretlint 采用 opt-in 方法。
    - 我们还需要用户自定义规则。
        - 参见 [Bring-your own-plugins (BYOP), via --custom-plugins option by KevinHock · Pull Request #255 · Yelp/detect-secrets](https://github.com/Yelp/detect-secrets/pull/255)
- GitHub 支持[秘密扫描](https://docs.github.com/en/code-security/secret-security/about-secret-scanning)，但它仅在提交后生效[~~推送~~](https://docs.github.com/en/code-security/secret-scanning/push-protection-for-users)。
    - Secretlint 在你的本地机器上运行，可以阻止提交。

## 哲学

- 减少 lint 的误报
- 集成到开发工作流
- 赋能用户贡献

### Opt-in 而非 Opt-out

Secretlint 采用 opt-in 方法。

根据我们的经验，默认报告各种错误的 lint 工具很难使用。
Opt-in 方法有助于逐步引入 Secretlint。

这将有助于通过配置减少误报。

### 规则即文档

我们认为每条规则本身就是一份文档。
因此，每条规则都应该有合理的文档。

我们需要描述为什么这个文件会报错。
没有文档的规则只是主观意见。

描述错误的原因将有助于减少误报。

此外，Secretlint CLI 支持终端中的超链接。
这意味着你可以从 lint 错误消息直接跳转到规则文档。

![输出中的可点击链接](https://assets.kitploit.com/production/public/readmes/6649/890de2bdbaaae05b3b40c5bbe32b8389a7672beb231308453e585e308afca2be.png)

> 在 iTerm 2 上的示例：Cmd + 点击错误消息的 messageId，在浏览器中打开 [AWSSecretAccessKey](https://github.com/secretlint/secretlint/blob/master/packages/%40secretlint/secretlint-rule-aws/README.md#awssecretaccesskey)。

如果你想了解支持超链接的终端，请参见[终端模拟器中的超链接](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)。

同时，欢迎为 secretlint 文档做出贡献！

### 为什么选择 Node.js？

- 包管理器
    - 需要包管理器来实现灵活的插件系统
    - Node.js 有 npm 和 pnpm 作为包管理器
    - 包管理器帮助用户安装自定义插件/规则
- 现有参考实现
    - Node.js 已经拥有可插拔的 lint 工具，如 ESLint、textlint、stylelint 等
    - 因此 Node.js 用户熟悉可插拔的 lint 工具
    - 我之前使用相同的思路创建了 textlint，因此我对 Node.js 很熟悉
- 用户
    - JavaScript 是一种流行的语言
    - 它让用户能够贡献
    - 用户可以亲手创建自己的规则

当然，secretlint 也支持 [Docker](https://hub.docker.com/r/secretlint/secretlint)。

## 更新日志

请参见 [Releases 页面](https://github.com/secretlint/secretlint/releases)。

## 贡献

随时欢迎拉取请求和收藏。

如有错误和功能请求，请[创建一个 issue](https://github.com/secretlint/secretlint/issues)。

另请参阅 [CONTRIBUTING.md](https://github.com/secretlint/secretlint/blob/HEAD/CONTRIBUTING.md) 和 [CODE_OF_CONDUCT.md](https://github.com/secretlint/secretlint/blob/HEAD/CODE_OF_CONDUCT.md)。

### 添加新规则

你可以使用 `pnpm run gen:rule` 命令来创建新规则。```shell script
pnpm run gen:rule