Skip to content

feat(golang): add extended-stdlib scope and module patterns for symbol capture - #5154

Merged
wagoodman merged 3 commits into
mainfrom
expand-golang-symbol-scopes
Aug 7, 2026
Merged

feat(golang): add extended-stdlib scope and module patterns for symbol capture#5154
wagoodman merged 3 commits into
mainfrom
expand-golang-symbol-scopes

Conversation

@wagoodman

@wagoodman wagoodman commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

golang.capture-symbols decides how much symbol data lands in the SBOM for grype's reachability analysis. It's none, stdlib, or all today, and the useful middle is missing: stdlib stops at the standard library, all multiplies SBOM size.

A new extended-stdlib configurable covers stdlib plus everything under golang.org/x/:

golang:
  capture-symbols: extended-stdlib

Also, a new capture-symbols-modules configurable for modules that are noisy in your binaries but not everyone's. It's unioned with whatever the scope selects, so it only ever widens:

golang:
  capture-symbols: extended-stdlib
  capture-symbols-modules:
    - github.com/klauspost/**

Patterns are standard doublestar globs, matched against the module path with any trailing major version suffix taken off, so a config does not quietly stop covering a module the day it bumps a major version:

golang:
  capture-symbols-modules:
    - github.com/klauspost/*            # every klauspost module, any major version
    - github.com/klauspost/**           # the same, plus anything nested under them
    - k8s.io/client-go                  # that module, any major version
    - github.com/klauspost/compress/v2  # v2 alone

A suffix is part of a module's path but not part of its identity, hence the asymmetry: a pattern that does not mention one covers every major version, and a pattern that does covers only that one. Only a trailing suffix counts, which is Go's own rule, so in github.com/anchore/syft/v2/thing the v2 stays an ordinary path element and github.com/anchore/**/thing is what reaches it. module.SplitPathVersion from golang.org/x/mod does the splitting, so gopkg.in's .vN form works and /v0 and /v1 are correctly not suffixes.

Ordering is none < stdlib < extended-stdlib < all. The existing three values and the none default are unchanged, and the module list is inert under none. Presets compile into glob lists internally, so a single matcher answers "does this module get symbols" instead of a preset branch sitting next to a separate glob branch.

An unrecognized capture-symbols value still falls back to none, but warns now instead of doing it silently. A malformed module pattern warns and gets skipped.

One thing worth a look beyond the feature: the Symbols field description in the JSON schema was wrong after this (it claimed only all and stdlib populate anything), and that description lives in the already-published 16.1.10. Rather than bump a version for a sentence, 16.1.10 is amended in place and schema/json/README.md grows an explicit exception for description-only changes: descriptions only, no shape change of any kind, $id unchanged. Anything else still needs a bump. Happy to split that into its own PR if you'd rather review the policy separately.

…ol capture

`golang.capture-symbols` decides how much symbol data lands in the SBOM for grype's reachability analysis. It's `none`, `stdlib`, or `all` today, and the useful middle is missing: `stdlib` stops at the standard library, `all` multiplies SBOM size.

A new `extended-stdlib` configurable covers stdlib plus everything under `golang.org/x/`:

```yaml
golang:
  capture-symbols: extended-stdlib
```

Also, a new `capture-symbols-include` configurable for modules that are noisy in your binaries but not everyone's. It's unioned with whatever the scope selects, so it only ever widens:

```yaml
golang:
  capture-symbols: extended-stdlib
  capture-symbols-include:
    - github.com/klauspost/**
```

Patterns are standard doublestar globs, which matters because module paths carry `/v2`-style suffixes:

```yaml
golang:
  capture-symbols-include:
    - github.com/klauspost/*     # compress, but not compress/v2
    - github.com/klauspost/**    # both
    - k8s.io/client-go           # exact match only
```

Ordering is `none` < `stdlib` < `extended-stdlib` < `all`. The existing three values
and the `none` default are unchanged, and the include list is inert under `none`.
Presets compile into glob lists internally, so a single matcher answers "does this
module get symbols" instead of a preset branch sitting next to a separate glob branch.

An unrecognized `capture-symbols` value still falls back to `none`, but warns now
instead of doing it silently. A malformed include pattern warns and gets skipped.

One thing worth a look beyond the feature: the `Symbols` field description in the JSON
schema was wrong after this (it claimed only `all` and `stdlib` populate anything), and
that description lives in the already-published `16.1.10`. Rather than bump a version for
a sentence, `16.1.10` is amended in place and `schema/json/README.md` grows an explicit
exception for description-only changes: descriptions only, no shape change of any kind,
`$id` unchanged. Anything else still needs a bump. Happy to split that into its own PR if
you'd rather review the policy separately.

Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>
@wagoodman wagoodman added the enhancement New feature or request label Aug 6, 2026
@oss-housekeeper

This comment was marked as resolved.

@wagoodman
wagoodman marked this pull request as ready for review August 6, 2026 15:11
@wagoodman
wagoodman requested a review from a team August 6, 2026 15:11

@kzantow kzantow left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is generally good, but left a note about the naming and ** vs *

Comment thread cmd/syft/internal/options/golang.go
…odules

The key's entries are go module paths, and `-include` sitting next to `capture-symbols` reads as plausibly taking symbol or package names instead. Those spellings parse and match nothing, which is quieter than the confusion `-include` was picked to avoid, so the name now says what the list holds.

`golang.CatalogerConfig.CaptureSymbolsModules` and `WithCaptureSymbolsModules` rename with it. Nothing behavioral changes; the key is new in this PR so there is no compatibility surface.

Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>
@wagoodman wagoodman changed the title feat(golang): add extended-stdlib scope and include patterns for symbol capture feat(golang): add extended-stdlib scope and module patterns for symbol capture Aug 6, 2026
@wagoodman wagoodman self-assigned this Aug 6, 2026
@wagoodman wagoodman added this to OSS Aug 6, 2026
@wagoodman wagoodman moved this to In Progress in OSS Aug 6, 2026

@kzantow kzantow left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM 👍

@wagoodman

Copy link
Copy Markdown
Contributor Author

I'll wait for the unicorns to disperse...

…ixes

`github.com/anchore/*` covered `github.com/anchore/syft` and silently stopped covering it the day it became `github.com/anchore/syft/v2`. The config keeps parsing, nothing warns, and symbols quietly go missing from the SBOM. Exact paths had the same hole: `github.com/klauspost/compress` did not cover `compress/v2` either, so no spelling short of `**` survived a major bump.

A major version suffix is part of a module's path but not part of its identity, so patterns are now matched against the module path both with and without it, using `module.SplitPathVersion` from `golang.org/x/mod` (already a direct dep, already used in this package for `PseudoVersion`).

```yaml
golang:
  capture-symbols-modules:
    - github.com/klauspost/*          # compress and compress/v2
    - github.com/klauspost/compress   # same module at every major version
    - github.com/klauspost/compress/v2  # v2 alone
```

Only a trailing suffix is a version, which is Go's own rule. In `github.com/anchore/syft/v2/thing` the `v2` is an ordinary path element naming a major subdirectory a nested module lives in, so it stays literal and `github.com/anchore/**/thing` is how you reach it. `/v0` and `/v1` are not valid suffixes and are left alone.

Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>
@wagoodman
wagoodman force-pushed the expand-golang-symbol-scopes branch from 34abea0 to 2ac071f Compare August 7, 2026 12:27
@wagoodman
wagoodman enabled auto-merge (squash) August 7, 2026 12:28
@wagoodman wagoodman moved this from In Progress to In Review in OSS Aug 7, 2026
@wagoodman
wagoodman merged commit da745b1 into main Aug 7, 2026
15 checks passed
@wagoodman
wagoodman deleted the expand-golang-symbol-scopes branch August 7, 2026 12:44
@github-project-automation github-project-automation Bot moved this from In Review to Done in OSS Aug 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants