GitLab Watchman

关于 GitLab Watchman

GitLab Watchman 是一款利用 GitLab API 检测暴露的机密信息和个人数据的应用程序。它还会枚举 GitLab 实例，收集任何有用的信息。

功能特点

机密检测

它会在 GitLab 中搜索内部共享的项目，并检查以下内容：

• 代码
• 提交记录
• Wiki 页面
• 议题
• 合并请求
• 里程碑
• 评论
• 代码片段

检测以下数据：

• GCP 密钥和服务账号文件
• AWS 密钥
• Azure 密钥和服务账号文件
• Google API 密钥
• Slack API 令牌和 Webhooks
• 私钥（SSH、PGP 及其他杂项私钥）
• 暴露的令牌（Bearer 令牌、访问令牌、client_secret 等）
• S3 配置文件
• Heroku、PayPal 等服务的令牌
• 明文密码
• 以及更多

基于时间的搜索

您可以运行 GitLab Watchman 来查找指定时间范围内的结果，可回溯至：

• 24 小时
• 7 天
• 30 天
• 所有时间

这意味着在完成一次深度扫描后，您可以定期安排 GitLab Watchman 运行，并仅返回所选时间范围内的结果。

枚举

GitLab Watchman 可以枚举 GitLab 实例中潜在有用的信息：

• 实例元数据
• 调用用户/令牌的信息
• 将所有用户输出到 CSV 文件
• 将所有项目输出到 CSV 文件
• 将所有组输出到 CSV 文件

签名规则

GitLab Watchman 使用自定义 YAML 签名规则来检测 GitLab 中的匹配项。这些签名规则从中央 Watchman Signatures 仓库 拉取。Slack Watchman 会在运行时自动更新其签名库，确保使用最新的签名规则来检测机密信息。

禁用签名规则

您可以通过在 watchman.conf 文件的 disabled_signatures 部分添加签名规则的 ID 来定义要禁用的签名规则。例如：

gitlab_watchman:
  disabled_signatures:
    - tokens_generic_bearer_tokens
    - tokens_generic_access_tokens

您可以在 Watchman Signatures 仓库 的各个 YAML 文件中找到签名规则的 ID。

日志记录

GitLab Watchman 提供以下日志记录选项：

• 终端友好的标准输出
• JSON 格式输出到标准输出

如果未指定选项，GitLab Watchman 默认使用终端友好的标准输出日志记录。这种方式更易于人类阅读。

同时也提供 JSON 格式的日志记录，非常适合导入 SIEM 或其他日志分析平台。

JSON 格式的日志可以轻松重定向到文件，如下所示：

gitlab-watchman --timeframe a --all --output json >> gitlab_watchman_log.json 

要求

GitLab 版本

GitLab Watchman 使用 v4 API，适用于 GitLab Enterprise Edition 版本：

• 13.0 及以上 - 支持

• GitLab.com - 支持

• 12.0 - 12.10 - 可能支持，未测试，但如果使用 v4 API，理论上可行

GitLab 许可证与 Elasticsearch

要搜索以下范围：

• blobs
• wiki_blobs
• commits

GitLab 实例必须配置 Elasticsearch，并且运行 Enterprise Edition，至少需要 GitLab Starter 或 Bronze 许可证。

GitLab 个人访问令牌

要运行 GitLab Watchman，您需要一个 GitLab 个人访问令牌。

您可以通过 GitLab GUI 创建个人访问令牌：设置 -> 访问令牌 -> 添加个人访问令牌

令牌需要具备以下范围的权限：

api

注意：个人访问令牌会代表创建它的用户进行操作，因此建议您使用服务账号创建令牌，否则应用程序将有权访问您的私有仓库。

GitLab URL

您还需要提供 GitLab 实例的 URL。

提供令牌和 URL

GitLab Watchman 会从环境变量 GITLAB_WATCHMAN_TOKEN 和 GITLAB_WATCHMAN_URL 中获取 GitLab 令牌和 URL。

watchman.conf 文件

配置选项可以通过名为 watchman.conf 的文件传递，该文件必须存储在您的主目录中。文件应采用 YAML 格式，示例如下：

gitlab_watchman:
  disabled_signatures:
    - tokens_generic_bearer_tokens
    - tokens_generic_access_tokens

GitLab Watchman 会在运行时查找此文件，并使用其中的配置选项。

安装

您可以通过 pip 安装最新的稳定版本：

python3 -m pip install gitlab-watchman

或者从源代码自行构建。下载发布版源代码，然后在顶层仓库目录下运行：

python3 -m build
python3 -m pip install --force-reinstall dist/*.whl

Docker 镜像

GitLab Watchman 也可以从 Docker Hub 以 Docker 镜像形式获取：

docker pull papermountain/gitlab-watchman:latest

然后您可以运行 GitLab Watchman 容器，确保传递所需的环境变量：

// 帮助
docker run --rm papermountain/gitlab-watchman -h

// 全面扫描
docker run --rm -e GITLAB_WATCHMAN_TOKEN=abc123 -e GITLAB_WATCHMAN_URL=https://example.gitlab.com papermountain/gitlab-watchman --timeframe a --all
docker run --rm --env-file .env papermountain/gitlab-watchman --timeframe a --all

用法

GitLab Watchman 会作为全局命令安装，使用方式如下：

usage: gitlab-watchman [-h] --timeframe {d,w,m,a} [--output {json,stdout}] [--version] [--all] [--blobs] [--commits] [--wiki-blobs] [--issues]
                   [--merge-requests] [--milestones] [--notes] [--snippets] [--enumerate] [--debug] [--verbose]

在 GitLab 中查找暴露的机密信息和个人数据

options:
  -h, --help            显示此帮助信息并退出
  --output {json,stdout}, -o {json,stdout}
                        将结果发送到哪里
  --version, -v         显示程序版本号并退出
  --all, -a             查找所有内容
  --blobs, -b           搜索代码 blob
  --commits, -c         搜索提交记录
  --wiki-blobs, -w      搜索 wiki blob
  --issues, -i          搜索议题
  --merge-requests, -mr
                        搜索合并请求
  --milestones, -m      搜索里程碑
  --notes, -n           搜索评论
  --snippets, -s        搜索代码片段
  --enumerate, -e       枚举此 GitLab 实例中的用户、组、项目。结果将保存为 CSV 文件
  --debug, -d           启用调试级别的日志记录
  --verbose, -V         为 JSON 日志启用更详细的输出。包含更多字段，但体积更大

required arguments:
  --timeframe {d,w,m,a}
                        搜索的时间范围：d = 24 小时，w = 7 天，m = 30 天，a = 所有时间

其他 Watchman 应用

您可能也对 Watchman 家族的其他应用感兴趣：

• Slack Watchman
• Slack Watchman for Enterprise Grid
• GitHub Watchman

许可证

本项目源代码基于 GNU General Public Licence 发布。本项目与 GitLab 无关。