AppScan 360° Static Analysis 部署故障诊断

如果在安装或使用 AppScan 360° Static Analysis 时遇到问题，请尝试使用以下信息进行故障诊断：

运行部署脚本时返回错误

缺少证书管理器依赖关系

  • 错误：
    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 附加组件。

  • 解决方案：

    验证 cert-manager 是否已部署并在 Kubernetes 集群上运行。查看系统需求和环境设置说明。

缺少 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 附加组件。

  • 解决方案：

    验证 Keda 是否已部署并在 Kubernetes 集群上运行。查看系统需求和环境设置说明。

资源已在使用或无法重新创建

  • 错误：
    • 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.
  • 根本原因：

    未提供部署脚本所需的参数或为选项提供的值无效。

  • 解决方案：

    请检查部署脚本的所有必需选项，并确保为选项指定了有效值。

部署脚本后 Pod 无法启动

作为部署后过程，您应该登录到集群，以验证所有 AppScan 360° SAST Pod是否已启动并正在运行。下面是一些与 Pod 相关的部署问题示例。

与持久卷 (PV) 和持久卷声明 (PVC) 相关的错误

创建 PVC 需要磁盘上有请求的存储大小可用。验证存放数据存储的磁盘空间是否有足够的空间来容纳请求的容量。未进行资源调配的 PVC 将导致 Pod 创建失败。

注： 使用云存储解决方案（如 azurefile ），可以实现大容量存储，但会收取费用。

如果未完全删除任何现有 AppScan 360° SAST 相关 PV 和 PVC，则由于名称冲突，任何新部署都将无法创建 PV 和 PVC，从而导致 Pod 创建失败。

  • 解决方案：

    在删除后等待几秒钟，以确保所有 PV 和 PVC 资源均已有效释放，然后再尝试新的部署。

用于创建 Pod 的 CPU/内存不足

每个 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 未移至“就绪”状态
  • 错误：
    • 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 注册表密钥。
  • 更新为部署脚本提供的注册表用户名和密码。查看 部署配置参数

证书已过期

要更新已过期的证书：
  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!

根本原因：

以前尝试在此集群上升级失败，将旧的密钥文件留在集群上。这些文件阻止新部署创建新部署所需的类似文件。

解决方案：

在尝试全新安装之前运行 undeploy 命令。查看 除去 AppScan 360° Static Analysis

服务不可访问

AppScan 360° SAST 应可通过作为部署脚本参数提供的 FQDN (https://<sast-ingress-fqdn>) 进行访问。可能会导致服务无法通过 FQDN 访问的错误示例包括：

缺少入口控制器依赖关系
  • 错误：
    • 无法访问此站点。

  • 根本原因：

    当未正确安装或配置入口控制器时，尝试从浏览器上的指定 FQDN 访问 AppScan 360° SAST 时，可能会出现此错误。

  • 解决方案：
    • 验证是否已在 Kubernetes 集群上部署并运行入口控制器。请查看先决条件部分，了解所有所需的依赖关系。

    • 确保用于配置入口控制器的静态 IP 解析为用于部署的 FQDN。

      这可以通过在云 DNS 管理工具上创建记录集或更新本地计算机的 /etc/hosts 文件来完成。

错误的 FQDN
  • 错误：
    • 无法访问此站点。
  • 根本原因：

    配置入口时使用的 FQDN 与访问服务时使用的 FQDN 不同。这里的另一个问题可能是 IP/DNS 映射错误。如果使用的 FQDN 与映射到入口 IP 的值标题，则服务将无法访问。

  • 解决方案：
    • 验证用于访问服务的 FQDN 是否与传递给部署脚本的值匹配。
    • 验证 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 之间可能存在连接问题。

  • 解决方案：
    • 验证是否使用了正确的 AppScan 360° SAST URL 配置了 ASCP 服务器。
    • 验证 ASCP 服务器机器是否正确解析 AppScan 360° SAST 入口 FQDN。
    • 请查看 ASCP 日志以获取更多详细信息。