docs: overriding a single --sbom-scanner-* flag discards the entire --sbom preset configuration

Description

The --sbom section of buildah-build(1) and buildah-commit(1) documents presets as "the set of options which they equate to", e.g.:

• "trivy", "trivy-cyclonedx": --sbom-scanner-image=ghcr.io/aquasecurity/trivy --sbom-scanner-command="trivy filesystem -q {ROOTFS} --format cyclonedx --output {OUTPUT}" --sbom-scanner-command="trivy filesystem -q {CONTEXT} --format cyclonedx --output {OUTPUT}" --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version

and the individual flags are documented standalone:

--sbom-scanner-image image — Generate SBOMs using the specified scanner image.

This strongly suggests that a preset is shorthand for its option values, and that specifying one of the options alongside a preset overrides just that value — e.g. that --sbom trivy-cyclonedx --sbom-scanner-image=<internal-mirror> keeps the preset's scanner commands and merge strategy. The interaction between a preset and the individual flags is otherwise undocumented.

The implementation in SBOMScanOptionsFromFlagSet (pkg/cli) behaves differently: if any of --sbom-scanner-image, --sbom-scanner-command, or --sbom-merge-strategy is set, the entire preset configuration is discarded and rebuilt only from the explicitly provided flags, see parse.go:

options, err := sbom.Preset(preset)
...
if image != "" || len(commands) > 0 || mergeStrategy != "" {
	options = &define.SBOMScanOptions{
		Image:         image,
		Commands:      slices.Clone(commands),
		MergeStrategy: define.SBOMMergeStrategy(mergeStrategy),
	}
}

Flags not set explicitly become zero values, and validation then fails:

if options.Image == "" || len(options.Commands) == 0 {
	return options, fmt.Errorf("sbom configuration missing one or more of (%q or %q)",
		"--sbom-scanner-image", "--sbom-scanner-command")
}

Steps to reproduce

$ buildah build \
    --sbom trivy-cyclonedx \
    --sbom-scanner-image registry.example.com/aquasecurity/trivy:0.65.0 \
    --sbom-output sbom.cdx.json \
    -t test .

Describe the results you received

Error: sbom configuration missing one or more of ("--sbom-scanner-image" or "--sbom-scanner-command")

Only the scanner image was overridden, yet the preset's scanner commands and merge strategy were silently dropped, failing validation.

Describe the results you expected

Either the preset's remaining values are kept when only --sbom-scanner-image is specified (per-flag override, as the "equate to" wording implies), or the documentation explicitly describes the all-or-nothing behavior.

Suggested documentation change

Add a note to the --sbom section of docs/buildah-build.1.md and docs/buildah-commit.1.md (this text is also vendored into Podman's podman-build.1.md and podman-farm-build.1.md), for example:

If any of --sbom-scanner-image, --sbom-scanner-command, or --sbom-merge-strategy is specified, the preset's values for these settings are not used as defaults for the others — the scanner configuration is built solely from the explicitly specified flags. To change a single aspect of a preset (for example, to use a mirrored scanner image), repeat the preset's other values explicitly:

bash复制

buildah build \
  --sbom trivy-cyclonedx \
  --sbom-scanner-image registry.example.com/aquasecurity/trivy:0.65.0 \
  --sbom-scanner-command="trivy filesystem -q {ROOTFS} --format cyclonedx --output {OUTPUT}" \
  --sbom-scanner-command="trivy filesystem -q {CONTEXT} --format cyclonedx --output {OUTPUT}" \
  --sbom-merge-strategy=merge-cyclonedx-by-component-name-and-version \
  --sbom-output sbom.cdx.json ...

It may also be worth clarifying in the --sbom-scanner-image / --sbom-scanner-command sections that these flags cannot be used standalone: the preset lookup runs unconditionally, so a valid --sbom preset name is always required.

If per-flag overriding is the intended behavior, please treat this as a bug report against the implementation instead.

Version

buildah v1.43.1