Bumblebee 怎么用：给开发机做一次 AI 供应链体检

从安装、自检、baseline 扫描到 exposure catalog 定向排查的保姆级教程

AI Stack Nav ｜ AI 工具教程 ｜ 2026-05-24

读者	适合阅读对象：开发者、独立站长、AI Agent/自动化工作流搭建者、DevSecOps 入门者，以及想检查本机依赖、MCP 配置和扩展风险的人。

目录

1. Bumblebee 是什么：它解决哪类风险
2. 为什么开发机也需要做 AI 供应链体检
3. Bumblebee 能扫描什么、不能扫描什么
4. 安装前准备：系统、Go 环境与权限边界
5. 第一步：安装 Bumblebee 并运行自检
6. 第二步：做一次 baseline 全局轻量体检
7. 第三步：扫描项目目录，找出真实开发依赖
8. 第四步：用 exposure catalog 做定向风险排查
9. 第五步：读懂 NDJSON 输出并生成整改清单
10. 团队落地方案：从个人体检到周期化安全巡检
11. Bumblebee 与 SBOM、OSV-Scanner、Snyk、EDR 的区别
12. 常见报错与排查方法
13. FAQ 常见问题

Bumblebee 是什么：它解决哪类风险

Bumblebee 是 Perplexity 开源的只读开发端点扫描器，面向 macOS 和 Linux 开发机，专门把本机磁盘上分散的包管理器元数据、锁文件、编辑器扩展、浏览器扩展和 AI 工具配置整理成结构化记录。

它要回答的不是“我的项目有没有漏洞”这么宽泛的问题，而是更具体的供应链响应问题：当安全公告点名某个包、扩展或版本时，哪些开发机现在能在本机元数据里看到命中痕迹？

定位	一句话理解：SBOM 更偏“交付物里有什么”，EDR 更偏“机器上运行过什么”，Bumblebee 关注的是“开发机磁盘上现在暴露了哪些供应链线索”。这正好补上 AI 开发环境中 MCP 配置、编辑器扩展、本地依赖散落难查的空白。

它不是传统漏洞扫描器

Bumblebee 默认不去访问漏洞数据库，也不会像通用 SCA 工具那样给每个依赖自动匹配 CVE。它更像一台“本机物料盘点仪”：先把真实存在的包、版本、来源文件和配置项列出来，再配合 exposure catalog 做精准命中。

它不是 EDR，也不是杀毒软件

Bumblebee 不监控进程、不抓网络流量、不阻断恶意行为。它强调 read-only，只读取明确范围内的元数据，不执行 npm、pip、go list 等命令，避免扫描动作本身触发 install script 或 postinstall 脚本。

为什么开发机也需要做 AI 供应链体检

过去很多团队把供应链安全重心放在 CI/CD、镜像、生产服务和制品仓库上。但 AI 编程工具普及之后，开发机本身变成了新的高价值入口：IDE 扩展可以读取项目，MCP Server 可能接触文件系统和外部服务，浏览器扩展可能影响账号会话，本地依赖则可能早已安装在多个项目目录里。

• 开发机通常保存代码仓库、API Key、SSH Key、云服务凭据、Cookie 和内部文档。
• AI Agent、MCP、编辑器插件让“本机配置”变成了新的自动化执行面。
• 供应链投毒事件发生时，安全团队最急迫的问题往往不是理论风险，而是“谁的电脑上已经出现了这个版本”。
• 只看仓库依赖文件不够，因为实际落在 node_modules、Python dist-info、浏览器扩展或 MCP 配置里的内容可能已经和仓库状态不一致。

Bumblebee 能扫描什么、不能扫描什么

下面这张表可以直接作为网站正文里的“能力边界速览”。写教程时建议先讲边界，再讲命令，这样读者不会误以为 Bumblebee 能一站式替代所有安全工具。

类别	Bumblebee 当前覆盖	适合解决的问题
npm / pnpm / Yarn / Bun	读取 package-lock、pnpm-lock、yarn.lock、bun.lock 以及部分 node_modules 元数据；v0.1 中 bun.lockb 只作为诊断存在。	排查某个被点名 npm 包或版本是否落在开发机上。
PyPI	读取 *.dist-info/METADATA、INSTALLER、direct_url.json、*.egg-info/PKG-INFO。	确认 Python 环境里是否存在被点名的包版本。
Go / RubyGems / Composer	读取 go.mod、go.sum、Gemfile.lock、gemspec、composer.lock、vendor/composer/installed.json。	覆盖多语言项目的本机依赖盘点。
MCP / AI 工具配置	读取 mcp.json、.mcp.json、claude_desktop_config.json、mcp_config.json、mcp_settings.json、cline_mcp_settings.json、~/.gemini/settings.json。	排查 AI Agent / MCP Server 配置里是否存在风险服务或异常来源。
编辑器扩展	读取 VS Code、Cursor、Windsurf、VSCodium 扩展 manifest。	定位被点名扩展是否安装在开发者机器上。
浏览器扩展	读取 Chromium 系列与 Firefox profile 内的扩展 manifest。	排查浏览器扩展供应链风险。

当前不适合用它做什么

• 不要把 Bumblebee 当作代码审计工具：它不读取业务源代码，也不判断代码逻辑是否安全。
• 不要把 Bumblebee 当作实时防护：它是 one-shot scanner，每次运行后退出，周期由 cron、launchd、systemd 或 MDM 负责。
• 不要把 Bumblebee 当作合规报告生成器：它输出 NDJSON 组件记录和 finding，需要你再做汇总、去重、整改跟踪。
• 不要期待它解析所有 AI 工具配置：例如 v0.1 中非 JSON 的 Codex config.toml、Continue YAML 不在解析范围内。

安装前准备：系统、Go 环境与权限边界

系统要求

• 操作系统：macOS 或 Linux。Windows 用户可先用 WSL 做实验，但不要把 WSL 结果等同于原生 Windows 开发环境。
• Go 版本：官方说明需要 Go 1.25+。建议先执行 go version 检查。
• 网络：安装阶段需要能访问 GitHub 与 Go module 下载源；正式扫描本身不需要联网。
• 权限：从普通用户权限开始，不要一上来 sudo 扫全盘；先确认 root 列表与输出内容。

建议的文件夹准备

mkdir -p ~/security/bumblebee
cd ~/security/bumblebee
mkdir -p output catalogs

建议把扫描输出、catalog 文件和整改记录统一放在一个目录下，方便复扫、归档和对比。团队使用时，可以把 catalog 走 Git 管理，把扫描结果进入内部日志平台或对象存储。

第一步：安装 Bumblebee 并运行自检

通过 go install 安装

# 安装最新 tagged release 到 $GOBIN
go install github.com/perplexityai/bumblebee/cmd/bumblebee@latest

# 如果要固定版本，可以显式指定标签，例如：
go install github.com/perplexityai/bumblebee/cmd/[email protected]

安装完成后，如果命令找不到，先检查 $GOBIN 或 $GOPATH/bin 是否已经加入 PATH。

# 查看 Go 安装路径
go env GOPATH GOBIN

# 常见做法：把 GOPATH/bin 加入 PATH
export PATH=”$PATH:$(go env GOPATH)/bin”

运行 selftest 自检

bumblebee selftest
# 预期输出类似：selftest OK (… findings in …ms)

bumblebee version

自检	为什么先跑 selftest：selftest 使用内置 fixture，不需要联网。它能快速确认本地二进制能正确识别预期的测试命中，适合作为个人安装后的烟雾测试，也适合作为团队分发前的健康检查。

第二步：做一次 baseline 全局轻量体检

baseline 适合日常轻量盘点，扫描常见全局/用户包根、语言工具链、编辑器扩展、浏览器扩展和 MCP 配置。它不适合扫整个 home 目录；如果要广泛扫 home，应使用 deep 并明确控制范围。

先预览将要扫描的根目录

bumblebee roots –profile baseline

这一步很重要：先看 Bumblebee 准备读取哪些 root，再决定是否继续扫描。对于团队推广，建议把 roots 输出也保存下来，方便解释扫描范围。

执行 baseline 扫描

bumblebee scan –profile baseline > output/baseline-inventory.ndjson

只扫描指定生态

# 只看 npm、PyPI 和 Go 生态
bumblebee scan –profile baseline \
  –ecosystem npm,pypi \
  –ecosystem go \
  > output/baseline-npm-pypi-go.ndjson

baseline 的核心价值是建立“这台开发机当前有哪些暴露面”的初始快照。第一次运行可以不做 findings-only，先留完整 inventory；后续遇到具体供应链风险时，再用 catalog 做精准命中。

第三步：扫描项目目录，找出真实开发依赖

project profile 适合扫描开发工作区，例如 ~/code、~/src、~/work、~/Developer。它比 baseline 更贴近实际项目依赖，适合作为团队例行巡检。

bumblebee scan –profile project \
  –root “$HOME/code” \
  –root “$HOME/Developer” \
  > output/project-inventory.ndjson

建议的项目目录策略

• 个人开发者：先填自己常用项目目录，不要直接扫整个家目录。
• 团队成员：统一约定项目根目录，例如 ~/work、~/src/company，减少漏扫和误扫。
• 临时排查：只针对近期接触过的仓库扫描，缩短运行时间，降低结果噪音。
• 输出命名：建议带上日期、机器或用户匿名编号，例如 project-2026-05-24.ndjson。

第四步：用 exposure catalog 做定向风险排查

Bumblebee 真正适合的场景，是“已经知道要查什么”。例如安全社区披露某个 npm 包的某个版本被投毒，或者某个编辑器扩展被下架，你就可以写成 catalog，然后让 Bumblebee 在本机元数据中精确匹配。

最小可用 catalog 示例

{
  “schema_version”: “0.1.0”,
  “entries”: [
    {
      “id”: “advisory-2026-0001”,
      “name”: “example-pkg 1.2.3 compromised release”,
      “ecosystem”: “npm”,
      “package”: “example-pkg”,
      “versions”: [“1.2.3”],
      “severity”: “critical”
    }
  ]
}

把上面的内容保存为 catalogs/example-advisory.json。注意 catalog 顶层必须是对象，包含 schema_version 与 entries；不要直接写成数组。

使用 catalog 进行 deep 扫描

bumblebee scan –profile deep \
  –root “$HOME” \
  –ecosystem npm,pypi,go \
  –exposure-catalog ./catalogs/example-advisory.json \
  –findings-only \
  –max-duration 10m \
  > output/findings-example-advisory.ndjson

应急	findings-only 的作用：当你只关心是否命中某个已知风险时，可以开启 –findings-only，压缩输出体积，只保留匹配到的 finding 与必要 summary。适合应急排查和批量收集。

第五步：读懂 NDJSON 输出并生成整改清单

Bumblebee 输出 NDJSON，即一行一个 JSON 对象。常见记录包括 package、finding、diagnostic、scan_summary。你可以用 jq、Python、日志平台或 SIEM 处理。

查看记录类型分布

cat output/baseline-inventory.ndjson \
  | jq -r ‘.record_type’ \
  | sort \
  | uniq -c

提取 finding 关键信息

cat output/findings-example-advisory.ndjson \
  | jq -r ‘select(.record_type==”finding”) | [
      .severity,
      .ecosystem,
      .package_name,
      .version,
      .source_file,
      .confidence,
      .evidence
    ] | @tsv’

整改清单模板

字段	说明	建议填写方式
风险编号	对应 catalog_id 或公告编号	advisory-2026-0001
命中对象	包、扩展或配置项名称	example-pkg
命中版本	Bumblebee 输出的 version	1.2.3
证据文件	source_file / project_path	保留路径但可脱敏用户名
置信度	high / medium / low	high 优先处理；low 需人工复核
处置动作	升级、删除、禁用扩展、移除 MCP Server、重装环境	写明具体命令或负责人
复扫结果	修复后重新运行同一 catalog	无 finding 后归档

团队落地方案：从个人体检到周期化安全巡检

个人开发者推荐流程

1. 安装 Bumblebee，并运行 selftest。
2. 执行 roots –profile baseline，确认扫描范围。
3. 跑一次 baseline 保存 inventory。
4. 对常用项目目录跑 project profile。
5. 遇到公告时写 catalog，执行 deep + –findings-only。
6. 对 finding 做升级、卸载、禁用或重装环境，最后复扫归档。

团队推广推荐流程

• 由安全负责人维护 catalog 仓库，所有新增条目必须带来源链接、影响范围、严重级别和审核记录。
• 通过 MDM、Jamf、osquery、cron、launchd 或 systemd 下发 one-shot 扫描任务。
• 输出先进入内部收集端，再由安全平台按 run_id、endpoint、record_type、catalog_id 去重。
• 不要把完整 NDJSON 原样发到公共群或外部工单，因为里面可能包含主机名、用户名、项目路径等内部信息。
• 保留 scan_summary，用于判断本次扫描是否完整、是否超时、是否需要重跑。

Bumblebee 与 SBOM、OSV-Scanner、Snyk、EDR 的区别

工具/方法	主要回答的问题	优势	限制
Bumblebee	开发机磁盘上是否出现被点名包、扩展、AI 工具配置或版本？	只读、适合应急暴露面排查，覆盖 MCP 与扩展等本机状态。	不自动查漏洞库，不替代 SCA/EDR。
SBOM	交付物或项目声明包含哪些组件？	适合制品治理、合规、交付追踪。	不一定反映开发机当前落盘状态。
OSV-Scanner	项目依赖是否命中 OSV 漏洞数据库？	适合仓库、CI、依赖漏洞检测。	重点是 manifest/lockfile 漏洞匹配，不覆盖全部本机扩展与 AI 配置。
Snyk / 商业 SCA	依赖、容器、代码、许可证等风险如何持续管理？	平台能力强，适合团队治理。	可能需要账号、平台接入和策略配置。
EDR	终端上运行了什么、是否有异常行为？	实时监控、响应和隔离能力强。	不一定能快速回答某个包版本是否在本机元数据中出现。

组合	组合使用建议：Bumblebee 更适合作为 DevSecOps 工具箱里的“本机暴露面体检器”。日常用 SBOM/SCA 管交付与仓库，用 EDR 管运行时行为；遇到投毒公告时，用 Bumblebee 补上开发机本地状态排查。

常见报错与排查方法

现象	可能原因	解决方法
bumblebee: command not found	GOBIN 或 GOPATH/bin 未加入 PATH	执行 go env GOPATH GOBIN，补充 PATH 后重新打开终端。
go: command not found	未安装 Go 或版本过旧	安装 Go 1.25+，再运行 go version 检查。
selftest 失败	二进制异常、版本不一致或本地构建失败	重新 go install 指定版本；团队分发前统一跑 selftest。
deep 扫描太慢	root 过大，扫描范围太宽	先限定 –ecosystem；缩小 –root；设置 –max-duration。
没有 finding	catalog 条目写错、生态名不匹配、版本不在本机	检查 ecosystem、package、versions；先跑 inventory 确认包名规范化结果。
结果里路径过多	输出包含 source_file 和 project_path	内部保存前可脱敏用户名；对外只保留必要证据字段。
MCP 配置未识别	配置文件不是当前支持的 JSON 文件名或格式	确认是否为 mcp.json、claude_desktop_config.json 等支持路径；非 JSON 配置需人工检查。

最佳实践清单：把“体检”做成可复盘流程

• 先跑 roots，再跑 scan：不要盲扫全盘。
• 先保存 baseline inventory，再做 findings-only 应急匹配。
• catalog 条目必须带来源、影响版本、严重级别和审核人。
• 输出文件按日期、profile、catalog 命名，便于复扫对比。
• finding 的整改动作要落到包升级、扩展禁用、MCP Server 移除或环境重建。
• 对 low confidence 的结果做人工复核，不要直接扩大影响面。
• 不要公开 raw NDJSON，至少脱敏 hostname、username、project_path、source_file。
• 把 Bumblebee 放进供应链应急流程，而不是单独依赖它做全部安全判断。

FAQ 常见问题

Bumblebee 适合普通用户吗？

如果你只是日常使用电脑、不写代码、不安装 AI Agent 或本地开发环境，Bumblebee 的价值有限。它更适合开发者、AI 自动化工作流使用者和团队安全人员。

Bumblebee 会不会读取我的源代码？

官方设计强调只读元数据，不读取业务源文件，也不执行包管理器命令。它主要读取锁文件、包安装元数据、扩展 manifest 和支持的 MCP JSON 配置。

扫描 MCP 配置会泄露 API Key 吗？

Bumblebee 会解析 MCP host config 以生成 server inventory，但不输出 env block 中的环境值。即便如此，扫描结果仍可能包含机器名、用户名和路径，分享前应脱敏。

为什么它不直接告诉我有没有漏洞？

Bumblebee 的定位是暴露面排查。它先告诉你本机有什么，再通过 exposure catalog 做精确匹配。漏洞情报、版本范围和处置策略需要由安全团队或其他漏洞数据库提供。

Windows 能用吗？

官方范围是 macOS 和 Linux。Windows 用户可用 WSL 做学习实验，但它不能完整代表 Windows 原生开发机状态。

baseline、project、deep 怎么选？

日常轻量盘点用 baseline；扫描明确工作区用 project；应急排查、指定根目录和 catalog 命中用 deep。

它能替代 OSV-Scanner 或 Snyk 吗？

不建议替代。OSV-Scanner、Snyk 更适合仓库/CI/漏洞数据库匹配；Bumblebee 更适合开发机本地状态和已知风险定向排查。

扫描后发现命中，下一步做什么？

先确认 finding 的 catalog_id、package、version、source_file 和 confidence；再升级或删除对应包/扩展/配置；最后用同一 catalog 复扫，确认 finding 消失并归档。

参考资料

• Perplexity AI Bumblebee GitHub 仓库：https://github.com/perplexityai/bumblebee
• Bumblebee README 与 docs 说明：安装、profile、输出、catalog 格式、扫描范围。
• MarkTechPost 对 Bumblebee 开源事件的报道：https://www.marktechpost.com/2026/05/23/perplexity-open-sources-bumblebee-a-read-only-supply-chain-scanner-for-developer-endpoints/
• Google Cloud 关于 AI supply chain security 的观点：https://cloud.google.com/transform/same-same-but-also-different-google-guidance-ai-supply-chain-security/
• GitHub Blog：Securing the AI software supply chain：https://github.blog/open-source/maintainers/securing-the-ai-software-supply-chain-security-results-across-67-open-source-projects/