如何看懂bumblebee的NDJSON输出package、finding与scan_summary三类记录完全解析【免费下载链接】bumblebeeRead-only developer endpoint scanner for on-disk package, extension, and developer-tool metadata, built to check exposure to known software supply-chain compromises.项目地址: https://gitcode.com/gh_mirrors/bumblebee12/bumblebeebumblebee是一个只读的开发者端点供应链安全扫描器它把磁盘上的包、插件和开发工具元数据整理成NDJSON 输出每行一个 JSON 对象。扫描结束后你会看到三类核心记录package发现一个包、finding命中一个威胁情报目录和scan_summary本次运行的总结。这篇完整指南带你从零读懂这三种记录的每个字段轻松掌握接收与排查方法。一、先搞懂bumblebee 的 NDJSON 长什么样NDJSONNewline Delimited JSON就是“一行一个 JSON 对象”。bumblebee 每运行一次就往输出流里逐行写入记录格式直观、便于管道处理和日志采集{record_type:package,record_id:package:3fa9...,package_name:example-pkg,version:1.2.3,...} {record_type:finding,record_id:finding:81c2...,catalog_id:advisory-2026-0042,...} {record_type:scan_summary,run_id:9b1f0c2e...,status:complete,...}默认情况下记录写入stdout诊断信息diagnostic写入stderr你也可以改用文件或 HTTP 上报详见 docs/transport.md。 小贴士每类记录都有自己的record_id前缀package:、finding:、scan_summary:一眼就能区分类型。二、package 记录这台机器上装了什么record_typepackage的每一行都代表 bumblebee 在某个位置发现的一个软件包。它是整个输出的“主角”字段不多但信息密度很高字段含义新手关注点package_name/normalized_name包名 / 归一化后的包名匹配威胁目录用的是归一化名version版本号精确匹配的关键ecosystem生态npm、pypi、go、rubygems等共 10 种取值source_file证据来源文件如pnpm-lock.yaml定位“怎么发现的”root_kind发现位置类型如project_root、deep_home_root区分全局工具链 vs 项目install_scope/package_manager安装作用域、包管理器全局 or 项目级has_lifecycle_scripts是否带安装钩子脚本供应链投毒的高危信号confidencehigh/medium/low结论可信度分级以confidence为例它是判断记录可信度的核心high—— 身份和版本都来自权威元数据medium—— 身份可靠但版本或来源不完整low—— 仅配置/路径/规格引用不能当作“已安装该精确版本”的证据。字段结构定义在 internal/model/model.go机器可读的校验规则见 docs/schema/v0.2.0/package-record.schema.json。各生态具体读取哪些文件如package-lock.json、go.sum、Gemfile.lock参见 docs/inventory-sources.md。三、finding 记录哪些包命中了“威胁名单”record_typefinding是警报信号。当你传入威胁情报目录exposure catalog后bumblebee 会把发现的包与目录条目做精确匹配命中一行就产出一条 finding字段含义finding_type当前恒为package_exposurecatalog_id/catalog_name命中的目录条目 ID 与名称如某次投毒事件编号severity严重级别如criticalecosystem/normalized_name/version命中包的身份evidence匹配证据例如exact nameversion match (version1.2.3)source_file/project_path命中位置方便人工复核仓库自带的 threat_intel/ 目录维护了多份来自公开威胁情报的样例目录可以直接拿来做演练bumblebee scan --profile deep --root $HOME \ --exposure-catalog ./threat_intel --findings-only--findings-only会抑制 package 记录、只保留 finding 和 summary适合应急排查。finding 的完整字段表见 docs/schema/v0.2.0/finding-record.schema.json。⚠️ 注意finding 只代表“磁盘元数据上存在这个包”不是网络、进程或文件哈希层面的入侵证据——它回答的是“谁可能被波及”而不是“谁已经被攻击”。四、scan_summary 记录如何判断这次扫描是否可信每次运行必定以一条scan_summary结尾它相当于“运单回执”。接收端最重要的规则是只有看到statuscomplete的 summary才把本次运行的记录提升为当前状态。关键字段速查字段含义statuscomplete/partial/error见下方解释package_records_emitted实际发出的 package 行数package_records_suppressed被--findings-only抑制的行数findings_emitted发出的 finding 数duplicates运行内被去重合并的重复观察数diagnostics_countstderr 侧诊断条数files_considered解析过的文件数timed_out/duration_ms是否超时 / 耗时roots本次实际扫描的根路径及类型可作审计依据http_batches_*、http_last_status使用 HTTP 上报时的投递统计三种status的正确姿势complete—— 运行完成且无终止性错误可作为当前状态partial—— 发了一部分记录但中途出错只能当原始证据不能替换旧状态error—— 还没产出可用数据就失败了。另外若http_batches_failed 0即使其余解析成功该次运行也不算可信快照http_last_status0表示最后一批连 HTTP 响应都没拿到。这些语义细节完整记录在 docs/transport.md 的 “scan_summary completion semantics” 一节和 docs/state-model.md。五、record_id 与 run_id去重和跨运行关联的两把钥匙新手最容易混淆的字段对一次讲清run_id每次运行随机生成标识“这一趟扫描”。同一台机器两次运行的run_id必然不同。record_id内容寻址的 SHA-256 哈希由该记录类型的规范身份字段元组算出跨运行、跨机器稳定。比如同一个包在同一配置下被观察两次record_id完全一致。因此接收端可以放心地用(endpoint_id, run_id, record_id)做运行内去重用record_id做跨运行关联。哈希算法与字段元组见 internal/model/model.go 中的StableID()实现字段级清单见 docs/state-model.md。六、3 分钟动手体验用 selftest 看真实输出不用等真实告警bumblebee 内置了端到端自检使用完全虚构的包名如bumblebee-selftest-evil0.0.0不发任何网络请求bumblebee selftest # selftest OK (2 findings in 1ms)想亲手解剖记录流一条命令即可bumblebee scan --profile baseline inventory.ndjson然后用任意工具按record_type过滤三种记录即可。内置测试用的样例包、威胁目录等夹具位于 cmd/bumblebee/selftest/fixtures/可对照阅读。七、新手常见疑问 FAQQ1为什么我的 package 行数比预期少看duplicates——同一来源文件的重复观察会被合并再看--findings-only是否会抑制 package 记录此时package_records_suppressed为正数属正常。Q2package_records_emitted为 0 一定有问题吗不一定。--findings-only运行时它就是 0 且完全合法但statuscomplete且无该选项、却 0 条记录说明该 profile 下没有可解析的清单文件——这也是一个有效的空状态。Q3baseline 和 project 的结果能互相“抵消”吗不能。两个 profile 是独立人群populationbaseline 扫描不能删除 project 观察到的包反之亦然。deep只用于按需事件排查不应用于更新当前状态。详见 docs/state-model.md 的 “Promotion rule”。Q4字段变了怎么办每条记录都带schema_version当前为0.2.0。接收端应按schema_version分版本解析旧版本0.1.0的 schema 也仍保留在 docs/schema/v0.1.0/。总结记录类型一句话理解典型用途package“这台机器有这个包”构建端点清单、历史趋势finding“它命中了威胁目录”事件响应、暴露面排查scan_summary“这次扫描可信吗”状态提升、运行审计读懂这三类记录你就掌握了 bumblebee NDJSON 输出的全部关键信息用package建清单、用finding追暴露、用scan_summary保信任。配合 README.md 的快速开始章节和 docs/state-model.md 的接收端建模建议即可从“看到输出”进阶到“用好输出”。【免费下载链接】bumblebeeRead-only developer endpoint scanner for on-disk package, extension, and developer-tool metadata, built to check exposure to known software supply-chain compromises.项目地址: https://gitcode.com/gh_mirrors/bumblebee12/bumblebee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考