====== Bumblebee ======

//Vytvořeno: **31.5.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/perplexityai/bumblebee|Bumblebee]] je read-only scanner vývojářských endpointů pro sběr metadat o balíčcích, rozšířeních a vývojářských nástrojích uložených na disku. Slouží hlavně k rychlé odpovědi na otázku, jestli se na konkrétním stroji nebo ve vývojových projektech nachází známý kompromitovaný balíček, verze nebo rozšíření.

===== K čemu je dobrý =====

Bumblebee řeší úzký problém v oblasti software supply-chain incident response:

  * bezpečnostní tým nebo vývojář už ví, který balíček/verze jsou podezřelé nebo kompromitované,
  * scanner projde lokální metadata na vývojářském stroji,
  * výstupem je inventář komponent nebo nálezy odpovídající zadanému katalogu expozic.

Není to obecný detektor malwaru. Bumblebee neříká, že stroj byl kompromitován. Říká, že na disku existuje metadata stopa komponenty, která odpovídá známému rizikovému záznamu.

Typická otázka, na kterou odpovídá:

> „Vyšlo advisory na ''example-pkg@1.2.3''. Které vývojářské stroje nebo projekty tuto verzi obsahují?“

===== Jak zapadá vedle SBOM a EDR =====

Bumblebee vyplňuje mezeru mezi klasickým SBOM a EDR:

  * SBOM popisuje hlavně to, co se dostalo do buildu nebo výsledného artefaktu.
  * EDR popisuje běžící procesy, síťovou aktivitu a chování endpointu.
  * Bumblebee popisuje lokální vývojářský stav podle metadat na disku: lockfiles, package-manager metadata, editor extensions, browser extensions, MCP konfigurace a další podporované zdroje.

To je praktické hlavně u vývojářských strojů, kde mohou zůstávat staré projekty, cache, lokální virtuální prostředí, rozšíření editorů nebo MCP konfigurace, které nejsou vidět v produkčním SBOM.

===== Co skenuje =====

Přesný seznam čtených souborů je popsaný v [[https://github.com/perplexityai/bumblebee/blob/main/docs/inventory-sources.md|dokumentaci inventory sources]]. Podle aktuální dokumentace Bumblebee pokrývá hlavně tyto oblasti:

  * npm ekosystém: ''package-lock.json'', ''npm-shrinkwrap.json'', ''node_modules/.package-lock.json'', ''node_modules/<pkg>/package.json''
  * pnpm: ''pnpm-lock.yaml'' a metadata v ''.pnpm'' layoutu
  * Yarn: ''yarn.lock''
  * Bun: textový ''bun.lock''; binární ''bun.lockb'' je pouze diagnostikován
  * PyPI: metadata v ''.dist-info'' a ''.egg-info''
  * Go modules: ''go.sum'' a ''go.mod''
  * RubyGems / Bundler: ''Gemfile.lock'' a vybrané ''.gemspec'' soubory
  * Composer / Packagist: ''composer.lock'' a ''vendor/composer/installed.json''
  * MCP server konfigurace v JSON souborech, například ''mcp.json'', ''.mcp.json'', ''claude_desktop_config.json'' nebo vybrané konfigurace Gemini / Claude Code
  * browser extensions pro Chromium-family a Firefox-family prohlížeče
  * editor extensions pro VS Code, Cursor, Windsurf a VSCodium
  * Homebrew formulae a casks podle instalačních metadat

===== Co záměrně nedělá =====

Bumblebee je navržený jako read-only scanner. Podle dokumentace:

  * nespouští package managery jako ''npm ls'', ''pip show'', ''go list'', ''bundle list'', ''composer show'' nebo ''brew list'',
  * nečte zdrojové soubory,
  * neprovádí vlastní lookup do advisory databází,
  * nemá vestavěný globální feed zranitelností,
  * neextrahuje secrety,
  * u MCP konfigurací neemituje hodnoty ani názvy environment proměnných.

To je důležité pro bezpečné použití na vývojářských endpointech: nástroj pouze čte vybraná metadata a generuje strukturovaný výstup.

===== Základní model použití =====

Bumblebee potřebuje jeden ze dvou vstupů:

  * buď se používá jako čistý inventarizační scanner,
  * nebo dostane exposure catalog se seznamem známých kompromitovaných komponent.

Praktický tok při incidentu:

  - z bezpečnostního reportu nebo threat-intelligence zdroje vznikne seznam kompromitovaných balíčků a verzí,
  - seznam se převede do JSON exposure catalogu,
  - Bumblebee se spustí proti lokálním rootům,
  - výstupem jsou ''finding'' záznamy pro přesné shody.

===== Instalace =====

Bumblebee je Go projekt bez externích non-stdlib závislostí. Podle README vyžaduje Go 1.25+.

Instalace poslední vydané verze:

<code bash>
go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest
</code>

Instalace konkrétní verze:

<code bash>
go install github.com/perplexityai/bumblebee/cmd/bumblebee@v0.1.1
</code>

Po instalaci je vhodné spustit self-test:

<code bash>
bumblebee selftest
</code>

Self-test používá vestavěné fixture balíčky a nedělá síťové volání. Pokud selže, lokální instalace nedetekuje to, co má.

===== Scan profily =====

Bumblebee má tři profily. Každé spuštění je jednorázové: scanner proběhne a skončí. Periodicitu musí řešit externí runner, například cron, systemd, launchd nebo MDM.

==== baseline ====

Profil ''baseline'' skenuje běžné globální a uživatelské umístění:

  * Homebrew metadata,
  * systémové a uživatelské Python instalace,
  * language toolchain a version manager adresáře,
  * Go cache,
  * editor extensions,
  * browser extensions,
  * MCP konfigurace.

Použití:

<code bash>
bumblebee scan --profile baseline > baseline.ndjson
</code>

Hodí se pro pravidelný lehký inventář endpointu.

==== project ====

Profil ''project'' skenuje vývojové adresáře, například ''~/code'', ''~/src'', ''~/Developer'' nebo explicitně předané roots.

Použití:

<code bash>
bumblebee scan --profile project \
  --root "$HOME/code" \
  --root "$HOME/Developer" \
  > project.ndjson
</code>

Hodí se pro pravidelný inventář známých workspace adresářů.

==== deep ====

Profil ''deep'' je určený hlavně pro incidentní nebo kampaňové kontroly. Vyžaduje explicitní ''--root'' a umí projít široký adresář, například celý ''$HOME''.

Typické použití při známém incidentu:

<code bash>
bumblebee scan --profile deep \
  --root "$HOME" \
  --exposure-catalog ./catalog.json \
  --findings-only
</code>

''deep'' není ideální jako běžný denní scan všeho. Smysl dává hlavně tehdy, když už existuje konkrétní exposure catalog a cílem je rychle ověřit expozici.

===== Exposure catalog =====

Exposure catalog je JSON seznam známých rizikových komponent. Formát je jednoduchý a pracuje s přesnou kombinací ekosystému, názvu balíčku a verze.

Minimalistický příklad:

<code json>
{
  "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"
    }
  ]
}
</code>

Použití katalogu:

<code bash>
bumblebee scan --profile deep \
  --root "$HOME" \
  --exposure-catalog ./catalog.json \
  --findings-only
</code>

Pokud advisory popisuje rozsah verzí, je potřeba podle dokumentace počítat s tím, že Bumblebee v katalogu používá přesné shody. Takový rozsah je tedy potřeba buď převést na konkrétní verze, nebo dělat širší korelaci mimo Bumblebee nad inventářem.

===== Kde brát seznam kompromitovaných komponent =====

Bumblebee sám neříká, co je kompromitované. K tomu je potřeba threat intelligence nebo ručně připravený katalog.

Repozitář obsahuje složku [[https://github.com/perplexityai/bumblebee/tree/main/threat_intel|threat_intel]] s ukázkovými a udržovanými exposure katalogy pro vybrané supply-chain kampaně. Dokumentace k této složce výslovně doporučuje záznamy před produkčním použitím zkontrolovat proti aktuálním advisories.

Další praktické zdroje mohou být:

  * vendor advisories,
  * GitHub Security Advisories,
  * OSV,
  * Socket, Wiz, Snyk a podobné bezpečnostní reporty,
  * interní SOC/CERT vstupy.

Výsledek z těchto zdrojů musí být převedený do formátu exposure catalogu.

===== Výstup =====

Bumblebee zapisuje výstup jako NDJSON, tedy jeden JSON záznam na řádek. README a [[https://github.com/perplexityai/bumblebee/blob/main/docs/state-model.md|state model dokumentace]] popisují tři důležité typy záznamů:

  * ''package'' — záznam o nalezené komponentě,
  * ''finding'' — shoda s exposure catalogem,
  * ''scan_summary'' — závěrečný souhrn běhu scanneru.

U dlouhodobého sběru je důležité pracovat jen s kompletními běhy. Dokumentace doporučuje považovat běh za použitelný pro aktuální stav až po přijetí odpovídajícího ''scan_summary'' se stavem ''complete''.

Příklad filtrování inventáře přes ''jq'':

<code bash>
jq 'select(.record_type == "package" and .ecosystem == "npm")' inventory.ndjson
</code>

Hledání konkrétního balíčku:

<code bash>
jq 'select(.record_type == "package" and .normalized_name == "example-pkg")' inventory.ndjson
</code>

Zobrazení MCP záznamů:

<code bash>
jq 'select(.record_type == "package" and .source_type == "mcp-config")' inventory.ndjson
</code>

===== Doporučené praktické použití =====

Pro osobní nebo malý vývojářský setup dává smysl začít takto:

<code bash>
bumblebee selftest

bumblebee scan --profile baseline > baseline.ndjson

bumblebee scan --profile project \
  --root "$HOME/code" \
  > project.ndjson
</code>

Při konkrétní supply-chain kampani:

<code bash>
bumblebee scan --profile deep \
  --root "$HOME" \
  --exposure-catalog ./threat_intel/nejaky-katalog.json \
  --findings-only
</code>

Pro firemní použití dává větší smysl:

  * pravidelně sbírat ''baseline'' a ''project'' inventář,
  * ukládat NDJSON do centrálního systému,
  * při incidentu korelovat známé kompromitované komponenty proti posledním kompletním scanům,
  * ''deep'' používat jen jako cílený incidentní scan.

===== Omezení =====

Aktuální dokumentace uvádí, že Bumblebee zatím nepokrývá například:

  * Cargo / Rust ''Cargo.lock'',
  * Maven / Gradle,
  * NuGet,
  * Hex,
  * Swift Package Manager,
  * Safari extensions,
  * binární Bun ''bun.lockb'' decoder.

Je také potřeba počítat s tím, že nález je metadata stopa, ne důkaz spuštění nebo kompromitace. Pokud Bumblebee najde rizikový balíček, je to vstup pro další šetření a remediaci.

===== Shrnutí =====

Bumblebee je praktický nástroj pro rychlou kontrolu expozice vývojářských strojů vůči známým supply-chain kompromitacím. Největší hodnotu má ve chvíli, kdy existuje konkrétní seznam podezřelých balíčků nebo verzí a je potřeba rychle zjistit, kde se v lokálním vývojářském prostředí nachází.

===== Zdroje =====

  * [[https://github.com/perplexityai/bumblebee|Bumblebee – GitHub repozitář]]
  * [[https://github.com/perplexityai/bumblebee/blob/main/docs/inventory-sources.md|Bumblebee – Inventory sources]]
  * [[https://github.com/perplexityai/bumblebee/blob/main/docs/state-model.md|Bumblebee – State model]]
  * [[https://github.com/perplexityai/bumblebee/tree/main/threat_intel|Bumblebee – Threat intelligence katalogy]]