okta-graveyard/repo-supervisor
GitHub: okta-graveyard/repo-supervisor
一款基于熵值分析的代码密钥检测工具，支持 GitHub PR 自动扫描和本地 CLI 两种运行模式。
Stars: 654 | Forks: 89
# Repo-supervisor
[](https://gitter.im/repo-supervisor/Lobby)
[](https://travis-ci.org/auth0/repo-supervisor)
:exclamation: Repo-supervisor 目前不再积极维护
Repo-supervisor 是一款帮助您检测代码中的秘密和密码的工具。安装非常简单，只需向您的 Github 仓库添加一个新的 webhook 即可。
它在两种独立的模式下运行。第一种模式允许我们扫描 Github pull request，第二种模式通过命令行工作，扫描本地目录。
- [Repo-supervisor](#repo-supervisor)
- [用法](#usage)
- [前置条件](#pre-requisites)
- [命令行模式](#command-line-mode)
- [Github Pull Request 模式](#github-pull-request-mode)
- [支持的文件](#supported-files)
- [安全检查](#security-checks)
- [常见问题](#frequently-asked-questions)
- [它是如何工作的？](#how-does-it-work)
- [为什么它没有找到任何秘密？](#why-doesnt-it-find-any-secrets)
- [如何添加对新文件类型的支持？](#how-to-add-support-for-new-file-types)
- [什么是 Auth0？](#what-is-auth0)
- [在 Auth0 创建免费账户](#create-a-free-account-in-auth0)
- [问题报告](#issue-reporting)
- [作者](#author)
- [许可证](#license)
## 用法
### 前置条件
要开始使用该工具，请从 Github 发布页面下载最新版本。有适用于 AWS Lambda 部署和 CLI 模式的两种捆绑包。使用 CLI 模式不需要任何额外配置，而要使用 PR 模式，则必须先将捆绑包部署到 AWS Lambda。
- [AWS Lambda 部署](docs/aws.lambda.deployment.md)
- [使用 Docker 镜像](docs/docker.image.md)
### 命令行模式
CLI 模式允许扫描带有源代码的本地目录，以检测文件中的秘密和密码。这是最简单的部署选项，它可以成为 CI 流水线的一部分。
扫描结果可以以纯文本或 JSON 格式返回：
```
$ npm ci && npm run build
$ node ./dist/cli.js ./test/fixtures/integration/dir.with.secrets
[./test/fixtures/integration/dir.with.secrets/foo/bar.js]
>> zJd-55qmsY6LD53CRTqnCr_g-
>> gm5yb-hJWRoS7ZJTi_YUj_tbU
>> GxC56B6x67anequGYNPsW_-TL
>> MLTk-BuGS8s6Tx9iK5zaL8a_W
>> 2g877BA_TsE-WoPoWrjHah9ta
[./test/fixtures/integration/dir.with.secrets/foo/foo.json]
>> d7kyociU24P9hJ_sYVkqzo-kE
>> q28Wt3nAmLt_3NGpqi2qz-jQ7
$ JSON_OUTPUT=1 node ./dist/cli.js ./test/fixtures/integration/dir.with.secrets
{"result":[{"filepath":"./test/fixtures/integration/dir.with.secrets/foo/bar.js","secrets":["zJd-55qmsY6LD53CRTqnCr_g-","gm5yb-hJWRoS7ZJTi_YUj_tbU","GxC56B6x67anequGYNPsW_-TL","MLTk-BuGS8s6Tx9iK5zaL8a_W","2g877BA_TsE-WoPoWrjHah9ta"]},{"filepath":"./test/fixtures/integration/dir.with.secrets/foo/foo.json","secrets":["d7kyociU24P9hJ_sYVkqzo-kE","q28Wt3nAmLt_3NGpqi2qz-jQ7"]}]}
```
### Github Pull Request 模式
在 Pull Request 模式下运行该工具，需要向 Github 仓库添加一个新的 webhook。无论何时有人打开、更新或关闭 PR，该 webhook 都应在 pull request 事件上触发。因此，当触发扫描时，它会根据扫描结果将 PR 状态更新为成功或失败。
Webhook 配置详情：
| 设置 | 值 |
| ------------ | ------------------ |
| Payload URL | AWS Lambda URL |
| Content type | `application/json` |
| 事件类型 | `Pull requests` |
每当工具发现安全问题时，它会将 PR 状态设置为 error，并添加一个查看报告的链接。报告链接是一个带有附加查询参数 `?id=` 的 AWS Lambda 部署 URL，该参数允许生成 HTML 报告。
查看示例报告：
根据扫描的成功或失败情况，它将设置相应的 PR 状态。
**Error - 检测到问题**
**Success - 未发现问题**
**报告了误报**
## 支持的文件
Repo-supervisor 旨在尽可能减少误报数量。这意味着它不会扫描所有的文件类型和扩展名。每个文件都根据其格式进行解析以提取字符串，这是一个需要使用语言分词器的上下文感知过程。目前支持的文件类型有：
- JSON (.json)
- JavaScript (.js)
- YAML (.yaml)
我们计划在未来添加新的文件类型。请阅读关于[如何添加新文件类型](docs/add.new.file.type.md)的文档以了解更多信息。
## 安全检查
这是该工具当前已实现的检查列表：
| 模块 | 详情 |
| ---------------- | -------------------------------------------------------------------------------- |
| **Entropy Meter** | 查找具有高熵值的字符串，以检测受支持文件类型中的秘密和密码。 |
## 常见问题
### 它是如何工作的？
**CLI 模式：**
- 扫描作为参数提供的目录
- 获取所有文件的列表，并仅返回与[受支持的扩展名](#supported-files)（如 `*.json` 或 `*.js`）匹配的文件
- 使用分词器处理每个受支持的文件（每种文件类型使用不同的分词器）
- 遍历所有提取的字符串并对其运行安全检查
- Entropy Meter - 计算熵值以查看其是否超过定义的阈值（[maxAllowedEntropy](config/filters/entropy.meter.json)）
- 以纯文本或 JSON 格式打印出检测到的问题
**Pull Request 模式：**
- 接收 webhook payload
- 处理 payload 并提取所有修改过的文件
- 遍历每个文件：
- 根据文件类型使用相应的分词器
- 从文件中提取字符串
- 对这些字符串运行安全检查
- 如果工具检测到问题，则将 CI 状态设置为 error，并附带报告链接
- 如果未发现问题，则将 CI 状态设置为 success
阅读有关 [CI 状态](https://developer.github.com/v3/repos/statuses/)定义的更多信息。
### 为什么它没有找到任何秘密？
请验证您要查找的秘密是否位于受支持的文件类型中。请在[支持的文件](#supported-files)部分了解更多信息。
### 如何添加对新文件类型的支持？
要支持新的文件类型，您需要创建一个新的解析器。由于结构复杂，某些文件类型可能需要使用外部分词器，例如 [JavaScript](src/parser/tokenizer/js/index.js) 文件。另一方面，对于简单的文件类型，这非常直接，就像处理 [JSON](src/parser/tokenizer/json/index.js) 文件一样。
阅读更多关于如何添加[新文件类型](docs/add.new.file.type.md)的信息。
## 问题报告
如果您发现了错误或有功能请求，请在此仓库的 issues 部分进行报告。请不要在公开的 GitHub issue 追踪器上报告安全漏洞。[负责任的披露计划](https://auth0.com/whitehat)详细说明了披露安全问题的流程。
## 作者
[Auth0](https://auth0.com)
## 许可证
本项目基于 MIT 许可证授权。有关更多信息，请参阅 [LICENSE](LICENSE) 文件。
**Success - 未发现问题**
**报告了误报**
## 支持的文件
Repo-supervisor 旨在尽可能减少误报数量。这意味着它不会扫描所有的文件类型和扩展名。每个文件都根据其格式进行解析以提取字符串，这是一个需要使用语言分词器的上下文感知过程。目前支持的文件类型有：
- JSON (.json)
- JavaScript (.js)
- YAML (.yaml)
我们计划在未来添加新的文件类型。请阅读关于[如何添加新文件类型](docs/add.new.file.type.md)的文档以了解更多信息。
## 安全检查
这是该工具当前已实现的检查列表：
| 模块 | 详情 |
| ---------------- | -------------------------------------------------------------------------------- |
| **Entropy Meter** | 查找具有高熵值的字符串，以检测受支持文件类型中的秘密和密码。 |
## 常见问题
### 它是如何工作的？
**CLI 模式：**
- 扫描作为参数提供的目录
- 获取所有文件的列表，并仅返回与[受支持的扩展名](#supported-files)（如 `*.json` 或 `*.js`）匹配的文件
- 使用分词器处理每个受支持的文件（每种文件类型使用不同的分词器）
- 遍历所有提取的字符串并对其运行安全检查
- Entropy Meter - 计算熵值以查看其是否超过定义的阈值（[maxAllowedEntropy](config/filters/entropy.meter.json)）
- 以纯文本或 JSON 格式打印出检测到的问题
**Pull Request 模式：**
- 接收 webhook payload
- 处理 payload 并提取所有修改过的文件
- 遍历每个文件：
- 根据文件类型使用相应的分词器
- 从文件中提取字符串
- 对这些字符串运行安全检查
- 如果工具检测到问题，则将 CI 状态设置为 error，并附带报告链接
- 如果未发现问题，则将 CI 状态设置为 success
阅读有关 [CI 状态](https://developer.github.com/v3/repos/statuses/)定义的更多信息。
### 为什么它没有找到任何秘密？
请验证您要查找的秘密是否位于受支持的文件类型中。请在[支持的文件](#supported-files)部分了解更多信息。
### 如何添加对新文件类型的支持？
要支持新的文件类型，您需要创建一个新的解析器。由于结构复杂，某些文件类型可能需要使用外部分词器，例如 [JavaScript](src/parser/tokenizer/js/index.js) 文件。另一方面，对于简单的文件类型，这非常直接，就像处理 [JSON](src/parser/tokenizer/json/index.js) 文件一样。
阅读更多关于如何添加[新文件类型](docs/add.new.file.type.md)的信息。
## 问题报告
如果您发现了错误或有功能请求，请在此仓库的 issues 部分进行报告。请不要在公开的 GitHub issue 追踪器上报告安全漏洞。[负责任的披露计划](https://auth0.com/whitehat)详细说明了披露安全问题的流程。
## 作者
[Auth0](https://auth0.com)
## 许可证
本项目基于 MIT 许可证授权。有关更多信息，请参阅 [LICENSE](LICENSE) 文件。标签：AWS Lambda, CI/CD安全, DevSecOps, Docker, GitHub安全, Llama, MITM代理, secrets 扫描, Webhook, 上游代理, 代码仓库安全, 信息泄露检测, 力导向图, 安全助手, 安全扫描, 安全配置错误, 安全防御评估, 密码检测, 密钥查找, 时序注入, 源码安全, 自定义脚本, 请求拦截, 错误基检测, 静态代码分析