Trivy 拉取 AWS ECR 私有镜像权限配置与认证原理详解【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy导读本文围绕 Trivy 扫描 AWS ECRElastic Container Registry私有镜像的场景展开完整覆盖两条主线本地环境如何让 Trivy 直接获得 ECR 授权不需要安装awsCLI以及Kubernetes 集群内如何为 Trivy 授予最小化的 AWS IAM 权限两种主流做法EKS Pod Identity/IAM Role Service Account以及 kube2iam / kiam。同时结合仓库源码剖析 Trivy 的 ECR 认证实现链路——从识别镜像域名中的 ECR 端点与区域、通过 AWS SDK 获取 authorization token到最终用AWS:xxxx凭证换取镜像访问权。读完本文你将能够直接扫描*.dkr.ecr.region.amazonaws.com私有镜像仓库并能安全地把 Trivy 部署到 EKS 集群中扫描位于 ECR 的镜像。关联文档docs/guide/advanced/private-registries/ecr.md涉及的相关入口文档还包括私有镜像仓库总览与配置文件参考。一、核心结论Trivy 通过 AWS SDK 直连 ECR无需 aws CLITrivy 拉取私有 ECR 镜像有一个关键前提区别于其他扫描器Trivy 内部直接使用 AWS SDKaws-sdk-go-v2因此你不需要在环境中预先安装awsCLI 工具也不需要手动执行aws ecr get-login-password之类的登录命令。这一点在 ECR 关联文档开篇即被明确同时也是其可以在 CI 流水线中零额外依赖运行的根基。从源码结构看Trivy 把 ECR 认证单独实现为一个注册表适配器适配器注册入口pkg/fanal/image/registry/token.go 在init()中依次注册了 GoogleGAR、ECR、AzureACR三类云厂商私有仓库ECR 核心实现pkg/fanal/image/registry/ecr/ecr.go类型定义pkg/fanal/types/image.go 中的RegistryOptions承载与 AWS 相关的配置字段AWSAccessKey、AWSSecretKey、AWSSessionToken、AWSRegion。整个认证流程GetToken的处理逻辑是当 Trivy 需要拉取镜像时它会遍历已注册的各个云端注册表适配器由CheckOptions判断目标镜像域名是否属于 ECR 端点格式如果是则调用GetCredential动态获取临时凭证详见下文认证调用链一节。提示如果你不需要集群/IAM 这类高级场景仅做本地 ECR 扫描可以先阅读私有注册表登录与传参了解trivy registry login的通用用法本文聚焦的是 ECR 特有的 IAM 权限授予方式。二、凭据来源既可用 AWS CLI 环境变量也可显式指定由于 Trivy 依赖的是 AWS SDK 而非awsCLI文档明确说明你可以直接沿用 AWS CLI 所约定的一组环境变量来提供凭据例如AWS_ACCESS_KEY_IDAWS_SECRET_ACCESS_KEYAWS_SESSION_TOKEN使用临时凭据 / STS 时AWS_REGION或AWS_DEFAULT_REGION从实现上印证ecr.go 在未提供显式静态凭据时会调用config.LoadDefaultConfig(...)即委托 AWS SDK v2 的标准默认凭据链解析环境变量、共享凭据文件乃至实例元数据IMDS角色只有当AWSAccessKey、AWSSecretKey与AWSRegion三项同时显式给出时ecr.go 才改为使用credentials.NewStaticCredentialsProvider构造静态凭据。这意味着在 EC2、EKS节点角色等具备 IMDS 的环境里只要角色具备拉取权限甚至可以不设置任何环境变量本地开发时设置上面四组环境变量即可让 Trivy 通过 SDK 自动完成 ECR 登录。值得注意的一个细节是源码在解析出目标域名所属 region 后会始终以域名中解析出的 region 为准来建立会话若显式配置的AWS_REGION与域名 region 不一致会打印一条警告日志并忽略显式配置ecr.go因此建议保持环境中的 region 与镜像仓库所在地一致。三、权限要求让 Trivy 具备从私有 ECR 拉取镜像的最小权限Trivy 能使用 AWS SDK不代表它天然有权拉取任何私有镜像。要让 Trivy 从私有 ECR 拉取镜像必须为 Trivy 所采用的 AWS 身份授予相应 IAM 权限。文档强调具体要授予什么、授予给谁取决于你以何种方式把 AWS Role 提供给 Trivy。两种主流方式分别是IAM Role for Service AccountIRSA——通过 EKS Pod Identity Webhook 为 Kubernetes ServiceAccount 绑定 IAM 角色适合 EKSkube2iam 或 kiam——通过 Pod 注解为每个 Pod 注入 IAM 角色。在 IAM 侧角色至少需要具备调用ecr:GetAuthorizationToken以及读取目标仓库与镜像清单的权限典型的最小策略包含ecr:GetAuthorizationTokenecr:BatchGetImageecr:GetDownloadUrlForLayer授权建议把 Resource 收敛到具体的arn:aws:ecr:region:ACCOUNT_ID:repository/repo-name与*token 权限面向账户级 API避免授予过于宽泛的权限。这两种方式都不需要把长期有效的 Access Key 写死在环境变量里属于生产环境推荐做法也是 ECR 关联文档后续给出 Helm 配置片段的直接目的。四、方式一通过 IAM Role for Service AccountIRSA注入角色IRSA 借助 EKS 的 OIDC 能力将 Kubernetes ServiceAccount 与 AWS IAM Role 绑定Pod 内凭证由 Webhook 自动注入。因此 Trivy 不需要配置任何密钥Pod 内的 AWS SDK 会自动以该角色身份调用 ECR API。实施方法是在Trivy 的 ServiceAccount 上添加 IAM 角色的注解。若使用官方 Helm Chart 部署 Trivy见 helm/trivy对应 values 片段如下trivy: serviceAccount: annotations: {} # eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/IAM_ROLE_NAME将注释掉的eks.amazonaws.com/role-arn行替换为真实的角色 ARN 即可例如trivy: serviceAccount: annotations: eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/trivy-ecr-pull-role要点说明该注解必须落在ServiceAccount上helm/trivy/values.yaml 中serviceAccount.annotationsEKS Pod Identity Webhook 会据此把AWS_ROLE_ARN、AWS_WEB_IDENTITY_TOKEN_FILE注入到由该 ServiceAccount 创建的 Pod之后 Trivy 容器内的 AWS SDK 凭据链会自动使用 Web Identity Token 换取临时角色凭据无需任何环境变量或 Secret前提是集群启用了 OIDC 并正确配置了信任关系且该角色拥有上文第三节所述 ECR 权限。五、方式二通过 kube2iam / kiam 注入角色如果集群运行在 AWS 之上但采用 kube2iam 或 kiam 这类基于注解annotation的 IAM 代理方案则将 IAM 角色注解加到 Trivy Pod 上而非 ServiceAccount 上。文档给出的 Helm values 片段如下podAnnotations: {} ## kube2iam/kiam annotation # iam.amazonaws.com/role: arn:aws:iam::ACCOUNT_ID:role/IAM_ROLE_NAME启用后的实际配置示例podAnnotations: iam.amazonaws.com/role: arn:aws:iam::123456789012:role/trivy-ecr-pull-role要点说明该注解落在Pod上对应 helm/trivy/values.yaml 的podAnnotationskube2iam/kiam 的代理进程会拦截 Trivy 访问 IMDS/STS 的请求以该角色身份代为换取临时凭据同样地Pod 内 Trivy 无需显式配置密钥SDK 默认凭据链即可命中代理提供的角色与 IRSA 相比此方案不要求 EKS OIDC适用于自建 Kubernetes 集群但需要额外维护 kube2iam/kiam 组件并注意其基于网络代理的架构对 Pod 网络与安全策略的要求。无论采用 IRSA 还是 kube2iam/kiam核心原则一致把 AWS 凭据与角色生命周期交给平台层Trivy 保持无密钥运行这既最小化了 Secret 泄露面也避免了长期 Access Key 落入镜像或环境变量。六、认证调用链从域名识别到 ECR Authorization Token理解为什么 Trivy 会自动识别 ECR 并完成登录有助于排障。结合 pkg/fanal/image/registry/ecr/ecr.go 与 pkg/fanal/image/registry/token.go调用链分三步1. 识别 ECR 端点与区域CheckOptions / determineRegionTrivy 使用正则从镜像域名中解析 ECR 端点与 regionecr.go^[^.]\.dkr[.-]ecr(?:-fips)?\.([^.])\.(?:amazonaws\.com(?:\.cn)?|sc2s\.sgov\.gov|c2s\.ic\.gov|on\.aws)$即支持下列域名形态标准形态registry-id.dkr.ecr.region.amazonaws.comFIPS 形态registry-id.dkr.ecr-fips.region.amazonaws.com中国区registry-id.dkr.ecr.region.amazonaws.com.cn隔离区GovCloudregistry-id.dkr.ecr.region.sc2s.sgov.gov、registry-id.dkr.ecr.region.c2s.ic.gov.on.aws形态registry-id.dkr-ecr.region.on.aws若正则无法匹配例如非 ECR 的 AWS 域名determineRegion返回空字符串CheckOptions会返回InvalidURLPattern错误并跳过该适配器ecr.go。ecr_test.gopkg/fanal/image/registry/ecr/ecr_test.go通过多组正反用例含xxx.ecr.ap-northeast-1.not-amazonaws.com、xxx.dkrecr.region-1.amazonaws.com、xxx.dkr.ecr.region-2.amazonaws.cn等非法形态验证了这条判定逻辑。2. 建立 AWS 会话getSession识别为 ECR 后Trivy 以解析出的 region 调用config.LoadDefaultConfig构建 AWS 会话ecr.go。此处有两个容易被忽略的实现细节HTTP 客户端被替换为awshttp.NewBuildableClient()构造的自定义 Transport用来支持 Trivy 自身的 TLS 选项——即--insecure跳过证书校验InsecureSkipVerify以及自定义 CA 证书RootCAs会透传到 ECR API 调用ecr.go这对需要代理或私有 CA 的企业网络尤为重要凭据解析遵循显式静态凭据优先、否则走 SDK 默认链的策略见第二节。3. 获取 Authorization TokenGetCredential会话就绪后Trivy 调用 ECR 的GetAuthorizationTokenAPIecr.go返回体中的AuthorizationToken是 base64 编码的AWS:token形态字符串Trivy 将其 base64 解码后按冒号切分得到用户名AWS密码解码后的 token随后该用户名/密码被封装成authn.Basic交给 go-containerregistry 去拉取镜像token.go。GetCredential的 base64 解码与切分逻辑同样有对应测试覆盖pkg/fanal/image/registry/ecr/ecr_test.go。综上Trivy 每扫描一次 ECR 镜像都会在运行时动态换取一次短期 authorization token不存在把 ECR 密码长期保存在本地的需求这正是无需安装 aws CLI、无需手动 login的根本原因。七、常见错误排查与前置条件核对结合认证调用链扫描 ECR 私有镜像失败时建议按以下顺序排查网络与域名镜像 tag 是否完整使用了ACCOUNT.dkr.ecr.region.amazonaws.com/repo:tag全限定名若域名不属于 ECR 端点格式Trivy 不会走 ECR 适配器也就不会自动登录凭据链可达性本地是否设置了AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY或所在节点具备 IMDS/角色在 EKS 内是否已通过 IRSA 注解或 kube2iam/kiam 注入角色IAM 权限所用角色是否包含ecr:GetAuthorizationToken以及仓库的BatchGetImage、GetDownloadUrlForLayer权限权限不足时GetAuthorizationToken会直接报错对应源码中 failed to get authorization token 错误路径ecr.goRegion 一致性是否出现过 region from AWS_REGION is being overridden 的警告该警告说明环境 region 与仓库域名 region 不一致而 SDK 会话最终以域名解析出的 region 为准企业网络 TLS若 ECR API 需要代理或走自定义 CA请结合 Trivy 的--insecure与 CA 配置使用相关 TLS 选项会透传到 ECR 请求见第六节步骤 2。八、小结对于扫描 AWS ECR 私有镜像这一高频场景Trivy 给出的方案是无额外依赖的自助认证本地场景下依靠 AWS SDK 标准凭据链 环境变量即可工作集群场景下则通过 IRSAServiceAccount 注解或 kube2iam/kiamPod 注解注入角色。底层由 ecr.go 完成端点识别、区域解析、动态换取AWS:token的全过程。按本文的 IAM 最小权限模型与两种注解注入方式配置即可在 CI 与 Kubernetes 环境中稳定、安全地扫描 ECR 私有镜像。进一步阅读私有镜像仓库登录与凭据传递通用指南docs/guide/advanced/private-registries/index.md通过trivy.yaml持久化注册表凭据docs/guide/references/configuration/config-file.md其他云厂商仓库接入参考ACR、Google Artifact Registry、Docker HubECR 适配器源码与测试pkg/fanal/image/registry/ecr/ecr.go、pkg/fanal/image/registry/ecr/ecr_test.go【免费下载链接】trivyFind vulnerabilities, misconfigurations, secrets, SBOM in containers, Kubernetes, code repositories, clouds and more项目地址: https://gitcode.com/GitHub_Trending/tr/trivy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考