golang: infer main-module version from image tag when build info is (devel) (#3)

* golang: infer main-module version from image tag when build info is (devel)

A Go binary built from a checkout carries no comparable main-module
version: build info reports "(devel)". A project like k3s sets its
version through `-ldflags -X pkg.Version=...`, which writes a separate
variable that never reaches buildinfo.Main.Version. The scanner sent
"(devel)" to OSV, which cannot range-match it, so OSV returned advisories
already fixed in the running version and the main module's always-present
pclntab symbols made every one of them land as a false positive.

In image mode, when a binary's main-module version is non-comparable,
recover a version from the image reference tag. The mapping is kept honest
so it can never silently under-report a real vulnerability:

- Main module only: dependencies keep their real build-info versions.
- Semver gated: the tag is used only when it normalizes to a full
  MAJOR.MINOR.PATCH semver. latest, digests and date-stamps infer nothing.
- k3s/rke2 aware: Docker tags cannot contain '+', so v1.36.3+k3s1 ships as
  v1.36.3-k3s1. A trailing -k3sN / -rke2rN is converted back to +k3sN /
  +rke2rN so it matches the versions those advisories are filed under.
- Provenance: any finding whose version was inferred carries an
  image-tag-version evidence note in both text and JSON output, so an
  inferred version is never mistaken for one read from the artifact.

When no plausible tag exists the original "(devel)" is kept, which
over-reports rather than guessing a version that could hide a real finding.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* golang: sharpen inferred-version provenance wording and pin the semver gate

Lead the provenance note with "version not in build info" so a reader of
text or JSON output cannot mistake an inferred version for one read from
the binary. For a generic image a clean-semver tag is a real guess that
could read too high, and this label is what keeps such a finding honest.

Add a test asserting golang.org/x/mod/semver.IsValid accepts the
normalized "+k3sN" build-metadata form, so the gate can never regress into
rejecting the very case the fallback exists to enable.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: cwayne18 <cwayne18@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: cwayne18

go.mod

@@ -5,6 +5,7 @@ go 1.25.0
 require (
 	github.com/glebarez/go-sqlite v1.22.0
 	github.com/knqyf263/go-rpmdb v0.1.1
+	golang.org/x/mod v0.38.0
 )
 
 require (

internal/analyze/analyze.go

@@ -289,6 +289,7 @@ func registryFor(opts Options) *ecosystem.Registry {
 		golang.New(golang.Options{
 			VersionOverride: opts.Version,
 			GoVersion:       opts.GoVersion,
+			Image:           opts.Image,
 			Logf:            opts.Logf,
 		}),
 		ospkg.New(ospkg.Options{

internal/ecosystem/golang/golang.go

@@ -36,6 +36,13 @@ type Plugin struct {
 	// ("1.24.0"). It matters for stdlib findings, which are toolchain-specific.
 	GoVersion string
 
+	// Image is the reference of the image being scanned, in image mode ("" for
+	// rootfs or source mode). It is the only place a version can be recovered
+	// for a main module whose build info reports "(devel)": `go build` from a
+	// checkout stamps no comparable version, so the image tag is the fallback.
+	// See mainModuleVersion for the safeguards that keep this from guessing.
+	Image string
+
 	// Logf receives progress messages. Never nil after New.
 	Logf func(format string, args ...any)
 }
@@ -44,6 +51,7 @@ type Plugin struct {
 type Options struct {
 	VersionOverride string
 	GoVersion       string
+	Image           string
 	Logf            func(format string, args ...any)
 }
 
@@ -56,6 +64,7 @@ func New(opts Options) *Plugin {
 	return &Plugin{
 		VersionOverride: opts.VersionOverride,
 		GoVersion:       opts.GoVersion,
+		Image:           opts.Image,
 		Logf:            logf,
 	}
 }
@@ -103,6 +112,51 @@ func mainModulePath(bin binscan.Binary) string {
 // binary's build info parsed exactly once per run.
 type state struct {
 	binaries []binary
+
+	// inferredNote, when non-empty, records that this component's Version was
+	// derived from the image tag rather than read from build info. The analysis
+	// phase attaches it as evidence to every finding so a reader can never
+	// mistake an inferred version for one read from the artifact.
+	inferredNote string
+}
+
+// mainModuleVersion resolves the version to report for a binary's own main
+// module, and a provenance note when that version was not the one build info
+// reported.
+//
+// Go stamps no comparable version on a main module built from a checkout: build
+// info reports "(devel)" (see isDevelVersion), which OSV cannot range-match, so
+// it returns advisories already fixed in the running version and every one of
+// them lands as a false positive against the module's own always-present code.
+//
+// The fallback is the image tag, but it is applied with the single hard rule
+// this tool never bends: it must not silently under-report. So it fires only for
+// the main module here, only when build info gave nothing comparable, and only
+// when the tag normalizes to real semver (moduleVersionFromImageTag refuses
+// "latest", digests and date-stamps). When it cannot infer, it returns the
+// original version unchanged -- which keeps today's behavior of querying OSV
+// with "(devel)" and over-reporting, the safe direction, rather than guessing a
+// version that could hide a real vulnerability.
+func (p *Plugin) mainModuleVersion(rawVersion string) (version, note string) {
+	if !isDevelVersion(rawVersion) {
+		return rawVersion, ""
+	}
+	if p.Image == "" {
+		return rawVersion, ""
+	}
+	inferred, tag, ok := moduleVersionFromImageTag(p.Image)
+	if !ok {
+		return rawVersion, ""
+	}
+	reported := rawVersion
+	if reported == "" {
+		reported = "(empty)"
+	}
+	// Lead with the fact that this version is not from the artifact. For a
+	// generic image a clean-semver tag is a genuine guess that could read too
+	// high, and this label is the only thing that keeps such a finding honest.
+	note = fmt.Sprintf("version not in build info (reported %s); inferred from image tag %q", reported, tag)
+	return inferred, note
 }
 
 // DetectImage implements ecosystem.ImageAnalyzer.
@@ -162,8 +216,19 @@ func (p *Plugin) groupAll(root string, bins []binscan.Binary) []ecosystem.Compon
 		// enumeration that left it out would miss the CVEs most likely to
 		// apply to all of them at once.
 		g.add(StdlibModule, binscan.NormalizeGoVersion(bin.Info.GoVersion), rel, bin.Path, main)
-		if m := bin.Info.Main; m.Path != "" && m.Version != "" {
-			g.add(m.Path, m.Version, rel, bin.Path, main)
+		if m := bin.Info.Main; m.Path != "" {
+			// The main module's build-info version can be "(devel)" for a
+			// binary built from a checkout, which OSV cannot match; recover a
+			// comparable version from the image tag when it is safe to. Only
+			// the main module is treated this way -- dependencies carry real
+			// versions -- and a note is kept so the inference is visible.
+			ver, note := p.mainModuleVersion(m.Version)
+			if ver != "" {
+				g.add(m.Path, ver, rel, bin.Path, main)
+				if note != "" {
+					g.markInferred(m.Path, ver, note)
+				}
+			}
 		}
 		for _, dep := range bin.Info.Deps {
 			m := dep
@@ -186,13 +251,24 @@ func (p *Plugin) group(root string, bins []binscan.Binary, modules []string) []e
 		rel := target.Rel(root, bin.Path)
 		for _, module := range modules {
 			version := p.VersionOverride
+			var note string
 			if version == "" {
 				version = bin.ModuleVersion(module)
+				// The requested module can be this binary's own main module,
+				// which has the same "(devel)" defect groupAll works around;
+				// give it the same image-tag fallback so a targeted scan is not
+				// stuck with a version OSV cannot match.
+				if mainModulePath(bin) == module {
+					version, note = p.mainModuleVersion(version)
+				}
 			}
 			if version == "" {
 				continue // module not linked into this binary
 			}
 			g.add(module, version, rel, bin.Path, mainModulePath(bin))
+			if note != "" {
+				g.markInferred(module, version, note)
+			}
 		}
 	}
 	return g.components()
@@ -245,6 +321,16 @@ func (g *grouper) components() []ecosystem.Component {
 	return out
 }
 
+// markInferred records on an already-added component that its version was
+// derived from the image tag rather than read from build info. The note travels
+// into the analysis phase through Component.Extra so every finding for the
+// component can carry the provenance as evidence.
+func (g *grouper) markInferred(module, version, note string) {
+	if c, ok := g.byKey[module+"@"+version]; ok {
+		c.Extra.(*state).inferredNote = note
+	}
+}
+
 // wantedModules resolves subjects to the module paths to look for, and reports
 // separately whether one of them asked for everything.
 //
@@ -321,7 +407,19 @@ func (p *Plugin) AnalyzeImage(ctx context.Context, img *target.Image, items []ec
 				logf:      p.Logf,
 			}
 			for _, req := range requests {
-				out = append(out, evaluate(ctx, ec, req.ID, req.Advisory))
+				f := evaluate(ctx, ec, req.ID, req.Advisory)
+				if st.inferredNote != "" {
+					// The version this finding was decided against was recovered
+					// from the image tag, not read from the binary. Recording it
+					// as evidence keeps the heuristic honest: a reader sees the
+					// inference and its source rather than trusting a version
+					// that was never in the artifact.
+					f.Evidence = append(f.Evidence, ecosystem.Evidence{
+						Origin: "image-tag-version",
+						Detail: st.inferredNote,
+					})
+				}
+				out = append(out, f)
 			}
 		}
 	}

internal/ecosystem/golang/golang_test.go

@@ -143,6 +143,90 @@ func fakeBinary(path string, deps map[string]string) binscan.Binary {
 	return binscan.Binary{Path: path, Info: info}
 }
 
+// mainVersionBinary is a binary whose own main module carries the given path and
+// version, used to exercise the "(devel)" main-module fallback.
+func mainVersionBinary(path, mainPath, mainVersion string) binscan.Binary {
+	return binscan.Binary{Path: path, Info: &buildinfo.BuildInfo{
+		Main:      debug.Module{Path: mainPath, Version: mainVersion},
+		GoVersion: "go1.24.0",
+	}}
+}
+
+// mainComponent returns the component for module out of an inventory, or nil.
+func mainComponent(comps []ecosystem.Component, module string) *ecosystem.Component {
+	for i := range comps {
+		if comps[i].Name == module {
+			return &comps[i]
+		}
+	}
+	return nil
+}
+
+func TestGroupAllInfersMainVersionFromImageTag(t *testing.T) {
+	const root = "/tmp/extract"
+	const mod = "github.com/k3s-io/k3s"
+	bins := []binscan.Binary{mainVersionBinary(root+"/bin/k3s", mod, "(devel)")}
+
+	p := New(Options{Image: "docker.io/rancher/k3s:v1.36.3-k3s1"})
+	comps := p.groupAll(root, bins)
+
+	c := mainComponent(comps, mod)
+	if c == nil {
+		t.Fatalf("main module %s missing from inventory", mod)
+	}
+	if c.Version != "v1.36.3+k3s1" {
+		t.Errorf("version = %q, want v1.36.3+k3s1 (inferred from image tag)", c.Version)
+	}
+	note := c.Extra.(*state).inferredNote
+	if note == "" || !strings.Contains(note, "v1.36.3-k3s1") {
+		t.Errorf("inferredNote = %q, want a provenance note citing the image tag", note)
+	}
+}
+
+func TestGroupAllKeepsDevelWhenTagNotUsable(t *testing.T) {
+	const root = "/tmp/extract"
+	const mod = "github.com/k3s-io/k3s"
+	bins := []binscan.Binary{mainVersionBinary(root+"/bin/k3s", mod, "(devel)")}
+
+	// A floating tag is not a version: inference is refused and the original
+	// "(devel)" is kept, which over-reports rather than guessing.
+	p := New(Options{Image: "docker.io/rancher/k3s:latest"})
+	comps := p.groupAll(root, bins)
+
+	c := mainComponent(comps, mod)
+	if c == nil {
+		t.Fatalf("main module %s missing from inventory", mod)
+	}
+	if c.Version != "(devel)" {
+		t.Errorf("version = %q, want (devel) unchanged", c.Version)
+	}
+	if note := c.Extra.(*state).inferredNote; note != "" {
+		t.Errorf("inferredNote = %q, want empty (nothing was inferred)", note)
+	}
+}
+
+func TestGroupAllRealMainVersionIsUntouched(t *testing.T) {
+	const root = "/tmp/extract"
+	const mod = "example.com/app"
+	bins := []binscan.Binary{mainVersionBinary(root+"/bin/app", mod, "v1.0.0")}
+
+	// Even with an image tag present, a main module that already has a real
+	// version must not be overwritten by the tag.
+	p := New(Options{Image: "example.com/app:v9.9.9"})
+	comps := p.groupAll(root, bins)
+
+	c := mainComponent(comps, mod)
+	if c == nil {
+		t.Fatalf("main module %s missing from inventory", mod)
+	}
+	if c.Version != "v1.0.0" {
+		t.Errorf("version = %q, want v1.0.0 (build-info version preserved)", c.Version)
+	}
+	if note := c.Extra.(*state).inferredNote; note != "" {
+		t.Errorf("inferredNote = %q, want empty", note)
+	}
+}
+
 func TestGroupComponents(t *testing.T) {
 	const root = "/tmp/extract"
 	bins := []binscan.Binary{
@@ -239,6 +323,47 @@ func TestGroupAllEnumeratesEveryLinkedModule(t *testing.T) {
 	}
 }
 
+func TestAnalyzeImageAttachesInferredVersionEvidence(t *testing.T) {
+	dir := t.TempDir()
+	binPath := filepath.Join(dir, "k3s")
+	if err := os.WriteFile(binPath, []byte("not a real elf, just needs to be readable"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	const mod = "github.com/k3s-io/k3s"
+	const note = "version not in build info (reported (devel)); inferred from image tag \"v1.36.3-k3s1\""
+	comp := ecosystem.Component{
+		Ecosystem: "Go",
+		Name:      mod,
+		Version:   "v1.36.3+k3s1",
+		PURL:      purl(mod, "v1.36.3+k3s1"),
+		Extra: &state{
+			binaries:     []binary{{path: binPath, rel: "/bin/k3s", main: mod}},
+			inferredNote: note,
+		},
+	}
+	// A requested id with no advisory: evaluate returns undetermined without
+	// needing a real Go binary, and we only care that provenance is attached.
+	item := ecosystem.WorkItem{Component: comp, Requested: []string{"CVE-2024-0001"}, Targeted: true}
+
+	findings, err := New(Options{}).AnalyzeImage(context.Background(), &target.Image{}, []ecosystem.WorkItem{item})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(findings) != 1 {
+		t.Fatalf("got %d findings, want 1", len(findings))
+	}
+	var found bool
+	for _, e := range findings[0].Evidence {
+		if e.Origin == "image-tag-version" && e.Detail == note {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("finding is missing image-tag-version provenance evidence: %+v", findings[0].Evidence)
+	}
+}
+
 func TestGroupAllSharesOneComponentAcrossBinaries(t *testing.T) {
 	const root = "/tmp/extract"
 	bins := []binscan.Binary{