疑難排解 AppScan 360° 靜態分析 部署

如果您在安裝或使用 AppScan 360° 靜態分析 時遇到問題，請嘗試使用下列資訊進行疑難排解：

執行部署 Script 時傳回錯誤

缺少 Cert Manager 相依關係

  • 錯誤：
    Error: unable to build kubernetes objects from release manifest: [resource mapping not found for name:
"analyzer-cert" namespace: "" from "": no matches for kind "Certificate" in version "cert-manager.io/v1"
ensure CRDs are installed first, resource mapping not found for name: "ascp-adapter-cert" namespace: "" 
from "": no matches for kind "Certificate" in version "cert-manager.io/v1"
  • 主要原因：

    當未在叢集上部署 cert-manager 附加元件相依關係時，便會發生此錯誤。AppScan 360° SAST 依賴 cert-manager 附加元件進行部署。

  • 解決方案：

    確認已在 Kubernetes 叢集上部署及執行 cert-manager。檢閱系統需求和環境設定指示。

缺少 Keda 相依關係

  • 錯誤：
    Error: unable to build kubernetes objects from release manifest: [resource mapping not found for name:
"analyzer-hpa" namespace: "" from "": no matches for kind "ScaledObject" in version "keda.sh/v1alpha1"
ensure CRDs are installed first, resource mapping not found for name: "ascp-adapter-hpa" namespace: "" 
from "": no matches for kind "ScaledObject" in version "keda.sh/v1alpha1"
  • 主要原因：

    當未在叢集上部署 Keda 附加元件相依關係時，便會發生此錯誤。AppScan 360° SAST 依賴 Keda 附加元件進行部署。

  • 解決方案：

    確認已在 Kubernetes 叢集上部署及執行 Keda。檢閱系統需求和環境設定指示。

資源已在使用中或無法重新建立

  • 錯誤：
    • Previous PVC storage not completely cleaned up.
    • Incomplete finalizers on pods.
    • Namespace stuck in termination state.
  • 主要原因：

    移除程序期間，並未完全清除先前部署的資源。若強制刪除名稱空間導致資源在叢集上未被追蹤，也會發生這種情況。

  • 解決方案：
    解決方案會因所涉及的資源問題類型而有所不同：
    • 清除卡在終止狀態的名稱空間
      kubectl get namespace "hcl-appscan-sast" -o json | tr -d "\n" | sed "s/\"finalizers\": \[[^]]\+\]/\"finalizers\": []/" | kubectl replace --raw /api/v1/namespaces/hcl-appscan-sast/finalize -f-

    • 清除卡在終止狀態的 pod

      kubectl delete pod <pod-name> --grace-period=0 --force --namespace <namespace>

    • 刪除孤立的 PV 和 PVC

      kubectl patch pv <pv-name> -p '{"metadata":{"finalizers":null}}'
kubectl delete pv --grace-period=0 --force --namespace <namespace> <pv-name>
kubectl patch pvc <pvc-name> -p '{"metadata":{"finalizers":null}}
kubectl delete pvc --grace-period=0 --force --namespace <namespace> <pvc-name>

未提供必要的參數

  • 錯誤：
    • ERROR: Authorization token is required for the deployment. Use the option '--auth-token' to specify the file path which contains the token.
    • ERROR: Authorization token file path specified for the option '--auth-token' does not exist. o ERROR: Rabbitmq password is required for the deployment. Use the option '--rabbitmq-pwd' to specify the file path which contains the password.
    • ERROR: Rabbitmq password file path specified for the option '--rabbitmq-pwd' does not exist.
    • ERROR: CA certificate & key are required for the deployment. Use the options '--cert, --cert-key' to specify the ca certificate and the private-key file paths.
    • ERROR: Certificate file path specified for the option '--cert' does not exist. 
    • ERROR: Certificate private key file path specified for the option '--cert-key' does not exist. 
    • ERROR: Configuration file path specified for the option '--config-file' does not exist.
  • 主要原因：

    未提供部署 Script 所需的參數，或提供給選項的值無效。

  • 解決方案：

    請檢閱部署 Script 的所有必要選項，並確定已將有效值指定給選項。

pod 在部署 Script 後無法啟動

作為後置部署程序，您應該登入叢集以驗證所有 AppScan 360° SAST pod 是否已啟動並正在執行。接著是一些 pod 相關部署問題的部署範例。

持續性磁區 (PV) 與持續性磁區要求 (PVC) 相關錯誤

建立 PVC 需要磁碟上有所要求的儲存空間大小可供使用。確認存放資料儲存體的磁碟空間是否足夠容納所要求的容量。未佈建的 PVC 會導致建立 pod 失敗。

註： 使用 azurefile 等雲端儲存解決方案可提供付費的大容量儲存空間。

如果任何現有 AppScan 360° SAST 相關 PV 及 PVC 並未完全移除，則任何新部署都將因名稱衝突而無法建立 PV 及 PVC，進而導致 pod 建立失敗。

  • 解決方案：

    移除後請等待幾秒鐘，以確保所有 PV 及 PVC 資源都能有效地釋放，然後再嘗試新的部署。

CPU/記憶體不足，無法建立 pod

每個 AppScan 360° SAST 元件都有針對各自 pod 定義的一組資源需求。如需詳細資料，請參閱資源需求一節。

當節點集區上無法使用每個 pod 所需的最低資源限制時，建立 pod 會失敗。

  • 解決方案：

    確保節點集區資源大小符合 AppScan 360° SAST 所定義的資源需求。

RabbitMQ 未啟動

RabbitMQ 服務必須已啟動且正在執行，AppScan 360° SAST 元件才能如預期運作。RabbitMQ 服務需要幾分鐘才能啟動，在部署 RabbitMQ 時，AppScan 360° SAST pod 嘗試啟動幾次都失敗的情況並不罕見。如果無法成功啟動 RabbitMQ 服務，接著 AppScan 360° SAST pod 就會失敗。

Pod 未移至「Ready」狀態
  • 錯誤：
    • Startup probe failed: …
    • Readiness probe failed: …
  • 主要原因：

    Pod 一或多個性能檢查失敗。

  • 解決方案：
    • 驗證相依元件正在執行並已正確配置。
    • 執行此指令 kubectl describe pod <pod-name> -n <namespace> 以檢查更多詳細資料。
    • 如需詳細資料，請檢查 Pod 日誌。請參閱疑難排解容器化掃描。

映像檔提取失敗

錯誤：

failed to authorize: failed to fetch anonymous token: unexpected status: 401 Unauthorized

主要原因：

這是因為尚未建立 AppScan 360° SAST 登錄密碼，或是目前的登錄密碼包含過期的認證所造成。

解決方案：

  • 刪除先前的 AppScan 360° SAST 登錄密碼。
  • 更新提供給部署 Script 的登錄使用者名稱和密碼。請參閱 部署配置參數

憑證過期

若要更新已過期的憑證：
  1. 重新執行部署指令，提供新的憑證和個別的私密金鑰。
  2. 從保留內部元件憑證的名稱空間中刪除下列密碼。系統會自動重新產生密碼。
    kubectl delete secret sast-service-tls gateway-tls workflow-manager-tls scan-manager-tls preparer-tls analyzer-tls ascp-adapter-tls sast-service-rabbitmq-tls --namespace hcl-appscan-sast
  3. 刪除名稱空間中的所有 pod。隨即會自動建立使用新產生的 TLS 密碼的新 pod。
    kubectl delete --all pods --namespace=hcl-appscan-sast

全新安裝時部署失敗

在某些情況下，將 AppScan 360° SAST 部署至目前沒有 SAST 部署的叢集可能會因為先前在叢集上進行的回復作業而失敗。可能讓叢集處於此狀態的操作例子是先前升級或重新配置 AppScan 360° SAST。
註： 部署程序會自動處理失敗的升級，並自動將叢集還原至先前的穩定版本。這些疑難排解準則僅適用於在叢集上進行全新安裝。

錯誤：

Helm 部署作業失敗，並出現一般錯誤 - ERROR: Deploy SAST services - failed. Installation aborted!

主要原因：

先前在此叢集上嘗試升級失敗，因而在叢集上留下舊的密碼檔案。這些檔案會阻止新部署建立新部署所需的類似檔案。

解決方案：

請先執行取消部署指令，然後再嘗試全新安裝。請參閱 移除 AppScan 360° 靜態分析

無法存取服務

AppScan 360° SAST 應可透過作為部署 Script 參數提供的 FQDN (https://<sast-ingress-fqdn>) 來存取。可能導致無法透過 FQDN 存取服務的錯誤例子包括：

缺少輸入控制器相依關係
  • 錯誤：
    • 無法連接至此站台。

  • 主要原因：

    若未安裝或正確配置輸入控制器，當嘗試從瀏覽器上指定的 FQDN 存取 AppScan 360° SAST 時，可能會出現此錯誤。

  • 解決方案：
    • 確認已在 Kubernetes 叢集上部署及執行輸入控制器。請檢閱必備項目一節以瞭解所有必要的相依關係。

    • 確保配置輸入控制器時使用的靜態 IP 會解析為用於部署的 FQDN。

      這可以透過在雲端 DNS 管理工具上建立記錄集或更新本端機器的 /etc/hosts 檔案來完成。

錯誤的 FQDN
  • 錯誤：
    • 無法連接至此站台。
  • 主要原因：

    配置輸入時使用的 FQDN 與存取服務時使用的 FQDN 不同。此處的另一個問題可能是錯誤的 IP/DNS 對映。如果使用的 FQDN 與對映至輸入 IP 的值不同，則無法存取服務。

  • 解決方案：
    • 確認存取服務時使用的 FQDN 是否與傳遞至部署 Script 的值相符。
    • 確認 FQDN 值對映至本端機器的 /etc/hosts 檔案或您的雲端 DNS 主機區域上的輸入 IP。
叢集連線遭拒
  • 錯誤：
    Kubernetes cluster unreachable: Get "http://localhost:8080/version": dial tcp [::1]:8080: connect: connection refused
  • 主要原因：

    此 config 檔案可能遺失或未正確配置，無法授與 kubectl 存取權給叢集。

  • 可能的解決方案：

    • 確定 config 檔案存在 .kube/config 中。

    • 確定 .kube/config 由現行使用者擁有。

    • 確定 .kube/config 有正確的許可權。

    • 匯出 KUBECONFIG。

閘道服務不在執行中

部署成功，但 pod 無法啟動
  • 錯誤：
    • 此處的錯誤訊息取決於主要原因
  • 主要原因：
    • Imagepullbackoff：這是 pod 失敗最常見的原因。當無法從所提供的儲存庫/儲存庫路徑提取映像檔時發生錯誤。
    • CPU 不足，記憶體不足：當叢集節點集區的任何節點都不符合為 AppScan 360° SAST 設定的最小 CPU 和記憶體時，便會發生此錯誤。
  • 解決方案：
    • 確認部署時提供的儲存庫包含正在部署的映像檔。
    • 確認所提供的儲存庫鑑別正確無誤。AppScan 360° SAST 部署需要準確的鑑別才能從儲存庫擷取映像檔。
    • 確認節點集區具有足夠的記憶體和 CPU 資源，符合部署期間設定的最低需求。
    • 如需詳細資料，請檢查 pod 錯誤日誌。
部署成功，但工作流程管理程式無法啟動
  • 錯誤：
    Failed to inject service URL to SAClientUtil ...
  • 主要原因：

    可能與 ASCP 伺服器發生連線問題，造成後續無法擷取公開金鑰。

  • 解決方案：

    • 驗證 ASCP 伺服器已啟動且正在執行。

    • 驗證伺服器資訊、鑑別記號以及憑證和金鑰皆正確。

    • 如需詳細資料，請檢查 pod 錯誤日誌。

在 ASCP 中的掃描為「正在起始設定」狀態，但從未進一步繼續
  • 錯誤：

    掃描狀態顯示「正在起始設定」，但不會進一步繼續。

  • 主要原因：

    可能在 ASCP 與 AppScan 360° SAST 之間發生連線問題。

  • 解決方案：
    • 驗證 ASCP 伺服器使用正確的 AppScan 360° SAST URL 進行配置。
    • 驗證 ASCP 伺服器機器可正確解析 AppScan 360° SAST 輸入 FQDN。
    • 請參閱 ASCP 日誌，以取得詳細資料。