Trivy 扫描注册表镜像报 MANIFEST_UNKNOWN 或 unable to initialize an image scanner 怎么排查

Trivy 扫描注册表镜像报 MANIFEST_UNKNOWN 或 unable to initialize an image scanner 怎么排查

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy

在 CI 或开发机上执行trivy image <镜像名>时，如果你扫描的是注册表里的镜像（而不是本地已拉取的镜像），有时会看到这样的报错：

FATAL image scan error: scan error: unable to initialize a scanner: unable to initialize an image scanner: 4 errors occurred: * docker error: unable to inspect the image (ContainerImageName): Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? * containerd error: containerd socket not found: /run/containerd/containerd.sock * podman error: unable to initialize Podman client: no podman socket found: stat podman/podman.sock: no such file or directory * remote error: GET https://index.docker.io/v2/ContainerImageName: MANIFEST_UNKNOWN: manifest unknown; unknown tag=0.1

这是 Trivy 官方 troubleshooting 文档记录的典型输出（其中镜像名和 tag 为文档示例值）。它的意思是：Trivy 按顺序在 Docker Engine、containerd、Podman、远程注册表四个位置查找这个镜像，全部失败。其中MANIFEST_UNKNOWN来自远程注册表，表示注册表上找不到该镜像对应的 manifest（通常是仓库路径或 tag 写错，或没有权限）。

排查的核心就是回答两个问题：镜像引用是否写对了；Trivy 能否访问你预期的那个镜像来源（本地运行时或远程注册表）。

第一步：核对镜像引用

官方文档把这两条列为最常见的错误，先排除它们再看其他配置：

• 镜像名拼写错误：逐项核对注册表地址、仓库名、tag；
• 漏写注册表前缀：不带注册主机名的镜像默认按 Docker Hub（index.docker.io）处理。你的镜像在自己的私有注册表里时，必须写成registry.example.com/你的仓库/镜像:tag的形式。

文档示例中unknown tag=0.1就属于这类问题：仓库或 tag 在注册表上不存在，注册表直接返回MANIFEST_UNKNOWN。在修复配置前，先用注册表自身的管理界面或其他拉取方式确认「这个完整镜像引用确实存在」。

第二步：确认镜像来自哪里，配置对应来源

Trivy 默认依次在 Docker Engine、containerd、Podman、注册表中查找镜像，这个查找顺序可以用--image-src参数修改。例如：

trivy image --image-src podman,containerd alpine:3.7.3

限定来源有两个好处：错误信息不再混杂四个来源的失败项，而且一旦在列出的来源中找不到，扫描直接失败、不会再往后查找，便于定位问题。按你的实际环境配置对应来源：

本地 Docker Engine

如果 docker socket 不在默认路径/var/run/docker.sock，需要指定--docker-host参数或DOCKER_HOST环境变量；通过 TCP 连接 daemon 时同理，必须给出正确的主机地址：

$ trivy image --docker-host tcp://127.0.0.1:2375 YOUR_IMAGE

本地 containerd

如果 containerd socket 不在默认路径（/run/containerd/containerd.sock），用CONTAINERD_ADDRESS覆盖，例如 k3s 环境：

$ export CONTAINERD_ADDRESS=/run/k3s/containerd/containerd.sock $ trivy image aquasec/nginx

如果镜像在 containerd 的非默认命名空间里，用CONTAINERD_NAMESPACE指定，例如 Kubernetes 的镜像在k8s.io命名空间：

$ export CONTAINERD_NAMESPACE=k8s.io $ trivy image aquasec/nginx

本地 Podman

需要先启用 Podman socket，再执行扫描：

$ systemctl --user enable --now podman.socket $ trivy image test

如果不想长期开着 socket，也可以只在扫描期间启动podman system service，并用--podman-host指向该 socket。

第三步：扫描远程注册表时的三类典型原因

如果镜像确实要从注册表拉取，官方文档列出三类常见失败原因。

1. 未认证（私有注册表）

私有注册表必须先认证。推荐用trivy registry login登录，凭据会保存在 Docker 配置文件（~/.docker/config.json）中，路径可用DOCKER_CONFIG环境变量配置：

$ cat ~/my_password.txt | trivy registry login --username foo --password-stdin ghcr.io $ trivy image ghcr.io/your/private_image

也可以在扫描时直接传凭据，但要注意官方警告：通过环境变量或 CLI 参数传入的凭据会被用于扫描过程中遇到的所有注册表，可能造成非预期暴露，因此优先使用trivy registry login按注册表精确配置：

$ TRIVY_USERNAME=YOUR_USERNAME TRIVY_PASSWORD=YOUR_PASSWORD trivy image YOUR_PRIVATE_IMAGE

多组凭据可以用逗号分隔，用户名和密码数量必须一致。CLI 的--password参数可用但不建议使用。不同注册表还有各自的认证方式（如 ECR 走 AWS SDK 环境变量、Google Artifact Registry 用GOOGLE_APPLICATION_CREDENTIALS指向服务账号 JSON、Azure ACR 用服务主体AZURE_CLIENT_ID/AZURE_CLIENT_SECRET/AZURE_TENANT_ID，自建的 BasicAuth 服务用TRIVY_USERNAME/TRIVY_PASSWORD，80 端口非 SSL 需加TRIVY_NON_SSL=true），详见 私有注册表文档。

2. 网络代理

如果网络内使用了代理，需要正确设置HTTP_PROXY、HTTPS_PROXY等环境变量，否则 Trivy 到注册表的请求会被拦截或走错通道。

3. 注册表使用自签名证书

证书校验失败时（报错形如Error: x509: certificate signed by unknown authority），正确做法是让 Trivy 信任该 CA，而不是关闭校验：

# Unix（macOS 除外）：指定 PEM 编码的 CA 证书 $ SSL_CERT_FILE=/path/to/ca.pem trivy image [YOUR_IMAGE] $ SSL_CERT_DIR=/path/to/certs trivy image [YOUR_IMAGE] # 所有系统：--cacert 指向 PEM 编码的 CA 证书文件 $ trivy image --cacert /path/to/ca.pem [YOUR_IMAGE]

也可以用TRIVY_INSECURE=true或--insecure参数允许不安全连接，但文档明确标注--insecure不建议在生产环境使用。/path/to/ca.pem、[YOUR_IMAGE]等占位符需替换为你自己的证书路径和镜像名。

验证与进一步调试

修复后重新执行原扫描命令：

$ trivy image <你的完整镜像引用>

能开始下载/分析镜像层并输出扫描结果，就说明问题已解决。

如果仍失败且报错信息不明显，可以开启 HTTP 请求/响应追踪来调试注册表连接与认证问题：

$ trivy image --trace-http registry.example.com/my-image:latest

注意官方警告：--trace-http虽然会尝试脱敏认证头等敏感信息，但请求和响应中仍可能暴露敏感数据，不要在生产环境或 CI/CD 流水线中使用，且该标志在 CI 环境中会自动禁用。

如果遇到的错误无法归入以上任何一类，文档给出的兜底操作是先清理缓存再重试：

$ trivy clean --all

以上排查内容对应仓库中的 troubleshooting 文档 的 "Unable to initialize an image scanner" 与 "Certification" 小节、容器镜像文档 的 Supported 与 Options 小节，以及 私有注册表文档。

【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy