az acr build and az acr task create | Customer is reporting confusion with parameters `--build-args` and `--secret-build-args`

[dbradish-microsoft]

Describe the bug

From @tejaswikolli-web ...

"
We have a request to update az acr | Microsoft Learn for more specific documentation on the use of build-args and secret-build-args in the az acr build command in Azure CLI.

The user has noted that some users have mistakenly exposed GitHub credentials by putting them in build-args instead of secret-build-args.

• --build-args: This is used to pass build arguments that are not sensitive. These arguments are not encrypted and can be seen by anyone who can view the build logs.

• --secret-build-args: This is used to pass sensitive build arguments, such as passwords or access tokens. These arguments are encrypted and cannot be seen in the build logs.

The user is requesting more specific documentation to help users understand the difference between these two options and to prevent the accidental exposure of sensitive information.
"

Currently the descriptions of these two parameters are as follows:

• --build-args: Build argument in '--build-arg name[=value]' format. Multiples supported by passing --build-arg multiple times.

• --secret-build-args: Secret build argument in '--secret-build-arg name[=value]' format. Multiples supported by passing '--secret-build-arg name[=value]' multiple times.

Two requests:

1. If customers are misunderstanding these two parameters and exposing secrets as a result, we need futher clarity given to the descriptions.
2. Currently there is no example using these two parameters. To help customers understand the use of these two parameters, please add two examples -- one for each parameter.

Related command

az acr build

Errors

No known customer error. This GitHub issue is about a reported customer misunderstanding.

Issue script & Debug output

n/a

Expected behavior

n/a

Environment Summary

Azure CLI 2.56.0

Additional context

This issue was originally reported through MSFT e-mail and and is being copied here for engineering response.

[yonzhan]

Thank you for opening this issue, we will look into it.

[tejaswikolli-web]

Please let us know if there in any update on this request.

[yuehaoliang]

Hello @tejaswikolli-web !

For az acr build , we provided 2 parameters --build-arg and --secret-build-arg. Similarly, for az acr task create, --arg and --secret-arg.

The primary distinction lies in the visibility of data entered by users into --arg—our team has access to this information in the backend. Conversely, data entered into --secret-arg remains confidential and is not accessible to our team. Consequently, users who are comfortable with our team having visibility into the arguments for troubleshooting purposes can utilize --arg. However, for those who wish to keep certain information, such as credentials (e.g., GitHub username and password), private, it is imperative to use --secret-arg.

We have observed instances where users inadvertently placed sensitive information in --arg, leading to credential leaks. To mitigate this risk, we strongly recommend highlighting the importance of using --secret-arg in our documentation. This ensures that users are informed and can make the right choice based on their privacy preferences.

[yuehaoliang]

@tejaswikolli-web , could you please help us in appropriately updating the document?

[yuehaoliang]

If customers are misunderstanding these two parameters and exposing secrets as a result, we need further clarity given to the descriptions.

I'm not good at composing formal documents; please help me rephrase my wording in a more appropriate manner.

--build-arg:
Build argument in '--build-arg name[=value]' format. Multiples supported by passing --build-arg multiple times. IMPORTANT: This option should not include any credentials. To pass credentials as arguments, use --secret-build-arg instead to prevent potential leaks.

--secret-build-arg:
Secret build argument in '--secret-build-arg name[=value]' format. Multiples supported by passing '--secret-build-arg name[=value]' multiple times. This option is securer for passing credentials as arguments.

Currently there is no example using these two parameters. To help customers understand the use of these two parameters, please add two examples -- one for each parameter.

For az acr build, how about adding the following examples? IMO, these examples appear redundant. Emphasizing that credentials should not be passed using --build-arg should suffice.

Examples:
Queue a local context as a Linux build, pass custom arguments, tag it, and push it to the registry.

az acr build -t sample/hello-world:{{.Run.ID}} -r MyRegistry --build-arg Name=Value .

Queue a local context as a Linux build, pass custom arguments with credentials, tag it, and push it to the registry.

az acr build -t sample/hello-world:{{.Run.ID}} -r MyRegistry --build-arg Name=Value --secret-build-arg Username=Username --secret-build-arg Password=Password .

[dbradish-microsoft]

@yuehaoliang, how about something like this ...

--build-args: Build argument in '--build-arg name[=value]' format. Multiples are supported by passing --build-arg multiple times. IMPORTANT: This parameter should not include passwords, access tokens, or sensitive information of any kind. To pass sensitive information in a parameter, use --secret-build-args instead.

--secret-build-args: Secret build argument in '--secret-build-arg name[=value]' format. Multiples are supported by passing --secret-build-arg multiple times. This parameter is secure and should be used for passing sensitive information.

[tejaswikolli-web]

wleo@microsoft.com

[yuehaoliang]

@yuehaoliang, how about something like this ...

--build-args: Build argument in '--build-arg name[=value]' format. Multiples are supported by passing --build-arg multiple times. IMPORTANT: This parameter should not include passwords, access tokens, or sensitive information of any kind. To pass sensitive information in a parameter, use --secret-build-args instead.

--secret-build-args: Secret build argument in '--secret-build-arg name[=value]' format. Multiples are supported by passing --secret-build-arg multiple times. This parameter is secure and should be used for passing sensitive information.

Much better wording! Looks good to me, thanks.
There is another command with a similar scenario: az acr task create. This command also features options like --arg and --secret-arg. Could you please update this documentation accordingly?

[yuehaoliang]

Hi @dbradish-microsoft , after reconsideration, we think it is not accurate to state that --secret-build-arg is secure and should be used for passing sensitive information. This is because we internally pass both --build-arg and --secret-build-arg to a docker build command. We cannot guarantee that they will not be exposed, as the CLI docker build --build-arg also carries risks; it depends on how the user defines the docker build process.

Could we state that --build-arg is visible to the ACR team, while --secret-build-arg is not?

[leodewang]

@dbradish-microsoft and @yuehaoliang - let's go with the following.

--build-args: Build argument in '--build-arg name[=value]' format. Multiples are supported by passing --build-arg multiple times. IMPORTANT: This parameter should not include passwords, access tokens, or sensitive information of any kind. This parameter value will be visible to the ACR team for debugging purposes.

--secret-build-args: Secret build argument in '--secret-build-arg name[=value]' format. Multiples are supported by passing --secret-build-arg multiple times. This parameter value is not surfaced to the ACR team and is more suitable for sensitive information.

[Hi-Fi]

Technically threre's one big issue with both of these things; if user has access to the resulting image, build history (https://docs.docker.com/engine/reference/commandline/image_history/) would have both visible as those are (in Dockerfile sense) just ARGs.

With docker build there's secret usage possibility with build kit, and now presenting argument starting with --secret can easily be confused to that one.

References:

• https://pythonspeed.com/articles/docker-build-secrets/
• https://docs.docker.com/build/building/secrets/

Partially this could be solved with multi stage build, but not always (e.g. when wanting to include OS packages that require authentication do download).