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.