bumblebee-skill

May 27, 2026 · View on GitHub

A Claude skill that wraps Perplexity's bumblebee CLI for supply-chain inventory and exposure scans on macOS and Linux developer endpoints.

When an advisory names a compromised npm, PyPI, Go, RubyGems, or Composer package — or when you just want to know what's currently installed where — this skill takes Claude through the whole loop: requirements check, install, scan, report.

Bumblebee itself is the real work; this repo is a ~150-line SKILL.md plus a small NDJSON-to-Markdown report helper. All scan logic, output formats, and exposure-catalog semantics belong to the upstream project.

About Bumblebee

Bumblebee is an internal tool that Perplexity uses to protect the developer machines behind Perplexity, Comet, and Computer; they open-sourced it on 2026-05-22 so other security teams can build on the same layer.

Why it exists. SBOM and vulnerability scanners cover repositories and build artifacts. Endpoint-inventory tools cover installed applications. Bumblebee fills a different gap: when a fresh supply-chain advisory drops, security responders need to know which developer laptops have a specific package, version, extension, or MCP config right now — and they need that answer fast and without making the situation worse.

Read-only by design. This is the part most security teams care about: many recent supply-chain worms spread through postinstall hooks. A scanner that calls npm to check for exposure has already triggered the very attack it's looking for. Bumblebee avoids that entirely:

  • Never executes install scripts or lifecycle hooks.
  • Never invokes package managers (npm, pnpm, bun, pip, …).
  • Reads only metadata (lockfiles, manifests, installed-package metadata) — never source files.
  • Not an EDR — does no process or network monitoring.

What it covers. Where most OSS tools cover one or two of these, Bumblebee covers all four in one pass: language package managers (npm, pnpm, Yarn, Bun, PyPI, Go modules, RubyGems, Composer), MCP host configs (Claude Desktop, Cursor, Cline, Gemini CLI, …), editor extensions (VS Code family — VS Code, Cursor, Windsurf, VSCodium), and browser extensions (Chromium family + Firefox).

Three scan profiles. baseline for routine inventory across standard developer locations, project for targeted scans of specific workspaces, deep for broad incident-response scans paired with an exposure catalog.

This skill is the Claude-facing thin wrapper: it turns "scan my machine for compromised npm packages" into the right bumblebee invocation, then renders the NDJSON output as a Markdown report.

What it does

  1. Verifies Go ≥ 1.25 is on the PATH (provides install hints if not — does not install Go automatically).
  2. Verifies or installs the bumblebee binary via go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest and runs bumblebee selftest as a sanity check.
  3. Drives one of three scan profiles:
    • baseline — global package roots, language toolchains, editor extensions, browser extensions, MCP host configs (5-minute default cap).
    • project — explicit project roots like ~/code or ~/Developer (10-minute default cap).
    • deep — broad roots up to $HOME for incident response, paired with an exposure catalog when available (15-minute default cap).
  4. Captures stdout (NDJSON inventory) and stderr (diagnostic NDJSON) into timestamped files in the working directory.
  5. Generates a human-readable Markdown report — findings grouped by severity, inventory tables by ecosystem / root kind / confidence — via the bundled scripts/render_report.py (Python 3 stdlib, no pip install needed).
  6. Summarizes findings in chat with links to the raw NDJSON and the report.

The skill is read-only by design — it never patches, uninstalls, or modifies anything. Remediation is left to the operator.

Install

Claude Code (CLI)

git clone https://github.com/mycelos-ai/bumblebee-skill.git ~/.claude/skills/bumblebee

Or, if you prefer to keep the repo elsewhere and symlink it (useful while iterating on the skill):

git clone https://github.com/mycelos-ai/bumblebee-skill.git ~/code/bumblebee-skill
ln -s ~/code/bumblebee-skill ~/.claude/skills/bumblebee

Then either run /reload-skills inside Claude Code (v2.1.152+) or start a new session. /skills should list bumblebee under your user skills.

Claude Desktop (Cowork)

In Cowork, drop the cloned folder into your Cowork skills directory, or zip it as bumblebee.skill and use the "Save skill" action on the file card. Cowork picks up the skill on the next session.

Project-scoped install

If you only want the skill for a single project:

git clone https://github.com/mycelos-ai/bumblebee-skill.git path/to/project/.claude/skills/bumblebee

Project skills override user skills with the same name.

Quick start

Once installed, just ask Claude in plain language. Some examples that reliably trigger the skill:

  • "Lauf mal eine Bumblebee Baseline-Scan auf meinem Mac."
  • "Check this machine for compromised npm packages."
  • "Run a deep scan against ~/code with this exposure catalog: ~/Downloads/catalog.json."
  • "Is chalk@5.3.1 installed anywhere on this machine?" — the skill will run an exposure scan with a one-entry catalog.

Output lands in the current working directory by default:

bumblebee-baseline-2026-05-27T08-00-00Z.ndjson    # raw records
bumblebee-baseline-2026-05-27T08-00-00Z.log       # diagnostic stderr
bumblebee-baseline-2026-05-27T08-00-00Z.report.md # human-readable summary

Exposure catalogs

Bumblebee can match installed packages against a JSON exposure catalog. Minimal shape:

{
  "schema_version": "0.1.0",
  "entries": [
    {
      "id": "advisory-2026-0042",
      "name": "example-pkg 1.2.3 (compromised release)",
      "ecosystem": "npm",
      "package": "example-pkg",
      "versions": ["1.2.3"],
      "severity": "critical"
    }
  ]
}

Ready-made catalogs for recent supply-chain campaigns live in threat_intel/ of the upstream Bumblebee repo — point --exposure-catalog at a single file or a directory of *.json.

Privacy and safety notes

  • Scan output is local-only. The skill never uploads NDJSON or reports anywhere; you decide what happens with them.
  • MCP host configs can contain secrets in their env blocks. Bumblebee does not emit those values, but the diagnostic .log file may reference paths to sensitive config files. Treat the output as inventory data and review before sharing.
  • Never run bumblebee with sudo — it's meant to inspect the current user's developer environment, not the whole system.
  • The skill respects DSGVO data-minimization: no telemetry, no third-party services, no remote calls beyond Bumblebee's own (which itself is read-only).

Verify the claims

This skill makes a few specific claims that you (or any reviewer evaluating it for inclusion in a directory) can check without trusting me:

1. The skill is small and inspectable. No bundled binaries, no obfuscation:

git clone https://github.com/mycelos-ai/bumblebee-skill.git
cd bumblebee-skill
wc -l SKILL.md scripts/render_report.py     # ~150 + ~250 lines, that's it
file scripts/render_report.py               # ASCII text, Python 3

2. The report helper has no external dependencies. Run it in a fresh Python 3 against the bundled demo NDJSON — no pip install should be needed:

python3 scripts/render_report.py examples/demo.ndjson /tmp/demo.report.md
cat /tmp/demo.report.md

You should see a Markdown report with a critical finding, an inventory table, and a scan summary — built entirely from Python's standard library.

3. Bumblebee itself is read-only. That's a property of the upstream CLI, not this skill, but it's easy to verify:

go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest
bumblebee selftest                          # uses embedded fixtures, makes no network calls
bumblebee scan --profile baseline > /tmp/inv.ndjson

Then audit the upstream source — read-only behavior is documented and enforced at internal/scanner/ in perplexityai/bumblebee. On macOS, sudo dtruss -f bumblebee scan ... will show you only read, openat, fstat, getdirentries syscalls — no execve of package managers.

4. The skill installs Bumblebee via the official go install path only. Search the SKILL.md:

grep -nE 'go install|curl|wget|sudo' SKILL.md

You should see exactly one go install invocation (go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest — the official upstream command), zero curl | bash or wget patterns, and the only sudo mentions are (a) Linux-distro install hints for Go that the user runs manually, plus (b) an explicit guardrail telling Claude never to run bumblebee itself with elevated privileges. The skill does no privilege escalation on its own.

5. The skill produces only local files. No telemetry, no remote calls beyond what bumblebee itself does (which is none — see point 3). Search:

grep -nEi 'http[s]?:|post |upload|telemetry|analytics' SKILL.md scripts/render_report.py

Every match should be either a documentation link (https://github.com/perplexityai/bumblebee, https://go.dev/dl/) or a prose warning ("do not upload outputs to third-party services without consent"). No HTTP clients, no analytics SDKs, no upload calls in code.

Repo layout

.
├── SKILL.md                   # the skill itself — frontmatter + workflow instructions
├── scripts/
│   └── render_report.py       # NDJSON → Markdown report, stdlib-only Python 3
├── examples/
│   └── demo.ndjson            # tiny fixture for verifying render_report.py
├── tools/
│   └── publish-skill.sh       # automate PRs to public skill directories (optional)
├── LICENSE                    # MIT for this wrapper repo
└── README.md

Versioning

This wrapper repo follows the upstream bumblebee CLI loosely: when a Bumblebee release changes the NDJSON record schema in a way that affects the report helper, this repo gets a matching tag. The skill itself targets bumblebee@latest and degrades gracefully on unknown record types.

Contributing

Bug reports and PRs welcome — especially around the report helper (catching new record types or improving the diagnostics section) and the SKILL.md trigger phrases. For Bumblebee-CLI bugs, please file upstream at perplexityai/bumblebee.

License

MIT for this wrapper. See LICENSE. Bumblebee itself is Apache-2.0 — see its license.