跳转到主要内容

Input reference

When Buildx evaluates policies, it provides information about build inputs through the input object. The structure of input depends on the type of resource your Dockerfile references.

Input types

Build inputs correspond to Dockerfile instructions:

Dockerfile instruction Input type Access pattern
FROM alpine:latest Image input.image
COPY --from=builder /app /app Image input.image
ADD https://example.com/file.tar.gz / HTTP input.http
RUN curl https://example.com/ HTTP input.http
ADD git@github.com:user/repo.git /src Git input.git
Build context (.) Local input.local

Each input type has specific fields available for policy evaluation.

HTTP inputs

HTTP inputs represent files downloaded over HTTP or HTTPS using the ADD instruction, or requests from RUN instructions when BuildKit's proxy is enabled. See Block URLs in build steps.

Example Dockerfile

FROM alpine
ADD --checksum=sha256:abc123... https://example.com/app.tar.gz /app.tar.gz

Available fields

input.http.url

The complete URL of the resource.

allow if {
    input.http.url == "https://example.com/app.tar.gz"
}

input.http.schema

The URL scheme (http or https).

# Require HTTPS for all downloads
allow if {
    input.http.schema == "https"
}

input.http.host

The hostname from the URL.

# Allow downloads from approved domains
allow if {
    input.http.host == "cdn.example.com"
}

input.http.path

The path component of the URL.

allow if {
    startswith(input.http.path, "/releases/")
}

input.http.checksum

The checksum specified with ADD --checksum=..., if present. Empty string if no checksum was provided.

# Require checksums for all downloads
allow if {
    input.http.checksum != ""
}

input.http.hasAuth

Boolean indicating if the request includes authentication (HTTP basic auth or bearer token).

# Require authentication for internal servers
allow if {
    input.http.host == "internal.company.com"
    input.http.hasAuth
}

Image inputs

Image inputs represent container images from FROM instructions or COPY --from references.

Example Dockerfile

FROM alpine:3.19@sha256:abc123...
COPY --from=builder:latest /app /app

Available fields

input.image.ref

The complete image reference as written in the Dockerfile.

allow if {
    input.image.ref == "alpine:3.19@sha256:abc123..."
}

input.image.host

The registry hostname. Docker Hub images use "docker.io".

# Only allow Docker Hub images
allow if {
    input.image.host == "docker.io"
}

# Only allow images from GitHub Container Registry
allow if {
    input.image.host == "ghcr.io"
}

input.image.repo

The repository name without the registry host.

allow if {
    input.image.repo == "library/alpine"
}

input.image.fullRepo

The full repository path including registry host.

allow if {
    input.image.fullRepo == "docker.io/library/alpine"
}

input.image.tag

The tag portion of the reference. Empty if using a digest reference.

# Allow only specific tags
allow if {
    input.image.tag == "3.19"
}

input.image.isCanonical

Boolean indicating if the reference uses a digest (@sha256:...).

# Require digest references
allow if {
    input.image.isCanonical
}

input.image.checksum

The SHA256 digest of the image manifest.

allow if {
    input.image.checksum == "sha256:abc123..."
}

input.image.platform

The target platform for multi-platform images.

allow if {
    input.image.platform == "linux/amd64"
}

input.image.os

The operating system from the image configuration.

allow if {
    input.image.os == "linux"
}

input.image.arch

The CPU architecture from the image configuration.

allow if {
    input.image.arch == "amd64"
}

input.image.hasProvenance

Boolean indicating if the image has provenance attestations.

# Require provenance for production images
allow if {
    input.image.hasProvenance
}

input.image.provenance

Metadata parsed from an image's SLSA provenance attestation. Buildx supports SLSA v0.2 and v1 predicates. Fields depend on what the attestation records; an absent field isn't equivalent to a Boolean value of false.

Field Description
predicateType SLSA provenance predicate URI.
buildType Identifier for the build process.
builderID Builder identifier recorded in the attestation.
invocationID Identifier for the build invocation.
startedOn, finishedOn Build timestamps in RFC 3339 format.
configSource.uri URI of the source containing the build definition.
configSource.digest Map of source digest algorithms to values.
configSource.path Path to the build definition within the source.
frontend BuildKit frontend used for the build.
buildArgs Map of build argument names to values.
rawArgs Map of frontend arguments, including build-arg: prefixes.
reproducible Whether the attestation declares the build reproducible.
hermetic Whether the attestation declares the build hermetic.
completeness.parameters Whether build parameters are fully recorded.
completeness.environment Whether the environment is fully recorded (v0.2).
completeness.materials Whether build dependencies are fully recorded.

For example, require an attestation that declares the build hermetic and records all dependencies:

allow if {
    input.image.provenance.hermetic == true
    input.image.provenance.completeness.materials == true
}

Accessing these fields during policy evaluation resolves the provenance metadata as needed. To inspect it without evaluating a policy, request the fields explicitly:

$ docker buildx policy eval --print --fields image.provenance \
    docker-image://registry.example.com/team/app:latest

These fields describe claims in the attestation. To verify who produced it, also check the image's attestation signatures.

input.image.labels

A map of image labels from the image configuration.

# Check for specific labels
allow if {
    input.image.labels["org.opencontainers.image.vendor"] == "Example Corp"
}

input.image.signatures

Array of attestation signatures. Each signature in the array has the following fields:

  • kind: Signature kind (e.g., "docker-github-builder", "self-signed")
  • type: Signature type (e.g., "bundle-v0.3", "simplesigning-v1")
  • timestamps: Trusted timestamps from transparency logs
  • dockerReference: Docker image reference
  • isDHI: Boolean indicating if this is a Docker Hardened Image
  • signer: Sigstore certificate details
# Require at least one signature
allow if {
    count(input.image.signatures) > 0
}

For Sigstore signatures, the signer object provides detailed certificate information from the signing workflow:

  • certificateIssuer: Certificate issuer
  • subjectAlternativeName: Subject alternative name from certificate
  • buildSignerURI: URI of the build signer
  • buildSignerDigest: Digest of the build signer
  • runnerEnvironment: CI/CD runner environment
  • sourceRepositoryURI: Source repository URL
  • sourceRepositoryDigest: Source repository digest
  • sourceRepositoryRef: Source repository ref (branch/tag)
  • sourceRepositoryIdentifier: Source repository identifier
  • sourceRepositoryOwnerURI: Repository owner URI
  • buildConfigURI: Build configuration URI
  • buildTrigger: What triggered the build
  • runInvocationURI: CI/CD run invocation URI
# Require signatures from GitHub Actions
allow if {
    some sig in input.image.signatures
    sig.signer.runnerEnvironment == "github-hosted"
    startswith(sig.signer.sourceRepositoryURI, "https://github.com/myorg/")
}

Provenance materials

input.image.provenance.materials contains the build dependencies recorded in an image's provenance. Each entry is an input object with the same image, git, or http fields used for direct build inputs.

For example, inspect the Git repository used to build a base image:

allow if {
    some material in input.image.provenance.materials
    material.git.host == "github.com"
    material.git.remote == "https://github.com/myorg/base.git"
}

An image material can have its own image.provenance.materials array. Access nested fields to resolve metadata for those dependencies as needed. Buildx supports image, Git, and HTTP material sources; unsupported material URIs are skipped with a warning. Checking a parent image doesn't automatically apply your rules to every material. Write explicit conditions for the dependencies you need to validate.

To inspect a nested field without evaluating a policy, use --fields:

$ docker buildx policy eval --print \
    --fields 'image.provenance.materials[0].git.commitChecksum' \
    docker-image://registry.example.com/team/base:latest

The example requests Git metadata for the first material. Choose the index and field for the material you want to inspect.

Git inputs

Git inputs represent Git repositories referenced in ADD instructions or used as build context.

Example Dockerfile

ADD git@github.com:moby/buildkit.git#v0.12.0 /src

Available fields

input.git.schema

The URL scheme (https, http, git, or ssh).

# Require HTTPS for Git clones
allow if {
    input.git.schema == "https"
}

input.git.host

The Git host (e.g., github.com, gitlab.com).

allow if {
    input.git.host == "github.com"
}

input.git.remote

The complete Git URL.

allow if {
    input.git.remote == "https://github.com/moby/buildkit.git"
}

input.git.ref

The Git reference.

allow if {
    input.git.ref == "refs/heads/master"
}

input.git.tagName

The tag name if the reference is a tag.

# Only allow version tags
allow if {
    regex.match(`^v[0-9]+\.[0-9]+\.[0-9]+$`, input.git.tagName)
}

input.git.branch

The branch name if the reference is a branch.

allow if {
    input.git.branch == "main"
}

input.git.subDir

The subdirectory path within the repository, if specified.

# Ensure clones are from the root
allow if {
    input.git.subDir == ""
}

input.git.isCommitRef

Boolean indicating if the reference is a commit SHA (as opposed to a branch or tag name).

# Require commit SHAs for production
allow if {
    input.env.target == "production"
    input.git.isCommitRef
}

input.git.checksum

The checksum of the Git reference. For commit references and branches, this is the commit hash. For annotated tags, this is the tag object hash.

allow if {
    input.git.checksum == "abc123..."
}

input.git.commitChecksum

The commit hash that the reference points to. For annotated tags, this differs from checksum (which is the tag object hash). For commit references and branches, this is the same as checksum.

allow if {
    input.git.commitChecksum == "abc123..."
}

input.git.isAnnotatedTag

Boolean indicating if the reference is an annotated tag (as opposed to a lightweight tag).

# Require annotated tags
allow if {
    input.git.tagName != ""
    input.git.isAnnotatedTag
}

input.git.commit

Object containing commit metadata:

  • author: Author name, email, when
  • committer: Committer name, email, when
  • message: Commit message
  • pgpSignature: PGP signature details if signed
  • sshSignature: SSH signature details if signed
# Check commit author
allow if {
    input.git.commit.author.email == "maintainer@example.com"
}

input.git.tag

Object containing tag metadata for annotated tags:

  • tagger: Tagger name, email, when
  • message: Tag message
  • pgpSignature: PGP signature details if signed
  • sshSignature: SSH signature details if signed
# Require signed tags
allow if {
    input.git.tag.pgpSignature != null
}

Local inputs

Local inputs represent the build context directory.

Available fields

input.local.name

The name or path of the local context.

allow if {
    input.local.name == "."
}

Local inputs are typically less restricted than remote inputs, but you can still write policies to enforce context requirements.

Environment fields

The input.env object provides build configuration information set by user on invoking the build, not specific to a resource type.

Available fields

input.env.filename

The name of the Dockerfile being built.

# Stricter rules for production Dockerfile
allow if {
    input.env.filename == "Dockerfile"
    input.image.isCanonical
}

# Relaxed rules for development
allow if {
    input.env.filename == "Dockerfile.dev"
}

input.env.target

The build target from multi-stage builds.

# Require signing only for release builds
allow if {
    input.env.target == "release"
    input.git.tagName != ""
    verify_git_signature(input.git.tag, "maintainer.asc")
}

input.env.depth

The input's depth in the provenance material tree. A direct build input has depth 0, its materials have depth 1, and each nested material increases the depth by one. For example, access material.env.depth when iterating over input.image.provenance.materials.

input.env.args

Build arguments passed with --build-arg. Access specific arguments by key.

# Check build argument values
allow if {
    input.env.args.ENVIRONMENT == "production"
    input.image.hasProvenance
}

Next steps

这篇文档对你有帮助吗？
想留言或继续讨论？请到 Cyberforums 赛博论坛参与。 参与讨论 / 回复