Expose formula patches in the JSON API (and optionally annotate them with CVEs)

[andrew]

While working on brew-vulns I wanted to find every formula in homebrew-core that ships with a patch applied. There's currently no way to get this from brew info --json or formulae.brew.sh; Formula#to_hash doesn't serialise patchlist, and formulae loaded from the API have an empty patchlist. The only options today are grepping a homebrew-core checkout for patch do / patch :DATA, or running brew ruby with HOMEBREW_NO_INSTALL_FROM_API=1 and walking Formula.all. Roughly 860 of the ~8400 core formulae currently carry at least one patch.

1. Add a patches key to Formula#to_hash. Something like:

"patches": [
  { "url": "https://.../fix.patch", "sha256": "...", "strip": "p1" },
  { "data": true, "strip": "p1" }
]

This would let brew-vulns and other downstream tooling (SBOM generators, OSV importers, distro-comparison tools) see which packages Homebrew has modified relative to the upstream tarball, without needing a full core checkout.

2. Allow patches to declare which CVEs they address. Right now this lives in comments: glibc applies a Debian patch tarball with apply "patches/any/CVE-2024-2961.patch", libquicktime has # Fix CVE-2016-2399 above its patch do block. Only about eight formulae mention a CVE at all, and where the data exists it can't be read programmatically. A small DSL addition would cover it:

patch do
  url "https://deb.debian.org/.../libquicktime_1.2.4-12.debian.tar.xz"
  sha256 "..."
  fixes "CVE-2016-2399", "CVE-2017-9122"
  apply "patches/CVE-2016-2399.patch", "patches/CVE-2017-9122_et_al.patch"
end

which would surface in the JSON as "fixes": ["CVE-2016-2399", "CVE-2017-9122"] on each patch entry. This is the same shape Fedora uses in spec changelogs and Alpine uses in secfixes: blocks, and it would let vulnerability scanners report "yes this version is affected upstream, but Homebrew's bottle is patched" instead of raising a false positive. Related: in #6826 @SMillerDev suggested handling CVEs at the audit layer; structured patch data would give that audit something to read.

I'm happy to put together the PR for part 1 if there's appetite; part 2 is more of a policy question about whether maintainers want to track that data in formulae at all.

[MikeMcQuaid]

Yeh, these both make sense to me! PRs welcome.

[MikeMcQuaid]

Could maybe even do some magic for 2 which infers it from standard file formats like those e.g. Debian uses.

[andrew]

PR for part one: Homebrew/brew#22459

[andrew]

22459 merged, patch data now in the api:

• 8,381 formulae all have the patches key
• 809 formulae have at least one patch
• 1,191 total patches: 972 external (with url/sha256), 219 embedded END/DATA patches (just strip, no url)

Example from llvm:

  "patches": [
    {
      "strip": "p1",
      "url": "https://github.com/llvm/llvm-project/compare/1381ad...f89e9.diff",
      "sha256": "f6dafd762737eb79761ab7ef814a9fc802ec4bb8d20f46691f07178053b0eb36"
    } 
  ]

next up, part 2

[andrew]

Part 2 patch to add fixes support: Homebrew/brew#22466

[andrew]

PR for part two: Homebrew/brew#22466

Ended up going with resolves rather than fixes, and added an optional type, so both the DSL and the JSON output match CycloneDX pedigree.patches terminology:

patch do
  url "https://deb.debian.org/.../libquicktime_1.2.4-12.debian.tar.xz"
  sha256 "..."
  type :backport
  resolves "CVE-2016-2399", "CVE-2017-9122"
  apply "patches/CVE-2016-2399.patch", "patches/CVE-2017-9122_et_al.patch"
end

type is one of :unofficial / :monkey / :backport / :cherry_pick. In the JSON API this comes out as:

"type": "backport",
"resolves": [
  {"type": "security", "id": "CVE-2016-2399"},
  {"type": "security", "id": "CVE-2017-9122"}
]

The inference Mike suggested is in there too: CVE ids found in the patch url, apply paths or local file path are merged into resolves automatically, so glibc, unzip, zip and libquicktime get populated with no formula changes.

[andrew]

For backfilling the existing 1,191 patches across 809 formulae, here's where the data sits today and where resolves can be mined from.

By patch kind

kind	count	likely type
external (has url)	972	varies, see below
embedded __END__ / string	218	:unofficial (almost all build fixes)
local file	1	:unofficial

External patches by source (n=972)

source	count	likely type	CVE lookup
github.com/*/commit/	497	:backport / :cherry_pick	OSV {"commit": sha} query + gh api commit message grep
raw.githubusercontent.com/Homebrew/homebrew-core/	272	:unofficial	git log -S<url> in homebrew-core → adding PR title/body
other distro ports trees (freebsd, macports, gentoo, nixpkgs, void, openbsd, netbsd)	48	mixed	download patch body, grep; FreeBSD VuXML for freebsd-ports
Debian/Ubuntu (deb.debian.org, salsa, sources, archive.ubuntu)	42	:backport	DEP-3 patch headers + Debian security-tracker by source package
gitlab.*/commit/	29	:backport / :cherry_pick	commit message grep
src.fedoraproject.org	12	:backport	patch body; Fedora changelog
other raw.githubusercontent.com	10	mixed	download + grep
gists	8	:unofficial	homebrew-core blame
github.com/*/compare/	7	:backport	range-diff; treat as multiple commits for OSV
Arch / Gentoo gitweb	7	mixed	patch body
everything else	40	mixed	download + grep

Already inferable with no formula changes (once #22466 lands): 25 unique CVEs across glibc, unzip, zip, libquicktime from apply filenames; 1 from a patch URL.

The 497 GitHub commit patches are the big prize for automation since OSV indexes fix-commits → CVEs directly. The 272 Homebrew-hosted raw patches are almost entirely macOS/compiler build fixes and will mostly end up with no resolves and type :unofficial.

[andrew]

Homebrew/brew#22466 has been merged and shipped in homebrew 6.0.4 now, I've rebased Homebrew/homebrew-core#285534, if this is looking good I can start to roll through more and more of the formula with patches to add them in

[MikeMcQuaid]

@andrew Yeh,when that's merged I'd be fine with other big PR(s) that just add as many as you want and we'll mark them as "syntax only" so we don't need to do the whole build shit.

[andrew]

Wired this up on the brew-vulns side in Homebrew/homebrew-brew-vulns#92: OSV results whose id or alias matches a formula's patches[].resolves are treated as already fixed (listed separately, excluded from the exit code and SARIF/CycloneDX). --no-ignore-patches opts out.

Testing it against the four formulae from Homebrew/homebrew-core#285534 turned up an OSV coverage gap worth noting. Most CVE records in OSV are auto-converted from NVD and have no affected[].package or ranges data — you can GET /vulns/CVE-2024-2961 but you cannot discover it by querying a repo URL or package. Of the ten CVEs glibc's patches resolve, only CVE-2025-15281 has a proper GIT-ecosystem entry against https://sourceware.org/git/glibc.git; the other nine and all of libquicktime's are bare NVD imports. So even with perfect repo-URL extraction (Homebrew/homebrew-brew-vulns#93), a scanner querying by upstream repo would only ever get one hit there.

That points at a possible third part to this thread: now that formulae carry structured resolves + patch url data, Homebrew has enough to emit OSV records itself — either contributing GIT-ecosystem ranges back upstream where missing, or publishing a Homebrew ecosystem feed that maps pkg:brew/<formula>@<version> to the CVEs it does and does not ship with. The latter would let any OSV-backed scanner answer "is this Homebrew bottle affected" directly rather than going via the upstream repo, and it falls out of the same brew info --json=v2 --eval-all data #92 already reads. Not proposing it yet, just flagging that the data is now sufficient.

[MikeMcQuaid]

That points at a possible third part to this thread: now that formulae carry structured resolves + patch url data, Homebrew has enough to emit OSV records itself — either contributing GIT-ecosystem ranges back upstream where missing, or publishing a Homebrew ecosystem feed that maps pkg:brew/<formula>@<version> to the CVEs it does and does not ship with. The latter would let any OSV-backed scanner answer "is this Homebrew bottle affected" directly rather than going via the upstream repo, and it falls out of the same brew info --json=v2 --eval-all data #92 already reads. Not proposing it yet, just flagging that the data is now sufficient.

This seems like a good idea 👍🏻

[p-linnane]

Picking up the backfill that Homebrew/homebrew-core#285534 floats for the remaining ~935 patch blocks (scripted by URL heuristic): I pulled the API patch data to scope it and it gave me pause. I sampled 59 of the upstream-commit patches and zero reference a CVE. Core patches are mostly build/portability fixes, not security backports, so a URL/filename heuristic finds very little beyond the cases already covered (the CVE-named patchsets like unzip that inference catches, plus the four you annotated by hand). And of the ~10 formulae that mention a CVE in source, most are outstanding/unfixed CVEs or version rationale (avahi, openslp, sylpheed, opentsdb), so a heuristic that greps for CVE strings risks injecting false "patched" signals.

So rather than scripting blind, I'd make it scanner-driven: run brew vulns over core with the #92 suppression branch, treat each reported CVE as a candidate, and add resolves only where a shipped patch actually fixes it, then re-run to confirm it suppresses. Every annotation removes a real false positive, and we never annotate a CVE OSV doesn't report against the bottled version. Main gate is #93 forge coverage, since glibc/libquicktime aren't queryable yet.

I can drop a per-patch inventory into a tracking issue as the working set and open the first batch from the scanner output once #92 / #93 land. Sound right, or do you still want the URL-heuristic sweep as a first pass and treat the scanner run as validation on top?

[andrew]

Sounds good to me

[andrew]

Status update on the three parts.

Part 1/2 (patches in JSON, resolves DSL): shipped in Homebrew 6.0.4. brew-vulns 0.4.0 (released today) reads patches[].resolves and suppresses matching OSV results.

Backfill (Homebrew/homebrew-brew-vulns#95): ran the scanner-driven pass over the 484 patched formulae that are currently queryable. 9 had OSV hits; every shipped patch turned out to be a build/portability fix, so zero new resolves annotations from that set. A wider sweep (OSV-by-commit on 486 GitHub-commit patches, DEP-3 headers on Debian patch tarballs, keyword grep over local Patches/) found one more: nvi → CVE-2015-2305 (Homebrew/homebrew-core#290337). The remaining annotated formulae (glibc, unzip, zip, lrzsz, libquicktime) can't be validated via repo query because their CVEs are bare NVD imports in OSV with no package data.

Part 3 (Homebrew OSV feed): prototyped. Homebrew/homebrew-brew-vulns#99 adds brew vulns --osv-export which emits OSV-schema records under a Homebrew ecosystem with BREW-<formula>-<CVE> ids and pkg:brew/ purls, one per resolved CVE. Demo repository at https://github.com/andrew/homebrew-advisory-database with the current 26 records, schema validation in CI, and a daily regeneration workflow. Records validate against ossf/osv-schema apart from the BREW prefix and Homebrew ecosystem not being registered yet, which is what the onboarding PR adds.

Plan is to transfer that repo into the Homebrew org once it's settled, then open the osv.dev new-data-source request and the ossf/osv-schema registration PR from there.

[andrew]

Quick update since the last one, mostly on part 3.

pkg:brew is now a registered purl type (package-url/purl-spec#796, merged 9 July). Off the back of that I've opened ossf/osv-schema#576 to register the Homebrew ecosystem and BREW- prefix — didn't wait on the org transfer since TBD source URLs are the norm there (vcpkg and Azure Linux both landed that way). --osv-export is on brew-vulns main via Homebrew/homebrew-brew-vulns#99 and its records now validate cleanly against that schema branch.

Backfill: #97 (homepage fallback) merged, which made 20 of the previously-skipped 314 patched formulae queryable. Re-scan found zero OSV hits for any of them, so still one net annotation (nvi, merged as Homebrew/homebrew-core#290337). Details on Homebrew/homebrew-brew-vulns#95. The homepage fallback also flagged a data error in core: libart's homepage points at an unrelated project — fix in Homebrew/homebrew-core#290393.

Next: transfer andrew/homebrew-advisory-database to the Homebrew org, then file the google/osv.dev issue to get the ecosystem plumbed (their process is issue-first). The purl mapping there is trivial; the version comparator will need to handle _N revision suffixes and Homebrew's non-semver version strings.

[MikeMcQuaid]

Next: transfer andrew/homebrew-advisory-database to the Homebrew org, then file the google/osv.dev issue to get the ecosystem plumbed (their process is issue-first). The purl mapping there is trivial; the version comparator will need to handle _N revision suffixes and Homebrew's non-semver version strings.

@andrew I'm game to transfer this over but would love, as much as possible, to consolidate all of this into existing repos. Desired end state is that all of this code and/or data lives in the combo between formulae.brew.sh, Homebrew/brew, Homebrew/homebrew-core (and Homebrew/homebrew-cask if you're handling those)

[andrew]

absolutely, I'm fine with whatever layout you'd like, I've just been working with what i have creds for