perplexityai/bumblebee: a read-only package inventory scanner for supply-chain response

The gap Bumblebee targets: messy local state, not shipped artifacts

Most supply-chain tooling answers one of two questions. An SBOM answers what shipped from a build. An EDR agent answers what ran or touched the network. Bumblebee's README states the third question directly: when an advisory names a package, extension, or version, which developer machines show a match in their on-disk metadata right now? That is a response question, not a build question, and the data that answers it is scattered across lockfiles, package-manager install metadata, extension manifests and MCP JSON configs. Bumblebee is for the person who has to answer it during an incident, on a population of developer laptops, without installing a package manager query or reading source files. It is a single static Go binary with no non-stdlib dependencies, which matters when the alternative is shipping a runtime and a dependency tree to every endpoint you are trying to inventory.

How the scanner works: read-only file parsing into NDJSON records

Each invocation performs one scan and exits. The scanner reads a fixed list of files documented in docs/inventory-sources.md and emits NDJSON, one component record per line, with diagnostics going to stderr as NDJSON as well. Every run ends with a scan_summary record, which the README says receivers use to decide whether to promote a run to current state. That is the whole architecture: no daemon, no package manager execution (the README explicitly rules out npm ls, pip show and go list), and no source-file reads. Coverage is a table of families mapped to an emitted ecosystem string. npm, pnpm, Yarn and Bun all emit ecosystem npm, sourced from package-lock.json, pnpm-lock.yaml, yarn.lock (Classic and Berry) and bun.lock respectively. PyPI reads *.dist-info/METADATA and egg-info PKG-INFO. Go modules read go.sum and go.mod. RubyGems, Composer and Homebrew each have their own receipt or lockfile sources. Editor extensions come from VS Code, Cursor, Windsurf and VSCodium manifests; browser extensions from Chromium-family manifest.json and Firefox extensions.json per profile. MCP servers come from a list of JSON host configs including mcp.json, .mcp.json, claude_desktop_config.json and ~/.claude.json. One detail worth flagging: the README says MCP host configs can carry environment values and credentials in their env blocks, and that Bumblebee parses these configs for server inventory but does not emit those values in its records. That is a deliberate boundary, and it is the kind of boundary you want documented rather than assumed.

Installing Bumblebee and running a first baseline scan

The project requires Go 1.25+ and has zero non-stdlib dependencies. The README gives two install paths: go install for the latest tagged release, or a pinned tag.

go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest

go install github.com/perplexityai/bumblebee/cmd/bumblebee@v0.1.1

The first command installs into $GOBIN. The second pins the v0.1.1 tag, which the release list dates to 2026-05-22. To build from a checkout instead, the README gives go build and go test:

go build -o bumblebee ./cmd/bumblebee
go test ./...

After installing, run the built-in end-to-end check. The fixtures are embedded in the binary, use deliberately fake package names (bumblebee-selftest-evil@0.0.0) and make no network calls. The README shows this output:

bumblebee selftest
# selftest OK (2 findings in 1ms)

A non-zero exit means the local install can no longer detect what it should, which the README frames as a pre-deployment smoke test for fleet rollouts. Then run a baseline scan and preview the roots it will touch before committing to a full sweep:

bumblebee scan --profile baseline > inventory.ndjson
bumblebee roots --profile baseline

The second command prints <root_kind>\t<path> lines without scanning. If a root you expected is missing, you have found that out before writing gigabytes of NDJSON.

Profiles and cadence: baseline, project and deep are not interchangeable

The three profiles exist because the populations and the cadences differ. baseline covers common global and user package roots, language toolchains, editor extensions, browser extensions and MCP configs, and the README positions it for recurring lightweight inventory via an external runner. project scans configured development directories such as ~/code, ~/src or ~/work. deep takes explicit --root paths and is meant for on-demand incident or campaign checks, usually combined with --ecosystem, --exposure-catalog and --findings-only. The constraint that matters operationally: baseline and project refuse bare-home roots, and only deep walks them. So a $HOME-wide sweep is deliberately a manual, bounded act rather than something a cron job can quietly start doing. Bumblebee is a one-shot scanner and the README is explicit that cadence is the runner's responsibility (cron, launchd, systemd, MDM). Each record carries profile and a per-root root_kind so receivers can keep populations separate. If you skip that separation on the receiving side, you will mix a laptop's global toolchain with a project workspace and have no way to tell them apart later.

Exposure catalogs and where the approach breaks down

When responders already know what they are looking for, --exposure-catalog takes a JSON file or a directory of *.json catalogs and flags exact matches. The directory is merged non-recursively and all files must share schema_version, which is a real constraint if your advisory feed emits mixed schema versions: the run will not silently pick one. --findings-only requires --exposure-catalog and suppresses package records while keeping findings. The limitation is in the word exact. This is a match against on-disk metadata, not a resolution of what a package manager would actually install. A lockfile that lists a version but was never installed, or an installed tree whose lockfile has drifted, will not be reconciled for you, because Bumblebee does not run npm ls or pip show. It also does not parse Codex config.toml or Continue YAML in v0.1, so an MCP inventory built from this tool has a documented hole. Loose SKILL.md directories without a lock file are not enumerated either. And because there is no daemon, there is no alerting: a machine that is asleep during the cron window is simply not in that run's output, and nothing in the tool will tell you it was missed.

Compared with Syft and Grype, and with EDR agents

The closest open source comparison is the Syft and Grype pair. Syft generates an SBOM from a directory, container image or filesystem, and Grype matches that SBOM against vulnerability databases. The difference in approach is the target and the trigger. Syft is built to describe an artifact completely, which is what you want for a build pipeline or a container registry. Bumblebee is built to describe a developer endpoint's messy local state, including browser extension manifests, editor extension manifests, MCP host configs and Homebrew install receipts, and it is built to be run on demand against a catalog you already have. It does not ship a vulnerability database and it does not resolve dependencies. If your question is 'what is in this image', Syft is the better tool. If your question is 'which of these two hundred laptops has this extension version installed right now', Bumblebee's coverage list is aimed at exactly that. Against EDR, the split is even cleaner: EDR observes execution and network behaviour, Bumblebee observes files at rest and never runs anything. That makes it safe to run broadly, and also means it cannot tell you a package was loaded, only that its metadata is present.

Licence, version stamping and the cost of keeping it current

Bumblebee is Apache-2.0, which permits commercial use and modification with the usual notice and patent terms; that is a statement about the licence text, not legal advice, and you should route it through your own review if you redistribute a modified binary. The upgrade surface is small in one sense and sharp in another. Small, because go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest is the whole upgrade path and there are no non-stdlib dependencies to audit. Sharp, because the output is a versioned contract: records carry schema_version (the README's example shows 0.2.0) and a scan_summary record gates whether a receiver promotes a run to current state. A schema change is a receiver-side change. The README also documents version precedence for the binary itself: -ldflags override, then the module version recorded by go install, then the in-tree default tracked in VERSION. If you build from a checkout with go build -ldflags "-X main.Version=v0.1.1" -o bumblebee ./cmd/bumblebee, you are responsible for keeping that string honest, and bumblebee version prints it alongside the VCS revision, build time and Go runtime so a record can be traced back to a specific build. The last push to the repository was on 2026-08-07, and the most recent tagged release is v0.1.2 from 2026-06-18.

Editorial conclusion

Adopt Bumblebee if you already have a runner (cron, launchd, systemd, MDM) and a receiver that can hold current state from scan_summary records, and if your response question is 'which machines show this package version on disk right now'. Do not adopt it as an EDR replacement, as a runtime monitor, or if you need Codex config.toml or Continue YAML parsed, since v0.1 does not parse those. Before rolling it out, verify three things: that bumblebee selftest exits zero on the target platform, that bumblebee roots --profile baseline prints the roots you expect (baseline and project refuse bare-home roots), and that your exposure catalog files all share one schema_version, because --exposure-catalog merges a directory non-recursively and rejects mixed versions.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. perplexityai/bumblebee on GitHub
4. README
5. Releases