1. 为什么依赖扫描是现在Python项目的必修课先说个我自己的经历。前年我接手维护一个内部数据分析平台代码本身没多大问题跑得也算稳但每次安全部门做巡检给出来的报告里永远有一条“高危漏洞”挂在那边位置就在依赖列表里。一开始我没太当回事觉得不就是个第三方库版本旧了点嘛又不对外开放能有多大风险。直到有一次一位同事在某个公开的代码仓库里发现我们用的那个旧版库已经在官方公告里被标记为“已被利用”级别攻击者可以通过特定的请求方式直接让服务进程崩溃甚至有可能执行恶意代码。那天我们几个人连夜升级依赖、改代码才把问题压下去。从那之后我养成一个习惯任何一个Python项目不管多小都要做依赖漏洞自动扫描。这个动作成本极低却能提前拦住很大一批本可以避免的问题。所谓的“依赖漏洞自动扫描工具”简单说就是把项目里所有用到的第三方库列出来跟公开的漏洞库做对比一旦发现某个版本存在已披露的安全问题时工具会提示你涉及的库名、受影响版本、风险等级以及可以修复到哪个版本。这类工具解决的痛点是你根本不可能手动去跟踪每一个库的每一个安全通告。一个稍微复杂点的Python项目随便就是几十上百个依赖而这些依赖下面还有各自的依赖它们会不断更新、不断曝出新的漏洞。指望靠人肉盯完全不现实。Python本身是一门非常好用的语言开发效率高生态也丰富爬虫、数据分析、可视化、量化交易什么都能干。但正因为第三方库太多、更新太快依赖安全隐患就成了一个被很多人忽视的角落。这篇文章我会从工具选型、实操流程、CI集成、问题排查这几个维度把“怎么给自己的Python项目加一道自动的依赖安全检查”这件事讲清楚。2. 主流扫描工具横评pip-audit、Safety、OSV-Scanner 怎么选市面上做Python依赖漏洞扫描的工具不少但我实测下来真正值得放进工具箱的其实是几款主流选手。先讲结论再逐个拆解。2.1 pip-audit官方系首选项适合绝大多数项目pip-audit 是 Python 软件基金会PSF旗下的一个项目目前也已经是 PyPA 的成员之一。它的工作方式很直接在你当前的环境里或者在一个指定的 requirements 文件里解析出所有依赖包及版本然后查询 Python 安全咨询数据库PyPI 官方维护的安全源把有已知漏洞的包列出来。我最喜欢它的一点是它支持你直接扫描整个虚拟环境。也就是说你在项目目录下执行pip-audit它会自动检测当前环境里装了哪些包、什么版本、有没有漏洞、安全修复版本是多少。如果你跟我一样平时喜欢在虚拟环境里直接跑项目这个功能用起来非常顺手。它的另外一个亮点是输出格式丰富。默认是纯文本表格但你可以用-f json输出成 JSON 格式方便后续接脚本分析还可以用-f markdown生成 Markdown 格式的报告直接贴到项目的文档或 issue 里非常直观。当然pip-audit 也不是没有缺点。因为查询的是官方安全源它更新是有延迟的某些新披露的漏洞未必能在第一时间覆盖到。不过对我这种“求稳”的用法来说它作为第一道防线完全够用。2.2 Safety老牌工具数据库更庞大但免费版有门槛如果你关注 Python 安全工具的时间比较长一定听说过 Safety。它以前叫pyup.io的安全检测部分后来独立出来成为很多企业团队的首选。Safety 的漏洞源比官方源要全一些覆盖的数据库更广更新也更及时。但这里有个关键点你必须知道Safety 从 2020 年之后调整了策略它的完整漏洞数据库不再对外完全免费开放。免费版本能用的依然是命令行扫描、本地数据库检测但如果你想使用最新、最全的漏洞数据源就需要付费订阅。我用过一段时间免费版基本功能没问题可以满足日常扫描需求只是它的输出建议里有时候会引导你去购买商业服务这个就看个人能不能接受了。如果你的项目是商业项目并且对漏洞数据的实时性和全面性有硬性要求Safety 的付费版可以考虑。但如果你只是个人项目、学习项目或者团队预算有限pip-audit 其实已经足够覆盖绝大部分场景。2.3 OSV-Scanner 和 Trivy更广生态的视角Google 开源的 OSV-Scanner 也值得关注。它的特点是直接对接 OSV.dev 这个全球开源漏洞数据库数据的来源更广泛不只是 PyPI还覆盖 npm、Maven、Go、Rust 等多种生态。你可以用一份配置同时扫描不同语言的依赖。对纯 Python 项目来说它可能没有 pip-audit 那么轻量但如果以后你的项目变成了多语言混合架构提前熟悉 OSV-Scanner 是有好处的。Trivy 则是更偏向容器和基础设施安全扫描的工具它扫描的覆盖面包含了操作系统依赖、语言依赖、IaC 配置等等。如果你的 Python 应用最终是打包成 Docker 镜像部署的那么 Trivy 直接扫镜像会比单纯扫描 requirements 文件更符合“最终交付物安全”的思路。2.4 选型建议按场景对号入座工具的选型没有绝对标准关键看你的使用场景。使用场景推荐工具理由个人项目、学习项目、中小规模项目pip-audit免费、轻量、官方维护、接入CI简单商业项目对漏洞数据全面性要求高Safety 付费版 / OSV-Scanner数据库覆盖广更新时间更快容器镜像部署、云原生环境Trivy直接扫描镜像和基础设施配置多语言混合项目OSV-Scanner一份配置覆盖多个语言生态我目前的主力组合是开发环境用 pip-audit 跑日常扫描部署前用 Trivy 扫最终镜像。这个组合兼顾了开发效率和交付安全实测下来很稳。3. 从零搭建一套依赖漏洞扫描流程工具选好了下面进入实操环节。我会从项目依赖锁定、基础扫描、结果解读、自动修复这几个环节逐步推进。3.1 先把依赖版本锁死扫描的前提在使用依赖扫描工具之前有一个前提条件必须满足你的项目依赖版本是明确固定的。如果 requirements.txt 里写的是requests2.20这种版本范围扫描工具顶多告诉你这个范围涉及的部分版本有漏洞但没法精确定位到你实际运行的版本。所以在做扫描之前我建议先把依赖锁死。这一步很简单在虚拟环境里执行pip freeze requirements.txt这条命令会把当前虚拟环境里所有已安装的包名和精确版本号导出到 requirements.txt。之后无论是本地部署还是打包镜像都基于这份文件安装依赖这样扫描工具能精确匹配到你真实的依赖版本。如果你是使用 Poetry 或 Pipenv 的项目它们本身就带有锁定文件分别是poetry.lock和Pipfile.lock锁定逻辑更严谨这种情况可以直接利用已有的锁文件作为扫描依据。3.2 pip-audit 基础扫描实操装一个全新的虚拟环境然后安装 pip-auditpip install pip-audit安装完成后在项目目录下执行最简单的扫描pip-audit它会自动检测当前 Python 环境的依赖情况并输出结果。如果一切正常会提示No known vulnerabilities found如果扫描到问题输出大概长这样Found 2 known vulnerabilities in 1 package Name Version ID Fix Versions ------------ ------- ---------------- ------------- requests 2.19.1 PYSEC-2023-123 2.31.0这里的关键信息是四列包名、当前版本、漏洞编号、修复版本。如果你只是想扫描某个特定的 requirements 文件而不希望影响当前环境用-r参数pip-audit -r requirements.txt这样它会直接解析文件内容不会动你当前的环境适合在 CI 流程里使用。3.3 看懂扫描结果漏洞编号、风险等级、修复版本很多刚接触扫描工具的人看到结果后第一反应是“有漏洞那我升级就好了”。这个想法方向没错但不能盲目操作。你要先学会看漏洞编号和风险信息。漏洞编号通常长这样PYSEC-2023-123。这个编号对应的是 Python 安全咨询数据库里的某一条通告。看到编号后你可以到对应的数据库网站查询详情里面会写明漏洞的触发条件、影响范围、修复建议。比如某个漏洞只影响requests的 2.19 到 2.30 版本且只有在你使用了特定函数并传递恶意参数时才会触发那你就要判断你的业务代码是否满足这些触发条件。另外你需要关注修复版本。工具一般会直接告诉你“Fix Versions”列也就是修复了该漏洞的版本号。升级到这个版本之后漏洞才能解除。只看修复版本还不够你还需要在升级前确认一件事新版本跟你的业务代码是否兼容。这里我习惯的做法是先小范围升级跑一遍项目的核心测试用例确认没有兼容性问题后再统一更新。切忌看到漏洞就“全量升级到最新版”这样很可能会引入新的兼容问题或行为变化得不偿失。3.4 自动修复与升级避坑尊重语义化版本pip-audit 没有提供“自动修复”的功能只负责发现漏洞。但幸运的是你可以借助pip-audit输出的修复版本提示结合pip install --upgrade手动升级或者用 pip-tools 这类工具来辅助管理。比如刚才的例子中输出显示requests的修复版本是2.31.0你可以执行pip install requests2.31.0升级后再次运行pip-audit确认问题消失。这里要特别提醒一点升级依赖时尽量遵循语义化版本规范。也就是说对于主版本.次版本.修订版本的结构如果修复版本只是“修订版本”的变更比如从 2.30.1 升到 2.30.2那是推荐优先选择的因为这种升级通常只修复问题不改变 API 行为。如果修复需要跨“次版本”比如从 2.x 升到 3.x就要格外小心因为新的次版本可能已经移除了某些 API 或改变了默认行为。我的实操心得是能小步升级就小步升级先修到最低修复版本然后再评估是否值得追逐最新版本。很多漏洞的修复版本设计得都比较保守直接升到那个版本通常不会有太大问题。4. 把漏洞扫描嵌进日常开发CI、定时任务与依赖更新策略扫描工具如果只是想起来的时候跑一下效果会大打折扣。依赖库会持续更新新的漏洞会不断被发现所以“自动”才是关键。这里的自动有两层含义一是在提交代码时自动扫描二是定时扫描做持续性监控。4.1 在 GitHub Actions 里加一道扫描关卡如果你的项目托管在 GitHub 上可以直接通过 GitHub Actions 把 pip-audit 加进工作流。这样每次 push 代码或提交 Pull Request 的时候系统都会自动跑一次依赖扫描发现问题就直接阻断合并。下面是一个典型的 workflow 配置name: dependency-audit on: push: paths: - requirements*.txt - pyproject.toml pull_request: paths: - requirements*.txt - pyproject.toml schedule: - cron: 0 2 * * 1 jobs: audit: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install pip-audit - name: Run pip-audit run: | pip-audit -r requirements.txt -l improvised这个配置文件做了三件事第一监听 requirements 文件的变更。只要依赖文件有改动就会触发扫描第二支持定时任务每周一凌晨两点自动跑一次全量检查第三指定了-l improvised参数表示不依赖本地环境直接从远程源解析依赖信息。这个参数在 CI 环境里很有用避免本地虚拟环境不一致导致的误判。你可以根据自己的需求调整python-version和cron时间甚至把扫描结果通过邮件或 Slack 机器人推送出来。4.2 在 GitLab CI 或其他平台上的集成如果你的团队用的是 GitLab CI原理是一样的只是配置文件格式不同。在.gitlab-ci.yml里加一个 job 就行了dependency-audit: stage: test image: python:3.11 script: - pip install pip-audit - pip-audit -r requirements.txt -l improvised only: changes: - requirements*.txt - pyproject.toml把扫描作为一个独立的 stage 放进测试流程中一旦扫描发现高危漏洞可以让这个 job 失败从而阻断进入下一步构建流程。4.3 本地定时扫描适合个人项目的小方案如果你的项目没上 CI或者你觉得跑 GitHub Actions 太麻烦也可以利用操作系统的定时任务在本地定时执行扫描。在 Linux / macOS 上可以用 croncrontab -e然后在打开的配置文件里加一行0 9 * * 1 cd /path/to/your/project /path/to/venv/bin/pip-audit -r requirements.txt /var/log/pip-audit.log 21这样每周一早上九点自动跑一次扫描并把结果追加到指定日志文件里。Windows 用户可以借助“任务计划程序”配置同样的定时任务。4.4 依赖更新策略第一时间修补而不是追求最新在 CI 加了扫描之后你可能会频繁收到“发现漏洞”的告警。这时候就需要一套自己的依赖更新策略了。我的建议是优先修补而非盲目升级到最新。扫描工具给出修复版本后先评估这个修复版本是否兼容你的代码。如果代码量不大测试覆盖也够可以直接升级到修复版本如果代码量很大或者涉及核心依赖就需要分阶段处理。关注依赖的间接依赖。很多时候漏洞并不在你直接引用的库里而是这个库的“下游依赖”出现了问题。比如你用了 A 库A 库依赖了 B 库而 B 库有漏洞扫描工具也会把 A 库标注为受影响。遇到这种情况你可以先看看有没有更新版的 A 库它是否升级了对 B 库的依赖要求。如果 A 库本身不更新你也可以通过pip install B修复版本的方式强制在项目里覆盖 B 库的版本。保持依赖的“新鲜度”习惯。我一般会在两周左右统一做一次依赖升级的小版本更新选择工作量最小的时候顺手做掉。这样做的好处是依赖库不会因为长期不更新而积累太多漏洞每次升级的 diff 也比较小出问题的概率低。5. 常见问题与排查技巧实录在实际使用扫描工具的过程中我踩过不少坑也总结了一些排查经验这里一并分享出来。5.1 扫描结果显示“无法解析依赖”怎么办这是新手最容易碰到的问题。当你在一个没有安装任何依赖的干净环境里直接用pip-audit -r requirements.txt有时候会遇到类似Could not resolve dependency的警告。原因通常是 requirements 文件里某个包名已经无法从当前配置的 PyPI 源中解析到。这种情况在国内环境尤其常见如果你配置了某些镜像源比如公司内部源或者某些高校的镜像源而镜像源没有完整同步所有包就可能出现解析失败。解决方法是在扫描前先把当前环境的基础依赖装上让 pip 能够从源里解析出版本信息。或者在命令里指定使用公共 PyPI 源pip-audit -r requirements.txt --index-url https://pypi.org/simple5.2 扫描结果跟本地环境不一致有时候你会遇到本地用pip list看到的版本和扫描工具识别到的版本不一致。这种情况通常跟虚拟环境有关。pip-audit 默认扫描的是当前激活的 Python 环境。如果你在系统 Python 环境下运行它扫描到的自然也是系统环境里的包而不是项目虚拟环境里的包。所以我的习惯是必须在项目对应的虚拟环境里运行 pip-audit。具体做法是先激活虚拟环境source .venv/bin/activate然后执行pip-audit这样就能保证扫描对象跟实际运行环境是一致的。5.3 修复漏洞之后依赖又冲突了升级某个包到修复版本后发现它跟其他依赖产生冲突这是很常见的情况。比如foo库要求bar2.0而漏洞修复需要bar2.0这个时候就必须权衡了。我的处理思路是先看漏洞的严重等级。如果是低危或者中危且当前业务代码并不涉及漏洞触发路径可以先放着在项目文档里记录待办如果是高危或严重等级那就需要优先级反转考虑是否替换上游库或者分析新版本下的兼容性必要时调整业务代码。工具能帮你发现问题和定位问题但最终的决策还是需要人来判断。这也是为什么我一直强调“不要盲扫盲升”。5.4 误报问题工具不是万能的扫描工具基于漏洞数据库做匹配可能会存在误报。比如某条安全通告影响的是某个 Python 版本而你的环境虽然库版本匹配但 Python 版本不在受影响范围内工具可能仍会提示风险。这种情况在 OSV-Scanner 里偶尔也会出现。碰到疑似误报不要急着忽略。先把漏洞编号拿去查询具体影响条件确认自己当前版本是否真的处于风险范围内。如果确认不影响可以给扫描工具添加白名单或忽略规则。但请注意白名单一定要记录理由并且定期复查因为漏洞的触发条件后续可能会被修正或扩大。5.5 团队协作时的统一扫描配置如果你的团队决定统一使用扫描工具建议把扫描命令和规则写进项目根目录的文档里或者直接做成 Makefile 任务.PHONY: audit audit: .venv/bin/pip-audit -r requirements.txt这样所有人用同一条命令就能跑扫描避免各自用不同参数导致结果不一致。我个人在实际操作中的体会是依赖漏洞扫描这件事最难的不是安装工具或看懂报告而是把它变成一种持续的习惯。工具只是辅助你发现问题的手段真正能保护项目的是你对依赖版本保持敬畏、在每次升级前做好评估、在每次发布前做好检查的流程。用扫描工具只是第一步把依赖检查融入到日常的开发节奏里才是真正省心的开始。
