Bumblebee Tutorial: Scan Your Dev Machine for Supply Chain Risks

Every time a supply chain attack hits, security teams ask: which dev machines have the compromised package installed? SBOMs cover production builds. EDR covers running processes. Neither checks the actual files sitting on a developer's laptop.

Perplexity open-sourced Bumblebee (May 22, 2026) to fill that gap: a small, read-only Go binary that inventories npm, pnpm, Yarn, Bun, PyPI, Go modules, RubyGems, Composer packages, plus MCP configs and editor/browser extensions. No install scripts, no network calls during scanning, no write operations.

DepScan checks a single package.json in the browser; Bumblebee checks your entire machine across 8 ecosystems. The same supply chain principles apply locally, not just in CI.

All scans are read-only. Bumblebee never executes a package manager or runs install scripts, which sidesteps attacks that hide in preinstall/postinstall hooks.

The first baseline scan on a working developer machine is a shock. Thousands of records, most of them transitive npm packages you have never heard of, plus every editor extension you installed once and forgot about. That is not a bug in the tool. An inventory is supposed to be exhaustive.

The mistake teams make here is trying to read the output. You do not read an inventory, you query it. Bumblebee's job ends at producing accurate NDJSON; deciding what matters is a separate step, and it is the step where most rollouts stall.

Before writing any query, look at exactly one record so you know what fields you actually have to work with:

Do this every time you upgrade the binary. Field names in a young tool are the least stable part of its interface, and a jq filter that silently returns nothing because a key was renamed is worse than no check at all, because it looks like a clean result.

Work outward from the things that can execute code with the least warning, not alphabetically and not by ecosystem size. In rough priority order:

If you invert that order and start with npm packages because there are the most of them, you will burn a day and never reach the MCP configs, which are the part of a modern dev machine that changed most recently and got reviewed least.

An inventory scanner produces a different class of false positive than a malware scanner. It is not telling you something is malicious, it is telling you something exists. The false positive appears one layer up, when you or your catalog decides that an existing thing is suspicious.

These are the patterns that reliably generate noise on a real machine:

The practical fix for all five is scoping. Use --profile project against your actual working directories for routine checks and save --profile deep for the moments when completeness genuinely beats signal-to-noise, which is to say incidents.

Resist the urge to build a permanent suppression list early. Suppressions written in the first week encode assumptions you have not tested yet, and they are the single most common reason a scanner goes quiet right before it was needed.

Almost every serious npm compromise in recent years reached its victims transitively. Nobody deliberately installed the malicious package; they installed something four levels above it. That is why an inventory built from lockfiles and installed trees tells you more than a list of your direct dependencies ever will.

The distinction matters enough to be explicit about it, because the two files answer completely different questions:

A scanner reading lockfiles and installed trees closes that gap without asking anyone to review a 4,000 line diff. Once you have the inventory, the follow-up question is always the same: who pulled this in?

Bumblebee tells you a package is present and where. Your package manager tells you why it is present. Use them together:

If the answer is a single direct dependency, you can usually resolve it by bumping that one package. If the answer is nine different paths through your tooling, you are looking at an override or a resolution pin instead.

One inventory-level check worth running regularly is a duplicate-version count. A package resolving to many versions across your projects means an advisory against any one of them requires per-project work rather than a single upgrade:

When a new supply chain compromise drops, the first question is: are we affected? Bumblebee's exposure catalog feature turns that into a 5-second answer instead of a manual grep across every developer machine.

Create a JSON file describing the compromised packages:

Then run a targeted deep scan against it:

The --findings-only flag means you only see records that match the catalog. No match, no output. This turns "is anyone running the compromised version?" into a trivially scriptable check you can run across your fleet.

A catalog hit is the start of the work, not the end of it. Once you have confirmed that a compromised package version is genuinely present on a machine, the clock is running on credential theft, and the order you do things in matters.

The single most important thing to internalise: uninstalling the package does not undo what it already did. If a malicious install script executed, it ran with your user's permissions, and it had access to everything your user has access to. Treat removal as cleanup, not containment.

Once the immediate response is done, work through the follow-up items while the details are still fresh. These are the ones teams routinely skip and later wish they had not:

CI runners deserve the same treatment as laptops here. They hold the most valuable credentials on the network and they install dependencies far more often than any human does, which is why hardening your GitHub Actions workflows belongs in the same remediation pass.

MCP (Model Context Protocol) configs define which external servers your AI coding tools connect to. After the ContextCrush incident in March 2026, this became a real attack surface: a malicious MCP server can exfiltrate code context, inject prompts, or pivot into your development environment.

Bumblebee checks these config files: mcp.json, .mcp.json, claude_desktop_config.json, mcp_config.json, mcp_settings.json, cline_mcp_settings.json, Gemini CLI/Code Assist settings, and ~/.claude.json.

This outputs every MCP server config found on the machine, with the server URL and transport type for each entry. You can then cross-reference against known compromised servers or your organization's allowlist.

For a quick browser-based check of a single config file without installing anything, use the MCPConfigCheck tool.

A one-off scan is useful during an incident. A daily scan turns Bumblebee into continuous inventory. Here's a crontab entry that runs at 2 AM every day:

On macOS, launchd is more reliable than cron for scheduled tasks. Here's a plist that achieves the same thing:

For security teams managing a fleet, forward these NDJSON files to a central log aggregator (Splunk, Elastic, or even a simple S3 bucket). When an advisory drops, you query your existing inventory instead of scanning every machine in real time.

A scheduled scan tells you about a problem the next morning. A scan in CI tells you before the code merges, which is the difference between a fix and an incident. The pattern is the same one you already used for incident response: a catalog plus --findings-only, evaluated as pass or fail.

Rather than depending on a specific exit code, treat any output at all as a failure. --findings-only prints nothing when nothing matches, so a line count is a reliable gate that will not break if the tool's exit-code behaviour changes between versions:

The runner needs the dependency tree on disk before the scan runs, so install first. Install with scripts disabled, because you do not want a lifecycle hook from an unreviewed package executing on a runner that holds your deploy credentials.

Check bumblebee scan --help on the version you pinned before wiring this up. Profiles differ in whether they infer roots or expect you to name them, and a CI job that scans the wrong directory reports a clean result forever.

Pinning the commit rather than tracking the default branch matters more than it looks. A security tool you rebuild from HEAD on every run is itself an unpinned dependency with the ability to read your entire workspace, which is the exact category of risk you installed it to manage.

Keep the catalog in the repository next to the workflow. Adding a compromised package to a JSON file in a pull request is a reviewable, auditable action, and it means the gate strengthens through the same process as the rest of your code.

Bumblebee fills the specific gap between SBOMs and EDR. It tells you what's on disk right now, not what ran or what shipped. Pair it with a VS Code extension audit for a more complete picture of your local attack surface.

The previous section lists what this particular tool has not built yet. This section is different: these are limits that no inventory scanner can engineer its way past, and knowing them is what keeps a green scan from turning into false confidence.

An inventory scanner answers exactly one question well: what is on this disk right now, by name and version. Every question that depends on behaviour, intent, or timing is outside its reach by construction.

None of that makes the scan worthless. It makes it one layer. The layer above it is behavioural (what the code does when it runs), the layer below it is provenance (whether the artifact you installed is the artifact that was built from the source you read), and a scanner sits squarely between the two without replacing either.

Provenance is where the biggest gains are available right now, because it is the layer most teams have nothing at all. Signed builds, published attestations, and integrity checks on anything you load from a third party all attack the problem earlier than a scan can. Subresource integrity is the cheapest version of this idea, and you can generate SRI hashes for third-party scripts in a minute.

The honest framing to carry into a security review: a clean Bumblebee scan means "none of the things we currently know are bad are sitting on this machine." That is genuinely valuable and it is not the same sentence as "this machine is clean." Attacks that hide in install-time lifecycle hooks or in a compromised CDN delivery path are specifically designed to be true and invisible at the same time.