Skip to content

Apk upstream matcher #3256

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
vaikas wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Apk upstream matcher #3256

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bf83e61
feat: Add ability to skip origin package lookups.
vaikas Feb 25, 2026
635d82e
feat: Add a flag to have APK packages to take advantage of OSV based …
vaikas Feb 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions cmd/grype/cli/commands/root.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import (
"github.com/anchore/grype/grype/match"
"github.com/anchore/grype/grype/matcher"
"github.com/anchore/grype/grype/matcher/dotnet"
"github.com/anchore/grype/grype/matcher/apk"
"github.com/anchore/grype/grype/matcher/dpkg"
"github.com/anchore/grype/grype/matcher/golang"
"github.com/anchore/grype/grype/matcher/hex"
Expand Down Expand Up @@ -388,6 +389,9 @@ func getMatcherConfig(opts *options.Grype) matcher.Config {
MissingEpochStrategy: opts.Match.Rpm.MissingEpochStrategy,
UseCPEsForEOL: opts.Match.Rpm.UseCPEsForEOL,
},
Apk: apk.MatcherConfig{
UseUpstreamMatcher: opts.Match.Apk.UseUpstreamMatcher,
},
}
}

Expand Down
8 changes: 8 additions & 0 deletions cmd/grype/cli/options/match.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ type matchConfig struct {
Stock matcherConfig `yaml:"stock" json:"stock" mapstructure:"stock"` // settings for the default/stock matcher
Dpkg dpkgConfig `yaml:"dpkg" json:"dpkg" mapstructure:"dpkg"` // settings for the dpkg matcher
Rpm rpmConfig `yaml:"rpm" json:"rpm" mapstructure:"rpm"` // settings for the rpm matcher
Apk apkConfig `yaml:"apk" json:"apk" mapstructure:"apk"` // settings for the apk matcher
}

var _ interface {
Expand Down Expand Up @@ -88,6 +89,11 @@ type rpmConfig struct {
UseCPEsForEOL bool `yaml:"use-cpes-for-eol" json:"use-cpes-for-eol" mapstructure:"use-cpes-for-eol"` // if CPEs should be used for EOL distro packages
}

// apkConfig contains configuration for the APK matcher.
type apkConfig struct {
UseUpstreamMatcher bool `yaml:"use-upstream-matcher" json:"use-upstream-matcher" mapstructure:"use-upstream-matcher"` // if the upstream/origin package name should be used during matching
}

func defaultGolangConfig() golangConfig {
return golangConfig{
matcherConfig: matcherConfig{
Expand Down Expand Up @@ -130,6 +136,7 @@ func defaultMatchConfig() matchConfig {
Stock: useCpe,
Dpkg: defaultDpkgConfig(),
Rpm: defaultRpmConfig(),
Apk: apkConfig{UseUpstreamMatcher: true},
}
}

Expand Down Expand Up @@ -182,4 +189,5 @@ func (cfg *matchConfig) DescribeFields(descriptions clio.FieldDescriptionSet) {
eolCpeDescription := `use CPE matching for packages from end-of-life distributions`
descriptions.Add(&cfg.Dpkg.UseCPEsForEOL, eolCpeDescription)
descriptions.Add(&cfg.Rpm.UseCPEsForEOL, eolCpeDescription)
descriptions.Add(&cfg.Apk.UseUpstreamMatcher, `use the upstream/origin package name when matching APK vulnerabilities`)
}
92 changes: 67 additions & 25 deletions grype/matcher/apk/matcher.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import (
"errors"
"fmt"

"github.com/anchore/grype/grype/distro"
"github.com/anchore/grype/grype/match"
"github.com/anchore/grype/grype/matcher/internal"
"github.com/anchore/grype/grype/pkg"
Expand All @@ -23,7 +24,33 @@ var (
})
)

type Matcher struct{}
type MatcherConfig struct {
UseUpstreamMatcher bool
}

type Matcher struct {
cfg MatcherConfig
}

func NewApkMatcher(cfg MatcherConfig) *Matcher {
return &Matcher{cfg: cfg}
}

// useUpstreamForPackage returns whether origin/upstream lookups should be performed
// for this package. Alpine always requires upstream lookups regardless of the config flag —
// it uses secdb-style advisories keyed by origin package name, so disabling lookups would
// silently miss vulnerabilities. OSV-based distros with per-sub-package entries (e.g.
// Chainguard, Wolfi) can disable upstream lookups via UseUpstreamMatcher=false to avoid
// false positives from origin-level entries applying to unaffected sub-packages.
//
// TODO: if Alpine ever publishes per-sub-package OSV advisories, this hardcoded override
// should be removed and Alpine should respect the flag like other distros.
func (m *Matcher) useUpstreamForPackage(p pkg.Package) bool {
Copy link
Copy Markdown
Contributor

@willmurphyscode willmurphyscode Mar 17, 2026

Choose a reason for hiding this comment

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

I'd love to make this more data driven. It seems like the actual logic we want is closer to, "If p is from a distro where there is fix info for binary APKs (if that's the right term) and not just origin/upstream APKs (if that's the right term), then we don't need to search upstream."

There's some subtlety here too:

  • a vulnerability can be about p or p's upstream
  • a vulnerability can come from distro data or NVD data
  • a fix or NAK can be about p or p's upstream, but always comes from distro data
  • after feat: suppress GHSA matches on language packages in fixed APKs #3282 lands, we can emit ignore rules to suppress aliases of the vuln on owned paths, either about p or p's upstream or both

Is there an approach we could do where we have a precedence where evidence of fix takes precedence over evidence of vulnerability which takes precedence over a search miss, and if there's data about both p and p's upstream/origin, the specific data (p) takes precedence. For example:

  1. NVD has a vuln on the upstream, Wolfi OSV has a fix on p -> package is not vulnerable, specific fix
  2. NVD has a vuln on p, Wolfi OSV has a fix on p's upstream -> package is not vulnerable; distro claims it's generally patched
  3. NVD has a vuln on upstream, Wolfi OSV has not info on this CVE -> package is vulnerable
  4. etc

That way Grype does the best matching job it can given the data it has, rather than hard-coding heuristics for different distros (which is something we've done a lot of and would love to stop doing). What do you think @vaikas ?

Copy link
Copy Markdown
Author

@vaikas vaikas Mar 17, 2026

Choose a reason for hiding this comment

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

This does not directly answer your question, but hopefully gives a bit more context on what problem the change is meant to address.

So the current use of 'origin' (and I think in this context == 'upstream') is imho a bit wonky in this context. In the current context, it says that pkg-a and pkg-a-sub were built from the same source code. But for the vuln identification purposes I fail to see why they should be treated identically (today, IIUC), in that if I see a pkg-a-sub I automatically 'inherit' all the vulns for pkg-a.
Some examples where this is especially wonky, when there are things like:
pkg
pkg-dev [headers for example]
pkg-doc [docs for example]
pkg-compat [shell scripts for example]

In today's world, if we see pkg-doc it's treated as pkg-a which doesn't make any sense. For Chainguard, we track occurances of vulnerabilities at the artifact level (APK) vs. origin because it's lossy.

And sub-packages can have vulns that do not appear in the origin package, so need to surface that as well.

I'm happy to hop on a call since that might be a higher BW conversation 🤣

So, that was the driving motivation for this change.

Copy link
Copy Markdown
Contributor

@willmurphyscode willmurphyscode Mar 18, 2026

Choose a reason for hiding this comment

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

That makes a lot of sense. I agree that saying pkg-docs is vulnerable because pkg is vulnerable is silly. The reason this practice exists in Grype is that historically, distros and CVEs are published against the source/upstream/origin package, and we're using the granularity we have.

The thing I don't love about the config option approach is that it makes it the user's responsibility to figure out whether they're scanning an image whose distro's publisher publishes granular vulnerability and fix data, but that's a question about the state of grype's database more than its a question about the user's preferences. I'm not opposed to having a config (we often put in configs with behavior changes so that people can pin back to older grype behavior), but I would love for the default behavior to be smarter.

Maybe this is something that should (eventually?) be on Grype's metadata about vulnerability providers? Like the matcher asks the database, "Hey, Is Wolfi one of the ones where binary APKs have fix data, or one of the ones where everything is stuck to the source/upstream/origin package?" and behaves differently based on the answer?

I'd be happy to jump on a call. We have a Vuln Data Office Hours appointment link if you find a convenient time on there.

if p.Distro != nil && p.Distro.Type == distro.Alpine {
return true
}
return m.cfg.UseUpstreamMatcher
}

func (m *Matcher) PackageTypes() []syftPkg.Type {
return []syftPkg.Type{syftPkg.ApkPkg}
Expand All @@ -43,12 +70,19 @@ func (m *Matcher) Match(store vulnerability.Provider, p pkg.Package) ([]match.Ma
}
matches = append(matches, directMatches...)

// indirect matches, via package's origin package
indirectMatches, err := m.findMatchesForOriginPackage(store, p)
if err != nil {
return nil, nil, err
// For secdb-style advisories that lack per-sub-package granularity, vulnerabilities are
// keyed under the origin/source package name rather than the individual sub-package.
// This lookup propagates those matches to the installed sub-package. When using an OSV-based
// advisory that has per-sub-package entries (e.g. Chainguard/Wolfi), this can be disabled
// (UseUpstreamMatcher=false) to avoid false positives from origin-level entries applying to
// unaffected sub-packages. Alpine is always exempt — see useUpstreamForPackage.
if m.useUpstreamForPackage(p) {
indirectMatches, err := m.findMatchesForOriginPackage(store, p)
if err != nil {
return nil, nil, err
}
matches = append(matches, indirectMatches...)
}
matches = append(matches, indirectMatches...)

// APK sources are also able to NAK vulnerabilities, so we want to return these as explicit ignores in order
// to allow rules later to use these to ignore "the same" vulnerability found in "the same" locations
Expand All @@ -70,23 +104,29 @@ func (m *Matcher) cpeMatchesWithoutSecDBFixes(provider vulnerability.Provider, p

cpeMatchesByID := matchesByID(cpeMatches)

// remove cpe matches where there is an entry in the secDB for the particular package-vulnerability pairing, and the
// installed package version is >= the fixed in version for the secDB record.
// Suppress CPE matches that the distro advisory has already marked as fixed.
// When UseUpstreamMatcher is false we only consult the direct package's advisory here,
// not the origin's. This means a CPE match won't be suppressed based on an origin-level
// fix — a deliberate tradeoff: a sub-package with its own CPEs may produce a false
// positive if the origin advisory already has the fix and version numbers are shared.
// In practice this is uncommon since APK sub-packages rarely have independent CPEs in NVD.
secDBVulnerabilities, err := provider.FindVulnerabilities(
search.ByPackageName(p.Name),
search.ByDistro(*p.Distro))
if err != nil {
return nil, err
}

for _, upstreamPkg := range pkg.UpstreamPackages(p) {
secDBVulnerabilitiesForUpstream, err := provider.FindVulnerabilities(
search.ByPackageName(upstreamPkg.Name),
search.ByDistro(*upstreamPkg.Distro))
if err != nil {
return nil, err
if m.useUpstreamForPackage(p) {
for _, upstreamPkg := range pkg.UpstreamPackages(p) {
secDBVulnerabilitiesForUpstream, err := provider.FindVulnerabilities(
search.ByPackageName(upstreamPkg.Name),
search.ByDistro(*upstreamPkg.Distro))
if err != nil {
return nil, err
}
secDBVulnerabilities = append(secDBVulnerabilities, secDBVulnerabilitiesForUpstream...)
}
secDBVulnerabilities = append(secDBVulnerabilities, secDBVulnerabilitiesForUpstream...)
}

secDBVulnerabilitiesByID := vulnerabilitiesByID(secDBVulnerabilities)
Expand Down Expand Up @@ -235,17 +275,19 @@ func (m *Matcher) findNaksForPackage(provider vulnerability.Provider, p pkg.Pack
}

// append all the upstream naks
for _, upstreamPkg := range pkg.UpstreamPackages(p) {
upstreamNaks, err := provider.FindVulnerabilities(
search.ByDistro(*upstreamPkg.Distro),
search.ByPackageName(upstreamPkg.Name),
nakConstraint,
)
if err != nil {
return nil, err
}
if m.useUpstreamForPackage(p) {
for _, upstreamPkg := range pkg.UpstreamPackages(p) {
upstreamNaks, err := provider.FindVulnerabilities(
search.ByDistro(*upstreamPkg.Distro),
search.ByPackageName(upstreamPkg.Name),
nakConstraint,
)
if err != nil {
return nil, err
}

naks = append(naks, upstreamNaks...)
naks = append(naks, upstreamNaks...)
}
}

meta, ok := p.Metadata.(pkg.ApkMetadata)
Expand Down
Loading
Loading