构建 Python 依赖漏洞扫描器:从 CVE 数据库集成到自动化修复的完整实战

原创2026-10-08 23:23:431,995 阅读

构建 Python 依赖漏洞扫描器:从 CVE 数据库集成到自动化修复的完整实战

导读

本文围绕 Simple Vulnerability Scanner 项目,系统讲解如何构建一个面向 Python 生态的依赖漏洞扫描器。在当前仓库中,这一主题由 angela 项目完整落地:它读取 pyproject.toml / requirements.txt,通过 OSV.dev 聚合 CVE 数据库批量查询已知漏洞,借助 PyPI Simple API 获取最新版本,并基于自研的 PEP 440 版本解析器完成版本比较与安全修复建议。读完本文,你将掌握从"解析依赖清单 → 查询漏洞数据库 → 版本比较 → 风险分级 → 修复建议 → 报告输出 → 自动化扫描"的完整实现链路,并能在自己项目中复现同类能力。

angela 漏洞扫描命令行输出

一、为什么依赖漏洞扫描至关重要

1.1 供应链攻击的现实威胁

依赖漏洞扫描的价值来自供应链攻击的频发。该项目的 概念文档 记录了几起标志性事件:

  • 2020 年 SolarWinds 事件:攻击者在 Orion 软件构建流程中注入恶意代码,最终波及超 18,000 家组织,恶意代码还带有 SolarWinds 的合法签名。
  • 2022 年 PyTorch 供应链攻击:攻击者在 PyPI 上传恶意包 torchtriton,利用 pip 依赖解析器会接受更高版本号同名包的特性,让 pip install torch 的用户在特定时间窗口内装上了窃取 AWS 凭证与 SSH 密钥的恶意代码。
  • 2021 年 ua-parser-js 劫持事件:周下载量 800 万的合法 npm 包因维护者凭证被盗被劫持,被推入包含加密货币矿工和密码窃取器的恶意版本。

这三类攻击向量分别是依赖混淆(恶意包与内部包同名)、域名抢注式拼写攻击(requsts 冒充 requests)和包接管(窃取维护者账号或接管废弃包)。

1.2 直接依赖与传递依赖的盲区

requests 依赖 urllib3,urllib3 又依赖 certifi。如果 certifi 存在漏洞,你的应用即使从未直接引用它也会受影响——这正是原文档强调的"只扫描直接依赖是不够的"核心观点,也是 angela 作为入门项目刻意标注的局限(详见 挑战文档 中的传递依赖扫描扩展方案)。

二、CVE 数据库访问:从 NVD 到 OSV.dev 的聚合查询

原文档第一步要求"集成 CVE 数据库访问",列举了 pip-audit、NVD、CVE Details 等途径,并强调理解 CVE 如何被标识、如何通过 CVSS 评分、如何跨版本追踪。angela 的选择是直接接入 OSV.dev——一个聚合 GitHub Security Advisories、PyPA、NIST NVD 等来源的开源漏洞数据库。

2.1 OSV.dev 的两步查询模型

OSV.dev 的批量查询端点 https://api.osv.dev/v1/querybatch 一次可携带上千个"包名 + 版本"对。angela 的 OSV 客户端 按 ScanPackages 分四步执行:

  1. 批量查询:一次 POST 提交所有 {package, ecosystem: "PyPI", version} 查询,拿到精简的漏洞 ID 引用列表。
  2. 收集唯一 ID:汇总所有包命中的漏洞 ID。
  3. 并发补全详情:对每个唯一漏洞 ID 执行 GET /v1/vulns/{id},使用 errgroup.SetLimit(15) 限制并发为 15,获取 summary、severity、fixed 版本、references 等完整字段。
  4. 构建按包分组的结果:将漏洞归并回各自的包,并做 CVE/GHSA/PYSEC 别名去重。
// 批量查询请求体
{
  "queries": [
    {"package": {"name": "requests", "ecosystem": "PyPI"}, "version": "2.28.0"},
    {"package": {"name": "django", "ecosystem": "PyPI"}, "version": "3.2.0"}
  ]
}

2.2 CVSS 评分与严重级别提取

CVSS(通用漏洞评分系统)是风险评估的核心输入。OSV 返回的 severity 字段可能混用 CVSS_V3、CVSS_V4 甚至纯文本标签,因此 angela 的严重级别提取逻辑(internal/osv/client.go 中 extractSeverity)做了三层容错:

  1. 优先解析 CVSS_V3 / CVSS_V4 数值评分,映射到 CRITICAL / HIGH / MODERATE / LOW;
  2. 非标准评分体系直接跳过;
  3. 兜底读取 database_specific.severity 定性标签,最终缺失时返回 UNKNOWN。

原文档给出了一个重要的实战提醒:不要盲信严重级别字段。同一漏洞在不同来源可能采用不同评分体系(GitHub 的 MODERATE 标签 vs NVD 的 CVSS 数值),必须始终保留降级路径。

2.3 别名去重:一个漏洞三个 ID

CVE-2023-32681(MITRE)、GHSA-j8r2-6x86-q33q(GitHub)、PYSEC-2023-80(PyPA)其实是同一个漏洞。OSV 会同时返回这三个 ID。angela 的 isDuplicate 函数用"本 ID 或任一别名已见过"判定重复,避免把一次漏洞事件统计成三个漏洞。

三、解析依赖清单:pyproject.toml 与 requirements.txt

原文档第二步建议"解析系统包管理器枚举已装软件",对 Linux 调用 apt/yum/pacman 子进程,对 Python 环境使用 pip list。angela 采用了面向 Python 项目文件的另一种路径:直接解析声明式依赖文件,在安装发生之前完成安全检查,更适合 CI/CD 场景。

3.1 统一的 Dependency 数据模型

types.go 定义了贯穿整个扫描流水线的核心结构:

type Dependency struct {
    Name    string   // 包名,如 "requests"
    Spec    string   // 版本约束,如 ">=2.28.0"
    Extras  []string // 可选特性,如 ["async", "security"]
    Markers string   // 环境标记,如 "python_version>='3.8'"
    Group   string   // 依赖组,如 "dev"、"test"
}

五个字段分别对应 PEP 508 依赖声明中的核心要素:包名需按 PEP 503 归一化(小写、-/_/. 等价),Spec 是 PEP 440 版本约束,Extras 对应 requests[security] 语法,Markers 决定依赖是否被 pip 安装,Group 追踪 [project.optional-dependencies] 来源。

3.2 两种解析器

  • pyproject.toml 解析器(internal/pyproject/parser.go):基于 pelletier/go-toml 反序列化,抽取 [project.dependencies] 与 [project.optional-dependencies]。
  • requirements.txt 解析器(internal/requirements/parser.go):按行解析纯文本格式。

仓库测试样例 testdata/pyproject.toml 展示了两种组的差异:

[project]
dependencies = [
    "requests>=2.28.0",
    "django>=3.2,<4.0",
    "click>=8.0.0",
    "pydantic>=2.0",
    "flask[async]>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",  # Code formatter
    "ruff>=0.1.0",
    "mypy>=1.0.0",
]

注意 django>=3.2,<4.0 这种复合约束和 flask[async] 的 extras 语法都会被正确解析——这正是后续漏洞扫描需要的最小版本提取(>=3.2,<4.0 提取为 3.2)的来源。

四、本地漏洞数据库与缓存策略

原文档第三步建议用 JSON 文件或 Python 字典建立本地漏洞映射,优点是可离线定制。angela 在架构上走了"在线聚合数据库 + 本地结果缓存"的混合路线:

  • 漏洞数据源在线化:OSV.dev 充当"全球漏洞数据库",免去自行维护 CVE 映射的工作量,同时支持 PyPI、npm、Maven、Go 等多生态。
  • PyPI 版本列表本地缓存:在 ~/.angela/cache/ 下为每个包存一份 JSON,包含 etag、versions、cached_at 三个字段,默认 TTL 为 1 小时(见 缓存实现)。

4.1 ETag 条件请求:省流量的关键

ETag 是 HTTP 服务器返回的资源版本标识。angela 首次请求后把 ETag 存进缓存,后续请求携带 If-None-Match: {etag}:

  • 服务器返回 304 Not Modified:刷新 TTL(Touch),直接返回缓存版本;
  • 返回 200:解析新 JSON,更新缓存;
  • 返回 404:包不存在,立即报错不重试;
  • 网络错误且存在缓存:降级使用过期缓存,保证扫描不因瞬时网络问题整体失败。

4.2 原子写入与路径穿越防护

缓存写入采用"临时文件 + os.Rename"的原子写模式,崩溃时原缓存文件不受损坏。缓存键路径使用 filepath.Base() 剥离目录分隔符:即使包名被恶意构造为 ../../../etc/passwd,最终也只会在缓存目录生成 passwd.json,杜绝目录穿越写盘。

五、版本比较逻辑:从语义化版本到完整 PEP 440

原文档第四步强调版本比较要处理语义化版本、预发布版和版本区间,并推荐使用 packaging.version。angela 用 Go 从零实现了完整 PEP 440 规范——这是本项目最有技术含量、也最能体现"不设简化假设"的部分。

5.1 为什么 PEP 440 不是语义化版本

PEP 440 的完整语法是:

[epoch!]release[.pre-release][.post-release][.dev-release][+local]

真实例子:

版本串 含义
2!1.0 epoch 2 的 1.0 版,压过所有 epoch 0/1 的版本
1.0a1 alpha 预发布
1.0.post3 稳定后的补丁版
1.0.dev5 开发快照
1.0+ubuntu2 本地版本标签

如果用字符串排序会得到灾难性的错误结论:"1.0a1" > "1.0"(ASCII 里 a 大于空串)、"1.10.0" < "1.9.0"。2023 年 3 月有人误上传 certifi==2023.03.07a1 预发布版,凡是不正确实现 PEP 440 的工具都把用户从稳定版 2023.02.23 升级到了 alpha 版,直接搞坏构建——这正是 angela 从零实现 PEP 440 的理由。

5.2 单正则解析全组件

version.go 用一个编译正则同时捕获 epoch、release 段、预发布、post 发布(显式 post3 与隐式 -3 两种形态)、dev 发布和本地版本:

(?i)^v?
(?:(\d+)!)?                              # epoch
(\d+(?:\.\d+)*)                          # release 段
(?:[-_.]?(alpha|a|beta|b|preview|pre|c|rc)[-_.]?(\d*))?  # 预发布
(?:[-_.]?(post|rev|r)[-_.]?(\d*)|-(\d+))?                # post 发布
(?:[-_.]?(dev)[-_.]?(\d*))?              # dev 发布
(?:\+(a-z0-9?))?$             # 本地版本

ParseVersion 将捕获组解析为 Version 结构体(Epoch、Release []int、PreKind、PreNum、Post、Dev、Local)。Post 和 Dev 用 -1 哨兵值区分"不存在"与"存在但为 0",否则 1.0、1.0.post0、1.0.post 无法正确排序。

5.3 PEP 440 排序规则

Compare 按 epoch → release → 预发布 → post → dev 的优先级逐级比较。预发布排序通过 preKey 生成可排序二元组实现:

1.0.dev1 < 1.0a1 < 1.0b1 < 1.0rc1 < 1.0 < 1.0.post1
  • 只有 dev 后缀(无 pre 无 post)排在最前,返回 (math.MinInt, math.MinInt);
  • 预发布按种类排序(a=0, b=1, rc=2)再按编号;
  • 正式版与 post 版排最后,返回 (math.MaxInt, math.MaxInt)。

5.4 防御性策略:稳定版过滤

  • 默认过滤预发布:LatestStable() 跳过所有 PreKind != "" 或 Dev >= 0 的版本,避免误升 alpha/beta;
  • 显式预发布开关:--include-prerelease 标志供测试场景显式接受预发布;
  • epoch 感知:2!1.0 不会与 1.0 混淆。

六、风险评分、严重级别分级与修复建议

原文档第五、六步要求按严重级别(critical/high/medium/low)组织发现并给出修复建议,angela 将这两步合并进了命令流程。

6.1 严重级别过滤与忽略规则

漏洞结果会经过两层过滤后再展示:

  1. filterIgnoredVulns:剔除配置中 ignore-vulns 指定的漏洞 ID(已接受的残余风险);
  2. filterVulnsBySeverity:剔除低于 --min-severity 阈值的漏洞。

严重级别按 CRITICAL → HIGH → MODERATE → LOW 顺序展示(终端输出见 output.go)。

6.2 修复版本与更新决策

每个漏洞记录都携带 FixedIn 字段(从 OSV 的 affected[].ranges[].events[].fixed 解析),给出首个修复版本;若尚无补丁则为空。UpdateResult 结构体记录了包名、旧版本约束、新版本约束以及变更类型:

type UpdateResult struct {
    Name    string
    OldSpec string
    NewSpec string
    OldVer  string
    NewVer  string
    Change  string  // "major" | "minor" | "patch"
    Skipped bool
    Reason  string
}

变更类型由 ClassifyChange 基于 release 段判定:主版本号不同 → major,次版本号不同 → minor,否则 → patch。终端输出按颜色区分(红色=major、黄色=minor、绿色=patch)。--safe 标志跳过 major 升级,防止 django==3.2 被直接升到 4.x 引发破坏性 API 变更。

6.3 配置驱动的行为定制

config.go 支持两个配置位置,按级联顺序加载:

# 方式一:项目根目录 .angela.toml
min-severity = "moderate"
ignore = ["django"]                # 更新时跳过
ignore-vulns = ["CVE-2023-1234"]  # 抑制的已知漏洞

# 方式二:pyproject.toml 内的 [tool.angela] 段(等价写法)
[tool.angela]
min-severity = "moderate"
ignore = []
ignore-vulns = []

min-severity 在加载时会被 strings.ToLower(strings.TrimSpace(...)) 归一化,"CRITICAL" 与 " critical " 统一为 "critical" 参与比较。angela init 命令会生成带注释的 pyproject.toml 模板,其中就包含这三项配置的注释示例。

七、多格式报告:终端、JSON 与可机器消费输出

原文档第七步要求生成纯文本、JSON、CSV 等多格式报告并包含扫描日期、系统信息等元数据。angela 的内置实现是彩色终端报告:

  • 更新列表按变更类型着色;
  • 漏洞按严重级别分组展示;
  • 汇总(ScanResult)包含总包数、总更新数、漏洞总数、耗时。

ScanResult 结构体同时承载了 Updates、Vulnerabilities、TotalPackages、TotalUpdated、TotalVulns、VulnsScanned、Duration 等字段,为机器可读输出预留了数据基础。仓库的 挑战文档 给出了完整的 --json 输出模式实现方案——定义 JSONOutput 结构体、json.MarshalIndent 序列化、--json-compact 单行模式,并配套 angela scan --json | jq '.vulnerabilities[].package' 的验证命令,可直接用于 CI/CD 流水线生成 GitHub Actions 注解。

八、自动化扫描工作流

原文档第八步要求通过 cron 或任务计划器定时扫描并接入邮件、Slack、webhook 通知。angela 以 CLI 单次执行为设计目标,但为自动化预留了完整路径:

8.1 定时任务编排

CLI 的无状态设计天然适配 cron:angela scan --file pyproject.toml --min-severity high 单条命令即可产出漏洞报告,退出码与输出可供 cron 收集。just dev-scan 等快捷命令封装了针对测试样例的标准调用。

8.2 守护进程与通知(扩展挑战)

挑战文档 第 7 项给出了连续监控守护进程的完整设计:

  • 文件监听:fsnotify 监听 pyproject.toml,事件防抖 5 秒后触发扫描;
  • 后台扫描:扫描不阻塞主循环,每分钟限一次,上次结果存入 ~/.angela/daemon_state.json 以便区分"新增漏洞"与"既有漏洞";
  • 通知:新 CVE 写入 ~/.angela/daemon.log,可选 webhook 推送 Slack/Discord、notify-send 桌面通知;
  • 优雅退出:监听 os.Interrupt / SIGTERM,取消进行中的扫描并落盘状态。

第 8 项挑战还提供了私有漏洞数据库插件化方案:定义 Source 接口(Name()、ScanPackages()、IsReachable()),让 OSV.dev、Snyk、企业内部漏洞库通过同一接口并行查询并按 ID 去重合并。

九、命令速查与运行指引

命令 作用 关键标志
angela init 生成带 angela 配置注释的 pyproject.toml —
angela update [path] 更新依赖到最新稳定版 -f/--file、--safe(跳过 major)、--vulns(同步扫描)、--include-prerelease
angela check [path] 预览可用更新,不修改文件 同上
angela scan [path] 仅做漏洞扫描 -f/--file
angela cache clear 清空 PyPI 版本与 ETag 缓存 —
全局 最低报告级别 --min-severity critical/high/moderate/low

本地快速体验(在当前仓库内):

go mod download
go run ./cmd/angela scan --file testdata/pyproject.toml
go run ./cmd/angela check --file testdata/pyproject.toml   # 干跑,不落盘
go run ./cmd/angela update --vulns --file testdata/pyproject.toml  # 更新 + 扫描

提示:PyPI Simple API 限速约 10 请求/秒,angela 默认 10 个并发 worker(internal/pypi/client.go 中 maxWorkers);若被限流可调低并发或执行 angela cache clear 后重试。缓存 TTL 为 1 小时,重复扫描基本走缓存命中。

十、实现要点与常见陷阱回顾

结合 实现指南,构建同类工具时有四个高频陷阱值得牢记:

  1. 包名未归一化:Django vs django。必须按 PEP 503 归一化(小写、-/_/. 等价),否则查询 PyPI 会 404。
  2. 忽略预发布过滤:取"最新版本"不能简单 versions[len-1],必须走 LatestStable() 过滤 alpha/beta/dev。
  3. 无视 context 取消:重试等待和睡眠必须配合 select { case <-ctx.Done(): ... },否则用户 Ctrl+C 后工具仍空转。
  4. 重试不做退避:固定 time.Sleep(1s) 在 API 过载时会火上浇油,指数退避(500ms → 1s → 2s)给服务恢复时间。

十一、项目边界与后续深化方向

angela 作为一个入门项目有三个明确边界:

  • 不扫描传递依赖:只检查依赖文件中显式列出的包,requests 依赖的 urllib3 漏洞需要另行列出才能发现;
  • 不支持离线模式:查询依赖 PyPI 与 OSV.dev 网络可达;
  • 单项目单次执行:CLI 每次面向一个依赖文件。

对应的深化路径在 挑战文档 中按难度分层给出:从简单的"严重级别背景色高亮""缓存命中统计"起步,到中等难度的 requirements.in 支持、传递依赖 BFS 解析、CycloneDX/SPDX SBOM 生成,再到进阶的守护进程与私有漏洞库插件。其中传递依赖解析需要调用 PyPI JSON API(https://pypi.org/pypi/{package}/json,Simple API 不携带依赖信息),并可能涉及 PubGrub 类约束求解算法,可进一步结合仓库内 API 限流器项目 理解 OSV.dev 与 PyPI 采用的 HTTP 限流机制。

结语

从"查询 CVE 数据库"到"生成自动化报告",Simple Vulnerability Scanner 的完整实现回答了原文档提出的每一步构建要求:OSV.dev 承担聚合漏洞数据源,pyproject.toml / requirements.txt 解析器完成包清单枚举,自研 PEP 440 解析器解决版本比较这一最易出错的技术点,严重级别分级与 FixedIn 修复版本构成风险评估闭环,update/check/scan 命令与 ETag 缓存则让安全扫描真正可落地、可重复执行。无论你是要把这套流程接入 CI,还是基于 概念文档 与 架构文档 从头复刻,本文覆盖的每一个环节都提供了可验证的源码依据与可直接运行的命令。

登录后查看全文
Cybersecurity-Projects