設定 AppScan Presence 以直接掃描 GitHub 儲存庫。

您可以使用 AppScan Presence，對 GitHub Enterprise 儲存庫執行靜態分析。

AppScan Presence 包含選擇性支援，可使用 GitHub 應用程式，從 GitHub Enterprise Server 對 GitHub 儲存庫執行靜態分析。GitHub 伺服器不必公開存取，但 AppScan 使用者必須擁有 GitHub 伺服器的網路存取權，以及存取 GitHub 中儲存庫的許可權。

AppScan Presence 已啟用 GitHub 掃描的執行個體，可使用在伺服器上定義的一個 GitHub 應用程式，與一個 GitHub Enterprise Server 建立關聯。

若要使用 AppScan Presence 來連線與掃描 GitHub Enterprise 儲存庫：
  1. 在具有 GitHub Enterprise Server 存取權的私有網路上，將 AppScan Presence 建立並安裝至資料夾位置。
    註： 連線到單一 GitHub 伺服器的單一 Presence 可讓組織中的所有使用者掃描該伺服器上擁有存取權的儲存庫。
  2. 在 GitHub Enterprise Server 上建立 GitHub 應用程式。
  3. 在 AppScan Presence 中啟動和配置 GitHub 特定參數。
  4. 建立掃描。

建立 GitHub 應用程式

開始之前，請先檢閱 GitHub 應用程式的相關資訊。

若要建立 GitHub 應用程式以與 AppScan Presence 搭配使用：

  1. 登入 GitHub。
  2. 選取「設定」 > 「開發人員設定」 > 「GitHub 應用程式」，按一下「新 GitHub 應用程式」。
  3. 指定下列應用程式參數：
    參數 值
    GitHub 應用程式名稱 您的應用程式名稱。
    說明 應用程式的說明。例如「開發伺服器的 ASoC 連接器」。
    首頁 URL HCL AppScan on Cloud URL。例如 https://cloud.appscan.com。
    回呼 URL 您的 AppScan Presence URL 加上 /signin-github。例如 https://www.example.com/signin-github。
    Webhook 取消勾選「作用中」
    儲存庫權限 「內容」和「中繼資料」設定為「唯讀」。
    帳戶權限 「電子郵件位址」設定為「唯讀」。
    此 GitHub 應用程式可以安裝在哪裡？ 「任何帳戶」。
  4. 按一下「建立 GitHub 應用程式」。
  5. 檢視「GitHub 應用程式」設定，並記下下列值以配置 AppScan Presence。
    • AppID
    • AppUrl
    • ClientId
    • ClientSecret

配置並啟動 AppScan Presence

  1. 建立 GitHub 應用程式的私密金鑰：
    1. 在 GitHub Enterprise 的 GitHub 應用程式視窗下，按一下「產生私密金鑰」。
    2. 重新命名已下載的檔案 GitHubAppKey.pem，並將其複製到 Presence 安裝資料夾。
  2. 在 Presence 安裝目錄中，找到 git_connect_settings.json 檔案，然後將其開啟以進行編輯。
  3. 在 git_connect_settings.json 的 GitConnectOptions 區段中，編輯如下參數：
    參數 說明 範例
    GitServerName GitHub 伺服器的名稱。 github01
    GitConnectUrl 此 Presence 所顯示之 Web 應用程式的 URL。 https://my-host-fqsn:44
    GithubAppId 您為此連線建立之 GitHub 應用程式的 AppID。 55
    GithubAppUrl GitHub 應用程式的安裝 URL。 https://github01.example.com/github-apps/asoc
    ClientId GitHub 應用程式的用戶端 ID。 <oauth client id>
    ClientSecret GitHub 應用程式的用戶端機密。 <oauth client secret>
    GitPlatformDomain GitHub Enterprise Server 的 URL。 https://github01.example.com
    Proxy 如果需要 Proxy 才能連線至 GitHub 伺服器，請取消此行的註解並提供 Proxy 詳細資料。 127.0.0.1:8888
    作用中 在 AppScan Presence 中啟用或停用 GitHub 連線功能。預設值是 false。 true
  4. 我們強烈建議您使用 HTTPS；如果您選擇使用 HTTP，網站會視為不安全，因此，您必須調整瀏覽器設定，以允許不安全的內容。

    為確保您使用 HTTPS，請在 git_connect_settings.json 的 Kestrel 區段中，編輯如下參數：

    參數 說明 範例
    Http 要由 AppScan Presence 使用的通訊協定。 Https
    Url 要由 AppScan Presence 使用的連接埠。 http://*:8080
    註： AppScan Presence 使用 Kestrel 來託管其 Web 應用程式。Kestrel 是內嵌式 Web 伺服器，可以使用配置檔中的 Kestrel 區段來配置。如需有關此伺服器配置的詳細資訊，請參閱為 ASP.NET Core Kestrel Web 伺服器配置端點。
  5. 將 GitHub 應用程式安裝在擁有該應用程式的帳戶上：
    1. 在瀏覽器中開啟應用程式 (GithubAppUrl) 的公開連結。
    2. 安裝應用程式。
    註： 您不需要將此安裝的存取權授與私有儲存庫，但應用程式應安裝在擁有該應用程式的帳戶上。

設定配置後，可啟動（或重新啟動）Presence 並開始掃描。日誌會寫入至主控台，並記錄位於日誌資料夾下的檔案。

AppScan Presence GitHub 掃描流程

以下說明使用 AppScan Presence 從 GitHub Enterprise Server 掃描儲存庫的流程：

  1. 使用者登入 ASoC。(1.2)
  2. 從 ASoC 中，傳回已連線伺服器之已配置的啟用 Presences 清單。然後，使用者選擇要用於掃描的 GitHub 伺服器。 ASoC 傳回存取 AppScan Presence 伺服器的 URL 及 GitHub 伺服器的 URL
  3. 當使用者按一下「連線至 GitHub」時，ASoC 會開啟指向 AppScan Presence (3) 的新瀏覽器標籤，其會啟動 oAuth 授權碼流程。然後，系統會將使用者重新導向至 GitHub Ent Server (4)，登入，同意 AppScan Presence 存取 GitHub 帳戶，然後再使用授權碼重新導向回 AppScan Presence
  4. AppScan Presence 從 GitHub Ent Server (5) 取得使用者存取記號，然後將其與使用 window.postMessage 將記號傳送至 ASoC 的指令碼一起傳回至使用者 (3)。
  5. ASoC 使用 GitHub 存取記號 (4) 取得使用者以及 AppScan Presence 使用之 GitHub 應用程式可存取的儲存庫清單。然後，使用者可以選擇要掃描的儲存庫。
  6. 在為所選儲存庫建立掃描之前，ASoC 會確認使用者是否可存取儲存庫。AppScan Presence API (3) 功能 RepoSignature 會為儲存庫詳細資料（儲存庫擁有者和儲存庫名稱）建立簽章。驗證存取權後，儲存庫詳細資料會以 AppScan Presence 的專屬私密金鑰簽署。簽章由 API 呼叫傳回至 ASoC。
  7. ASoC 透過佈建 Presence ID (Git Connect)、儲存庫詳細資料和簽章，使用 UsersAPI (2) 建立掃描。UserAPI 會使用與所提供 AppScan Presence 執行個體相關聯的公開金鑰來驗證簽章。如果驗證成功，則會為儲存庫建立掃描。
  8. 針對作業輪詢 Presence WebAPI (6) 的 Presence 服務會取得擷取掃描儲存庫的新作業。Presence 會使用關聯的 GitHub 應用程式私密金鑰連線至 GitHub Ent Server (7)，擷取儲存庫作為 zip 檔案，然後將其串流至 Presence WebAPI (UploadRepo)
  9. 儲存庫 zip 檔案儲存在 ASoC 中，且可掃描。掃描完成後，會在 ASoC 中檢視及分析結果。結果包含 GitHub Ent Server 的連結，參考程式碼中的相關行以分類和補救。 ASoC 可開啟具有相關程式碼的新標籤。