feat(attest-sbom): add kosli attest sbom

[AlexKantor87]

Slice 2 of #1162. Adds the kosli attest sbom command, using the reader merged in #1165.

Replaces #1166, which went through five review rounds and eight commits. This is the same code squashed to one commit, with one deliberate change: the end-to-end test is no longer skipped, so CI is red on purpose until the server side is on staging. See "Why CI is red".

What it does

kosli attest sbom --name my-sbom --sbom-file bom.json --flow f --trail t

Reads the SBOM, records what it says about itself, and uploads the file as an attachment.

Why only one file

The file is uploaded as-is, so the checksum recorded against it is the checksum of the file the customer handed us. They can verify it by hand.

That only holds for a single file. The CLI tars and gzips two or more attachments before upload, which would compress the SBOM and break the checksum that was just recorded for it. So --sbom-file and --attachments cannot be used together, and since --sbom-file is required the pair can never be satisfied: --attachments is refused and hidden from --help.

An already-compressed file is also rejected, because the format and the summary have to be read out of it.

Why the uploader is handed bytes, not a path

The reader loads the whole file in one go, so the size has to be limited somewhere, and the checksum has to describe what the server receives. Two earlier versions each fixed half of this and moved the race one step: first the file was stat'd and then opened separately (a file still being written grows in between), then it was read once but the uploader was given the path, which internal/requests opens and reads again when it builds the request body.

Now there is one read. The path is stat'd first (a fifo with no writer blocks on open, so a type check after opening would never run), then read through an io.LimitReader capped one byte past the ceiling, and that same buffer produces the fingerprint, the parsed summary and the upload. internal/requests gains a file-bytes form item for exactly this. A test hands the built request body to sha256 and checks it equals original_fingerprint; the round-trip against a local server shows the stored evidence_archive_fingerprint equal to the fixture's digest.

The ceiling is below the API's 10MB request limit rather than equal to it, because the JSON payload is counted against that limit alongside the file. The margin is a guess at a small payload, not a bound: --user-data rides in the same body and can push the total past 10MB on its own. Raising the ceiling needs direct-to-S3 upload, which is kosli-dev/server#6536.

Why the format and checksum are recorded twice

They go inside attestation_data, where the server's schema can enforce them, and again as the sbom_format and sbom_sha256 annotations, which is where a reader sees them on the trail page.

Holding one value in two places is usually a mistake. Here both come from the same read of the same file in the same pass, so they cannot drift apart: if the CLI is wrong they are wrong together rather than disagreeing.

Passing either key through --annotate is an error rather than being silently overwritten.

Why the URL says "system"

The slug is the attestation family, not the type. The server tells system types apart by type_name in the body, which is sbom here.

Why CI is red

TestAttestSbomRoundTrip reports an SBOM to a real server. CI runs against the current staging server image, which does not know what an sbom attestation is until https://github.com/kosli-dev/server/pull/6863 merges and deploys, so the POST comes back System attestation type 'sbom' does not exist.

That failure is accurate and is left in place. The previous PR skipped this test to get a green tick, which made CI say "nothing is broken" while the one test that proves the command works was not running. Green here should mean the feature works, so this stays red until it does.

Everything else in the file passes today: the --dry-run cases prove the payload the command builds, the error cases need no server, and the packaging test asserts local logic only.

The ticket already requires this order: the command must not be released until the server side is in production, because a released command pointed at a server that does not know the type fails for every customer who tries it.

What was run

The full CLI suite, locally, against a server image built from the branch behind server#6863. That server knows the sbom type, so the round-trip test runs for real there: 2667 tests, two failures, both TestAttestGitlabPRCommandTestSuite and both reproduced identically on a clean clone of main, so they are the environment and not this change.

The stored attestation was then read back from the server's database. original_fingerprint, the sbom_sha256 annotation and evidence_archive_fingerprint all equal the SHA-256 of the fixture on disk, which is the whole promise of the command.

Also run: go build ./..., go vet ./..., gofmt, golangci-lint on the changed packages, the empty-flag audit for this command (all 25 flags refuse an empty value), and kosli attest sbom --help.

Every guard has been mutation-tested: each of the size comparison, the read limit, the directory check, the gzip rejection, the mutual exclusion with --attachments, both reserved annotation keys, the annotation merge, the fingerprint, and the bytes handed to the uploader turns a test red when broken.

How to run the suite locally on an arm64 Mac is written up in the AlexKantor tracker under process/cli-local-test-environment.md.

🤖 Generated with Claude Code

[claude]

Claude finished @AlexKantor87's task in 3m 47s —— View job

---

Review: feat(attest-sbom): add kosli attest sbom

• Static analysis (go build, go vet, go mod tidy)
• Read changed files
• Review posted (2 inline comments on cmd/kosli/root.go)

Static analysis

Check	Result
go build ./...	pass
go vet ./...	pass
go mod tidy + git diff --exit-code go.mod go.sum	clean

Findings

Both are in cmd/kosli/root.go — the shared machinery this PR touches — and neither is a live bug.

1. viperAppliedFlags[f.Name] = true is still unconditional (root.go:854). The reply to the last round said it had been moved to record only "after Set returns without error". It hasn't: the assignment sits outside the if err != nil block, so a refused Set is still recorded as applied-from-config. Unreachable today (bindErr aborts the run at root.go:727 before any PreRunE reads the map), so this is the invariant not matching the doc comment on line 777 rather than a defect. One-line fix suggested inline.

2. bindFlags's doc comment is now orphaned (root.go:775-781). The new var and helper were inserted between that comment and the function, so lines 775-776 read as the opening of the viperAppliedFlags comment and godoc attaches the block to the var. bindFlags ends up undocumented.

Nothing else new surfaced. The findings from the earlier rounds all check out as addressed in the tree as it stands: file-bytes carries the hashed bytes end to end, os.Stat precedes os.Open, both reserved annotation keys have their own case, --attachments is hidden and the prose no longer names it, and the default: case in createMultipartRequestBody closes the silent-skip. I re-ran the "every Type spelling" check behind that last one — the Type: "env" hit is PolicyPayload.Type in testHelpers.go:609, not a FormItem, so the conclusion holds and no existing caller is caught by the new error.

One observation, not a request: sbom.ProcessSBOMFile now has no production caller (attestSbom.go uses ProcessSBOM), so the 35-case parser suite in internal/sbom exercises a wrapper the product no longer calls. It's a two-line delegate, so the risk is negligible — worth knowing rather than changing.

Worth calling out

• The read → hash → parse → upload path is now genuinely single-pass. Handing requests a FileBytes instead of a path is the right shape for the invariant, and TestSbomUploadsTheBytesItHashed asserts it at the seam that matters: sha256 of form[1].Content.Data equals both original_fingerprint and sbom_sha256, with a literal digest as an anchor so an empty buffer can't pass.
• The fifo test earns its keep. The select with a timeout makes the stat-before-open ordering a red run rather than a package hang, which is the rare case of a test that catches a regression a plain assertion couldn't.
• Passing the bytes as a parameter instead of a field turns "the body cannot be built before the file is read" into a compile error rather than a runtime guard. That's the stronger version of the fix that was asked for.
• The --attachments source attribution is careful in the direction that's easy to get wrong: it stays silent when the flag was typed, because the env value was never applied, and both branches have a test.

CI

PR checks is green; Main was still running at review time. The round-trip test's deliberate red is well argued in the PR body, and the stated plan — hold as draft until server#6863 deploys, so main never carries a failing required check — is the right resolution.
· branch claude/1162-attest-sbom-command