企业官网建设流程全解析

BuildKit 安全校验指南：SecretsUsedInArgOrEnv 规则与 Dockerfile 构建密钥（Build Secrets）最佳实践

【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit

本篇技术指南围绕 BuildKit Dockerfile 前端内置的构建检查规则SecretsUsedInArgOrEnv展开，讲解为何在ARG/ENV指令中声明敏感数据属于安全隐患，从源码层面剖析该规则的触发逻辑（敏感键名正则匹配）、放行策略与局部跳过机制，并给出基于RUN --mount=type=secret构建密钥挂载的完整修复方案，帮助你在镜像构建阶段安全注入令牌、口令等凭据，且保证其不会落入最终镜像或镜像元数据。

规则一览：输出信息与触发场景

SecretsUsedInArgOrEnv是 BuildKit 内置构建检查（Build checks）规则集的一员，规则定义位于 frontend/dockerfile/linter/ruleset.go，其正式规则文档见 frontend/dockerfile/docs/rules/secrets-used-in-arg-or-env.md。

规则名称：SecretsUsedInArgOrEnv

当 Dockerfile 中出现将敏感数据放入ARG或ENV指令的情况时，构建检查会输出如下告警消息：

Potentially sensitive data should not be used in the ARG or ENV commands

若命中具体的键名，告警详情还会携带指令类型与键名，格式由 ruleset.go 中的RuleSecretsUsedInArgOrEnv.Format定义：

Do not use ARG or ENV instructions for sensitive data (ARG "SECRET_PASSPHRASE") Do not use ARG or ENV instructions for sensitive data (ENV "apikey")

该规则并不是实验性规则，默认即参与构建检查，无需任何开关即可生效。

为什么不能在 ARG/ENV 中放置敏感数据

在本地开发环境中，通过环境变量向运行中的进程传递密钥是常见做法；但把这种做法照搬到 Dockerfile 中是不安全的，原因如下：

• ENV的值会固化进镜像：ENV指令会把变量写入镜像的配置（OCI Image Config 的Config.Env字段），任何人拉取该镜像都可以通过docker inspect或 OCI 镜像配置直接读取到明文密钥。
• ARG的默认值同样会暴露：ARG指令声明的默认值会记录在镜像构建历史（history）中，docker history即可查看，密钥随之泄露。
• 即使构建后删除，也会残留在镜像层中：在RUN中通过ARG/ENV引用的值会参与该层命令字符串的计算与记录，构建层与元数据中都会留下痕迹。

因此，规则文档（SecretsUsedInArgOrEnv.md）明确建议：不要用ARG或ENV承载敏感数据，而应改用构建密钥挂载（secret mounts）——它能够在构建期间安全地向构建进程暴露密钥，且不会持久化到最终镜像或其元数据中。

触发与放行逻辑：源码级的键名匹配

该规则的判定核心并不依赖构建参数的实际值，而是根据ARG/ENV的键名来推断其是否可能承载敏感数据。实现位于 frontend/dockerfile/dockerfile2llb/validations.go：

• 维护一组“敏感令牌”词表：apikey、auth、credential、credentials、key、password、pword、passwd、secret、token；
• 同时维护一组“允许令牌”词表：public、file、version；
• 通过正则(?i)(?:_|^)(?:敏感令牌)(?:_|$)（大小写不敏感）匹配键名——即敏感词必须是键名中的完整单词，前后可以是下划线或键名边界；
• 若键名命中敏感正则且没有命中允许正则，则判定违规并上报（validateNoSecretKey）。

这套词表逻辑可以直接解释大量实际场景：

值得注意的是，即使键名只声明而没有赋任何值（例如ARG SECRET_PASSPHRASE或ENV git_key=），只要键名匹配，规则依然会告警——因为该键名本身就暗示了此处可能注入敏感数据。这些行为均被集成测试覆盖，参见 frontend/dockerfile/dockerfile_check_test.go 中的testSecretsUsedInArgOrEnv用例。

运行构建检查：--check 与告警输出

BuildKit 的构建检查以一次“构建调用”的形式执行，但产出的是检查结果而非构建产物。官方文档索引见 frontend/dockerfile/linter/docs/_index.md。执行方式：

$ docker build --check .

告警默认级别为Level 1（warning），并会附上触发的具体行号，例如：

SecretsUsedInArgOrEnv: Do not use ARG or ENV instructions for sensitive data (ARG "SECRET_PASSPHRASE") (line 4)

若希望将告警升级为构建失败，可以显式开启错误模式，相关配置解析逻辑见 frontend/dockerfile/linter/linter.go 中的ParseLintOptions，例如在 Dockerfile 首行加入指令：

# check=error=true

关于各规则的启停、实验性规则开关与告警升级的完整配置方式，可进一步阅读仓库内的规则总索引 frontend/dockerfile/docs/rules/_index.md 与 linter 实现 frontend/dockerfile/linter/linter.go。

修复方案：用 secret mounts 替代 ARG/ENV

规则文档给出的推荐修复方式，是使用 BuildKit 的构建密钥挂载。其核心能力是：在单个RUN指令执行期间，将构建方提供的密钥以只读文件或环境变量的形式暴露给构建进程；该密钥既不写入任何镜像层，也不进入镜像配置与构建历史。

反面示例（❌ Bad）

用ARG传入 AWS 凭据：

ARG AWS_ACCESS_KEY_ID ARG AWS_SECRET_ACCESS_KEY RUN aws s3 cp s3://my-bucket/file .

上述写法会把两个密钥固化进镜像层与构建历史，属于规则明确禁止的用法，docker build --check会立即给出告警。

正面示例（✅ Good）

改用 secret mounts，并通过env选项把密钥以环境变量的形式注入RUN：

RUN --mount=type=secret,id=aws_key_id,env=AWS_ACCESS_KEY_ID \ --mount=type=secret,id=aws_secret_key,env=AWS_SECRET_ACCESS_KEY \ aws s3 cp s3://my-bucket/file .

构建时通过--secret传递密钥：

$ docker buildx build \ --secret id=aws_key_id,env=AWS_ACCESS_KEY_ID \ --secret id=aws_secret_key,env=AWS_SECRET_ACCESS_KEY .

其中--secret id=<id>,env=<环境变量名>表示：从本机环境变量<环境变量名>读取值，作为 id 为<id>的密钥提供给构建。若希望从文件读取，则改用--secret id=aws_key_id,src=/path/to/key。

secret mount 参数详解

RUN --mount=type=secret的挂载参数由 frontend/dockerfile/instructions/commands_runmount.go 解析，type=secret被定义为独立的挂载类型MountTypeSecret（见 commands_runmount.go），随后由 frontend/dockerfile/dockerfile2llb/convert_secrets.go 中的dispatchSecret转换为底层 LLB 操作。常用选项如下：

其中env选项在源码层面有更细的行为：dispatchSecret会通过llb.SecretAsEnvName把密钥转为环境变量，而 convert_secrets.go 中的withSecretEnvMask还会在RUN指令的环境求值层把该变量值遮蔽为****，一方面避免真实值出现在求值中间状态中，另一方面也向调试输出明确“此值来自密钥挂载”。

单条指令级别的规则跳过

SecretsUsedInArgOrEnv规则支持在 Dockerfile 中以注释指令形式做局部跳过，适合确认某个键名确实安全、或必须兼容遗留镜像层历史行为的场景。语法为注释指令# check=skip=<规则名>，其解析入口在 frontend/dockerfile/dockerfile2llb/convert.go（newRuleLinter）与 frontend/dockerfile/linter/linter.go（WithMergedConfigFromComments）。

示例：明确声明下面的ENV password是业务需要的（规则检查会跳过该指令）：

# check=skip=SecretsUsedInArgOrEnv // allow secret in environment ENV password=bar

也可以跳过全部规则（同样只对紧跟其后的单条指令生效）：

# check=skip=all // is local to only this instruction ARG alternate_password

这些局部跳过指令的作用域仅限紧随其后的那一条指令，其行为在 frontend/dockerfile/dockerfile_check_test.go 的集成测试中均有覆盖。

小结

SecretsUsedInArgOrEnv是 BuildKit Dockerfile 前端中最直接的凭据泄漏防线之一：它以键名语义推断敏感数据，拦截ARG/ENV承载密钥的写法，并把开发者导向 BuildKit 的构建密钥（secret mounts）机制。实践中建议遵循如下策略：

1. 在 CI 与本地统一使用docker build --check将安全检查纳入常规构建流程；
2. 需要密钥的RUN一律改用--mount=type=secret（文件形式或env=环境变量形式），并配合--secret在构建时注入；
3. 对确有需求的个别指令，用# check=skip=SecretsUsedInArgOrEnv做最小范围的显式豁免，并附注释说明原因；
4. 涉及public、file、version等允许词表语义的键名可正常命名，不会触发告警。

相关实现与测试可继续深入阅读：linter/ruleset.go、dockerfile2llb/validations.go、dockerfile2llb/convert_secrets.go 与 dockerfile_check_test.go。

【免费下载链接】buildkitconcurrent, cache-efficient, and Dockerfile-agnostic builder toolkit项目地址: https://gitcode.com/GitHub_Trending/bu/buildkit