bumblebee

# Bumblebee Security Scan

Bumblebee (https://github.com/perplexityai/bumblebee) is a read-only inventory collector that surfaces package, extension, and developer-tool metadata on developer endpoints. It answers a focused supply-chain question: when an advisory names a package or version, do any matches exist on this machine right now?

This skill drives a single Bumblebee scan from start to finish:

1. Verify Go is on the PATH (provide install guidance if not).
2. Verify or install the `bumblebee` binary.
3. Run the requested scan profile (`baseline`, `project`, or `deep`).
4. Save raw NDJSON output plus a Markdown report into the user's workspace.
5. Summarize findings — especially exposure-catalog matches — in the chat reply.

Communicate with the user in the language they used (German for Stefan). Code, commit messages, and on-disk file contents stay in English to match existing project conventions.

## When to Use This Skill

Use this skill when an advisory, incident report, or exposure catalog names compromised packages,
developer tools, browser/editor extensions, or MCP host configuration that may exist on a local
macOS or Linux developer endpoint.

Use it for read-only inventory and exposure checks. Do not use it to patch, uninstall, quarantine,
or otherwise mutate the scanned machine.

## Step 1 — Clarify the scan request

Before running anything, confirm two things with the user via `AskUserQuestion`, unless the message already pins them down:

- **Profile**: `baseline` (global package roots), `project` (specific dev folders like `~/code`), or `deep` (explicit `--root` paths, including `$HOME` for incident response).
- **Roots**: For `project` and `deep` profiles, ask which directories to scan. `deep` is the only profile that accepts a bare-home root.

If the user has an advisory or exposure-catalog file ready, also ask whether they want to pass it via `--exposure-catalog`. The skill does not ship its own catalogs — point them at `threat_intel/` in the Bumblebee repo if they ask where to find ready-made ones.

Skip the questions for one-liner asks like "lauf mal ne Baseline-Scan" — just run a baseline.

## Step 2 — Check Go

Run `command -v go && go version` in bash. Three outcomes:

- **Go ≥ 1.25 present** → continue.
- **Go present but < 1.25** → tell the user the version, explain Bumblebee needs Go 1.25+, and stop until they upgrade.
- **Go missing** → do not install Go automatically. Show platform-appropriate instructions and stop:
  - macOS: `brew install go` (or download from https://go.dev/dl/).
  - Debian/Ubuntu: prefer the official tarball from https://go.dev/dl/ because distro repos lag; `sudo apt install golang-go` only as fallback.
  - Fedora/RHEL: `sudo dnf install golang` or the official tarball.

After installation, the user must ensure `$GOBIN` (or `$HOME/go/bin`) is on `$PATH` so `bumblebee` is found later.

## Step 3 — Check or install Bumblebee

Run `command -v bumblebee && bumblebee version`. If missing:

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

Then re-check `bumblebee version`. If the binary still cannot be located, the user's `GOBIN`/`PATH` is likely misconfigured — surface the resolved `go env GOPATH` and `go env GOBIN` so they can fix it. Do not fall back to running the binary by absolute path silently; explain what is happening.

Once installed, also run `bumblebee selftest` as a sanity check. A non-zero exit means the local install is broken and the scan should not proceed.

## Step 4 — Run the scan

All scans write NDJSON to a file. Use the workspace folder for output so the user can open the results afterwards.

Output filenames (use the user's workspace path; the example below assumes `$OUT` is set):

- `bumblebee-<profile>-<UTC-timestamp>.ndjson` — raw records.
- `bumblebee-<profile>-<UTC-timestamp>.report.md` — Markdown report (generated in Step 5).

Pick a sensible `--max-duration` so a runaway scan does not hang the session. Reasonable defaults:

- `baseline`: 5m
- `project`: 10m
- `deep`: 15m (warn the user that scanning `$HOME` can still take longer; offer to raise the limit)

Always stream stderr to a sibling `.log` file — Bumblebee emits diagnostic NDJSON there that helps explain partial scans.

### Baseline

```bash
bumblebee scan --profile baseline \
  --max-duration 5m \
  > "$OUT/bumblebee-baseline-$TS.ndjson" \
  2> "$OUT/bumblebee-baseline-$TS.log"
```

Optional: scope to specific ecosystems if the user only cares about, say, npm and PyPI:

```bash
bumblebee scan --profile baseline --ecosystem npm,pypi ...
```

### Project

Each `--root` must be an existing absolute path. Reject bare `$HOME` for this profile (Bumblebee will reject it too — surface the message clearly).

```bash
bumblebee scan --profile project \
  --root "$HOME/code" \
  --root "$HOME/Developer" \
  --max-duration 10m \
  > "$OUT/bumblebee-project-$TS.ndjson" \
  2> "$OUT/bumblebee-project-$TS.log"
```

### Deep

Used for incident response — broad roots are allowed but should be paired with an exposure catalog and `--findings-only` whenever possible, so the output stays focused.

```bash
bumblebee scan --profile deep \
  --root "$HOME" \
  --exposure-catalog "$CATALOG" \
  --findings-only \
  --max-duration 15m \
  > "$OUT/bumblebee-deep-$TS.ndjson" \
  2> "$OUT/bumblebee-deep-$TS.log"
```

If the user has no catalog, run deep without `--findings-only` but warn them that the NDJSON file can grow large (hundreds of MB on dense developer machines).

## Step 5 — Generate the Markdown report

Run the bundled helper to turn the NDJSON into a human-readable report. Resolve
the helper from the installed Bumblebee skill directory; never run a
workspace-relative `scripts/render_report.py` from the scanned project.

```bash
BUMBLEBEE_SKILL_DIR="/absolute/path/to/the/bumblebee-skill-directory"
test -f "$BUMBLEBEE_SKILL_DIR/scripts/render_report.py"
python3 "$BUMBLEBEE_SKILL_DIR/scripts/render_report.py" \
  "$OUT/bumblebee-<profile>-$TS.ndjson" \
  "$OUT/bumblebee-<profile>-$TS.report.md"
```

The helper groups records by type and ecosystem, lists every `finding` record with its catalog entry and severity, and embeds the `scan_summary` for traceability. It is dependency-free Python 3 — no `pip install` needed.

If `render_report.py` exits non-zero (malformed NDJSON, missing summary), surface stderr to the user instead of silently producing an empty report.

## Step 6 — Present results

End the turn with:

- A short summary in chat: profile, root(s), record counts, and — most importantly — any findings with their severity. If there are zero findings, say so explicitly; silence on findings is the kind of thing that gets misread.
- `computer://` links to both the NDJSON and the Markdown report so the user can open them directly.
- If diagnostics in the `.log` file indicate skipped roots or read errors, mention it and link the log too.

Do not paste large chunks of NDJSON into the chat — it is noisy and not where the user will read it.

## Safety and privacy notes

- Bumblebee is read-only by design. Do not propose patches, deletions, or `npm uninstall` actions from inside this skill; the user runs remediation themselves once they know what is affected.
- MCP host configs can carry secrets in their `env` blocks. Bumblebee does not emit those values, but the `.log` file may still contain paths to sensitive config files. Treat the output files as containing inventory data and do not upload them to third-party services without the user's explicit consent (DSGVO-relevant).
- Never run `bumblebee` with elevated privileges (`sudo`). It is meant to inspect the current user's developer environment, not the whole system.

## Failure modes to watch for

- `bumblebee: command not found` after `go install` → almost always a `PATH`/`GOBIN` problem. Show `go env GOPATH GOBIN PATH` to debug.
- `refusing to scan bare home with profile baseline` → use `deep` for `$HOME`, or pick a subdirectory for `project`.
- Scan times out → either narrow the `--root` set, scope with `--ecosystem`, or raise `--max-duration`. Do not loop and retry blindly.
- Exposure catalog rejected → check that the JSON has both `schema_version` and `entries` keys (bare top-level arrays are rejected) and that `schema_version` is one Bumblebee understands.

## Limitations

- This skill only reports local inventory and exposure matches; it does not remediate affected packages, extensions, or configs.
- Scan coverage depends on Bumblebee's supported ecosystems, the selected roots, and the current user's filesystem permissions.
- Results are point-in-time evidence and should be re-run after package installs, dependency updates, or incident-response changes.

## Reference

See `scripts/render_report.py` for the report layout. Bumblebee's own documentation lives at https://github.com/perplexityai/bumblebee — consult `docs/inventory-sources.md`, `docs/transport.md`, and `docs/state-model.md` when a question goes beyond what this skill covers.

## Credit

Bumblebee is developed by Perplexity (https://github.com/perplexityai/bumblebee, Apache-2.0). All scan logic, output formats, and exposure-catalog semantics belong to that project. This repository is just a thin Claude-skill wrapper around the official `bumblebee` CLI; the wrapper itself is MIT-licensed (see `LICENSE`).