bumblebee-scanner

A cross-platform, npx/pnpm-compatible wrapper for Perplexity AI's Bumblebee supply-chain inventory scanner.

This CLI tool automatically handles the installation of the underlying Bumblebee binary, keeps the threat intelligence catalogs continuously synced without relying on local Git, and provides cross-platform desktop notifications if compromised or vulnerable packages are found in your projects.

Usage

Run immediately with NPX / PNPM DLX (Zero Install)

You can run the scanner immediately without installing it globally. It will download what it needs into a local cache (~/.bumblebee-scanner) and execute.

# Scan the current directory
npx bumblebee-scanner

# Or using pnpm
pnpm dlx bumblebee-scanner

Scan specific projects

Use the --root flag (or -r) to explicitly define which projects to scan. You can provide multiple roots.

npx bumblebee-scanner --root ./my-backend --root ./my-frontend --root ~/Workspace/other-project

Global Installation

If you prefer to have the command available globally on your system:

npm install -g bumblebee-scanner
# or
pnpm install -g bumblebee-scanner

# Then run it from anywhere:
bumblebee-scanner --root ~/Workspace/clients

How it works

1. Smart Binary Resolution:
   • On macOS and Linux, it automatically downloads the lightweight pre-compiled Bumblebee binary directly from GitHub Releases.
   • On Windows, it safely falls back to compiling the binary via Go (requires go to be installed on the system).
2. Git-Free Threat Intel Sync: Before scanning, it uses pure HTTP to download and extract the latest .json exposure catalogs directly from the upstream repository. It does not require git to be installed on the host machine.
3. Targeted Scanning: It runs bumblebee scan --profile project to safely read your lockfiles (package-lock.json, pnpm-lock.yaml, go.sum, etc.) without ever executing arbitrary package manager scripts.
4. Desktop Notifications (Safe for CI/CD): If a vulnerability is found, it prints a readable summary to your terminal and triggers a native OS notification (macOS Notification Center, Windows Toast, or Linux Desktop Notify). In headless environments (like GitHub Actions), notifications gracefully degrade to console logs.

Local Development & Testing

If you'd like to contribute or run the tests locally:

git clone https://github.com/SadekHM/bumblebee-scanner.git
cd bumblebee-scanner
pnpm install
pnpm test

License & Credits

This wrapper is licensed under the Apache License 2.0.

This tool acts as a wrapper for Bumblebee, an open-source tool created by Perplexity AI. Bumblebee is also licensed under the Apache License 2.0. Please see the CREDITS.md file for required attribution notices.