# go-build attestor

Source: https://www.testifysec.com/docs/cilock/attestors/go-build/

The cilock go-build attestor reads the build information Go embeds in each compiled binary (module graph, VCS revision, build settings) from the step's products and writes a .gobuild.json sidecar that survives strip.

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.

 

| Name | `go-build` |
| --- | --- |
| Predicate type | `https://aflock.ai/attestations/go-build/v0.1` |
| Lifecycle | `postproduct` |
| Default binary? | No |
| Category | build (primary) |
| Recommended trace | light — light eBPF assist helps |
| Auto-attaches when | - preargv\_prefix: go build<br>- preargv\_prefix: go install<br>- preargv\_regex: ^(\\S\*/)?go -C(=\| )\\S+ (build\|install)( \|$) |

The facts in this box are generated from the CI/lock binary's own catalog (`cilock tools list`). Do not hand-edit — run `npm run gen:catalog`.

 

## 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

 

```json
{
  "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

 

```bash
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`](https://www.testifysec.com/docs/cilock/attestors/product)
 - [Catalog row](https://www.testifysec.com/docs/cilock/reference/attestor-catalog)

 

---

**This page is generated from the CI/lock tool catalog.** Don't edit it here — the source is [`attestation/detection/docs/go-build.doc.md`](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/go-build.doc.md) in [aflock-ai/rookery](https://github.com/aflock-ai/rookery). The same catalog powers `cilock tools show go-build` in the CLI, so a single edit keeps the terminal and the website in sync.

[Edit this page →](https://github.com/aflock-ai/rookery/edit/main/attestation/detection/docs/go-build.doc.md) ·  [Add a new tool →](https://github.com/aflock-ai/rookery/new/main/attestation/detection/docs)

When you open the pull request: if you are an **AI agent**, add the `ai-agent` label. If you are a **human**, add the `human` label.

Reference generated from the product documentation. Match commands and support details to your installed release.