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

[andrew]

Two updates.

Part 3: ossf/osv-schema#576 merged this morning, so Homebrew is now a registered OSV ecosystem with the BREW- id prefix. The records at andrew/homebrew-advisory-database now validate against upstream main rather than the PR branch. Next step is the google/osv.dev data-source issue and the org transfer of the advisory repo.

brew-vulns → brew: opened Homebrew/brew#23080 to move the scanner into brew itself as a built-in brew vulns command, per the plan in Homebrew/homebrew-brew-vulns#111. No new Gemfile entries; SARIF/CycloneDX output and CVSS v4.0 scoring are deferred to follow-ups to keep the first PR reviewable. Once that ships the tap becomes a deprecation stub and --osv-export moves with it.

[andrew]

Homebrew/brew#23080 merged this morning, so brew vulns is now a built-in command on main. It'll ship in the next tagged release; the tap is being deprecated in Homebrew/homebrew-brew-vulns#112 once that's out.

The advisory database has been transferred into the org as Homebrew/homebrew-advisory-database. Both upstream registrations are done: Homebrew ecosystem and BREW- prefix in ossf/osv-schema#576, pkg:brew purl type in package-url/purl-spec#796. Next step there is the osv.dev data-source request, which needs a Homebrew version comparator and pkg:brew handling in google/osv.dev first.

Two follow-up PRs to brew are open: Homebrew/brew#23103 restores the non-forge head-URL fallback so formulae like bash, go, and zsh are queried instead of skipped, and Homebrew/brew#23106 adds brew generate-vulns-advisories as the built-in replacement for the tap's --osv-export so the advisory database can regenerate without the gem (Homebrew/advisory-database#2 switches the workflow over once that lands).

Current advisory count is 32 records across 5 formulae (glibc, libquicktime, lrzsz, unzip, zip); 6 of those are new libquicktime CVEs picked up since the June 28 seed. The resolves backfill into homebrew-core is still the main lever for growing that.

[Bo98]

Next step there is the osv.dev data-source request, which needs a Homebrew version comparator and pkg:brew handling in google/osv.dev first.

What's the plan in regards to the fixed version tracking? I know right now it points to the latest but that's largely a placeholder I assume.

[andrew]

Yes, placeholder. The real boundary is the pkg_version where the resolving patch first landed in homebrew-core, which is derivable from git log -S on the formula file. Goes together with changing the daily job from wipe-and-rebuild to add-or-update so records don't drift or vanish when a patch is dropped from core (more on that in Homebrew/homebrew-brew-vulns#111). Neither built yet; on the list after Homebrew/brew#23106.

[Bo98]

There is a FormulaVersions API you can use, but yeah we probably want it so that after initial creation of the vulnerability in the database it stays fixed from then on as there's no guarantee older formula files remain readable by the current version of brew. It would allow us to manually override it as well if there's cases where a patch was incomplete and later rectified, or if we want to backdate some of the CVE fixes to their true fixed version (e.g. libquicktime was fixed in revision 4 rather than 5).

[MikeMcQuaid]

Yeh FormulaVersions worth poking at if you haven't already @andrew

[andrew]

Thanks, FormulaVersions is what I'll use for the initial derivation. And yes, the generator now preserves affected[].ranges from whatever's on disk, so a hand-corrected fixed (like libquicktime _4) sticks through subsequent runs. Ships in Homebrew/brew#23106.

[andrew]

brew vulns shipped in Homebrew 6.0.11, along with the follow-ups: Homebrew/brew#23103 (non-forge head-URL fallback), Homebrew/brew#23106 (brew generate-vulns-advisories), Homebrew/brew#23112 (generator merges into existing records instead of overwriting, so hand-corrected fixed boundaries stick and records persist after their annotation leaves core), and Homebrew/brew#23115 (FormulaVersions-derived initial fixed for new records; e.g. unzip CVE-2014-8139 → 6.0_6 where current is 6.0_8). The tap deprecation PR is ready at Homebrew/homebrew-brew-vulns#112.

The advisory repo is now Homebrew/advisory-database (renamed to drop the homebrew- prefix so setup-homebrew stops treating it as a tap in CI). It's set up as an accumulating store: CONTRIBUTING.md covers both the auto-generated path and direct curated PRs with a BREW-0000-0000 placeholder id, and the daily regenerate no longer wipes. The org ruleset on main needs PRs, so Homebrew/advisory-database#7 changes the workflow to open one; first run under the new setup produced 33 files (26 rewritten with published/database_specific, 6 new libquicktime CVEs, nvi newly picked up).

osv.dev onboarding: ossf/osv-schema#580 fills the BREW database URLs and version-ordering language; google/osv.dev#5659 is the data-source issue with a draft PR at google/osv.dev#5660 adding the Homebrew ecosystem comparator (a Python port of PkgVersion/Version#<=>) and the pkg:brew purl mapping.

[MikeMcQuaid]

Nice work @andrew and @p-linnane! Let's just make sure we get https://github.com/Homebrew/advisory-database fully cleaned up like a normal Homebrew repo (e.g. hooked up in https://github.com/Homebrew/.github/blob/main/.github/actions/sync/shared-config.rb https://github.com/Homebrew/.github/blob/main/.github/workflows/sync-shared-config.yml#L38) etc.

[kmarekspartz]

Hey all, I'm working on some related things.

My current focus: Homebrew/brew#23152

Also tracking google/oss-fuzz-vulns#51 and google/osv.dev#2353 which reduce the quality of the brew vulns output.

Lastly, I am trying a local patch to have brew generate SBOMs that can be checked against https://github.com/Homebrew/advisory-database.

commit dd71766e086df81825762a122a156b151a701b35
Author: Kyle Marek-Spartz <kyle.marek.spartz@gmail.com>
Date:   Tue Jul 21 13:47:43 2026 -0500

    sbom: add purl external references for sources

diff --git a/Library/Homebrew/sbom.rb b/Library/Homebrew/sbom.rb
index 1ca7d29245..b42c050e81 100644
--- a/Library/Homebrew/sbom.rb
+++ b/Library/Homebrew/sbom.rb
@@ -546,7 +546,13 @@ class SBOM
         licenseConcluded: assert_value(license),
         downloadLocation: source.url,
         copyrightText:    assert_value(nil),
-        externalRefs:     [],
+        externalRefs:     [
+          {
+            referenceCategory: "PACKAGE-MANAGER",
+            referenceLocator:  tap ? "pkg:brew/#{tap}/#{name}@#{spec_version}" : "pkg:brew/#{name}@#{spec_version}",
+            referenceType:     "purl",
+          },
+        ].compact,
         checksums:        [
           {
             algorithm:     "SHA256",

[andrew]

Update since 14 July.

Merged

• vulns: add advisory matcher and dev-cmd/advisory-match brew#23329: brew advisory-match, an authoring-time dev-cmd that finds every OSV.dev advisory reachable for a formula and emits candidate BREW-* records for review. It queries the GIT ecosystem (forge repo), language registries (PyPI/npm/crates/CPAN/Hackage/Hex/RubyGems/Maven/NuGet/CRAN, derived from stable.url and each resource), distro ecosystems (via a Repology-built formula-to-srcname map), and CPANSA; resolves distro records to their upstream CVEs; and evaluates each hit's affected[] range against the shipped version. Runs in advisory-database CI, not on user machines. A 50-formula calibration run produced 1,618 candidates in ~7 minutes with 91% precision on the 34 :affected records; the three false positives were upstream data issues.
• Add RepologyIndex and rake repology:build advisory-database#11: RepologyIndex builds data/repology.json (the formula-to-distro-srcname map) nightly; 5,256 formulae covered.
• Backfill fixed versions for old CVE patches advisory-database#25: backfilled fixed boundaries for the older patch-derived records.
• RepologyIndex: index sibling-formula projects; run tests on PRs advisory-database#27: index now includes projects that group sibling formulae (ffmpeg + ffmpeg@N, wget + wget2) instead of skipping them.
• CONTRIBUTING: describe reviewing source: matched candidates advisory-database#28: CONTRIBUTING review checklist for source: matched candidate PRs.

Open

• Publish data/advisories.json indexed by formula name advisory-database#30: publishes the whole corpus as one data/advisories.json, indexed by formula name.
• Add Ingest workflow: nightly brew advisory-match --all advisory-database#29: nightly Ingest workflow that runs brew advisory-match --all and opens a candidates PR.
• generate-formula-api: attach vulnerabilities from advisory-database brew#23341: brew generate-formula-api fetches data/advisories.json once per build and attaches hash["vulnerabilities"] = {open:, patched:, fixed_count:} to each formula's API JSON. No live OSV call in the formulae.brew.sh build path; advisory-database is the cache.
• formula: render vulnerabilities from the API JSON formulae.brew.sh#2245: renders vulnerabilities on the formula page (open advisories linked to osv.dev/vulnerability/<id>, plus a "Homebrew ships patches for" line).

Once those four are merged the next site deploy shows the section for whatever's in advisory-database (44 records / 10 formulae today), and Ingest grows it nightly.

@kmarekspartz thanks for Homebrew/brew#23152 and the SBOM purl patch. Vulns::Identify.registry_package (in #23329) is the derivation point for pkg:pypi/pkg:npm/etc. purls if you want to wire the SBOM change through it; happy to review.

osv.dev ingestion still waiting on google/osv.dev#5660 (needs a PkgVersion comparator); until then brew vulns will read the corpus from data/advisories.json directly.

[kmarekspartz]

Adding patches to a formula based on the data in brew vulns --no-fix-available: Homebrew/homebrew-core#297346

We may want to extend the cli filters to distinguish between new release available but formula hasn't been updated, and there's a patch available but no release.

[kmarekspartz]

Likely need a flag for listing which "... packages skipped - no supported source URL" to make that actionable, too.

[kmarekspartz]

Draft of incorporating my SBOM patch and third party purls as requested by @andrew: https://github.com/Homebrew/brew/pull/23459/changes

It looks correct to me but intend to try this out locally a bit before marking it as ready for review.

[kmarekspartz]

Looking across my installed but skipped formula, the two main clusters are:

• GNU Savannah hosted, but OSV doesn't seem to have data integrated directly from GNU about these.
• Python hosted packages that aren't getting recognized as such

Given the Python packages, I'm starting a branch to amend the scanner to look more closely at the upstream ecosystem(s) in the OSV data.

There were a couple that are on GitLab/GitHub already that should be addressable with a formula change, but I have an existing formula change open, so would encourage someone else to take on getting these two formula updated:

• libtasn1: https://gitlab.com/gnutls/libtasn1
• aspell: https://github.com/GNUAspell/aspell