go-build attestor

Reads the build information the Go toolchain embeds in every binary it compiles, for each Go binary among the step's products, and records it in the predicate and in a .gobuild.json file next to the binary.

What it captures

The attestor runs after products are recorded. For each product it calls Go's debug/buildinfo.ReadFile. A file that is not a Go binary, or whose build information was already stripped, goes to skipped_non_go. For each Go binary it writes <binary>.gobuild.json (temp file, then rename) and digests the binary and the sidecar.

Fields (the json tags on Attestor and BinaryInfo):

• binaries[], sorted by path:
  • path: the binary, relative to the working directory.
  • sidecar_path: the sidecar written for it; empty if the write failed.
  • go_version: the toolchain, e.g. go1.26.3.
  • main_path: the main package path.
  • main_module: path, version, sum, replace of the main module.
  • deps[]: every dependency module the toolchain recorded, same shape.
  • settings: the build settings as a map, e.g. -trimpath, -ldflags, CGO_ENABLED, GOOS, GOARCH, vcs.revision, vcs.time, vcs.modified.
• skipped_non_go[]: product paths that were not readable as Go binaries.

When to use

On any step that runs go build or go install. Release pipelines often strip binaries later, which removes the build information for good; this attestor captures it while the binary still has it. Auto-detection attaches it when the command starts with go build or go install, or when the working directory has a go.mod.

Flags

None.

Output shape

{
  "binaries": [
    {
      "path": "bin/server",
      "sidecar_path": "bin/server.gobuild.json",
      "go_version": "go1.26.3",
      "main_path": "example.com/acme/server",
      "main_module": { "path": "example.com/acme/server", "version": "(devel)" },
      "deps": [
        { "path": "golang.org/x/sys", "version": "v0.30.0", "sum": "h1:..." }
      ],
      "settings": { "-trimpath": "true", "GOOS": "linux", "GOARCH": "amd64", "vcs.revision": "3f2a9c1...", "vcs.modified": "false" }
    }
  ]
}

Subjects, per Go binary: binary:<path> (digest of the binary, which cilock verify --artifactfile <binary> matches) and go-build-sidecar:<path> (digest of the sidecar JSON).

Gotchas

• It needs products. With no products (for example under cilock attest, or when the build wrote nothing in the working directory) it records an empty predicate and no error.
• No Go binary is not an error. Non-Go products land in skipped_non_go and the run continues.
• The sidecar is a new file. <binary>.gobuild.json is written into your tree next to each binary. Ship it with the binary, or let a later step's product attestor hash it.
• A failed sidecar write is a warning. The build information is still in the predicate, but there is no sidecar_path and no go-build-sidecar: subject.
• Stripped before the step ends is too late. If the same step strips the binary, the build information is gone and the binary is listed in skipped_non_go.

CLI example

cilock run --step build -a go-build -k key.pem -o build.bundle.json \
  -- go build -trimpath -o bin/server ./cmd/server

See also

• product
• Catalog row