deadshot

死亡射手

Deadshot 是一个拉取请求扫描器，它通过将每个 diff 行与一组已知的秘密表达式进行匹配来查找通过 PR 引入的秘密。

应用能力：

服务负责：

• 实时拉取请求差异处理器检查通过新代码提交到 Github 的秘密
• 如果 PR 对话标记了某些内容，则通知用户
• 当您通过 regex.json 中的标志启用 Slack 通知的代码中识别到某些机密时，Slack 会通知安全团队通道

服务不：

• 进行任何静态或动态代码分析

它是如何运作的？

Deadshot 是一个 Flask-Celery-Redis 多容器应用程序，作为 Github 应用程序安装，以在针对安装了 Github 应用程序的存储库的主分支创建的每个拉取请求上运行。

Flask 容器是服务的入口点，它公开 blueprints.py 中定义的 API 路由。一旦 API 路由上收到 Pull 请求负载，服务就会将负载转发到 Redis 队列，以便 Celery 容器拾取并扫描 Pull 请求的差异。 celery 容器扫描指定的机密正则表达式后，会对 PR 进行评论，slack 通知安全团队渠道，或者创建 JIRA 票证供团队跟进。 Github 应用程序配置有 Flask API URL 和用于生成有效负载 SHA 校验和的共享密钥。

设置 API URL 的一种方法是在主机上部署此代码并向该主机分配应用程序负载均衡器。

创建 Github 应用程序

注意：创建应用程序时，请确保您已准备好用于要在其上部署 Deadshot 容器的主机的 DNS 以及用于 Webhook 密钥的安全密钥字符串。

Github 管理员需要在运行或部署 Deadshot 应用程序之前在 Github 上创建并安装 Github 应用程序。要了解有关创建 Github 应用程序的更多信息，请阅读本指南

应用程序名称：deadshot（全部小写。这很重要，因为服务使用此名称来获取它在 PR 上发表的先前评论）

Webhook URL：http(s)://your-hosted-deadshot-dns/api/v1/deadshot-webhook

要在本地测试此功能，您可以创建一个 ngrok 端点以输入到您的 Github 应用程序 Webhook 部分

Github 应用程序权限

要使此应用程序正常工作，您的 Github 应用程序必须在 Github 应用程序的权限页面上启用以下权限和订阅： 存储库权限：

• 元数据：只读
• PullRequest：读取和写入
• Webhooks：读取和写入

所有其他权限均保持默认值“无访问权限”不变

订阅活动：

• 拉取请求
• 拉取请求审查

最后点击“创建GitHub应用程序”。成功创建应用程序后，请点击应用程序网页顶部的“生成私钥”链接

生成私钥后，将其存储在安全位置。生成的私钥是用于生成应用程序交互的会话令牌的数据之一。

生成私钥后，在您希望其监控的所有组织上安装该应用程序。

奔跑的死亡射手

这是一个多容器应用程序，旨在通过 /bin/run.sh 启动所有三个容器（Flask、Celery、Redis），因此运行 Dockerfile 映像应该会启动整个应用程序

环境变量：

注意：对于使用 docker-compose.yaml 进行部署，请在 localdev.env 中填充这些环境变量。如果您通过 Dockerfile.api、Dockerfile.celery 单独构建和运行每个容器映像来部署它，那么这些环境变量位于各自的 Dockerfile 中

下面的三个变量是用户提供的单字符串值

• GITHUB_URL：这是访问您的 Github 实例的 URL。请提供不带方案或端口的 DNS。例如。如果您的 Github Web URL 是 https://github.mockcompany.com，则提供值 github.mockcompany.com
• GITHUB_API：这是 Github 的 API URL。例如。如果您的 Github DNS 为 https://github.mockcompany.com 那么您的 API 将类似于 https://github.mockcompany.com/api/v3
• JIRA_SERVER= 您公司的 JIRA 服务器 Web URL

以下环境变量加载其中包含凭据的文件的路径。在运行应用程序之前，加载此处可用文件中的 json 文件键值。

• SECRET_GITHUB_SECRET：此变量加载 github_secrets.json 并具有 Github 应用程序的共享 Webhook 密钥、集成 ID 和 pem 密钥。所有这三个秘密都是从 Github 应用程序设置页面 webhook 获取的 Secret - 这是在应用程序创建过程中配置的秘密集成 ID - 这是 github 应用程序设置页面上显示的应用程序 ID pem key - 这是在应用程序创建过程中生成的私钥应用程序安装过程
• SECRET_SLACK_WEBHOOKS：此 slack_webhook.json 具有 Webhook URL，当 Deadshot 应用程序在您在 regex.json 中设置 slack_alert=True 的 PR 中找到机密时，将向该 URL 发送 slack 通知
• SECRET_JIRA_AUTH：这将加载 jira_user.json 并具有用于访问组织的 JIRA 板的用户 ID 的用户名和密码注意：如果您未在 SECRET_SLACK_WEBHOOKS 和 SECRET_JIRA_AUTH 中提供有效值，则服务将发生软故障并打印有关启动 slack 失败的错误消息docker 容器日志中的 jira 和 jira 方法

注意：如果您不移动 JSON 机密文件位置，则无需更新 Dockerfiles 或 docker-compose.yaml 中已存在的上述三个环境变量值

运行/提供 Docker 镜像

此命令将使用 docker-compose.yaml 来启动所有容器。在运行以下命令之前，请使用与您的组织相关的值更新配置/环境/localdev.env

make serve

完成此操作并且不打算使用 Dockerfile 来为应用程序提供服务后，请跳转到“服务器运行状况检查”部分

使用 Dockerfile 构建和运行服务

有两种构建和运行 Dockerfile 的方法。存储库中存在四个 Dockerfile，其中三个用于为该服务工作所需的每个容器生成单独的映像，第四个是 Dockerfile 设置，用于创建一个可用于启动Flask 应用程序或 celery 工作程序取决于提供的 DEADSHOT_RUN_MODE 环境变量值（api 或工作程序）要运行以下任何步骤，您需要位于存储库的根文件夹中

注意：确保您已更新 Dockerfile.api 和 Dockerfile.celery 文件中的环境变量

从各个 Dockerfile 构建镜像

共有三个与此步骤相关的 Dockerfile。 Dockerfile.api、Dockerfile.celery 和 Dockerfile.redis

构建 Flask API 镜像

 docker build -f Dockerfile.api -t deadshot-api:<version> .

构建 celery 图像

 docker build -f Dockerfile.celery -t deadshot-worker:<version> .

构建redis镜像

 docker build -f Dockerfile.redis -t deadshot-redis:<version> .

运行构建的图像

前面步骤中构建的三个映像都在不同的网络中运行，因此它们无法相互通信。为了实现容器间通信，我们需要将它们添加到容器网络中

创建 Docker 网络

 docker network create deadshot-network

按以下顺序使用创建的网络运行映像： 启动 redis 容器：

 docker run --net deadshot-network --name redis deadshot-redis:<version>

启动芹菜容器：

 docker run --net deadshot-network deadshot-worker:<version>

启动 Flask API 容器：

 docker run --net deadshot-network -p 9001:9001 deadshot-api:<version>

为 Flask API 容器和 celery Worker 容器构建并运行单个映像

仅当您有一个允许您在部署时输入环境变量、机密和其他配置的编排时，此步骤才有用。如果您没有可配置的 CI/CD 设置，请使用上述运行容器的方法。

基于 DEADSHOT_RUN_MODE 环境变量构建单个 docker 映像来启动 api 和 celery Worker

make build

该命令还将创建服务所需的redis镜像

如果构建的映像使用环境变量 DEADSHOT_RUN_MODE=api 运行，它将启动 Flask 应用程序如果使用环境变量 DEADSHOT_RUN_MODE=worker 运行映像，则将启动 celery Worker

服务器健康检查

现在 API 已准备好接收请求，在浏览器中导航到http://localhost:9001/api/v1/heartbeat应该返回有效响应，或者您可以执行curl

curl localhost:9001/api/v1/healthcheck

两者都应显示以下消息： {"healthcheck": "ready"}

运行拉取请求扫描

如果您有用于 Pull 请求的 Github 应用程序的 Webhook 负载，那么您可以在本地运行以下curl 命令来测试您的应用程序：

curl -X POST -H " content-type: application/json " -H " X-GitHub-Enterprise-Host: github.mockcompany.com " -H " X-Hub-Signature: sha1=85df4936c6396c149be94144befab41168149840 " -H " X-GitHub-Event: pull_request " -d @tests/fixtures/good_pr.json http://localhost:9001/api/v1/deadshot-webhook

添加新的正则表达式

如果您希望该工具监视其他类型的机密，请在 regex.json 文件中添加正则表达式

注意：除了正则表达式匹配之外，熵检查标志还允许您查找高熵结果

局限性

目前，Deadshot 仅在 Github Enterprise 上进行了测试，但应该也可以与 Github cloud 一起使用。