很多开发者在用 AI 编程助手时都遇到过这样的场景让 Agent 修一个 bug它唰唰唰改完代码顺手给你pip install了一个新依赖或者你在提示词里让它“用最流行的方案实现”结果它挑了一个三年没维护、CVE 一堆的库。代码功能确实没毛病但依赖关系一出来安全这块就开始“埋雷”。AI coding agents 写代码的速度是传统开发者的好几倍。但问题恰恰出在这里代码生成速度快依赖引入的速度也快代码审查还能靠人眼依赖安全和库使用安全很少有人能跟上这个速度。如果不断言一句这篇文章想表达的核心判断是这样的AI 编程时代真正需要重新设计的安全防线不是让 AI“生成更安全的代码”而是让 AI“按照安全规则去选择和调用第三方库”。前者依赖模型能力后者依赖工程流程。这篇文章想聊的就是这件事怎么给 AI coding agents 建立一套“库安全使用规则”让它帮我们写代码的同时不在依赖层面给项目留下安全隐患。你会看到具体可复制的规则文件写法、配套的自动化检查工具、落地到 CI 的完整配置以及最常见的坑和排查方式。如果你正在用 Cursor、Copilot、Claude Code、Codex 这类 AI 编程工具或者自己基于 LLM 开发 coding agent这篇文章值得读完并收藏。1. 为什么 AI Coding Agents 让“库安全”问题被放大了很多人觉得AI 写代码的安全问题在于“它可能写出 SQL 注入、XSS、反序列化漏洞”。这个担心不无道理但站在工程实践的角度看一个更隐蔽、更普遍的问题被忽略了AI 在库的引入和使用方式上几乎没有风险意识。1.1 AI 选库的常见套路与风险先还原一下 Agent 的工作过程。当你在 IDE 里让 AI “实现某个功能”时它通常不是从零开始造轮子而是从训练数据里回忆“这个问题一般用什么库解决”然后在代码里import一个库自动执行安装命令把库加进依赖根据该库的 README、文档或记忆里的 API写出调用代码。这个链路本身无可厚非甚至和人类开发者的行为一致。但差异在于人类开发者选库时会下意识做一个“安全评估”这个库最近有没有更新Star 数多少维护者还活跃吗历史上有没有高危漏洞AI 不会做这些事它只会判断“这个库在语义上能不能完成任务”。于是我们开始看到下列问题在团队里反复出现Agent 引入了一个存在已知 RCE 漏洞的旧版本库Agent 为了解决一个无关紧要的兼容问题把一个带底层原生代码native library的传递依赖拉进了项目Agent 从网上“学习”到了一个拼写相近的恶意包并且真的把它装进了环境Agent 频繁修改requirements.txt或package.json但没有任何人逐行核对依赖变更。这些问题的共性是出问题的位置不在 AI 写的业务代码里而在依赖解析和库选择的边界上。也就是说传统代码安全 Review 关注的是“你写的代码有没有毛病”而 Agent 场景下还必须增加一层“你引入的库和依赖关系有没有毛病”。1.2 为什么人工审查跟不上有一个很现实的原因让这个问题更棘手AI 生成代码的速度太快了尤其是 Agent 自主运行的场景。一个 Agent 可能在几分钟内完成一次“安装依赖、运行测试、修复错误、再跑”的循环。在这种节奏下如果安全检查还停留在“等开发者在 Code Review 时看一眼”基本等于没检查。更麻烦的是很多 Agent 对“修复错误”有一种过度执念。比如 CI 里报了一个 lint 错误Agent 会想尽办法让测试通过包括但不限于升级依赖、引入新库、绕过某些检查。它以为自己在解决问题实际上可能是在制造问题。这也解释了为什么单纯的“提示 AI 注意安全”并不可靠你需要从工具和流程层面强制约束它。1.3 核心判断库安全是 AI 编程时代的新“关键路径”传统软件工程里依赖安全是“常识”但因为有人工 review 环节即使偶尔出错也有机会被拦下来。到了 AI coding agents 时代依赖选择、依赖安装、依赖升级都开始变成“自动化动作”。自动化动作没有安全意识只会放大风险。所以结论就变得非常清晰想安全地使用 AI 编程 Agent必须把“库安全规则”从人脑记忆转移到一个 Agent 能读取、工具链能执行的标准化文件中。这就是“guide AI coding agents on how to use libraries securely”这句话的真正含义。2. 先搞清楚一个概念AI Coding Agents 是怎么“用库”的为了不让后面的方案变成空中楼阁我们先拆解一下 Agent 使用第三方库的三种典型方式。三种方式的风险和应对策略完全不同。2.1 方式一代码生成时按记忆 import这是最常见的一种。你告诉 Agent “解析一下这个 JSON”它直接写出import json或import orjson。此时 Agent 并没有执行任何命令只是基于训练记忆选择库。这种方式的隐患在于“训练数据不等于实时安全数据”。Agent 训练时某个库是安全的等到实际运行时该库可能已经被曝出高危漏洞。Agent 对此毫无感知它会继续按旧记忆使用。另外Agent 对“哪个库更安全”的判断往往来自“热门程度”而不是漏洞历史这就可能导致它选了一个看起来很火、但实际上维护停滞的库。2.2 方式二自主执行安装命令更复杂的情况是Agent 具备执行命令的权限。它发现代码缺少依赖就会自动运行pip install requests或npm install lodash之类的命令。这是风险最高的一种方式。原因有三个版本不确定性如果不加版本号安装命令默认拉取当前最新版本而“最新”不等于“经过安全验证”。某些场景下最新版本可能引入不兼容变更或新的安全问题。依赖混淆Dependency Confusion风险如果项目的私有仓库和公共仓库配置不当Agent 安装的包名可能被公共仓库上的同名恶意包抢注从而被投毒。传递依赖不可控你让 Agent 装一个库这个库又会自动拉取几十个传递依赖。这些传递依赖是否符合安全基线Agent 根本不会检查。可以说在 Agent 自主执行安装命令时它是在“替你做决定”但又不具备你作为开发者本该有的判断力。2.3 方式三在提示词或规则文件指导下使用库第三种方式是新趋势开发者在项目里提供一个专门的规则文件例如AGENTS.md、CLAUDE.md或agent-rules.txt告诉 Agent 哪些库可以用、哪些不能用、版本约束是什么、安装前必须执行什么检查。Agent 在执行任务时先读取文件再按要求操作。这才是真正值得推广的做法。因为它把“人的安全经验”变成了“机器可执行的约束”而不是指望 Agent 自己“聪明地”避坑。本文后面重点讲的就是这个方式的工程落地细节。3. 库安全到底包含哪些内容不只是”别用旧版本“如果把“库安全”仅仅理解为“依赖版本要新”那这个理解太浅了。一个真正可落地的库安全规则至少覆盖下面几个维度。3.1 已知漏洞CVE检测这是最基础的一条。每个依赖包的历史版本里都可能存在已公开漏洞例如 Python 生态的CVE-2023-XXXX、JavaScript 生态的GHSA-XXXX。规则应该要求 Agent 在引入任何新依赖后运行漏洞扫描工具确保没有已公开的已知安全漏洞。常见工具包括生态常用工具Pythonpip-audit、osv-scannerNode.jsnpm audit、osv-scannerJavaOWASP Dependency-Check、osv-scannerGogovulncheck从经验看osv-scanner是目前覆盖面广、接入成本低的通用方案因为它读取锁定文件lockfile即可工作不依赖具体语言包管理器。3.2 许可证合规很多 AI 生成的代码会顺手引入开源库但开源库的许可证类型并不都是宽松的。GPL、AGPL 这类传染性许可证在某些商业项目中会带来合规问题。AI Agent 通常不会主动告诉你“我用的这个库是 AGPL 协议的可能会影响你的商业闭源分发”。所以你要主动通过规则文件要求它引入依赖前先检查许可证类型遇到高风险许可证必须停止并询问。3.3 依赖混淆与恶意包防护随着 AI 编程工具的流行一个更恶意的风险浮出水面攻击者会注册一些看起来像“知名库拼写错误”或“知名库公司名”的恶意包等待 AI Agent 在自动补全或自动安装时踩中。有些攻击者甚至会专门研究 AI 模型训练时常用的库名提前把恶意版本发布到公共仓库。要在规则文件里明确要求只能从官方源安装依赖禁止从非官方地址安装如果安装失败不得自行更换来路不明的源。这一点在涉及私有仓库时尤其重要。3.4 版本锁定与可复现性Agent 的另一个坏习惯是倾向于使用“通配版本”或“最新版本”比如numpy1.24。这会让构建结果不可复现。两个开发者、两个 CI 环境可能装出不同的依赖树安全问题也因此难以追踪。最佳实践是所有直接依赖都锁定到精确版本并用锁文件固定完整依赖树。规则文件里必须要求 Agent 修改依赖后运行lock相关命令并提交锁文件变更。3.5 传递依赖的可见性很多时候直接依赖是安全的问题出在它的子依赖里。因此规则也应要求 Agent 在引入新依赖后生成或更新 SBOM软件物料清单至少要让开发者能看清完整依赖树。如果项目已经有依赖更新审查工具如 Dependabot规则里要写明由这些工具负责升级Agent 不要擅自升级。4. 给 AI Coding Agents 建立“库安全使用规则”的完整方案聊完背景进入真正的实操。下面这套方案不需要引入复杂平台只需要三个层面的配合项目里的规则文件Agent 读取并遵守命令执行前的安全检查脚本Agent 调用CI 里的强制卡点即使 Agent 不遵守也拦得住。4.1 规则文件让安全要求变成 Agent 的“工作手册”规则文件推荐放在项目根目录命名可参考你的 Agent 工具约定。例如Cursor / CopilotAGENTS.mdClaude CodeCLAUDE.md通用AGENTS.md目前是最常见的约定文件本身是 Markdown 格式Agent 会自动读取。下面给出一个可以选择直接使用的示例。# AGENTS.md ## 角色 你是本项目的 AI 编码助手可以修改代码、运行命令但必须遵守本文件中的安全规则。 ## 依赖引入规则 1. 在添加任何第三方库之前先搜索项目内是否已有可复用依赖优先复用现有依赖。 2. 必须从官方源安装依赖禁止使用来源不明的镜像源或安装命令。 3. 必须使用精确版本号禁止使用 latest、1.0.0 之类的不确定版本。 4. 安装完成后必须运行安全扫描命令 - Python: uv pip audit 或 pip-audit - Node.js: npm audit - 通用: osv-scanner --lockfile lockfile-path 5. 如果扫描发现高危漏洞禁止通过“忽略”或“升级到最新版”的方式强行解决必须停下并向用户报告。 6. 禁止修改锁文件来绕过安全检查。 7. 修改依赖后必须同步更新锁文件并在变更描述里列出新增依赖及用途。 ## 许可证规则 1. 引入新依赖前检查其许可证类型。 2. 如果许可证是 AGPL、GPL-3.0 或 SSPL默认禁止引入除非用户明确确认。 3. 遇到不确定许可证的包停下并询问用户不要猜。 ## 安全边界 1. 禁止向依赖仓库提交凭据、令牌、私钥。 2. 禁止在代码中硬编码密钥或密码必须提示用户使用环境变量或密钥管理服务。 3. 禁止关闭安全告警或修改审计工具的判断阈值。这个文件看起来简单但它是整个方案的地基。Agent 读到的不是“你最好注意安全”而是一组明确的操作指令。你可以发现规则里所有句子都是“动作条件”而不是抽象的价值观。Agent 对“注意安全”没有概念但它知道“安装后要运行 pip-audit”是什么意思。4.2 在规则文件里搞一个“允许库列表”和“禁用库列表”只有通用规则还不够。不同项目对库的使用约束不一样。比如某个项目出于供应链安全考虑允许用的 HTTP 客户端只有requests和httpx另一个项目可能禁止使用某些已知维护不积极的库。可以在AGENTS.md后面追加一个项目专属列表## 项目允许使用的库 - requests (2.31.x, 2.32.x) - httpx (0.27.x) - pydantic (2.7.x) - fastapi (0.111.x) ## 项目禁止使用的库 - selenium本项目不需要浏览器自动化 - scrapy如需爬虫请先和用户确认 - anyio如果只是 FastAPI 间接依赖不要直接 import - pyyaml优先使用 ujson 或 orjson 处理配置如果你愿意还可以升级为结构化策略文件比如security-policy.json并在AGENTS.md里注明 Agent 每次操作依赖前必须读取该文件。这样即使规则说明比较长Agent 也不会漏掉关键条目。{ dependencyPolicy: { allowedOnly: false, allowedPackages: [requests, httpx, pydantic, fastapi], blockedPackages: [selenium, scrapy, anyio, pyyaml], blockedLicenses: [AGPL-3.0, GPL-3.0, SSPL-1.0], exactVersions: true, scanRequired: [pip-audit, osv-scanner, npm audit], maxVulnerabilitySeverity: moderate } }这里有一个实际经验带 Agent 的项目允许列表比禁用列表更好用。因为你不可能列完所有危险包但你可以限定一个受信任范围。一旦 Agent 发现“用户要求安装的包不在允许列表里”正确动作是停下来询问而不是自作主张。4.3 给 Agent 安装命令设置“安全带”规则文件是软约束Agent 不一定每次都能完整执行。所以还要在命令层面加一个“安全带”把安装命令包装成一个脚本脚本内部先做检查再执行安装。这里有一个关键点要注意不要直接教 Agent 使用原始的pip install xxx而是创建一个项目级封装脚本。在 Windows 环境中可以创建一个install_deps.py或 PowerShell 脚本在 Linux/macOS 环境下可以创建一个scripts/install-deps.sh。下面是一个最小封装示例适用于 Python 项目Linux/macOS#!/usr/bin/env bash # 文件路径scripts/install-deps.sh set -euo pipefail echo 解析依赖并生成锁文件 uv pip compile pyproject.toml -o requirements.lock echo 运行漏洞扫描 osv-scanner --lockfile requirements.lock echo 扫描结果无高危漏洞执行安装 uv pip install -r requirements.lock然后在AGENTS.md里写清楚## 安装依赖时 必须运行: bash scripts/install-deps.sh 禁止直接运行: pip install package这样做的意义是Agent 再灵活也只能在这个脚本允许的轨道上安装依赖。扫描不过安装就失败Agent 就会停下反馈问题而不是继续“尝试修复”。5. 配套自动化检查在 CI 层把门焊死规则文件和脚本能拦住大部分 Agent 的“无意识违规”但不能完全依赖 Agent 自觉。生产项目还有一个终极防线CI 流水线。只要依赖里有已知高危漏洞或不符合策略CI 必须失败。5.1 常规依赖扫描 CI 示例以 GitHub Actions 为例下面这个 workflow 适合 Python 项目在每次 push 时运行漏洞扫描。如果你用其他 CI 平台原理是一样的读锁文件、跑扫描器、以退出码决定成败。# 文件路径.github/workflows/security-scan.yml name: Dependency Security Scan on: push: paths: - pyproject.toml - requirements.lock - poetry.lock pull_request: jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install osv-scanner run: | curl -sSL https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64 -o /usr/local/bin/osv-scanner chmod x /usr/local/bin/osv-scanner - name: Scan lockfile run: osv-scanner --lockfile requirements.lock - name: Install and run pip-audit run: | pip install pip-audit pip-audit -r requirements.lock5.2 许可证扫描如果项目对许可证合规要求严格比如闭源商业项目还需要在 CI 里加一个许可证检查。工具可以选择license-checkerNode.js、pip-licensesPython等。这里给一个 Python 项目的思路pip install pip-licenses pip-licenses --formatplain --ordercount --filter-typespackage \ --ignore-packageswheel licenses.txt然后在 CI 里解析licenses.txt如果检测到 AGPL / GPL / SSPL 之类就报错。这一步可以写在 CI 脚本里也可以接专门的合规平台。核心目的是依赖库的许可证问题不能依赖 Agent 自行判断。5.3 SBOM 生成让依赖树可审计更进一步每次发布前或依赖变更后生成一份 SBOM 归档。SPDX 是常见格式CycloneDX 也很流行。cd $PROJECT_DIR pip install cyclonedx-bom cyclonedx-py -i requirements.lock -o sbom.xml有了 SBOM安全团队可以在发布前审查依赖全貌也能在漏洞情报出来时快速定位“哪个版本受影响、哪些服务在用”。AI Agent 的生产力优势要想真正落地到企业级项目SBOM 这一环是躲不开的。6. 落地示例让 Agent 在一个真实功能任务中遵守“库安全规则”规则文件写了、脚本配了、CI 加了那实际跑起来是什么样子下面用一个最小场景走一遍完整链路。6.1 项目结构示例假设项目是一个简单的 FastAPI 服务my-api/ ├── .github/workflows/security-scan.yml ├── AGENTS.md ├── pyproject.toml ├── requirements.lock ├── scripts/ │ ├── install-deps.sh │ └── scan-deps.sh └── app/ └── main.pypyproject.toml里用精确版本约束[project] name my-api version 0.1.0 requires-python 3.11 dependencies [ fastapi0.111.0, uvicorn0.30.1, pydantic2.7.4, requests2.32.3, ] [tool.pip-audit] # 示例配置忽略不影响生产环境运行的 dev 依赖 skip-editable true6.2 给 Agent 的任务你可以这样发起任务请实现一个/health接口返回服务的当前状态。要求遵循 AGENTS.md 中的所有安全规则。如果需要新增依赖请先说明原因再调用scripts/install-deps.sh完成安装。一个遵守规则的 Agent应该按下面顺序操作读取AGENTS.md检查app/main.py当前实现如果使用内置FastAPI即可完成不新增任何依赖修改代码、运行测试最后额外执行一次bash scripts/scan-deps.sh确认依赖安全。scan-deps.sh内容可以这样写#!/usr/bin/env bash # 文件路径scripts/scan-deps.sh set -euo pipefail echo 1. 使用 osv-scanner 扫描已知漏洞 osv-scanner --lockfile requirements.lock echo 2. 使用 pip-audit 检查 Python 依赖漏洞 pip-audit -r requirements.lock echo 3. 检查许可证合规示例只打印实际按项目策略决定是否失败 pip-licenses --formatplain --ordercount || true echo 依赖安全检查完成无阻断问题。6.3 运行结果验证如果所有命令退出码为 0控制台大概长这样 1. 使用 osv-scanner 扫描已知漏洞 Scanned 5 lockfile packages, found 0 vulnerabilities. 2. 使用 pip-audit 检查 Python 依赖漏洞 Found 0 known vulnerabilities in 5 dependencies. 3. 检查许可证合规示例只打印实际按项目策略决定是否失败 Licenses: fastapi BSD-3-Clause uvicorn BSD-3-Clause pydantic MIT requests Apache-2.0 ... 依赖安全检查完成无阻断问题。这个任务本身不复杂但注意一个细节Agent 没有被要求“不得使用新库”而是被要求“如果需要新增依赖先说明原因再走脚本”。这样它就会倾向于复用现有依赖而不是一上来就引入新库。这正是规则文件带来的行为改变。7. 常见问题与排查思路在给团队推行这套方案时有几个问题是反复出现的整理成表格方便排查。问题现象可能原因排查方式解决方案Agent 不读取 AGENTS.md还是擅自装包工具版本过旧或未配置“读取项目规则文件”检查 IDE / CLI 的 Agent 文档确认规则文件名是否正确统一规则文件名在启动命令中显式--memory指定规则文件路径AGENTS.md 写了禁止列表Agent 仍然视而不见禁止列表是自然语言Agent 解析有歧义用结构化策略文件JSON/YAML替代纯文本参考上文 security-policy.json在 AGENTS.md 中引用文件路径pip-audit报出漏洞Agent 擅自执行升级规则里没有写明“发现有漏洞后必须停下”检查 AGENTS.md 中的漏洞处理指令是否明确增加“发现高危漏洞时禁止自行升级必须向用户报告并等待指示”Agent 从非官方源下载依赖规则文件未明确“只能使用官方源”或系统全局源配置被污染检查 pip / npm 的全局配置文件在规则文件和管理端固定源地址并在 CI 中禁止非官方源许可证检查总是误报检测工具覆盖了开发依赖或工具链自带的依赖查看许可证检查器的过滤配置在扫描脚本里配置忽略 dev/test 类依赖或建立白名单CI 扫描通过率太低团队选择删除扫卡规则过于严格影响了正常迭代查看历史失败记录区分阻断策略先设为“warning”运行一周再逐步收紧为“error”阻断有一个经验值得强调不要一开始就把所有检查设成“阻断”。如果第一次推行就让 CI 频繁失败团队很快就会把安全扫描当作“狼来了”最后干脆关掉。建议先让扫描结果进入 MR 评论或人工检查运行一两周确认误报率可控后再把危险项升级为阻断。8. 最佳实践与工程建议方案跑通之后还要注意一些容易被忽略的细节。这里按“开发者、Agent、CI/平台”三个角色分别给出建议。8.1 开发者侧规则文件要“短而可执行”规则文件不是越长越好。从实践效果看如果超过 50 行且包含大量泛泛而谈的句子Agent 的执行效果会明显下降。更好的做法是规则文件保持精简只写“必须做”和“不能做”用结构化数据文件承载完整策略把“为什么这么规定”写在给人类看的文档里而不是塞进 AGENTS.md每季度根据 Agent 的实际违规案例修订一次规则。另外规则文件的命名尽量要兼容主流工具。Cursor 和 Copilot 支持AGENTS.mdClaude Code 支持CLAUDE.md。如果你同时使用多款工具可以保持同一份内容复制到多个文件名尽量让维护源只有一个。8.2 Agent 侧升级依赖要遵循最小变更原则对 AI coding agents 最该强调的一条铁律是不要为了修复一个非阻断问题而升级整个依赖树。最小变更原则在人工开发里是常识在 Agent 场景里很容易被打破。所以规则文件里建议明确每次依赖变更只修改与任务直接相关的包升级前先说明版本变化带来的影响升级后跑测试和安全扫描确保无回归如果测试失败禁止通过“降级其他依赖”的方式绕过。8.3 CI / 平台侧安全扫描必须和 Agent 的执行权限解耦这只是整条链路里的一个提醒即便团队里已经有很成熟的 CI 安全卡点也不要给 Agent 开放过高的本地执行权限。Agent 在开发者本机跑安装命令时它不应有向生产环境发布包的权限。安全边界是分层的本机规则文件 封装脚本仓库分支保护 MR 审查CI依赖扫描 许可证检查 SBOM 归档生产环境镜像或制品发布前再做一次不可变审计。每一层的目标都不是“让 Agent 变乖”而是“即使 Agent 偶尔出错也有下一层兜底”。9. 总结与后续学习方向回到开头那个判断AI coding agents 真正需要的不只是“更聪明的代码生成”而是“更明确的工程约束”。库安全这件事正好是检验约束力的一块试金石。规则文件、封装脚本、CI 扫描三层配合就能让 Agent 在快速产出的同时不把供应链安全搞崩。如果你接下来想继续深入这几个方向值得关注尝试用osv-scanner扫描现有项目的 lockfile看看历史依赖里是否存在已知漏洞学习 SPDX 和 CycloneDX 两种 SBOM 格式了解依赖可审计性的具体标准如果你的 Agent 工具支持自定义工具调用可以考虑把“依赖扫描”作为 Agent 必须调用的一次工具关注 AI Agent 领域关于“可信执行边界”的讨论这类框架会越来越成熟。希望这篇内容能帮你少踩几个依赖安全的坑。建议收藏备用下次给项目接入 AI 编程助手时直接把规则文件改一改就能用。
AI编程助手库安全指南：为Agent建立可执行的依赖使用规则
很多开发者在用 AI 编程助手时都遇到过这样的场景让 Agent 修一个 bug它唰唰唰改完代码顺手给你pip install了一个新依赖或者你在提示词里让它“用最流行的方案实现”结果它挑了一个三年没维护、CVE 一堆的库。代码功能确实没毛病但依赖关系一出来安全这块就开始“埋雷”。AI coding agents 写代码的速度是传统开发者的好几倍。但问题恰恰出在这里代码生成速度快依赖引入的速度也快代码审查还能靠人眼依赖安全和库使用安全很少有人能跟上这个速度。如果不断言一句这篇文章想表达的核心判断是这样的AI 编程时代真正需要重新设计的安全防线不是让 AI“生成更安全的代码”而是让 AI“按照安全规则去选择和调用第三方库”。前者依赖模型能力后者依赖工程流程。这篇文章想聊的就是这件事怎么给 AI coding agents 建立一套“库安全使用规则”让它帮我们写代码的同时不在依赖层面给项目留下安全隐患。你会看到具体可复制的规则文件写法、配套的自动化检查工具、落地到 CI 的完整配置以及最常见的坑和排查方式。如果你正在用 Cursor、Copilot、Claude Code、Codex 这类 AI 编程工具或者自己基于 LLM 开发 coding agent这篇文章值得读完并收藏。1. 为什么 AI Coding Agents 让“库安全”问题被放大了很多人觉得AI 写代码的安全问题在于“它可能写出 SQL 注入、XSS、反序列化漏洞”。这个担心不无道理但站在工程实践的角度看一个更隐蔽、更普遍的问题被忽略了AI 在库的引入和使用方式上几乎没有风险意识。1.1 AI 选库的常见套路与风险先还原一下 Agent 的工作过程。当你在 IDE 里让 AI “实现某个功能”时它通常不是从零开始造轮子而是从训练数据里回忆“这个问题一般用什么库解决”然后在代码里import一个库自动执行安装命令把库加进依赖根据该库的 README、文档或记忆里的 API写出调用代码。这个链路本身无可厚非甚至和人类开发者的行为一致。但差异在于人类开发者选库时会下意识做一个“安全评估”这个库最近有没有更新Star 数多少维护者还活跃吗历史上有没有高危漏洞AI 不会做这些事它只会判断“这个库在语义上能不能完成任务”。于是我们开始看到下列问题在团队里反复出现Agent 引入了一个存在已知 RCE 漏洞的旧版本库Agent 为了解决一个无关紧要的兼容问题把一个带底层原生代码native library的传递依赖拉进了项目Agent 从网上“学习”到了一个拼写相近的恶意包并且真的把它装进了环境Agent 频繁修改requirements.txt或package.json但没有任何人逐行核对依赖变更。这些问题的共性是出问题的位置不在 AI 写的业务代码里而在依赖解析和库选择的边界上。也就是说传统代码安全 Review 关注的是“你写的代码有没有毛病”而 Agent 场景下还必须增加一层“你引入的库和依赖关系有没有毛病”。1.2 为什么人工审查跟不上有一个很现实的原因让这个问题更棘手AI 生成代码的速度太快了尤其是 Agent 自主运行的场景。一个 Agent 可能在几分钟内完成一次“安装依赖、运行测试、修复错误、再跑”的循环。在这种节奏下如果安全检查还停留在“等开发者在 Code Review 时看一眼”基本等于没检查。更麻烦的是很多 Agent 对“修复错误”有一种过度执念。比如 CI 里报了一个 lint 错误Agent 会想尽办法让测试通过包括但不限于升级依赖、引入新库、绕过某些检查。它以为自己在解决问题实际上可能是在制造问题。这也解释了为什么单纯的“提示 AI 注意安全”并不可靠你需要从工具和流程层面强制约束它。1.3 核心判断库安全是 AI 编程时代的新“关键路径”传统软件工程里依赖安全是“常识”但因为有人工 review 环节即使偶尔出错也有机会被拦下来。到了 AI coding agents 时代依赖选择、依赖安装、依赖升级都开始变成“自动化动作”。自动化动作没有安全意识只会放大风险。所以结论就变得非常清晰想安全地使用 AI 编程 Agent必须把“库安全规则”从人脑记忆转移到一个 Agent 能读取、工具链能执行的标准化文件中。这就是“guide AI coding agents on how to use libraries securely”这句话的真正含义。2. 先搞清楚一个概念AI Coding Agents 是怎么“用库”的为了不让后面的方案变成空中楼阁我们先拆解一下 Agent 使用第三方库的三种典型方式。三种方式的风险和应对策略完全不同。2.1 方式一代码生成时按记忆 import这是最常见的一种。你告诉 Agent “解析一下这个 JSON”它直接写出import json或import orjson。此时 Agent 并没有执行任何命令只是基于训练记忆选择库。这种方式的隐患在于“训练数据不等于实时安全数据”。Agent 训练时某个库是安全的等到实际运行时该库可能已经被曝出高危漏洞。Agent 对此毫无感知它会继续按旧记忆使用。另外Agent 对“哪个库更安全”的判断往往来自“热门程度”而不是漏洞历史这就可能导致它选了一个看起来很火、但实际上维护停滞的库。2.2 方式二自主执行安装命令更复杂的情况是Agent 具备执行命令的权限。它发现代码缺少依赖就会自动运行pip install requests或npm install lodash之类的命令。这是风险最高的一种方式。原因有三个版本不确定性如果不加版本号安装命令默认拉取当前最新版本而“最新”不等于“经过安全验证”。某些场景下最新版本可能引入不兼容变更或新的安全问题。依赖混淆Dependency Confusion风险如果项目的私有仓库和公共仓库配置不当Agent 安装的包名可能被公共仓库上的同名恶意包抢注从而被投毒。传递依赖不可控你让 Agent 装一个库这个库又会自动拉取几十个传递依赖。这些传递依赖是否符合安全基线Agent 根本不会检查。可以说在 Agent 自主执行安装命令时它是在“替你做决定”但又不具备你作为开发者本该有的判断力。2.3 方式三在提示词或规则文件指导下使用库第三种方式是新趋势开发者在项目里提供一个专门的规则文件例如AGENTS.md、CLAUDE.md或agent-rules.txt告诉 Agent 哪些库可以用、哪些不能用、版本约束是什么、安装前必须执行什么检查。Agent 在执行任务时先读取文件再按要求操作。这才是真正值得推广的做法。因为它把“人的安全经验”变成了“机器可执行的约束”而不是指望 Agent 自己“聪明地”避坑。本文后面重点讲的就是这个方式的工程落地细节。3. 库安全到底包含哪些内容不只是”别用旧版本“如果把“库安全”仅仅理解为“依赖版本要新”那这个理解太浅了。一个真正可落地的库安全规则至少覆盖下面几个维度。3.1 已知漏洞CVE检测这是最基础的一条。每个依赖包的历史版本里都可能存在已公开漏洞例如 Python 生态的CVE-2023-XXXX、JavaScript 生态的GHSA-XXXX。规则应该要求 Agent 在引入任何新依赖后运行漏洞扫描工具确保没有已公开的已知安全漏洞。常见工具包括生态常用工具Pythonpip-audit、osv-scannerNode.jsnpm audit、osv-scannerJavaOWASP Dependency-Check、osv-scannerGogovulncheck从经验看osv-scanner是目前覆盖面广、接入成本低的通用方案因为它读取锁定文件lockfile即可工作不依赖具体语言包管理器。3.2 许可证合规很多 AI 生成的代码会顺手引入开源库但开源库的许可证类型并不都是宽松的。GPL、AGPL 这类传染性许可证在某些商业项目中会带来合规问题。AI Agent 通常不会主动告诉你“我用的这个库是 AGPL 协议的可能会影响你的商业闭源分发”。所以你要主动通过规则文件要求它引入依赖前先检查许可证类型遇到高风险许可证必须停止并询问。3.3 依赖混淆与恶意包防护随着 AI 编程工具的流行一个更恶意的风险浮出水面攻击者会注册一些看起来像“知名库拼写错误”或“知名库公司名”的恶意包等待 AI Agent 在自动补全或自动安装时踩中。有些攻击者甚至会专门研究 AI 模型训练时常用的库名提前把恶意版本发布到公共仓库。要在规则文件里明确要求只能从官方源安装依赖禁止从非官方地址安装如果安装失败不得自行更换来路不明的源。这一点在涉及私有仓库时尤其重要。3.4 版本锁定与可复现性Agent 的另一个坏习惯是倾向于使用“通配版本”或“最新版本”比如numpy1.24。这会让构建结果不可复现。两个开发者、两个 CI 环境可能装出不同的依赖树安全问题也因此难以追踪。最佳实践是所有直接依赖都锁定到精确版本并用锁文件固定完整依赖树。规则文件里必须要求 Agent 修改依赖后运行lock相关命令并提交锁文件变更。3.5 传递依赖的可见性很多时候直接依赖是安全的问题出在它的子依赖里。因此规则也应要求 Agent 在引入新依赖后生成或更新 SBOM软件物料清单至少要让开发者能看清完整依赖树。如果项目已经有依赖更新审查工具如 Dependabot规则里要写明由这些工具负责升级Agent 不要擅自升级。4. 给 AI Coding Agents 建立“库安全使用规则”的完整方案聊完背景进入真正的实操。下面这套方案不需要引入复杂平台只需要三个层面的配合项目里的规则文件Agent 读取并遵守命令执行前的安全检查脚本Agent 调用CI 里的强制卡点即使 Agent 不遵守也拦得住。4.1 规则文件让安全要求变成 Agent 的“工作手册”规则文件推荐放在项目根目录命名可参考你的 Agent 工具约定。例如Cursor / CopilotAGENTS.mdClaude CodeCLAUDE.md通用AGENTS.md目前是最常见的约定文件本身是 Markdown 格式Agent 会自动读取。下面给出一个可以选择直接使用的示例。# AGENTS.md ## 角色 你是本项目的 AI 编码助手可以修改代码、运行命令但必须遵守本文件中的安全规则。 ## 依赖引入规则 1. 在添加任何第三方库之前先搜索项目内是否已有可复用依赖优先复用现有依赖。 2. 必须从官方源安装依赖禁止使用来源不明的镜像源或安装命令。 3. 必须使用精确版本号禁止使用 latest、1.0.0 之类的不确定版本。 4. 安装完成后必须运行安全扫描命令 - Python: uv pip audit 或 pip-audit - Node.js: npm audit - 通用: osv-scanner --lockfile lockfile-path 5. 如果扫描发现高危漏洞禁止通过“忽略”或“升级到最新版”的方式强行解决必须停下并向用户报告。 6. 禁止修改锁文件来绕过安全检查。 7. 修改依赖后必须同步更新锁文件并在变更描述里列出新增依赖及用途。 ## 许可证规则 1. 引入新依赖前检查其许可证类型。 2. 如果许可证是 AGPL、GPL-3.0 或 SSPL默认禁止引入除非用户明确确认。 3. 遇到不确定许可证的包停下并询问用户不要猜。 ## 安全边界 1. 禁止向依赖仓库提交凭据、令牌、私钥。 2. 禁止在代码中硬编码密钥或密码必须提示用户使用环境变量或密钥管理服务。 3. 禁止关闭安全告警或修改审计工具的判断阈值。这个文件看起来简单但它是整个方案的地基。Agent 读到的不是“你最好注意安全”而是一组明确的操作指令。你可以发现规则里所有句子都是“动作条件”而不是抽象的价值观。Agent 对“注意安全”没有概念但它知道“安装后要运行 pip-audit”是什么意思。4.2 在规则文件里搞一个“允许库列表”和“禁用库列表”只有通用规则还不够。不同项目对库的使用约束不一样。比如某个项目出于供应链安全考虑允许用的 HTTP 客户端只有requests和httpx另一个项目可能禁止使用某些已知维护不积极的库。可以在AGENTS.md后面追加一个项目专属列表## 项目允许使用的库 - requests (2.31.x, 2.32.x) - httpx (0.27.x) - pydantic (2.7.x) - fastapi (0.111.x) ## 项目禁止使用的库 - selenium本项目不需要浏览器自动化 - scrapy如需爬虫请先和用户确认 - anyio如果只是 FastAPI 间接依赖不要直接 import - pyyaml优先使用 ujson 或 orjson 处理配置如果你愿意还可以升级为结构化策略文件比如security-policy.json并在AGENTS.md里注明 Agent 每次操作依赖前必须读取该文件。这样即使规则说明比较长Agent 也不会漏掉关键条目。{ dependencyPolicy: { allowedOnly: false, allowedPackages: [requests, httpx, pydantic, fastapi], blockedPackages: [selenium, scrapy, anyio, pyyaml], blockedLicenses: [AGPL-3.0, GPL-3.0, SSPL-1.0], exactVersions: true, scanRequired: [pip-audit, osv-scanner, npm audit], maxVulnerabilitySeverity: moderate } }这里有一个实际经验带 Agent 的项目允许列表比禁用列表更好用。因为你不可能列完所有危险包但你可以限定一个受信任范围。一旦 Agent 发现“用户要求安装的包不在允许列表里”正确动作是停下来询问而不是自作主张。4.3 给 Agent 安装命令设置“安全带”规则文件是软约束Agent 不一定每次都能完整执行。所以还要在命令层面加一个“安全带”把安装命令包装成一个脚本脚本内部先做检查再执行安装。这里有一个关键点要注意不要直接教 Agent 使用原始的pip install xxx而是创建一个项目级封装脚本。在 Windows 环境中可以创建一个install_deps.py或 PowerShell 脚本在 Linux/macOS 环境下可以创建一个scripts/install-deps.sh。下面是一个最小封装示例适用于 Python 项目Linux/macOS#!/usr/bin/env bash # 文件路径scripts/install-deps.sh set -euo pipefail echo 解析依赖并生成锁文件 uv pip compile pyproject.toml -o requirements.lock echo 运行漏洞扫描 osv-scanner --lockfile requirements.lock echo 扫描结果无高危漏洞执行安装 uv pip install -r requirements.lock然后在AGENTS.md里写清楚## 安装依赖时 必须运行: bash scripts/install-deps.sh 禁止直接运行: pip install package这样做的意义是Agent 再灵活也只能在这个脚本允许的轨道上安装依赖。扫描不过安装就失败Agent 就会停下反馈问题而不是继续“尝试修复”。5. 配套自动化检查在 CI 层把门焊死规则文件和脚本能拦住大部分 Agent 的“无意识违规”但不能完全依赖 Agent 自觉。生产项目还有一个终极防线CI 流水线。只要依赖里有已知高危漏洞或不符合策略CI 必须失败。5.1 常规依赖扫描 CI 示例以 GitHub Actions 为例下面这个 workflow 适合 Python 项目在每次 push 时运行漏洞扫描。如果你用其他 CI 平台原理是一样的读锁文件、跑扫描器、以退出码决定成败。# 文件路径.github/workflows/security-scan.yml name: Dependency Security Scan on: push: paths: - pyproject.toml - requirements.lock - poetry.lock pull_request: jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install osv-scanner run: | curl -sSL https://github.com/google/osv-scanner/releases/latest/download/osv-scanner_linux_amd64 -o /usr/local/bin/osv-scanner chmod x /usr/local/bin/osv-scanner - name: Scan lockfile run: osv-scanner --lockfile requirements.lock - name: Install and run pip-audit run: | pip install pip-audit pip-audit -r requirements.lock5.2 许可证扫描如果项目对许可证合规要求严格比如闭源商业项目还需要在 CI 里加一个许可证检查。工具可以选择license-checkerNode.js、pip-licensesPython等。这里给一个 Python 项目的思路pip install pip-licenses pip-licenses --formatplain --ordercount --filter-typespackage \ --ignore-packageswheel licenses.txt然后在 CI 里解析licenses.txt如果检测到 AGPL / GPL / SSPL 之类就报错。这一步可以写在 CI 脚本里也可以接专门的合规平台。核心目的是依赖库的许可证问题不能依赖 Agent 自行判断。5.3 SBOM 生成让依赖树可审计更进一步每次发布前或依赖变更后生成一份 SBOM 归档。SPDX 是常见格式CycloneDX 也很流行。cd $PROJECT_DIR pip install cyclonedx-bom cyclonedx-py -i requirements.lock -o sbom.xml有了 SBOM安全团队可以在发布前审查依赖全貌也能在漏洞情报出来时快速定位“哪个版本受影响、哪些服务在用”。AI Agent 的生产力优势要想真正落地到企业级项目SBOM 这一环是躲不开的。6. 落地示例让 Agent 在一个真实功能任务中遵守“库安全规则”规则文件写了、脚本配了、CI 加了那实际跑起来是什么样子下面用一个最小场景走一遍完整链路。6.1 项目结构示例假设项目是一个简单的 FastAPI 服务my-api/ ├── .github/workflows/security-scan.yml ├── AGENTS.md ├── pyproject.toml ├── requirements.lock ├── scripts/ │ ├── install-deps.sh │ └── scan-deps.sh └── app/ └── main.pypyproject.toml里用精确版本约束[project] name my-api version 0.1.0 requires-python 3.11 dependencies [ fastapi0.111.0, uvicorn0.30.1, pydantic2.7.4, requests2.32.3, ] [tool.pip-audit] # 示例配置忽略不影响生产环境运行的 dev 依赖 skip-editable true6.2 给 Agent 的任务你可以这样发起任务请实现一个/health接口返回服务的当前状态。要求遵循 AGENTS.md 中的所有安全规则。如果需要新增依赖请先说明原因再调用scripts/install-deps.sh完成安装。一个遵守规则的 Agent应该按下面顺序操作读取AGENTS.md检查app/main.py当前实现如果使用内置FastAPI即可完成不新增任何依赖修改代码、运行测试最后额外执行一次bash scripts/scan-deps.sh确认依赖安全。scan-deps.sh内容可以这样写#!/usr/bin/env bash # 文件路径scripts/scan-deps.sh set -euo pipefail echo 1. 使用 osv-scanner 扫描已知漏洞 osv-scanner --lockfile requirements.lock echo 2. 使用 pip-audit 检查 Python 依赖漏洞 pip-audit -r requirements.lock echo 3. 检查许可证合规示例只打印实际按项目策略决定是否失败 pip-licenses --formatplain --ordercount || true echo 依赖安全检查完成无阻断问题。6.3 运行结果验证如果所有命令退出码为 0控制台大概长这样 1. 使用 osv-scanner 扫描已知漏洞 Scanned 5 lockfile packages, found 0 vulnerabilities. 2. 使用 pip-audit 检查 Python 依赖漏洞 Found 0 known vulnerabilities in 5 dependencies. 3. 检查许可证合规示例只打印实际按项目策略决定是否失败 Licenses: fastapi BSD-3-Clause uvicorn BSD-3-Clause pydantic MIT requests Apache-2.0 ... 依赖安全检查完成无阻断问题。这个任务本身不复杂但注意一个细节Agent 没有被要求“不得使用新库”而是被要求“如果需要新增依赖先说明原因再走脚本”。这样它就会倾向于复用现有依赖而不是一上来就引入新库。这正是规则文件带来的行为改变。7. 常见问题与排查思路在给团队推行这套方案时有几个问题是反复出现的整理成表格方便排查。问题现象可能原因排查方式解决方案Agent 不读取 AGENTS.md还是擅自装包工具版本过旧或未配置“读取项目规则文件”检查 IDE / CLI 的 Agent 文档确认规则文件名是否正确统一规则文件名在启动命令中显式--memory指定规则文件路径AGENTS.md 写了禁止列表Agent 仍然视而不见禁止列表是自然语言Agent 解析有歧义用结构化策略文件JSON/YAML替代纯文本参考上文 security-policy.json在 AGENTS.md 中引用文件路径pip-audit报出漏洞Agent 擅自执行升级规则里没有写明“发现有漏洞后必须停下”检查 AGENTS.md 中的漏洞处理指令是否明确增加“发现高危漏洞时禁止自行升级必须向用户报告并等待指示”Agent 从非官方源下载依赖规则文件未明确“只能使用官方源”或系统全局源配置被污染检查 pip / npm 的全局配置文件在规则文件和管理端固定源地址并在 CI 中禁止非官方源许可证检查总是误报检测工具覆盖了开发依赖或工具链自带的依赖查看许可证检查器的过滤配置在扫描脚本里配置忽略 dev/test 类依赖或建立白名单CI 扫描通过率太低团队选择删除扫卡规则过于严格影响了正常迭代查看历史失败记录区分阻断策略先设为“warning”运行一周再逐步收紧为“error”阻断有一个经验值得强调不要一开始就把所有检查设成“阻断”。如果第一次推行就让 CI 频繁失败团队很快就会把安全扫描当作“狼来了”最后干脆关掉。建议先让扫描结果进入 MR 评论或人工检查运行一两周确认误报率可控后再把危险项升级为阻断。8. 最佳实践与工程建议方案跑通之后还要注意一些容易被忽略的细节。这里按“开发者、Agent、CI/平台”三个角色分别给出建议。8.1 开发者侧规则文件要“短而可执行”规则文件不是越长越好。从实践效果看如果超过 50 行且包含大量泛泛而谈的句子Agent 的执行效果会明显下降。更好的做法是规则文件保持精简只写“必须做”和“不能做”用结构化数据文件承载完整策略把“为什么这么规定”写在给人类看的文档里而不是塞进 AGENTS.md每季度根据 Agent 的实际违规案例修订一次规则。另外规则文件的命名尽量要兼容主流工具。Cursor 和 Copilot 支持AGENTS.mdClaude Code 支持CLAUDE.md。如果你同时使用多款工具可以保持同一份内容复制到多个文件名尽量让维护源只有一个。8.2 Agent 侧升级依赖要遵循最小变更原则对 AI coding agents 最该强调的一条铁律是不要为了修复一个非阻断问题而升级整个依赖树。最小变更原则在人工开发里是常识在 Agent 场景里很容易被打破。所以规则文件里建议明确每次依赖变更只修改与任务直接相关的包升级前先说明版本变化带来的影响升级后跑测试和安全扫描确保无回归如果测试失败禁止通过“降级其他依赖”的方式绕过。8.3 CI / 平台侧安全扫描必须和 Agent 的执行权限解耦这只是整条链路里的一个提醒即便团队里已经有很成熟的 CI 安全卡点也不要给 Agent 开放过高的本地执行权限。Agent 在开发者本机跑安装命令时它不应有向生产环境发布包的权限。安全边界是分层的本机规则文件 封装脚本仓库分支保护 MR 审查CI依赖扫描 许可证检查 SBOM 归档生产环境镜像或制品发布前再做一次不可变审计。每一层的目标都不是“让 Agent 变乖”而是“即使 Agent 偶尔出错也有下一层兜底”。9. 总结与后续学习方向回到开头那个判断AI coding agents 真正需要的不只是“更聪明的代码生成”而是“更明确的工程约束”。库安全这件事正好是检验约束力的一块试金石。规则文件、封装脚本、CI 扫描三层配合就能让 Agent 在快速产出的同时不把供应链安全搞崩。如果你接下来想继续深入这几个方向值得关注尝试用osv-scanner扫描现有项目的 lockfile看看历史依赖里是否存在已知漏洞学习 SPDX 和 CycloneDX 两种 SBOM 格式了解依赖可审计性的具体标准如果你的 Agent 工具支持自定义工具调用可以考虑把“依赖扫描”作为 Agent 必须调用的一次工具关注 AI Agent 领域关于“可信执行边界”的讨论这类框架会越来越成熟。希望这篇内容能帮你少踩几个依赖安全的坑。建议收藏备用下次给项目接入 AI 编程助手时直接把规则文件改一改就能用。