# secrets hook：检测硬编码的密钥

> 在命令行中扫描代码库里硬编码的凭证。

规范链接: https://lagune.ai/zh-CN/docs/hooks/secrets
语言: zh-CN
原文: https://lagune.ai/docs/hooks/secrets
最后更新: 2026-11-03

`secrets` hook 会标记没有从环境中读取、而是**固化在源代码中的凭证**。它依据的是**来源**（字面量还是环境变量读取），而不是值的内容，因此不需要一份详尽的服务商前缀清单，也几乎不会产生误报。它是 [`secrets` 专项](https://lagune.ai/zh-CN/docs/catalog) 背后的确定性引擎。

服务商格式特征、连接字符串中的凭证，以及赋给以密钥命名的标识符的字面量，都**与语言无关**：同一个字符串在任何文件里读起来都一样。而依赖语法的两种启发式规则（带硬编码默认值的环境变量读取，以及流入日志 sink 的密钥）则**能识别语言**，因此绝不会在 Rust 文件里去找 JavaScript 的 `console.log`，Python 的 `os.getenv("X", "default")` 也会按它自己的写法识别。

## 如何运行

```bash
npx lagune read secrets                  # scans the whole project
npx lagune read secrets --dir src        # scans a directory
npx lagune read secrets --file config.ts # scans a single file
```

扫描最多输出两个部分。**Hardcoded secrets found** 是发现项集合（以密钥命名的环境变量带有硬编码默认值、嵌在连接字符串里的凭证，或匹配收录的服务商格式的值），因此 hook 会以非零退出码退出。**Secret handling to review manually** 是线索集合：赋给以密钥命名的标识符的普通字面量（它的来源可以判定，但值是否真是密钥无法判定），以及流入日志或响应 sink 的以密钥命名的值。扫描结果干净时会输出 `no hardcoded secrets found`。

### CLI 选项

| 选项     | 值       | 说明                                                         |
| -------- | -------- | ------------------------------------------------------------ |
| `--dir`  | 一个目录 | 将扫描范围限定在某个目录。可重复使用，也可与 `--file` 组合。 |
| `--file` | 一个文件 | 将扫描范围限定在单个文件。可重复使用，也可与 `--dir` 组合。  |

不带任何选项时，它会扫描整个项目。

### 语言覆盖范围

环境变量默认值这一发现项和日志 sink 这一线索，读取的是每种语言各自的一组写法，因此只覆盖下列语言，在其他语言中不会报告。其余三种信号会在**所有**文件上运行。

| 信号             | 语言                                                                             |
| ---------------- | -------------------------------------------------------------------------------- |
| 环境变量默认值   | JavaScript/TypeScript、Python、Ruby、PHP、Kotlin、Java、Go（`cmp.Or`）、Rust、C# |
| 日志 / 响应 sink | JavaScript/TypeScript、Python、Ruby、PHP、Java、Kotlin、Go、Rust、C、C++、C#     |

**这是否涉及政策问题？**

不涉及。识别密钥的格式，以警告它已被提交，是标准的防御性工具做法，gitleaks、trufflehog 和 GitHub push-protection 做的也是同样的事。这个 hook 只附带检测特征（公开的令牌**格式**），从不包含真实可用的密钥，它负责审计和解释，而不是外泄数据。

## 常见问题

### secrets hook 如何避免误报？

它依据的是来源，而不是值的内容。高置信度的格式（服务商令牌、环境变量默认值、连接字符串）属于发现项，会以非零退出码退出。赋给以密钥命名的标识符的普通字面量是一条需要确认的审查线索，而从 process.env 读取的同名标识符根本不会被标记。