Aletheore依赖安全完全指南:OSV漏洞检查+许可证分类+PR差异自动报告

原创2026-11-05 11:51:111,923 阅读

Aletheore依赖安全完全指南:OSV漏洞检查+许可证分类+PR差异自动报告

Aletheore 是一款开源(AGPL-3.0)的依赖安全审计 CLI:一条命令扫描仓库,自动完成 OSV 漏洞检查、依赖许可证分类,还能以 GitHub Action 形式在 PR 上自动报告新增漏洞与密钥,让依赖安全审查从"人工逐包核对"变成"CI 自动把关"。

本指南面向第一次接触 Aletheore 的开发者,按"本地扫描 → 读懂结果 → 接入 CI"的顺序,带你在 10 分钟内搭好一套完整的依赖安全流程。

Aletheore 依赖安全审计宣传图:一个文件的修改如何通过依赖图追踪到五个关联模块

📌 核心能力一览

  • 🔍 OSV 漏洞检查:批量查询 OSV.dev,覆盖 Python、Node、Go、Rust、Java 等 9 大生态
  • 📜 许可证分类:自动识别 permissive / copyleft 四类许可证并提示风险
  • 🤖 PR 差异自动报告:GitHub Action 对比 base 与 head,只报告"这次改动新引入"的问题
  • 📊 本地 Dashboard:依赖图、漏洞数量趋势图,扫描结果一目了然
  • 🔒 确定性强扫描:本地扫描不调用 LLM、无需账号,可重复、可审计

一、快速上手:3 条命令完成首次依赖安全扫描

Aletheore 需要 Python 3.11–3.14 和 pipx。在你想审查的仓库目录下执行:

pipx install aletheore
aletheore scan .
aletheore dashboard .

执行 scan 后,Aletheore 会在仓库下生成 .aletheore/air.json 证据文件(结构见 schemas/air.schema.json),随后打开 dashboard 即可浏览依赖图、漏洞统计与历史趋势。

💡 提示:scan 是纯确定性扫描,不调用 LLM、不需要任何账号,可以放心在 CI 里反复运行。

二、OSV 漏洞检查:自动解析 9 大生态的依赖清单

很多工具只查 package.json 里的直接依赖,而 Aletheore 会解析仓库中所有深度的依赖清单,包括 lock 文件里的完整传递依赖树——间接依赖的漏洞同样会暴露出来。

支持的生态与清单文件:

生态 解析的清单文件
Python(PyPI) requirements.txt、pyproject.toml(含 optional-dependencies、Poetry 分组)
JavaScript(npm) package.json + package-lock.json(含 v1 老格式)
Go go.mod
Rust(crates.io) Cargo.lock、Cargo.toml
Java(Maven) pom.xml(含多模块、parent POM)
Ruby(RubyGems) Gemfile.lock、*.gemspec
PHP(Packagist) composer.lock、composer.json
.NET(NuGet) packages.lock.json、*.csproj、Directory.Packages.props
Swift(SwiftURL) Package.resolved

解析逻辑集中在 src/aletheore/vulnerabilities.py 的清单解析器列表中,随后所有依赖会一次性批量提交给 OSV.dev 接口,而不是逐个串行请求。每条命中的漏洞还会并行拉取详情,并按 CVSS v3.1 向量计算出 critical / high / medium / low 四个严重级别(无 CVSS 数据的漏洞不会被误判为"低危",而是原样保留)。

查看结果只需一条命令:

aletheore query vulnerabilities --path .

Aletheore 依赖安全检查对应的本地 Dashboard 依赖图,彩色节点展示模块间依赖关系

⚡ 提速细节:查询结果会缓存在 ~/.cache/aletheore/vulnerability-cache.json(TTL 24 小时)。因为新漏洞会不断披露到旧版本上,缓存故意保持短周期——既避免同一台机器一天内重复请求,又不会漏掉新披露的 CVE。

三、许可证分类:4 类 License 自动识别

引入一个 GPL 依赖到 MIT 项目里,是不少团队踩过的合规深坑。Aletheore 的许可证检查会:

  1. 读取仓库自身声明的许可证(pyproject.toml、package.json 的 license 字段,或 LICENSE 文件文本匹配)
  2. 逐个查询每个依赖在对应注册表中的许可证(PyPI、npm、crates.io、Maven Central 等)
  3. 归入四个分类:
分类 示例 含义
permissive MIT、BSD、Apache-2.0 宽松许可证,无特别约束
copyleft-weak LGPL、MPL、EPL、CDDL 文件级弱 copyleft
copyleft-strong GPL、AGPL 强 copyleft,衍生代码可能需同许可
unknown 注册表无法确认 需要人工跟进

分类规则在 src/aletheore/licenses.py 中实现。设计上有个贴心之处:只有非 permissive 的依赖才会作为 finding 出现——和漏洞检查"只报真实问题"的思路一致,避免报告被几百个 MIT 包刷屏。

aletheore query licenses --path .

Aletheore 许可证检查与漏洞排查可用的模块依赖关系图(AIRview),展示源码文件间的导入边

📝 注意:许可证分类是"事实性归类",不是法律兼容性裁决。分类结果帮你圈出需要人工确认的少数依赖,最终判断仍需结合分发方式与法务意见。

四、漏洞优先级:结合依赖图判断真实暴露面

扫描出的漏洞不等于等价的"危险"。Aletheore 的配套阅读手册 src/aletheore/manual/part-5-security.md 给出了明确的优先级规则:

  • 被代码实际 import 的包上的漏洞,优先于只出现在清单、却无处引用的包
  • 证据文件 air.json 中的 dependency_vulnerabilities.checked 字段告诉你检查是否真正执行过——当 checked 为 false 时,绝不能宣称"没有漏洞",而应引用 reason 字段说明
  • 密钥类 finding 的 match_preview 始终脱敏,报告中永远不要贴出真实值

这正是"证据驱动(evidence-grounded)"的含义:每个结论都指向可核查的文件与行号。

五、PR 差异自动报告:GitHub Action 一键接入 CI

本地扫描解决"现在有没有问题",而 PR 审查更关心"这次改动新引入了什么问题"。Aletheore 提供的 GitHub Action(定义见 action.yml)正是为此设计:

工作原理(3 步)

  1. 分别 checkout PR 的 base 与 head 两个版本
  2. 对两个版本各跑一次 aletheore scan
  3. 用 aletheore diff 对比两份 air.json,只输出新增 / 已解决的差异

报告三通道

  • 💬 PR 评论:新增/解决的密钥、依赖漏洞、分层违规,外加模块数、依赖图边数等汇总变化;后续 push 只更新同一条评论,不刷屏
  • ✏️ 行内标注:新密钥直接在 "Files changed" 对应行高亮(因为只有当前文件的密钥同时具备真实路径和行号,其余类型保留在评论中)
  • 📄 Step Summary:无 PR 的普通 push 也能在运行摘要里看到同一份报告

最小接入配置:

name: Aletheore
on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  evidence:
    runs-on: ubuntu-latest
    steps:
      - uses: Aletheore/Aletheore@v0.10.2
        with:
          fail-on-new-secrets: true
          fail-on-new-vulnerabilities: true

两个 fail-on-new-* 开关会让 CI 在发现新问题时以非零码退出,直接把依赖安全变成合并门槛。完整输入参数(base-ref、head-ref、full、post-pr-comment 等)见 action.yml;diff 命令本身还支持 --format sarif,可输出 GitHub 代码扫描直接消费的 SARIF 2.1.0 日志(用法见 src/README.md)。

Aletheore PR 差异自动报告效果:机器人评论将行为回归发现自动贴到 Pull Request 上,并附 reply/dismiss 交互

六、离线扫描与隐私控制:网络行为一目了然

依赖漏洞和许可证检查需要访问 OSV.dev 与各包注册表,如果你处于离线环境或希望完全本地化:

# 先看看这次扫描"可能"发出哪些网络请求(只解释,不执行)
aletheore scan . --explain-network

# 跳过注册表与静态分析检查,纯本地扫描
aletheore scan . --no-check-vulnerabilities --no-check-licenses --no-check-static-analysis

🔒 关键承诺:确定性扫描全程不调用 LLM,本地证据留在你自己机器上;跳过检查的结果会明确记录"未检查"而不是伪装成"无问题"。

七、常用命令速查表

我想…… 命令
完整扫描当前仓库 aletheore scan .
查看依赖漏洞清单 aletheore query vulnerabilities --path .
查看许可证分类清单 aletheore query licenses --path .
查看密钥发现 aletheore query secrets --path .
对比两次扫描的差异 aletheore diff old/air.json new/air.json
输出 SARIF 供代码扫描消费 aletheore diff old/air.json new/air.json --format sarif
打开本地 Dashboard aletheore dashboard .

每次 scan 都会把快照滚存到 .aletheore/history/(保留最近 20 份),aletheore query changes 即可对比"与上一次扫描相比发生了什么"。

八、小结

  • 一条 scan 命令即可覆盖 9 大生态的 OSV 漏洞检查与 4 类许可证识别,结果全部落在可核查的 air.json 证据里
  • query vulnerabilities / query licenses 让排查像查日志一样简单
  • GitHub Action 把"新增漏洞即失败"变成 CI 门禁,PR 评论 + 行内标注让审查者第一时间看到问题
  • 本地扫描确定性、无 LLM、可离线,网络行为可用 --explain-network 事先审计

从本地一条命令,到 PR 上的自动化门禁,Aletheore 让依赖安全审查真正"跑得起来"。建议先用 aletheore demo 体验内置演示,再迁移到你自己的仓库上。

登录后查看全文
Aletheore