Brew-browser

brew-browser v0.5.0 — Opt-in vulnerability scanning

Signed + notarized. macOS 13+, Apple Silicon. Auto-updates from v0.4.0 via the in-app updater.

Highlights

You can now find out which of your installed Homebrew formulae have known CVEs — without leaving the app. v0.5.0 adds opt-in vulnerability scanning powered by the official brew vulns subcommand (Homebrew/homebrew-brew-vulns, by Andrew Nesbitt, published January 2026). When you turn it on, brew-browser shells out to brew vulns to query OSV.dev's GIT ecosystem for vulnerabilities matching your installed formula versions, then optionally enriches each finding with richer prose from the GitHub Advisories API.

Off by default. Both new toggles (vulnerability scanning + GitHub auth for enrichment) sit behind explicit consent in Settings → Network. No first-launch user generates a single OSV query without flipping the switch.

What's new

Opt-in vulnerability scanning. Settings → Network → Vulnerability Scanning toggles the feature on. When brew vulns isn't installed yet, the Settings card shows a one-click installer button that runs brew install homebrew/brew-vulns/brew-vulns for you and streams the output into the Activity drawer. After install, flip the toggle and the first scan kicks off automatically.

Dashboard Exposure card. A new card on the Dashboard shows your aggregate exposure: counts of critical / high / medium / low / unknown findings across all installed formulae, plus a "Scan now" button to force a refresh. When you're clean, the card shows a ✓ checkmark and "No known vulnerabilities" — the clean state IS the message, no collapsing.

Sidebar count badge. A small count badge on the Library nav item shows how many of your installed packages have at least one known CVE. The badge color tracks the highest severity (red for critical, orange for high, amber for medium, blue for low, grey for unknown). Hidden when the count is zero so the sidebar stays uncluttered.

PackageRow severity dots. Library rows get a small color-coded dot next to the installed pill when a package has known vulnerabilities. Hover for a tooltip; click through to the detail panel for the full list. The dots are synchronously hidden when the feature is off — no extra IPC chatter.

PackageDetail Security card. Open any installed formula's detail panel and you'll see a new Security card listing every CVE/GHSA finding for that package: severity pill, advisory ID (linked out to GHSA or OSV when there's a reference URL), summary text, and the version range where it's fixed. When the package is outdated AND at least one finding has a fixed_in range, an "Upgrade to fix" button is wired straight into the existing brew upgrade pipeline. A "Check vulnerabilities" button lets you force a per-package re-scan whenever you want.

Install-set fingerprint optimization. Daily scans on an unchanged install set serve from cache instantly. The backend records a SHA-256 fingerprint of your sorted kind:name:version lines alongside the scan results. On the next open, if nothing has changed, the cached report is returned without re-shelling brew vulns (which can take 60+ seconds with 200 packages). The "Scan now" button on the Dashboard Exposure card forces a full re-scan when you want the latest.

Refresh integration. When you click Refresh on the Dashboard or in Library — which now runs brew update, refreshes the catalog, AND reloads your installed list — the vuln scan re-runs as part of the same flow. So a refresh that learned about a new upstream version of openssl@3 and a new CVE for it shows you the security finding in the same beat as the new version number.

Post-mutation re-scans. Every install / upgrade / uninstall invalidates the affected cache entry and triggers a per-package re-scan, so the Security card and severity dot reflect reality immediately after you act — no stale ✓ from yesterday's pre-upgrade state.

How to enable

1. Open Settings → Network → Vulnerability Scanning.
2. If brew vulns isn't installed, click Install brew vulns. The output streams into the Activity drawer. Takes ~10 seconds.
3. Flip the Enable vulnerability scanning toggle on.
4. The first scan kicks off automatically. Larger install sets take longer; the Exposure card shows progress.
5. Optional: in Settings → GitHub, sign in to GitHub if you want GHSA enrichment — richer summaries, patched-version ranges, and reference links from api.github.com/advisories. Without GitHub auth, you still get full OSV data; GHSA is purely a UX upgrade.

To turn it off later: flip the same toggle. The on-disk cache stays around (in case you turn it back on) but no scans run and no UI surfaces show vulnerability information. Offline Mode hard-locks the feature regardless.

Trust boundary

This is the first feature that involves an outbound path opened by a subprocess, not by brew-browser itself. The architecture is explicit so the privacy story stays auditable:

• api.osv.dev — OSV.dev's GIT-ecosystem query endpoint. POST'd by brew vulns, not by brew-browser directly. We invoke the subprocess; the subprocess opens the socket. Same trust posture as every other brew call (the brew install you ran yesterday also opens sockets to GitHub, OCI registries, and bottle mirrors — and you'd see them in the Activity drawer if you looked).
• github.com, gitlab.com, codeberg.org — source-URL and version-tag resolution by brew vulns so it can match your installed version against the vulnerable-version ranges OSV publishes. Same subprocess-as-origin posture.
• api.github.com/advisories/{GHSA_ID} — GHSA enrichment from brew-browser's own Rust code, only when both Vulnerability Scanning AND GitHub Sign-in are on. Three independent toggles must align for a single request to leave the box: master Offline Mode off, vulnerability-scanning toggle on, github-enabled toggle on. Failure (rate limit, network error) leaves the OSV record unchanged and logs without bothering you.

Full server-side audit in memory-bank/security.md §17. The gate-composition table, threat model, and pre-launch checklist all live there.

Known limitations (honest gaps)

• Casks aren't supported. brew vulns is formula-only. Cask packages render the same UI shell in the Security card but the body honestly says "Cask coverage isn't supported — brew vulns is formula-only." This isn't fake clean state; we'd rather be honest about the gap than tell you a package is safe when we have no idea.
• Formulae with tarball-only sources may show empty results. brew vulns resolves vulnerabilities by mapping source URLs to upstream version tags in OSV's GIT ecosystem. Formulae whose source is a tarball without a corresponding Git tag may not match cleanly. This is rare in practice (most Homebrew formulae point at GitHub/GitLab releases that have both tarball and tag), but worth knowing about if a formula you expected to see findings for shows none.
• GHSA enrichment is best-effort. If you've enabled GitHub sign-in, GHSA gives you richer data than OSV alone. But if api.github.com rate-limits you, throws a 5xx, or is unreachable, the enrichment quietly fails and you see the OSV record without the prose extras. No retry, no toast — the scan is reliable; the cherry on top isn't load-bearing.

What's NOT changed

• Without opting in, nothing changes about your outbound posture. No OSV traffic, no GHSA requests, no brew vulns invocations. The previous ten outbound paths from v0.4.0 are unchanged.
• The Settings UI keeps the same shape. The new Vulnerability Scanning section sits at the bottom of Network alongside the existing Updates and Enhanced Trending History subsections — same nested-subsection pattern, same "locked off" treatment when Offline Mode is on.
• No new dependencies in the frontend. The store, types, and components are pure additions.
• Two new Rust dependencies (sha2, hex) for the install-set fingerprint. Both are widely used; SHA-256 is the right primitive here because Rust's DefaultHasher is non-deterministic across process runs (its salt is randomized to defeat HashDoS) — a hash recorded to disk would mismatch every subsequent launch.

Under the hood

• +78 backend tests (507 → 585). Pin the new gates exhaustively: toggle off → FeatureDisabled, paranoid on → ParanoidModeBlocked, FirstLaunch → FeatureDisabled (opt-in preserved), Corrupt settings → ParanoidModeBlocked (fail-closed), forward-compat for v0.4.x settings.json missing the new field, formula name validator rejects shell metas + empty + oversize, cache TTL is 6 hours, fingerprint is order-independent, GHSA enrichment short-circuits when github_enabled is off. +6 of those tests are a captured-fixture pin against real brew vulns --json output — the live smoke test on a 326-package install caught five integration assumptions that were wrong (severity wire is UPPERCASE; fixed_versions is an array not a string; install-detection needed brew --prefix brew-vulns, not brew commands; --include-aliases needs --quiet; brew-vulns exits 1 on findings per CI-scanner convention). All five are now regression-pinned and commented at the trap sites.
• One new error variant vulns_not_installed in the BrewError union, with a friendly message routing the user to the one-click installer (not a generic exit-non-zero toast).
• Two on-disk caches at ~/Library/Application Support/brew-browser/: vulns_cache.json (1 MiB cap, 6h per-record TTL) for scan records + the install-set fingerprint; ghsa_cache.json (2 MiB cap) for the enrichment payloads. Both fail soft on corrupt + future-schema — no first-launch user can be wedged by a bad cache file.

Acknowledgements

• brew vulns by Andrew Nesbitt — github.com/Homebrew/homebrew-brew-vulns. Published January 2026. brew-browser is a thin orchestration layer over this subcommand for vulnerability data; all of the hard work (source-URL extraction, version-tag matching, OSV query) is brew-vulns'.
• OSV.dev — the open-source vulnerability database that brew vulns queries. osv.dev.
• GitHub Advisories — the GHSA dataset that powers the enrichment layer. github.com/advisories.

Issues & feedback

github.com/msitarzewski/brew-browser/issues. Every error toast in the app has a "Report" button that pre-fills the issue with your context. Use it — that's literally what the button is for.