Aletheore依赖安全完全指南:OSV漏洞检查+许可证分类+PR差异自动报告
Aletheore依赖安全完全指南:OSV漏洞检查+许可证分类+PR差异自动报告
Aletheore 是一款开源(AGPL-3.0)的依赖安全审计 CLI:一条命令扫描仓库,自动完成 OSV 漏洞检查、依赖许可证分类,还能以 GitHub Action 形式在 PR 上自动报告新增漏洞与密钥,让依赖安全审查从"人工逐包核对"变成"CI 自动把关"。
本指南面向第一次接触 Aletheore 的开发者,按"本地扫描 → 读懂结果 → 接入 CI"的顺序,带你在 10 分钟内搭好一套完整的依赖安全流程。
📌 核心能力一览
- 🔍 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 .
⚡ 提速细节:查询结果会缓存在 ~/.cache/aletheore/vulnerability-cache.json(TTL 24 小时)。因为新漏洞会不断披露到旧版本上,缓存故意保持短周期——既避免同一台机器一天内重复请求,又不会漏掉新披露的 CVE。
三、许可证分类:4 类 License 自动识别
引入一个 GPL 依赖到 MIT 项目里,是不少团队踩过的合规深坑。Aletheore 的许可证检查会:
- 读取仓库自身声明的许可证(
pyproject.toml、package.json的 license 字段,或 LICENSE 文件文本匹配) - 逐个查询每个依赖在对应注册表中的许可证(PyPI、npm、crates.io、Maven Central 等)
- 归入四个分类:
| 分类 | 示例 | 含义 |
|---|---|---|
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 的配套阅读手册 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 步)
- 分别 checkout PR 的 base 与 head 两个版本
- 对两个版本各跑一次
aletheore scan - 用
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)。
六、离线扫描与隐私控制:网络行为一目了然
依赖漏洞和许可证检查需要访问 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 体验内置演示,再迁移到你自己的仓库上。



