很多開發者在用 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 編程助手時直接把規則文件改一改就能用。