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

* feat(golang): add extended-stdlib scope and include patterns for symbol 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> * refactor(golang): rename capture-symbols-include to capture-symbols-modules 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> * feat(golang): match capture-symbols-modules across major version suffixes `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> --------- Signed-off-by: Alex Goodman <wagoodman@users.noreply.github.com>
2026-11-01 15:06:36 +01:00 · 2026-08-07 12:44:42 +00:00
parent 68da404bd7
commit da745b13e8
16 changed files with 648 additions and 28 deletions
@@ -35,3 +35,24 @@ Create the new schema by running `make generate-json-schema` from the root of th
 - If there is an existing schema for the given version and the new schema **does not** match the existing schema, an error is shown indicating to increment the version appropriately (see the "Versioning" section)

 ***Note: never delete a JSON schema and never change an existing JSON schema once it has been published in a release!*** Only add new schemas with a newly incremented version. All previous schema files must be stored in the `schema/json/` directory.
+
+### Exception: `description`-only corrections
+
+A published schema may be amended in place for one narrow case: the change touches only `description` text and leaves the data shape identical. Descriptions are documentation carried alongside the schema rather than constraints a validator evaluates, so correcting one cannot invalidate a document that already validated against that version. Minting a new version instead would leave the old one permanently describing the tool incorrectly, and spend a version number on no semantic change.
+
+This applies when **every** one of the following holds:
+
+- the only differences are `description` values
+- no field, type, enum, `required` entry, or `$ref` is added, removed, or altered
+- the `$id` version is unchanged
+
+Anything else, including adding a field that happens to be optional, is a schema change and needs a version bump per the "Versioning" section above.
+
+The generator blocks an in-place edit by design, since it refuses to overwrite a file that differs from what it would produce. To amend one, delete the schema file and regenerate so it is rewritten from the current Go doc comments:
+
+```bash
+rm schema/json/schema-$VERSION.json
+make generate-json-schema
+```
+
+The result is byte-identical to what the generator produces, so do not hand-edit the JSON. Re-running `make generate-json-schema` afterwards should report `No change to the existing schema!`, and `make check-json-schema-drift` should pass. Confirm with `git diff` that the only changes are the intended description lines.
@@ -1662,7 +1662,7 @@
            "type": "array"
          },
          "type": "object",
-          "description": "Symbols are the function symbols from this module that are compiled into the binary, extracted from\nthe binary symbol table (pclntab) and grouped by the import path of the package that owns them. Each\nvalue is the sorted, deduplicated list of symbol names local to that package, i.e. with the import\npath prefix stripped (e.g. import path \"github.com/foo/bar\" -\u003e \"(*Type).Method\"). The fully qualified\nname is the import path, a \".\", and the local name. One exception: the binary's main package appears\nunder the key \"main\" (the name the linker assigns), not its original source import path, which is not\nrecoverable from the binary. Populated only when the golang cataloger's capture-symbols scope covers\nthis package: the \"all\" scope populates every module package plus the synthetic stdlib package, while\nthe \"stdlib\" scope populates only the stdlib package."
+          "description": "Symbols are the function symbols from this module that are compiled into the binary, extracted from\nthe binary symbol table (pclntab) and grouped by the import path of the package that owns them. Each\nvalue is the sorted, deduplicated list of symbol names local to that package, i.e. with the import\npath prefix stripped (e.g. import path \"github.com/foo/bar\" -\u003e \"(*Type).Method\"). The fully qualified\nname is the import path, a \".\", and the local name. One exception: the binary's main package appears\nunder the key \"main\" (the name the linker assigns), not its original source import path, which is not\nrecoverable from the binary. Populated only when the golang cataloger's capture-symbols scope covers\nthis package: the \"all\" scope populates every module package plus the synthetic stdlib package, the\n\"extended-stdlib\" scope populates the stdlib package plus every module under golang.org/x/, and the\n\"stdlib\" scope populates only the stdlib package. The capture-symbols-modules glob patterns populate\nany additional modules they match."
        }
      },
      "type": "object",
@@ -1662,7 +1662,7 @@
            "type": "array"
          },
          "type": "object",
-          "description": "Symbols are the function symbols from this module that are compiled into the binary, extracted from\nthe binary symbol table (pclntab) and grouped by the import path of the package that owns them. Each\nvalue is the sorted, deduplicated list of symbol names local to that package, i.e. with the import\npath prefix stripped (e.g. import path \"github.com/foo/bar\" -\u003e \"(*Type).Method\"). The fully qualified\nname is the import path, a \".\", and the local name. One exception: the binary's main package appears\nunder the key \"main\" (the name the linker assigns), not its original source import path, which is not\nrecoverable from the binary. Populated only when the golang cataloger's capture-symbols scope covers\nthis package: the \"all\" scope populates every module package plus the synthetic stdlib package, while\nthe \"stdlib\" scope populates only the stdlib package."
+          "description": "Symbols are the function symbols from this module that are compiled into the binary, extracted from\nthe binary symbol table (pclntab) and grouped by the import path of the package that owns them. Each\nvalue is the sorted, deduplicated list of symbol names local to that package, i.e. with the import\npath prefix stripped (e.g. import path \"github.com/foo/bar\" -\u003e \"(*Type).Method\"). The fully qualified\nname is the import path, a \".\", and the local name. One exception: the binary's main package appears\nunder the key \"main\" (the name the linker assigns), not its original source import path, which is not\nrecoverable from the binary. Populated only when the golang cataloger's capture-symbols scope covers\nthis package: the \"all\" scope populates every module package plus the synthetic stdlib package, the\n\"extended-stdlib\" scope populates the stdlib package plus every module under golang.org/x/, and the\n\"stdlib\" scope populates only the stdlib package. The capture-symbols-modules glob patterns populate\nany additional modules they match."
        }
      },
      "type": "object",