Back in January I released brew-vulns, a gem that added CVE scanning to Homebrew. It shelled out to brew info --json=v2, derived a source repository URL and version tag for each installed formula, and queried osv.dev for anything known against that repo at that version. As of Homebrew 6.0.11 that command is built in and the gem is deprecated. Getting useful answers out of brew vulns in between meant changing what data Homebrew publishes about its own packages, registering Homebrew with the specs that vulnerability tooling is built on, standing up an advisory database, and porting Homebrew’s version comparison to Python so osv.dev can order our releases.

$ brew vulns
Checking 142 packages for vulnerabilities...
(18 packages skipped - no supported source URL)

openssl@3 (3.4.1)
  CVE-2024-13176 (medium) - Timing side-channel in ECDSA signature...
    Fixed in: 3.4.2

Found 1 vulnerability in 1 package

10 resolved by formula patches (not counted; pass --no-ignore-patches to include):
  glibc: CVE-2024-2961, CVE-2024-33599, CVE-2024-33600, CVE-2025-0395, ...

About a month after the first release Mike McQuaid invited me to transfer the repo into the Homebrew org, and from then on it was being run against all of homebrew-core rather than just my laptop. That’s roughly 8,400 formulae, enough real data to find edge cases fixtures never do. OSV records with malformed affected ranges were passing versions through silently, so range evaluation became fail-closed. Vulnerability summaries occasionally contain terminal escape sequences and needed sanitising before printing. One pathological query could pull unbounded pages from the OSV API, so both pagination and the thread pool that fetches vulnerability detail got hard caps, and CI users needed a distinct exit code for “the scan errored” as opposed to “the scan found something”.

Formula patches

Hundreds of formulae in homebrew-core ship with at least one patch applied on top of the upstream tarball, and some of those patches fix CVEs, so the bottle a user installs is not affected even when the upstream version number falls inside an advisory’s range. A query keyed on repo and version reports those as open regardless. There was also no programmatic way to find out which formulae carried patches at all: brew info --json didn’t serialise the patch list, formulae.brew.sh didn’t show it, and formulae loaded from the API had an empty one, leaving a grep over a full homebrew-core checkout as the only option.

I opened a discussion proposing two changes to Homebrew itself: add patches to the JSON output, and let a patch declare which CVEs it resolves. Mike said yes to both more or less immediately. Patches went into Formula#to_hash the same day, which surfaced 1,191 of them across 809 formulae, 972 with an external URL and 219 embedded in the formula file as __END__ data. The patch do DSL then gained resolves and type:

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

The vocabulary matches CycloneDX’s pedigree.patches so SBOM tooling can read it without translation, and CVE ids are auto-inferred from the patch URL and apply filenames, which meant glibc, unzip, zip and libquicktime populated without any formula edits.

That change sat in review for close to a month and shipped in Homebrew 6.0.4, at which point brew-vulns could consume it: any OSV result whose id or alias matches a resolves entry is reported as patched, excluded from the exit code, and marked analysis.state: resolved in CycloneDX output. Bo Anderson later mapped resolves through the API layer so it survives the JSON round-trip when formulae are loaded without a local homebrew-core checkout.

Annotation backfill

With the DSL merged, the next job was populating it across those 1,191 existing patches. Of the 972 external ones, 497 point at GitHub commit URLs (in principle queryable in OSV by commit hash), 272 point at raw files hosted in homebrew-core itself, 42 come from Debian, and the rest scatter across MacPorts, FreeBSD ports, Fedora, Gentoo and gists. Patrick Linnane sampled 59 of the GitHub-commit patches and found zero that referenced a CVE; homebrew-core’s patches are almost entirely build and portability fixes, and a heuristic that greps formula source for CVE strings risks marking things patched that aren’t, since several of the CVE mentions in core are comments about unfixed issues.

So the approach flipped from annotating every patch by URL heuristic to running the scanner over every patched formula and only annotating where a real finding gets suppressed. That pass covered the 484 patched formulae with a resolvable source repo and turned up nine with open OSV findings; in every case the shipped patch was a build fix unrelated to the CVE, so zero new annotations came out of it.

A wider sweep querying OSV by commit hash for the GitHub-commit patches, reading DEP-3 headers on the Debian tarballs, and grepping local patch bodies found exactly one more: nvi carries a Debian regex patch that fixes CVE-2015-2305. Along the way, extending the scanner’s homepage fallback to cover formulae hosted outside GitHub, GitLab and Codeberg also turned up an unrelated data bug where libart’s homepage field pointed at a completely different project.

The glibc formula’s Debian patch tarball resolves ten CVEs, and querying OSV by the sourceware.org repo URL returns exactly one of them. The other nine exist in OSV only as records auto-converted from NVD, and those conversions carry no affected[].package data: you can GET /v1/vulns/CVE-2024-2961 and read the record, but no query by package, purl or repository will ever return it. All of libquicktime’s patched CVEs were in the same state. So even a scanner with perfect repo-URL derivation has a recall ceiling set by how much of NVD has been enriched with package data upstream, and for the C libraries Homebrew ships a lot of, the answer is not much.

By this point Homebrew had structured resolves data, version history and patch metadata for every formula, which together are enough to act as an OSV data source. I added an --osv-export flag to the tap that walks every formula’s resolves list and emits one OSV-schema JSON record per CVE, under a Homebrew ecosystem with pkg:brew/<name> package URLs, BREW-<formula>-<CVE> ids, and the resolving patch details carried in ecosystem_specific. A demo repository held the initial 26 records with schema validation running in CI, and any OSV-aware tool reading that feed could answer whether a given Homebrew package version was affected by a given CVE without going near the upstream repo.

Spec registrations

For anyone else’s tooling to read those records, two specs needed a Homebrew entry and osv.dev needed code to handle it. The package-url spec defines the pkg: identifier format that OSV, CycloneDX, SPDX and most SBOM tooling use to name packages, and it maintains a registry of allowed types. A pkg:brew type had been proposed in 2023 by William Woodruff and again by others afterwards, and it finally landed via Rui Chen earlier this year. One wrinkle specific to Homebrew is that formula names can contain @ for version-pinned variants like openssl@3 and [email protected], and @ is also purl’s version separator, so pkg:brew/openssl@3 is ambiguous and the @ in the name has to be percent-encoded as pkg:brew/openssl%403.

The OSV schema keeps its own registry of ecosystem names and id prefixes, and records that use an unregistered one fail validation. Registering Homebrew and the BREW- prefix was straightforward, as was documenting the database URL and how Homebrew versions sort, which any tool evaluating an affected range needs to implement.

Getting osv.dev itself to ingest the feed is the piece still in progress. Two additions are needed per ecosystem in the osv.dev importer: a purl-to-package mapping, which for pkg:brew is a couple of lines, and a version comparator so that range queries like “is 6.0_7 inside introduced: 0, fixed: 6.0_8” can be evaluated server-side. Homebrew versions are the upstream version string with an optional _N revision suffix that increments when a formula changes without an upstream release, and the upstream strings are whatever each project uses, semver or otherwise. The comparator is therefore a Python port of Homebrew’s Ruby Version#<=> logic, which runs to a couple of hundred lines of edge cases. The draft PR is open; until it merges and ingestion is enabled, brew vulns can’t query {ecosystem: "Homebrew"} over the API and has to fetch the advisory database’s static JSON directly instead.

Advisory database

I transferred the demo repository into the Homebrew org once the schema registration merged, initially as Homebrew/homebrew-advisory-database. That name lasted about a day: the homebrew- prefix is how the setup-homebrew CI action identifies taps, and CI runs started failing on an attempt to tap a directory full of JSON files, so it became Homebrew/advisory-database and every reference to the old name across brew and the repo’s own workflows had to follow.

The repo holds one JSON file per advisory, currently 33 across six formulae (glibc, libquicktime, lrzsz, nvi, unzip, zip), all generated from resolves annotations. A daily GitHub Actions workflow regenerates them, and because the org’s branch ruleset requires pull requests on main the workflow opens a PR instead of pushing. Regeneration originally ran gem install brew-vulns followed by brew vulns --osv-export, which meant the tap couldn’t be archived until brew had a native replacement; that arrived as brew generate-vulns-advisories, a hidden dev command, and the workflow switched over.

The fixed boundary in each record needed more care than “whatever version ships today”. If unzip’s formula gained a CVE-2014-8139 patch at revision 6.0_6 and the current revision is 6.0_8, a record saying fixed: 6.0_8 wrongly flags 6.0_6 and 6.0_7 as vulnerable. The generator now walks homebrew-core’s git history via FormulaVersions to find the first revision where the resolving patch appeared, and merges into existing records rather than overwriting them so a hand-corrected boundary or a curated record survives the next nightly run. The contributing guide covers the curated path for cases the generator can’t express, using a BREW-0000-0000 placeholder id that a maintainer replaces on merge.

Merging into Homebrew/brew

Around this point I was added as a Homebrew maintainer, which made the next stretch a lot smoother since it involved landing a run of interdependent changes across brew, homebrew-core and the advisory database in quick succession. The scanner moved into Library/Homebrew/cmd/vulns.rb with a supporting vulns/ module directory, following the same pattern as brew livecheck, and the tracking issue has the full design doc listing everything that changed on the way in.

User-facing commands in brew’s cmd/ directory can’t lazy-load gem groups (a RuboCop cop enforces it), which was the biggest constraint on the port: anything the command needs has to be in the vendored bundle already or reimplemented, and adding five gems to every Homebrew install for one subcommand wasn’t going to fly. The tap depended on purl, vers, cvss-suite, sbom and sarif-ruby, and all five went.

The sbom and sarif-ruby gems were only used for --cyclonedx and --sarif output, so those flags are dropped for now and will return as direct JSON emission validated against the published schemas. The purl gem was used exactly once, to extract the ecosystem token from an OSV record’s affected.package.purl field, and since the merged code only evaluates SEMVER ranges locally that lookup is never reached.

The vers gem became a small Homebrew::Vulns::Semver module implementing strict SemVer 2.0 comparison. Homebrew’s own Version class isn’t a drop-in here: it sorts 1.0.0-alpha.1 above 1.0.0-alpha.beta where the SemVer spec says numeric prerelease identifiers sort below alphanumeric ones, and it compares +build metadata where SemVer says build metadata is ignored for ordering. Getting either wrong turns a range boundary into a false positive or negative.

The cvss-suite gem became Homebrew::Vulns::CVSS, which implements the CVSS v3.0/v3.1 base-score formula and buckets the result. CVSS v4.0 scoring requires a roughly 270-entry MacroVector lookup table plus interpolation between entries, so v4 vectors currently fall through to the next severity entry on the record; almost every record with a v4 vector also carries a v3 one, so in practice little is lost.

The tap’s --all flag was going to become --eval-all to match other brew commands, until --eval-all was replaced across brew with a tap-trust mechanism while the PR was in review, so with no arguments brew vulns now scans every formula from a trusted tap and falls back to installed formulae otherwise. The tap also always read the current formula definition for the source URL and version, so an old installed keg would be checked against whatever version the formula had since been bumped to. The built-in command reads the installed keg’s SPDX SBOM instead, and if an outdated keg predates SBOM generation the scan warns and exits nonzero rather than reporting a version it never checked.

All of that shipped together in Homebrew 6.0.11, and the tap is now a deprecation stub pointing at the built-in command.

Coverage

The command as shipped queries OSV’s GIT ecosystem by repo URL, which covers about 73% of homebrew-core (6,210 of 8,492 formulae); the other 2,282 have no derivable GitHub, GitLab or Codeberg URL and are skipped, with a count reported at the end of the run. Closing that gap means finding other keys that join a formula to an advisory, and doing the joining once at authoring time in the advisory database rather than on every user’s machine. That way brew vulns stays at a single batched API call however many matching strategies feed the database behind it.

Of the skipped formulae, 322 have a stable.url pointing at a language package registry (145 PyPI, 144 npm, plus Maven, Hackage, CPAN, crates and a few others), and a URL like files.pythonhosted.org/.../foo-1.2.tar.gz encodes enough to build a pkg:pypi/[email protected] purl and query OSV’s PyPI ecosystem directly. The same applies to the 12,283 resource blocks across homebrew-core, which are vendored dependencies inside formulae; about 91% of those are registry URLs (over 10,000 PyPI alone) and none are scanned today.

That leaves roughly 1,960 formulae hosted on SourceForge, GNU mirrors, gnome.org download servers, Debian archives and the like, with no direct package identifier at all. For those the join goes through Repology, which already indexes Homebrew alongside every major Linux distro: look up the formula name, get back the Debian, Alpine and openSUSE source-package names for the same upstream, query OSV’s distro ecosystems for those, and collect the CVE aliases.

Repology’s bulk dumps turned out to be 10GB+ PostgreSQL restores rather than anything directly loadable, so the index builder paginates the API instead, about 43 pages at one request per second, and writes a distilled formula -> {distro -> srcname} map into the advisory repo. Name matching needs normalisation (postgresql@16 maps to Repology’s postgresql, libmatio maps to matio, and Repology sometimes lists a Debian binary package where the OSV feed keys on the source package), and corrections to Repology’s project grouping go upstream to repology-rules instead of into a local override layer.

OSV has no CPAN, CTAN or LuaRocks ecosystem, and 61 formulae vendor at least one CPAN module, so that path reads the cpan-security-advisory database directly. Between the registry URLs, the Repology mapping and the CPAN feed, roughly 96% of homebrew-core ends up with at least one automated join key, with a few hundred formulae left over that will need a hand-curated mapping file in the advisory repo.

Next

The scan output can surface in more of Homebrew than a dedicated subcommand. Running the scanner once inside brew generate-formula-api and attaching a vulnerabilities field to each formula’s JSON would put open findings on formulae.brew.sh formula pages and in brew info without a live query, since both already read that JSON. From there brew install could warn when the version being installed has an open advisory, and brew upgrade could list which CVEs each pending bump resolves alongside the version change, so the security case for an upgrade is visible when you’re deciding whether to run it.

Every installed keg already carries an SPDX SBOM listing its dependencies with versions, and the built-in command reads that SBOM for the top-level source URL now, so the inventory for scanning a formula’s whole dependency tree is already on disk and the remaining work is the same matching problem as everything above. Casks are harder because a large share of them package closed-source applications, with no upstream repo to query and no visible dependency list to walk. The EU Cyber Resilience Act will change that from outside Homebrew: vendors selling into Europe will have to produce SBOMs for their products, and as those start to appear for the apps that casks install, scanning a cask’s dependency tree becomes the same job as scanning a keg’s.

On the maintainer side, a homebrew-core PR that bumps a formula is the natural place to report which CVEs the bump closes, which are still open at the new version, and which affect any vendored resource blocks. Running the full matcher against the one changed formula is cheap enough to sit inside brew test-bot alongside the existing audit checks. Anything it finds that isn’t already a BREW-* record is a candidate for the advisory database, giving it a second feed driven by formula changes as well as the nightly advisory sweep. Restoring --sarif and --cyclonedx output brings back the code-scanning and SBOM integrations for downstream projects that want to scan their own Brewfiles in CI.

Underneath all of that, osv.dev ingestion is still the gate for querying {ecosystem: "Homebrew"} directly rather than fetching the advisory JSON, and CVSS v4 scoring still needs its lookup table before v4-only records get a severity label.

Thanks to Mike McQuaid and Patrick for all the help getting this over the line so far, and to the rest of the Homebrew maintainers for reviews across an unreasonable number of pull requests. If you’re on Homebrew 6.0.11 or later brew vulns is already there; the advisory database and the discussion thread that most of this fell out of are good places to follow along.