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 中提供有效值，則服務將發生發生軟故障並列印有關啟動軟故障並列印有關啟動軟故障的錯誤訊息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 一起使用。