安全指南：為Agent建立可執(zhí)行的依賴使用規(guī)則)
很多開(kāi)發(fā)者在用 AI 編程助手時(shí)都遇到過(guò)這樣的場(chǎng)景讓 Agent 修一個(gè) bug它唰唰唰改完代碼順手給你pip install了一個(gè)新依賴或者你在提示詞里讓它“用最流行的方案實(shí)現(xiàn)”結(jié)果它挑了一個(gè)三年沒(méi)維護(hù)、CVE 一堆的庫(kù)。代碼功能確實(shí)沒(méi)毛病但依賴關(guān)系一出來(lái)安全這塊就開(kāi)始“埋雷”。AI coding agents 寫代碼的速度是傳統(tǒng)開(kāi)發(fā)者的好幾倍。但問(wèn)題恰恰出在這里代碼生成速度快依賴引入的速度也快代碼審查還能靠人眼依賴安全和庫(kù)使用安全很少有人能跟上這個(gè)速度。如果不斷言一句這篇文章想表達(dá)的核心判斷是這樣的AI 編程時(shí)代真正需要重新設(shè)計(jì)的安全防線不是讓 AI“生成更安全的代碼”而是讓 AI“按照安全規(guī)則去選擇和調(diào)用第三方庫(kù)”。前者依賴模型能力后者依賴工程流程。這篇文章想聊的就是這件事怎么給 AI coding agents 建立一套“庫(kù)安全使用規(guī)則”讓它幫我們寫代碼的同時(shí)不在依賴層面給項(xiàng)目留下安全隱患。你會(huì)看到具體可復(fù)制的規(guī)則文件寫法、配套的自動(dòng)化檢查工具、落地到 CI 的完整配置以及最常見(jiàn)的坑和排查方式。如果你正在用 Cursor、Copilot、Claude Code、Codex 這類 AI 編程工具或者自己基于 LLM 開(kāi)發(fā) coding agent這篇文章值得讀完并收藏。1. 為什么 AI Coding Agents 讓“庫(kù)安全”問(wèn)題被放大了很多人覺(jué)得AI 寫代碼的安全問(wèn)題在于“它可能寫出 SQL 注入、XSS、反序列化漏洞”。這個(gè)擔(dān)心不無(wú)道理但站在工程實(shí)踐的角度看一個(gè)更隱蔽、更普遍的問(wèn)題被忽略了AI 在庫(kù)的引入和使用方式上幾乎沒(méi)有風(fēng)險(xiǎn)意識(shí)。1.1 AI 選庫(kù)的常見(jiàn)套路與風(fēng)險(xiǎn)先還原一下 Agent 的工作過(guò)程。當(dāng)你在 IDE 里讓 AI “實(shí)現(xiàn)某個(gè)功能”時(shí)它通常不是從零開(kāi)始造輪子而是從訓(xùn)練數(shù)據(jù)里回憶“這個(gè)問(wèn)題一般用什么庫(kù)解決”然后在代碼里import一個(gè)庫(kù)自動(dòng)執(zhí)行安裝命令把庫(kù)加進(jìn)依賴根據(jù)該庫(kù)的 README、文檔或記憶里的 API寫出調(diào)用代碼。這個(gè)鏈路本身無(wú)可厚非甚至和人類開(kāi)發(fā)者的行為一致。但差異在于人類開(kāi)發(fā)者選庫(kù)時(shí)會(huì)下意識(shí)做一個(gè)“安全評(píng)估”這個(gè)庫(kù)最近有沒(méi)有更新Star 數(shù)多少維護(hù)者還活躍嗎歷史上有沒(méi)有高危漏洞AI 不會(huì)做這些事它只會(huì)判斷“這個(gè)庫(kù)在語(yǔ)義上能不能完成任務(wù)”。于是我們開(kāi)始看到下列問(wèn)題在團(tuán)隊(duì)里反復(fù)出現(xiàn)Agent 引入了一個(gè)存在已知 RCE 漏洞的舊版本庫(kù)Agent 為了解決一個(gè)無(wú)關(guān)緊要的兼容問(wèn)題把一個(gè)帶底層原生代碼native library的傳遞依賴?yán)M(jìn)了項(xiàng)目Agent 從網(wǎng)上“學(xué)習(xí)”到了一個(gè)拼寫相近的惡意包并且真的把它裝進(jìn)了環(huán)境Agent 頻繁修改requirements.txt或package.json但沒(méi)有任何人逐行核對(duì)依賴變更。這些問(wèn)題的共性是出問(wèn)題的位置不在 AI 寫的業(yè)務(wù)代碼里而在依賴解析和庫(kù)選擇的邊界上。也就是說(shuō)傳統(tǒng)代碼安全 Review 關(guān)注的是“你寫的代碼有沒(méi)有毛病”而 Agent 場(chǎng)景下還必須增加一層“你引入的庫(kù)和依賴關(guān)系有沒(méi)有毛病”。1.2 為什么人工審查跟不上有一個(gè)很現(xiàn)實(shí)的原因讓這個(gè)問(wèn)題更棘手AI 生成代碼的速度太快了尤其是 Agent 自主運(yùn)行的場(chǎng)景。一個(gè) Agent 可能在幾分鐘內(nèi)完成一次“安裝依賴、運(yùn)行測(cè)試、修復(fù)錯(cuò)誤、再跑”的循環(huán)。在這種節(jié)奏下如果安全檢查還停留在“等開(kāi)發(fā)者在 Code Review 時(shí)看一眼”基本等于沒(méi)檢查。更麻煩的是很多 Agent 對(duì)“修復(fù)錯(cuò)誤”有一種過(guò)度執(zhí)念。比如 CI 里報(bào)了一個(gè) lint 錯(cuò)誤Agent 會(huì)想盡辦法讓測(cè)試通過(guò)包括但不限于升級(jí)依賴、引入新庫(kù)、繞過(guò)某些檢查。它以為自己在解決問(wèn)題實(shí)際上可能是在制造問(wèn)題。這也解釋了為什么單純的“提示 AI 注意安全”并不可靠你需要從工具和流程層面強(qiáng)制約束它。1.3 核心判斷庫(kù)安全是 AI 編程時(shí)代的新“關(guān)鍵路徑”傳統(tǒng)軟件工程里依賴安全是“常識(shí)”但因?yàn)橛腥斯?review 環(huán)節(jié)即使偶爾出錯(cuò)也有機(jī)會(huì)被攔下來(lái)。到了 AI coding agents 時(shí)代依賴選擇、依賴安裝、依賴升級(jí)都開(kāi)始變成“自動(dòng)化動(dòng)作”。自動(dòng)化動(dòng)作沒(méi)有安全意識(shí)只會(huì)放大風(fēng)險(xiǎn)。所以結(jié)論就變得非常清晰想安全地使用 AI 編程 Agent必須把“庫(kù)安全規(guī)則”從人腦記憶轉(zhuǎn)移到一個(gè) Agent 能讀取、工具鏈能執(zhí)行的標(biāo)準(zhǔn)化文件中。這就是“guide AI coding agents on how to use libraries securely”這句話的真正含義。2. 先搞清楚一個(gè)概念A(yù)I Coding Agents 是怎么“用庫(kù)”的為了不讓后面的方案變成空中樓閣我們先拆解一下 Agent 使用第三方庫(kù)的三種典型方式。三種方式的風(fēng)險(xiǎn)和應(yīng)對(duì)策略完全不同。2.1 方式一代碼生成時(shí)按記憶 import這是最常見(jiàn)的一種。你告訴 Agent “解析一下這個(gè) JSON”它直接寫出import json或import orjson。此時(shí) Agent 并沒(méi)有執(zhí)行任何命令只是基于訓(xùn)練記憶選擇庫(kù)。這種方式的隱患在于“訓(xùn)練數(shù)據(jù)不等于實(shí)時(shí)安全數(shù)據(jù)”。Agent 訓(xùn)練時(shí)某個(gè)庫(kù)是安全的等到實(shí)際運(yùn)行時(shí)該庫(kù)可能已經(jīng)被曝出高危漏洞。Agent 對(duì)此毫無(wú)感知它會(huì)繼續(xù)按舊記憶使用。另外Agent 對(duì)“哪個(gè)庫(kù)更安全”的判斷往往來(lái)自“熱門程度”而不是漏洞歷史這就可能導(dǎo)致它選了一個(gè)看起來(lái)很火、但實(shí)際上維護(hù)停滯的庫(kù)。2.2 方式二自主執(zhí)行安裝命令更復(fù)雜的情況是Agent 具備執(zhí)行命令的權(quán)限。它發(fā)現(xiàn)代碼缺少依賴就會(huì)自動(dòng)運(yùn)行pip install requests或npm install lodash之類的命令。這是風(fēng)險(xiǎn)最高的一種方式。原因有三個(gè)版本不確定性如果不加版本號(hào)安裝命令默認(rèn)拉取當(dāng)前最新版本而“最新”不等于“經(jīng)過(guò)安全驗(yàn)證”。某些場(chǎng)景下最新版本可能引入不兼容變更或新的安全問(wèn)題。依賴混淆Dependency Confusion風(fēng)險(xiǎn)如果項(xiàng)目的私有倉(cāng)庫(kù)和公共倉(cāng)庫(kù)配置不當(dāng)Agent 安裝的包名可能被公共倉(cāng)庫(kù)上的同名惡意包搶注從而被投毒。傳遞依賴不可控你讓 Agent 裝一個(gè)庫(kù)這個(gè)庫(kù)又會(huì)自動(dòng)拉取幾十個(gè)傳遞依賴。這些傳遞依賴是否符合安全基線Agent 根本不會(huì)檢查?？梢哉f(shuō)在 Agent 自主執(zhí)行安裝命令時(shí)它是在“替你做決定”但又不具備你作為開(kāi)發(fā)者本該有的判斷力。2.3 方式三在提示詞或規(guī)則文件指導(dǎo)下使用庫(kù)第三種方式是新趨勢(shì)開(kāi)發(fā)者在項(xiàng)目里提供一個(gè)專門的規(guī)則文件例如AGENTS.md、CLAUDE.md或agent-rules.txt告訴 Agent 哪些庫(kù)可以用、哪些不能用、版本約束是什么、安裝前必須執(zhí)行什么檢查。Agent 在執(zhí)行任務(wù)時(shí)先讀取文件再按要求操作。這才是真正值得推廣的做法。因?yàn)樗选叭说陌踩?jīng)驗(yàn)”變成了“機(jī)器可執(zhí)行的約束”而不是指望 Agent 自己“聰明地”避坑。本文后面重點(diǎn)講的就是這個(gè)方式的工程落地細(xì)節(jié)。3. 庫(kù)安全到底包含哪些內(nèi)容不只是”別用舊版本“如果把“庫(kù)安全”僅僅理解為“依賴版本要新”那這個(gè)理解太淺了。一個(gè)真正可落地的庫(kù)安全規(guī)則至少覆蓋下面幾個(gè)維度。3.1 已知漏洞CVE檢測(cè)這是最基礎(chǔ)的一條。每個(gè)依賴包的歷史版本里都可能存在已公開(kāi)漏洞例如 Python 生態(tài)的CVE-2023-XXXX、JavaScript 生態(tài)的GHSA-XXXX。規(guī)則應(yīng)該要求 Agent 在引入任何新依賴后運(yùn)行漏洞掃描工具確保沒(méi)有已公開(kāi)的已知安全漏洞。常見(jiàn)工具包括生態(tài)常用工具Pythonpip-audit、osv-scannerNode.jsnpm audit、osv-scannerJavaOWASP Dependency-Check、osv-scannerGogovulncheck從經(jīng)驗(yàn)看osv-scanner是目前覆蓋面廣、接入成本低的通用方案因?yàn)樗x取鎖定文件lockfile即可工作不依賴具體語(yǔ)言包管理器。3.2 許可證合規(guī)很多 AI 生成的代碼會(huì)順手引入開(kāi)源庫(kù)但開(kāi)源庫(kù)的許可證類型并不都是寬松的。GPL、AGPL 這類傳染性許可證在某些商業(yè)項(xiàng)目中會(huì)帶來(lái)合規(guī)問(wèn)題。AI Agent 通常不會(huì)主動(dòng)告訴你“我用的這個(gè)庫(kù)是 AGPL 協(xié)議的可能會(huì)影響你的商業(yè)閉源分發(fā)”。所以你要主動(dòng)通過(guò)規(guī)則文件要求它引入依賴前先檢查許可證類型遇到高風(fēng)險(xiǎn)許可證必須停止并詢問(wèn)。3.3 依賴混淆與惡意包防護(hù)隨著 AI 編程工具的流行一個(gè)更惡意的風(fēng)險(xiǎn)浮出水面攻擊者會(huì)注冊(cè)一些看起來(lái)像“知名庫(kù)拼寫錯(cuò)誤”或“知名庫(kù)公司名”的惡意包等待 AI Agent 在自動(dòng)補(bǔ)全或自動(dòng)安裝時(shí)踩中。有些攻擊者甚至?xí)ｉT研究 AI 模型訓(xùn)練時(shí)常用的庫(kù)名提前把惡意版本發(fā)布到公共倉(cāng)庫(kù)。要在規(guī)則文件里明確要求只能從官方源安裝依賴禁止從非官方地址安裝如果安裝失敗不得自行更換來(lái)路不明的源。這一點(diǎn)在涉及私有倉(cāng)庫(kù)時(shí)尤其重要。3.4 版本鎖定與可復(fù)現(xiàn)性Agent 的另一個(gè)壞習(xí)慣是傾向于使用“通配版本”或“最新版本”比如numpy1.24。這會(huì)讓構(gòu)建結(jié)果不可復(fù)現(xiàn)。兩個(gè)開(kāi)發(fā)者、兩個(gè) CI 環(huán)境可能裝出不同的依賴樹(shù)安全問(wèn)題也因此難以追蹤。最佳實(shí)踐是所有直接依賴都鎖定到精確版本并用鎖文件固定完整依賴樹(shù)。規(guī)則文件里必須要求 Agent 修改依賴后運(yùn)行l(wèi)ock相關(guān)命令并提交鎖文件變更。3.5 傳遞依賴的可見(jiàn)性很多時(shí)候直接依賴是安全的問(wèn)題出在它的子依賴?yán)?。因此?guī)則也應(yīng)要求 Agent 在引入新依賴后生成或更新 SBOM軟件物料清單至少要讓開(kāi)發(fā)者能看清完整依賴樹(shù)。如果項(xiàng)目已經(jīng)有依賴更新審查工具如 Dependabot規(guī)則里要寫明由這些工具負(fù)責(zé)升級(jí)Agent 不要擅自升級(jí)。4. 給 AI Coding Agents 建立“庫(kù)安全使用規(guī)則”的完整方案聊完背景進(jìn)入真正的實(shí)操。下面這套方案不需要引入復(fù)雜平臺(tái)只需要三個(gè)層面的配合項(xiàng)目里的規(guī)則文件Agent 讀取并遵守命令執(zhí)行前的安全檢查腳本Agent 調(diào)用CI 里的強(qiáng)制卡點(diǎn)即使 Agent 不遵守也攔得住。4.1 規(guī)則文件讓安全要求變成 Agent 的“工作手冊(cè)”規(guī)則文件推薦放在項(xiàng)目根目錄命名可參考你的 Agent 工具約定。例如Cursor / CopilotAGENTS.mdClaude CodeCLAUDE.md通用AGENTS.md目前是最常見(jiàn)的約定文件本身是 Markdown 格式Agent 會(huì)自動(dòng)讀取。下面給出一個(gè)可以選擇直接使用的示例。# AGENTS.md ## 角色 你是本項(xiàng)目的 AI 編碼助手可以修改代碼、運(yùn)行命令但必須遵守本文件中的安全規(guī)則。 ## 依賴引入規(guī)則 1. 在添加任何第三方庫(kù)之前先搜索項(xiàng)目?jī)?nèi)是否已有可復(fù)用依賴優(yōu)先復(fù)用現(xiàn)有依賴。 2. 必須從官方源安裝依賴禁止使用來(lái)源不明的鏡像源或安裝命令。 3. 必須使用精確版本號(hào)禁止使用 latest、1.0.0 之類的不確定版本。 4. 安裝完成后必須運(yùn)行安全掃描命令 - Python: uv pip audit 或 pip-audit - Node.js: npm audit - 通用: osv-scanner --lockfile lockfile-path 5. 如果掃描發(fā)現(xiàn)高危漏洞禁止通過(guò)“忽略”或“升級(jí)到最新版”的方式強(qiáng)行解決必須停下并向用戶報(bào)告。 6. 禁止修改鎖文件來(lái)繞過(guò)安全檢查。 7. 修改依賴后必須同步更新鎖文件并在變更描述里列出新增依賴及用途。 ## 許可證規(guī)則 1. 引入新依賴前檢查其許可證類型。 2. 如果許可證是 AGPL、GPL-3.0 或 SSPL默認(rèn)禁止引入除非用戶明確確認(rèn)。 3. 遇到不確定許可證的包停下并詢問(wèn)用戶不要猜。 ## 安全邊界 1. 禁止向依賴倉(cāng)庫(kù)提交憑據(jù)、令牌、私鑰。 2. 禁止在代碼中硬編碼密鑰或密碼必須提示用戶使用環(huán)境變量或密鑰管理服務(wù)。 3. 禁止關(guān)閉安全告警或修改審計(jì)工具的判斷閾值。這個(gè)文件看起來(lái)簡(jiǎn)單但它是整個(gè)方案的地基。Agent 讀到的不是“你最好注意安全”而是一組明確的操作指令。你可以發(fā)現(xiàn)規(guī)則里所有句子都是“動(dòng)作條件”而不是抽象的價(jià)值觀。Agent 對(duì)“注意安全”沒(méi)有概念但它知道“安裝后要運(yùn)行 pip-audit”是什么意思。4.2 在規(guī)則文件里搞一個(gè)“允許庫(kù)列表”和“禁用庫(kù)列表”只有通用規(guī)則還不夠。不同項(xiàng)目對(duì)庫(kù)的使用約束不一樣。比如某個(gè)項(xiàng)目出于供應(yīng)鏈安全考慮允許用的 HTTP 客戶端只有requests和httpx另一個(gè)項(xiàng)目可能禁止使用某些已知維護(hù)不積極的庫(kù)?？梢栽贏GENTS.md后面追加一個(gè)項(xiàng)目專屬列表## 項(xiàng)目允許使用的庫(kù) - requests (2.31.x, 2.32.x) - httpx (0.27.x) - pydantic (2.7.x) - fastapi (0.111.x) ## 項(xiàng)目禁止使用的庫(kù) - selenium本項(xiàng)目不需要瀏覽器自動(dòng)化 - scrapy如需爬蟲請(qǐng)先和用戶確認(rèn) - anyio如果只是 FastAPI 間接依賴不要直接 import - pyyaml優(yōu)先使用 ujson 或 orjson 處理配置如果你愿意還可以升級(jí)為結(jié)構(gòu)化策略文件比如security-policy.json并在AGENTS.md里注明 Agent 每次操作依賴前必須讀取該文件。這樣即使規(guī)則說(shuō)明比較長(zhǎng)Agent 也不會(huì)漏掉關(guān)鍵條目。{ 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 } }這里有一個(gè)實(shí)際經(jīng)驗(yàn)帶 Agent 的項(xiàng)目允許列表比禁用列表更好用。因?yàn)槟悴豢赡芰型晁形ｋU(xiǎn)包但你可以限定一個(gè)受信任范圍。一旦 Agent 發(fā)現(xiàn)“用戶要求安裝的包不在允許列表里”正確動(dòng)作是停下來(lái)詢問(wèn)而不是自作主張。4.3 給 Agent 安裝命令設(shè)置“安全帶”規(guī)則文件是軟約束Agent 不一定每次都能完整執(zhí)行。所以還要在命令層面加一個(gè)“安全帶”把安裝命令包裝成一個(gè)腳本腳本內(nèi)部先做檢查再執(zhí)行安裝。這里有一個(gè)關(guān)鍵點(diǎn)要注意不要直接教 Agent 使用原始的pip install xxx而是創(chuàng)建一個(gè)項(xiàng)目級(jí)封裝腳本。在 Windows 環(huán)境中可以創(chuàng)建一個(gè)install_deps.py或 PowerShell 腳本在 Linux/macOS 環(huán)境下可以創(chuàng)建一個(gè)scripts/install-deps.sh。下面是一個(gè)最小封裝示例適用于 Python 項(xiàng)目Linux/macOS#!/usr/bin/env bash # 文件路徑scripts/install-deps.sh set -euo pipefail echo 解析依賴并生成鎖文件 uv pip compile pyproject.toml -o requirements.lock echo 運(yùn)行漏洞掃描 osv-scanner --lockfile requirements.lock echo 掃描結(jié)果無(wú)高危漏洞執(zhí)行安裝 uv pip install -r requirements.lock然后在AGENTS.md里寫清楚## 安裝依賴時(shí) 必須運(yùn)行: bash scripts/install-deps.sh 禁止直接運(yùn)行: pip install package這樣做的意義是Agent 再靈活也只能在這個(gè)腳本允許的軌道上安裝依賴。掃描不過(guò)安裝就失敗Agent 就會(huì)停下反饋問(wèn)題而不是繼續(xù)“嘗試修復(fù)”。5. 配套自動(dòng)化檢查在 CI 層把門焊死規(guī)則文件和腳本能攔住大部分 Agent 的“無(wú)意識(shí)違規(guī)”但不能完全依賴 Agent 自覺(jué)。生產(chǎn)項(xiàng)目還有一個(gè)終極防線CI 流水線。只要依賴?yán)镉幸阎呶Ｂ┒椿虿环喜呗訡I 必須失敗。5.1 常規(guī)依賴掃描 CI 示例以 GitHub Actions 為例下面這個(gè) workflow 適合 Python 項(xiàng)目在每次 push 時(shí)運(yùn)行漏洞掃描。如果你用其他 CI 平臺(tái)原理是一樣的讀鎖文件、跑掃描器、以退出碼決定成敗。# 文件路徑.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 許可證掃描如果項(xiàng)目對(duì)許可證合規(guī)要求嚴(yán)格比如閉源商業(yè)項(xiàng)目還需要在 CI 里加一個(gè)許可證檢查。工具可以選擇license-checkerNode.js、pip-licensesPython等。這里給一個(gè) Python 項(xiàng)目的思路pip install pip-licenses pip-licenses --formatplain --ordercount --filter-typespackage \ --ignore-packageswheel licenses.txt然后在 CI 里解析licenses.txt如果檢測(cè)到 AGPL / GPL / SSPL 之類就報(bào)錯(cuò)。這一步可以寫在 CI 腳本里也可以接專門的合規(guī)平臺(tái)。核心目的是依賴庫(kù)的許可證問(wèn)題不能依賴 Agent 自行判斷。5.3 SBOM 生成讓依賴樹(shù)可審計(jì)更進(jìn)一步每次發(fā)布前或依賴變更后生成一份 SBOM 歸檔。SPDX 是常見(jiàn)格式CycloneDX 也很流行。cd $PROJECT_DIR pip install cyclonedx-bom cyclonedx-py -i requirements.lock -o sbom.xml有了 SBOM安全團(tuán)隊(duì)可以在發(fā)布前審查依賴全貌也能在漏洞情報(bào)出來(lái)時(shí)快速定位“哪個(gè)版本受影響、哪些服務(wù)在用”。AI Agent 的生產(chǎn)力優(yōu)勢(shì)要想真正落地到企業(yè)級(jí)項(xiàng)目SBOM 這一環(huán)是躲不開(kāi)的。6. 落地示例讓 Agent 在一個(gè)真實(shí)功能任務(wù)中遵守“庫(kù)安全規(guī)則”規(guī)則文件寫了、腳本配了、CI 加了那實(shí)際跑起來(lái)是什么樣子下面用一個(gè)最小場(chǎng)景走一遍完整鏈路。6.1 項(xiàng)目結(jié)構(gòu)示例假設(shè)項(xiàng)目是一個(gè)簡(jiǎn)單的 FastAPI 服務(wù)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] # 示例配置忽略不影響生產(chǎn)環(huán)境運(yùn)行的 dev 依賴 skip-editable true6.2 給 Agent 的任務(wù)你可以這樣發(fā)起任務(wù)請(qǐng)實(shí)現(xiàn)一個(gè)/health接口返回服務(wù)的當(dāng)前狀態(tài)。要求遵循 AGENTS.md 中的所有安全規(guī)則。如果需要新增依賴請(qǐng)先說(shuō)明原因再調(diào)用scripts/install-deps.sh完成安裝。一個(gè)遵守規(guī)則的 Agent應(yīng)該按下面順序操作讀取AGENTS.md檢查app/main.py當(dāng)前實(shí)現(xiàn)如果使用內(nèi)置FastAPI即可完成不新增任何依賴修改代碼、運(yùn)行測(cè)試最后額外執(zhí)行一次bash scripts/scan-deps.sh確認(rèn)依賴安全。scan-deps.sh內(nèi)容可以這樣寫#!/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. 檢查許可證合規(guī)示例只打印實(shí)際按項(xiàng)目策略決定是否失敗 pip-licenses --formatplain --ordercount || true echo 依賴安全檢查完成無(wú)阻斷問(wèn)題。6.3 運(yùn)行結(jié)果驗(yàn)證如果所有命令退出碼為 0控制臺(tái)大概長(zhǎng)這樣 1. 使用 osv-scanner 掃描已知漏洞 Scanned 5 lockfile packages, found 0 vulnerabilities. 2. 使用 pip-audit 檢查 Python 依賴漏洞 Found 0 known vulnerabilities in 5 dependencies. 3. 檢查許可證合規(guī)示例只打印實(shí)際按項(xiàng)目策略決定是否失敗 Licenses: fastapi BSD-3-Clause uvicorn BSD-3-Clause pydantic MIT requests Apache-2.0 ... 依賴安全檢查完成無(wú)阻斷問(wèn)題。這個(gè)任務(wù)本身不復(fù)雜但注意一個(gè)細(xì)節(jié)Agent 沒(méi)有被要求“不得使用新庫(kù)”而是被要求“如果需要新增依賴先說(shuō)明原因再走腳本”。這樣它就會(huì)傾向于復(fù)用現(xiàn)有依賴而不是一上來(lái)就引入新庫(kù)。這正是規(guī)則文件帶來(lái)的行為改變。7. 常見(jiàn)問(wèn)題與排查思路在給團(tuán)隊(duì)推行這套方案時(shí)有幾個(gè)問(wèn)題是反復(fù)出現(xiàn)的整理成表格方便排查。問(wèn)題現(xiàn)象可能原因排查方式解決方案Agent 不讀取 AGENTS.md還是擅自裝包工具版本過(guò)舊或未配置“讀取項(xiàng)目規(guī)則文件”檢查 IDE / CLI 的 Agent 文檔確認(rèn)規(guī)則文件名是否正確統(tǒng)一規(guī)則文件名在啟動(dòng)命令中顯式--memory指定規(guī)則文件路徑AGENTS.md 寫了禁止列表Agent 仍然視而不見(jiàn)禁止列表是自然語(yǔ)言Agent 解析有歧義用結(jié)構(gòu)化策略文件JSON/YAML替代純文本參考上文 security-policy.json在 AGENTS.md 中引用文件路徑pip-audit報(bào)出漏洞Agent 擅自執(zhí)行升級(jí)規(guī)則里沒(méi)有寫明“發(fā)現(xiàn)有漏洞后必須停下”檢查 AGENTS.md 中的漏洞處理指令是否明確增加“發(fā)現(xiàn)高危漏洞時(shí)禁止自行升級(jí)必須向用戶報(bào)告并等待指示”Agent 從非官方源下載依賴規(guī)則文件未明確“只能使用官方源”或系統(tǒng)全局源配置被污染檢查 pip / npm 的全局配置文件在規(guī)則文件和管理端固定源地址并在 CI 中禁止非官方源許可證檢查總是誤報(bào)檢測(cè)工具覆蓋了開(kāi)發(fā)依賴或工具鏈自帶的依賴查看許可證檢查器的過(guò)濾配置在掃描腳本里配置忽略 dev/test 類依賴或建立白名單CI 掃描通過(guò)率太低團(tuán)隊(duì)選擇刪除掃卡規(guī)則過(guò)于嚴(yán)格影響了正常迭代查看歷史失敗記錄區(qū)分阻斷策略先設(shè)為“warning”運(yùn)行一周再逐步收緊為“error”阻斷有一個(gè)經(jīng)驗(yàn)值得強(qiáng)調(diào)不要一開(kāi)始就把所有檢查設(shè)成“阻斷”。如果第一次推行就讓 CI 頻繁失敗團(tuán)隊(duì)很快就會(huì)把安全掃描當(dāng)作“狼來(lái)了”最后干脆關(guān)掉。建議先讓掃描結(jié)果進(jìn)入 MR 評(píng)論或人工檢查運(yùn)行一兩周確認(rèn)誤報(bào)率可控后再把危險(xiǎn)項(xiàng)升級(jí)為阻斷。8. 最佳實(shí)踐與工程建議方案跑通之后還要注意一些容易被忽略的細(xì)節(jié)。這里按“開(kāi)發(fā)者、Agent、CI/平臺(tái)”三個(gè)角色分別給出建議。8.1 開(kāi)發(fā)者側(cè)規(guī)則文件要“短而可執(zhí)行”規(guī)則文件不是越長(zhǎng)越好。從實(shí)踐效果看如果超過(guò) 50 行且包含大量泛泛而談的句子Agent 的執(zhí)行效果會(huì)明顯下降。更好的做法是規(guī)則文件保持精簡(jiǎn)只寫“必須做”和“不能做”用結(jié)構(gòu)化數(shù)據(jù)文件承載完整策略把“為什么這么規(guī)定”寫在給人類看的文檔里而不是塞進(jìn) AGENTS.md每季度根據(jù) Agent 的實(shí)際違規(guī)案例修訂一次規(guī)則。另外規(guī)則文件的命名盡量要兼容主流工具。Cursor 和 Copilot 支持AGENTS.mdClaude Code 支持CLAUDE.md。如果你同時(shí)使用多款工具可以保持同一份內(nèi)容復(fù)制到多個(gè)文件名盡量讓維護(hù)源只有一個(gè)。8.2 Agent 側(cè)升級(jí)依賴要遵循最小變更原則對(duì) AI coding agents 最該強(qiáng)調(diào)的一條鐵律是不要為了修復(fù)一個(gè)非阻斷問(wèn)題而升級(jí)整個(gè)依賴樹(shù)。最小變更原則在人工開(kāi)發(fā)里是常識(shí)在 Agent 場(chǎng)景里很容易被打破。所以規(guī)則文件里建議明確每次依賴變更只修改與任務(wù)直接相關(guān)的包升級(jí)前先說(shuō)明版本變化帶來(lái)的影響升級(jí)后跑測(cè)試和安全掃描確保無(wú)回歸如果測(cè)試失敗禁止通過(guò)“降級(jí)其他依賴”的方式繞過(guò)。8.3 CI / 平臺(tái)側(cè)安全掃描必須和 Agent 的執(zhí)行權(quán)限解耦這只是整條鏈路里的一個(gè)提醒即便團(tuán)隊(duì)里已經(jīng)有很成熟的 CI 安全卡點(diǎn)也不要給 Agent 開(kāi)放過(guò)高的本地執(zhí)行權(quán)限。Agent 在開(kāi)發(fā)者本機(jī)跑安裝命令時(shí)它不應(yīng)有向生產(chǎn)環(huán)境發(fā)布包的權(quán)限。安全邊界是分層的本機(jī)規(guī)則文件 封裝腳本倉(cāng)庫(kù)分支保護(hù) MR 審查CI依賴掃描 許可證檢查 SBOM 歸檔生產(chǎn)環(huán)境鏡像或制品發(fā)布前再做一次不可變審計(jì)。每一層的目標(biāo)都不是“讓 Agent 變乖”而是“即使 Agent 偶爾出錯(cuò)也有下一層兜底”。9. 總結(jié)與后續(xù)學(xué)習(xí)方向回到開(kāi)頭那個(gè)判斷AI coding agents 真正需要的不只是“更聰明的代碼生成”而是“更明確的工程約束”。庫(kù)安全這件事正好是檢驗(yàn)約束力的一塊試金石。規(guī)則文件、封裝腳本、CI 掃描三層配合就能讓 Agent 在快速產(chǎn)出的同時(shí)不把供應(yīng)鏈安全搞崩。如果你接下來(lái)想繼續(xù)深入這幾個(gè)方向值得關(guān)注嘗試用osv-scanner掃描現(xiàn)有項(xiàng)目的 lockfile看看歷史依賴?yán)锸欠翊嬖谝阎┒磳W(xué)習(xí) SPDX 和 CycloneDX 兩種 SBOM 格式了解依賴可審計(jì)性的具體標(biāo)準(zhǔn)如果你的 Agent 工具支持自定義工具調(diào)用可以考慮把“依賴掃描”作為 Agent 必須調(diào)用的一次工具關(guān)注 AI Agent 領(lǐng)域關(guān)于“可信執(zhí)行邊界”的討論這類框架會(huì)越來(lái)越成熟。希望這篇內(nèi)容能幫你少踩幾個(gè)依賴安全的坑。建議收藏備用下次給項(xiàng)目接入 AI 編程助手時(shí)直接把規(guī)則文件改一改就能用。 AI編程助手庫(kù)安全指南：為Agent建立可執(zhí)行的依賴使用規(guī)則
很多開(kāi)發(fā)者在用 AI 編程助手時(shí)都遇到過(guò)這樣的場(chǎng)景讓 Agent 修一個(gè) bug它唰唰唰改完代碼順手給你pip install了一個(gè)新依賴或者你在提示詞里讓它“用最流行的方案實(shí)現(xiàn)”結(jié)果它挑了一個(gè)三年沒(méi)維護(hù)、CVE 一堆的庫(kù)。代碼功能確實(shí)沒(méi)毛病但依賴關(guān)系一出來(lái)安全這塊就開(kāi)始“埋雷”。AI coding agents 寫代碼的速度是傳統(tǒng)開(kāi)發(fā)者的好幾倍。但問(wèn)題恰恰出在這里代碼生成速度快依賴引入的速度也快代碼審查還能靠人眼依賴安全和庫(kù)使用安全很少有人能跟上這個(gè)速度。如果不斷言一句這篇文章想表達(dá)的核心判斷是這樣的AI 編程時(shí)代真正需要重新設(shè)計(jì)的安全防線不是讓 AI“生成更安全的代碼”而是讓 AI“按照安全規(guī)則去選擇和調(diào)用第三方庫(kù)”。前者依賴模型能力后者依賴工程流程。這篇文章想聊的就是這件事怎么給 AI coding agents 建立一套“庫(kù)安全使用規(guī)則”讓它幫我們寫代碼的同時(shí)不在依賴層面給項(xiàng)目留下安全隱患。你會(huì)看到具體可復(fù)制的規(guī)則文件寫法、配套的自動(dòng)化檢查工具、落地到 CI 的完整配置以及最常見(jiàn)的坑和排查方式。如果你正在用 Cursor、Copilot、Claude Code、Codex 這類 AI 編程工具或者自己基于 LLM 開(kāi)發(fā) coding agent這篇文章值得讀完并收藏。1. 為什么 AI Coding Agents 讓“庫(kù)安全”問(wèn)題被放大了很多人覺(jué)得AI 寫代碼的安全問(wèn)題在于“它可能寫出 SQL 注入、XSS、反序列化漏洞”。這個(gè)擔(dān)心不無(wú)道理但站在工程實(shí)踐的角度看一個(gè)更隱蔽、更普遍的問(wèn)題被忽略了AI 在庫(kù)的引入和使用方式上幾乎沒(méi)有風(fēng)險(xiǎn)意識(shí)。1.1 AI 選庫(kù)的常見(jiàn)套路與風(fēng)險(xiǎn)先還原一下 Agent 的工作過(guò)程。當(dāng)你在 IDE 里讓 AI “實(shí)現(xiàn)某個(gè)功能”時(shí)它通常不是從零開(kāi)始造輪子而是從訓(xùn)練數(shù)據(jù)里回憶“這個(gè)問(wèn)題一般用什么庫(kù)解決”然后在代碼里import一個(gè)庫(kù)自動(dòng)執(zhí)行安裝命令把庫(kù)加進(jìn)依賴根據(jù)該庫(kù)的 README、文檔或記憶里的 API寫出調(diào)用代碼。這個(gè)鏈路本身無(wú)可厚非甚至和人類開(kāi)發(fā)者的行為一致。但差異在于人類開(kāi)發(fā)者選庫(kù)時(shí)會(huì)下意識(shí)做一個(gè)“安全評(píng)估”這個(gè)庫(kù)最近有沒(méi)有更新Star 數(shù)多少維護(hù)者還活躍嗎歷史上有沒(méi)有高危漏洞AI 不會(huì)做這些事它只會(huì)判斷“這個(gè)庫(kù)在語(yǔ)義上能不能完成任務(wù)”。于是我們開(kāi)始看到下列問(wèn)題在團(tuán)隊(duì)里反復(fù)出現(xiàn)Agent 引入了一個(gè)存在已知 RCE 漏洞的舊版本庫(kù)Agent 為了解決一個(gè)無(wú)關(guān)緊要的兼容問(wèn)題把一個(gè)帶底層原生代碼native library的傳遞依賴?yán)M(jìn)了項(xiàng)目Agent 從網(wǎng)上“學(xué)習(xí)”到了一個(gè)拼寫相近的惡意包并且真的把它裝進(jìn)了環(huán)境Agent 頻繁修改requirements.txt或package.json但沒(méi)有任何人逐行核對(duì)依賴變更。這些問(wèn)題的共性是出問(wèn)題的位置不在 AI 寫的業(yè)務(wù)代碼里而在依賴解析和庫(kù)選擇的邊界上。也就是說(shuō)傳統(tǒng)代碼安全 Review 關(guān)注的是“你寫的代碼有沒(méi)有毛病”而 Agent 場(chǎng)景下還必須增加一層“你引入的庫(kù)和依賴關(guān)系有沒(méi)有毛病”。1.2 為什么人工審查跟不上有一個(gè)很現(xiàn)實(shí)的原因讓這個(gè)問(wèn)題更棘手AI 生成代碼的速度太快了尤其是 Agent 自主運(yùn)行的場(chǎng)景。一個(gè) Agent 可能在幾分鐘內(nèi)完成一次“安裝依賴、運(yùn)行測(cè)試、修復(fù)錯(cuò)誤、再跑”的循環(huán)。在這種節(jié)奏下如果安全檢查還停留在“等開(kāi)發(fā)者在 Code Review 時(shí)看一眼”基本等于沒(méi)檢查。更麻煩的是很多 Agent 對(duì)“修復(fù)錯(cuò)誤”有一種過(guò)度執(zhí)念。比如 CI 里報(bào)了一個(gè) lint 錯(cuò)誤Agent 會(huì)想盡辦法讓測(cè)試通過(guò)包括但不限于升級(jí)依賴、引入新庫(kù)、繞過(guò)某些檢查。它以為自己在解決問(wèn)題實(shí)際上可能是在制造問(wèn)題。這也解釋了為什么單純的“提示 AI 注意安全”并不可靠你需要從工具和流程層面強(qiáng)制約束它。1.3 核心判斷庫(kù)安全是 AI 編程時(shí)代的新“關(guān)鍵路徑”傳統(tǒng)軟件工程里依賴安全是“常識(shí)”但因?yàn)橛腥斯?review 環(huán)節(jié)即使偶爾出錯(cuò)也有機(jī)會(huì)被攔下來(lái)。到了 AI coding agents 時(shí)代依賴選擇、依賴安裝、依賴升級(jí)都開(kāi)始變成“自動(dòng)化動(dòng)作”。自動(dòng)化動(dòng)作沒(méi)有安全意識(shí)只會(huì)放大風(fēng)險(xiǎn)。所以結(jié)論就變得非常清晰想安全地使用 AI 編程 Agent必須把“庫(kù)安全規(guī)則”從人腦記憶轉(zhuǎn)移到一個(gè) Agent 能讀取、工具鏈能執(zhí)行的標(biāo)準(zhǔn)化文件中。這就是“guide AI coding agents on how to use libraries securely”這句話的真正含義。2. 先搞清楚一個(gè)概念A(yù)I Coding Agents 是怎么“用庫(kù)”的為了不讓后面的方案變成空中樓閣我們先拆解一下 Agent 使用第三方庫(kù)的三種典型方式。三種方式的風(fēng)險(xiǎn)和應(yīng)對(duì)策略完全不同。2.1 方式一代碼生成時(shí)按記憶 import這是最常見(jiàn)的一種。你告訴 Agent “解析一下這個(gè) JSON”它直接寫出import json或import orjson。此時(shí) Agent 并沒(méi)有執(zhí)行任何命令只是基于訓(xùn)練記憶選擇庫(kù)。這種方式的隱患在于“訓(xùn)練數(shù)據(jù)不等于實(shí)時(shí)安全數(shù)據(jù)”。Agent 訓(xùn)練時(shí)某個(gè)庫(kù)是安全的等到實(shí)際運(yùn)行時(shí)該庫(kù)可能已經(jīng)被曝出高危漏洞。Agent 對(duì)此毫無(wú)感知它會(huì)繼續(xù)按舊記憶使用。另外Agent 對(duì)“哪個(gè)庫(kù)更安全”的判斷往往來(lái)自“熱門程度”而不是漏洞歷史這就可能導(dǎo)致它選了一個(gè)看起來(lái)很火、但實(shí)際上維護(hù)停滯的庫(kù)。2.2 方式二自主執(zhí)行安裝命令更復(fù)雜的情況是Agent 具備執(zhí)行命令的權(quán)限。它發(fā)現(xiàn)代碼缺少依賴就會(huì)自動(dòng)運(yùn)行pip install requests或npm install lodash之類的命令。這是風(fēng)險(xiǎn)最高的一種方式。原因有三個(gè)版本不確定性如果不加版本號(hào)安裝命令默認(rèn)拉取當(dāng)前最新版本而“最新”不等于“經(jīng)過(guò)安全驗(yàn)證”。某些場(chǎng)景下最新版本可能引入不兼容變更或新的安全問(wèn)題。依賴混淆Dependency Confusion風(fēng)險(xiǎn)如果項(xiàng)目的私有倉(cāng)庫(kù)和公共倉(cāng)庫(kù)配置不當(dāng)Agent 安裝的包名可能被公共倉(cāng)庫(kù)上的同名惡意包搶注從而被投毒。傳遞依賴不可控你讓 Agent 裝一個(gè)庫(kù)這個(gè)庫(kù)又會(huì)自動(dòng)拉取幾十個(gè)傳遞依賴。這些傳遞依賴是否符合安全基線Agent 根本不會(huì)檢查?？梢哉f(shuō)在 Agent 自主執(zhí)行安裝命令時(shí)它是在“替你做決定”但又不具備你作為開(kāi)發(fā)者本該有的判斷力。2.3 方式三在提示詞或規(guī)則文件指導(dǎo)下使用庫(kù)第三種方式是新趨勢(shì)開(kāi)發(fā)者在項(xiàng)目里提供一個(gè)專門的規(guī)則文件例如AGENTS.md、CLAUDE.md或agent-rules.txt告訴 Agent 哪些庫(kù)可以用、哪些不能用、版本約束是什么、安裝前必須執(zhí)行什么檢查。Agent 在執(zhí)行任務(wù)時(shí)先讀取文件再按要求操作。這才是真正值得推廣的做法。因?yàn)樗选叭说陌踩?jīng)驗(yàn)”變成了“機(jī)器可執(zhí)行的約束”而不是指望 Agent 自己“聰明地”避坑。本文后面重點(diǎn)講的就是這個(gè)方式的工程落地細(xì)節(jié)。3. 庫(kù)安全到底包含哪些內(nèi)容不只是”別用舊版本“如果把“庫(kù)安全”僅僅理解為“依賴版本要新”那這個(gè)理解太淺了。一個(gè)真正可落地的庫(kù)安全規(guī)則至少覆蓋下面幾個(gè)維度。3.1 已知漏洞CVE檢測(cè)這是最基礎(chǔ)的一條。每個(gè)依賴包的歷史版本里都可能存在已公開(kāi)漏洞例如 Python 生態(tài)的CVE-2023-XXXX、JavaScript 生態(tài)的GHSA-XXXX。規(guī)則應(yīng)該要求 Agent 在引入任何新依賴后運(yùn)行漏洞掃描工具確保沒(méi)有已公開(kāi)的已知安全漏洞。常見(jiàn)工具包括生態(tài)常用工具Pythonpip-audit、osv-scannerNode.jsnpm audit、osv-scannerJavaOWASP Dependency-Check、osv-scannerGogovulncheck從經(jīng)驗(yàn)看osv-scanner是目前覆蓋面廣、接入成本低的通用方案因?yàn)樗x取鎖定文件lockfile即可工作不依賴具體語(yǔ)言包管理器。3.2 許可證合規(guī)很多 AI 生成的代碼會(huì)順手引入開(kāi)源庫(kù)但開(kāi)源庫(kù)的許可證類型并不都是寬松的。GPL、AGPL 這類傳染性許可證在某些商業(yè)項(xiàng)目中會(huì)帶來(lái)合規(guī)問(wèn)題。AI Agent 通常不會(huì)主動(dòng)告訴你“我用的這個(gè)庫(kù)是 AGPL 協(xié)議的可能會(huì)影響你的商業(yè)閉源分發(fā)”。所以你要主動(dòng)通過(guò)規(guī)則文件要求它引入依賴前先檢查許可證類型遇到高風(fēng)險(xiǎn)許可證必須停止并詢問(wèn)。3.3 依賴混淆與惡意包防護(hù)隨著 AI 編程工具的流行一個(gè)更惡意的風(fēng)險(xiǎn)浮出水面攻擊者會(huì)注冊(cè)一些看起來(lái)像“知名庫(kù)拼寫錯(cuò)誤”或“知名庫(kù)公司名”的惡意包等待 AI Agent 在自動(dòng)補(bǔ)全或自動(dòng)安裝時(shí)踩中。有些攻擊者甚至?xí)ｉT研究 AI 模型訓(xùn)練時(shí)常用的庫(kù)名提前把惡意版本發(fā)布到公共倉(cāng)庫(kù)。要在規(guī)則文件里明確要求只能從官方源安裝依賴禁止從非官方地址安裝如果安裝失敗不得自行更換來(lái)路不明的源。這一點(diǎn)在涉及私有倉(cāng)庫(kù)時(shí)尤其重要。3.4 版本鎖定與可復(fù)現(xiàn)性Agent 的另一個(gè)壞習(xí)慣是傾向于使用“通配版本”或“最新版本”比如numpy1.24。這會(huì)讓構(gòu)建結(jié)果不可復(fù)現(xiàn)。兩個(gè)開(kāi)發(fā)者、兩個(gè) CI 環(huán)境可能裝出不同的依賴樹(shù)安全問(wèn)題也因此難以追蹤。最佳實(shí)踐是所有直接依賴都鎖定到精確版本并用鎖文件固定完整依賴樹(shù)。規(guī)則文件里必須要求 Agent 修改依賴后運(yùn)行l(wèi)ock相關(guān)命令并提交鎖文件變更。3.5 傳遞依賴的可見(jiàn)性很多時(shí)候直接依賴是安全的問(wèn)題出在它的子依賴?yán)?。因此?guī)則也應(yīng)要求 Agent 在引入新依賴后生成或更新 SBOM軟件物料清單至少要讓開(kāi)發(fā)者能看清完整依賴樹(shù)。如果項(xiàng)目已經(jīng)有依賴更新審查工具如 Dependabot規(guī)則里要寫明由這些工具負(fù)責(zé)升級(jí)Agent 不要擅自升級(jí)。4. 給 AI Coding Agents 建立“庫(kù)安全使用規(guī)則”的完整方案聊完背景進(jìn)入真正的實(shí)操。下面這套方案不需要引入復(fù)雜平臺(tái)只需要三個(gè)層面的配合項(xiàng)目里的規(guī)則文件Agent 讀取并遵守命令執(zhí)行前的安全檢查腳本Agent 調(diào)用CI 里的強(qiáng)制卡點(diǎn)即使 Agent 不遵守也攔得住。4.1 規(guī)則文件讓安全要求變成 Agent 的“工作手冊(cè)”規(guī)則文件推薦放在項(xiàng)目根目錄命名可參考你的 Agent 工具約定。例如Cursor / CopilotAGENTS.mdClaude CodeCLAUDE.md通用AGENTS.md目前是最常見(jiàn)的約定文件本身是 Markdown 格式Agent 會(huì)自動(dòng)讀取。下面給出一個(gè)可以選擇直接使用的示例。# AGENTS.md ## 角色 你是本項(xiàng)目的 AI 編碼助手可以修改代碼、運(yùn)行命令但必須遵守本文件中的安全規(guī)則。 ## 依賴引入規(guī)則 1. 在添加任何第三方庫(kù)之前先搜索項(xiàng)目?jī)?nèi)是否已有可復(fù)用依賴優(yōu)先復(fù)用現(xiàn)有依賴。 2. 必須從官方源安裝依賴禁止使用來(lái)源不明的鏡像源或安裝命令。 3. 必須使用精確版本號(hào)禁止使用 latest、1.0.0 之類的不確定版本。 4. 安裝完成后必須運(yùn)行安全掃描命令 - Python: uv pip audit 或 pip-audit - Node.js: npm audit - 通用: osv-scanner --lockfile lockfile-path 5. 如果掃描發(fā)現(xiàn)高危漏洞禁止通過(guò)“忽略”或“升級(jí)到最新版”的方式強(qiáng)行解決必須停下并向用戶報(bào)告。 6. 禁止修改鎖文件來(lái)繞過(guò)安全檢查。 7. 修改依賴后必須同步更新鎖文件并在變更描述里列出新增依賴及用途。 ## 許可證規(guī)則 1. 引入新依賴前檢查其許可證類型。 2. 如果許可證是 AGPL、GPL-3.0 或 SSPL默認(rèn)禁止引入除非用戶明確確認(rèn)。 3. 遇到不確定許可證的包停下并詢問(wèn)用戶不要猜。 ## 安全邊界 1. 禁止向依賴倉(cāng)庫(kù)提交憑據(jù)、令牌、私鑰。 2. 禁止在代碼中硬編碼密鑰或密碼必須提示用戶使用環(huán)境變量或密鑰管理服務(wù)。 3. 禁止關(guān)閉安全告警或修改審計(jì)工具的判斷閾值。這個(gè)文件看起來(lái)簡(jiǎn)單但它是整個(gè)方案的地基。Agent 讀到的不是“你最好注意安全”而是一組明確的操作指令。你可以發(fā)現(xiàn)規(guī)則里所有句子都是“動(dòng)作條件”而不是抽象的價(jià)值觀。Agent 對(duì)“注意安全”沒(méi)有概念但它知道“安裝后要運(yùn)行 pip-audit”是什么意思。4.2 在規(guī)則文件里搞一個(gè)“允許庫(kù)列表”和“禁用庫(kù)列表”只有通用規(guī)則還不夠。不同項(xiàng)目對(duì)庫(kù)的使用約束不一樣。比如某個(gè)項(xiàng)目出于供應(yīng)鏈安全考慮允許用的 HTTP 客戶端只有requests和httpx另一個(gè)項(xiàng)目可能禁止使用某些已知維護(hù)不積極的庫(kù)?？梢栽贏GENTS.md后面追加一個(gè)項(xiàng)目專屬列表## 項(xiàng)目允許使用的庫(kù) - requests (2.31.x, 2.32.x) - httpx (0.27.x) - pydantic (2.7.x) - fastapi (0.111.x) ## 項(xiàng)目禁止使用的庫(kù) - selenium本項(xiàng)目不需要瀏覽器自動(dòng)化 - scrapy如需爬蟲請(qǐng)先和用戶確認(rèn) - anyio如果只是 FastAPI 間接依賴不要直接 import - pyyaml優(yōu)先使用 ujson 或 orjson 處理配置如果你愿意還可以升級(jí)為結(jié)構(gòu)化策略文件比如security-policy.json并在AGENTS.md里注明 Agent 每次操作依賴前必須讀取該文件。這樣即使規(guī)則說(shuō)明比較長(zhǎng)Agent 也不會(huì)漏掉關(guān)鍵條目。{ 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 } }這里有一個(gè)實(shí)際經(jīng)驗(yàn)帶 Agent 的項(xiàng)目允許列表比禁用列表更好用。因?yàn)槟悴豢赡芰型晁形ｋU(xiǎn)包但你可以限定一個(gè)受信任范圍。一旦 Agent 發(fā)現(xiàn)“用戶要求安裝的包不在允許列表里”正確動(dòng)作是停下來(lái)詢問(wèn)而不是自作主張。4.3 給 Agent 安裝命令設(shè)置“安全帶”規(guī)則文件是軟約束Agent 不一定每次都能完整執(zhí)行。所以還要在命令層面加一個(gè)“安全帶”把安裝命令包裝成一個(gè)腳本腳本內(nèi)部先做檢查再執(zhí)行安裝。這里有一個(gè)關(guān)鍵點(diǎn)要注意不要直接教 Agent 使用原始的pip install xxx而是創(chuàng)建一個(gè)項(xiàng)目級(jí)封裝腳本。在 Windows 環(huán)境中可以創(chuàng)建一個(gè)install_deps.py或 PowerShell 腳本在 Linux/macOS 環(huán)境下可以創(chuàng)建一個(gè)scripts/install-deps.sh。下面是一個(gè)最小封裝示例適用于 Python 項(xiàng)目Linux/macOS#!/usr/bin/env bash # 文件路徑scripts/install-deps.sh set -euo pipefail echo 解析依賴并生成鎖文件 uv pip compile pyproject.toml -o requirements.lock echo 運(yùn)行漏洞掃描 osv-scanner --lockfile requirements.lock echo 掃描結(jié)果無(wú)高危漏洞執(zhí)行安裝 uv pip install -r requirements.lock然后在AGENTS.md里寫清楚## 安裝依賴時(shí) 必須運(yùn)行: bash scripts/install-deps.sh 禁止直接運(yùn)行: pip install package這樣做的意義是Agent 再靈活也只能在這個(gè)腳本允許的軌道上安裝依賴。掃描不過(guò)安裝就失敗Agent 就會(huì)停下反饋問(wèn)題而不是繼續(xù)“嘗試修復(fù)”。5. 配套自動(dòng)化檢查在 CI 層把門焊死規(guī)則文件和腳本能攔住大部分 Agent 的“無(wú)意識(shí)違規(guī)”但不能完全依賴 Agent 自覺(jué)。生產(chǎn)項(xiàng)目還有一個(gè)終極防線CI 流水線。只要依賴?yán)镉幸阎呶Ｂ┒椿虿环喜呗訡I 必須失敗。5.1 常規(guī)依賴掃描 CI 示例以 GitHub Actions 為例下面這個(gè) workflow 適合 Python 項(xiàng)目在每次 push 時(shí)運(yùn)行漏洞掃描。如果你用其他 CI 平臺(tái)原理是一樣的讀鎖文件、跑掃描器、以退出碼決定成敗。# 文件路徑.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 許可證掃描如果項(xiàng)目對(duì)許可證合規(guī)要求嚴(yán)格比如閉源商業(yè)項(xiàng)目還需要在 CI 里加一個(gè)許可證檢查。工具可以選擇license-checkerNode.js、pip-licensesPython等。這里給一個(gè) Python 項(xiàng)目的思路pip install pip-licenses pip-licenses --formatplain --ordercount --filter-typespackage \ --ignore-packageswheel licenses.txt然后在 CI 里解析licenses.txt如果檢測(cè)到 AGPL / GPL / SSPL 之類就報(bào)錯(cuò)。這一步可以寫在 CI 腳本里也可以接專門的合規(guī)平臺(tái)。核心目的是依賴庫(kù)的許可證問(wèn)題不能依賴 Agent 自行判斷。5.3 SBOM 生成讓依賴樹(shù)可審計(jì)更進(jìn)一步每次發(fā)布前或依賴變更后生成一份 SBOM 歸檔。SPDX 是常見(jiàn)格式CycloneDX 也很流行。cd $PROJECT_DIR pip install cyclonedx-bom cyclonedx-py -i requirements.lock -o sbom.xml有了 SBOM安全團(tuán)隊(duì)可以在發(fā)布前審查依賴全貌也能在漏洞情報(bào)出來(lái)時(shí)快速定位“哪個(gè)版本受影響、哪些服務(wù)在用”。AI Agent 的生產(chǎn)力優(yōu)勢(shì)要想真正落地到企業(yè)級(jí)項(xiàng)目SBOM 這一環(huán)是躲不開(kāi)的。6. 落地示例讓 Agent 在一個(gè)真實(shí)功能任務(wù)中遵守“庫(kù)安全規(guī)則”規(guī)則文件寫了、腳本配了、CI 加了那實(shí)際跑起來(lái)是什么樣子下面用一個(gè)最小場(chǎng)景走一遍完整鏈路。6.1 項(xiàng)目結(jié)構(gòu)示例假設(shè)項(xiàng)目是一個(gè)簡(jiǎn)單的 FastAPI 服務(wù)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] # 示例配置忽略不影響生產(chǎn)環(huán)境運(yùn)行的 dev 依賴 skip-editable true6.2 給 Agent 的任務(wù)你可以這樣發(fā)起任務(wù)請(qǐng)實(shí)現(xiàn)一個(gè)/health接口返回服務(wù)的當(dāng)前狀態(tài)。要求遵循 AGENTS.md 中的所有安全規(guī)則。如果需要新增依賴請(qǐng)先說(shuō)明原因再調(diào)用scripts/install-deps.sh完成安裝。一個(gè)遵守規(guī)則的 Agent應(yīng)該按下面順序操作讀取AGENTS.md檢查app/main.py當(dāng)前實(shí)現(xiàn)如果使用內(nèi)置FastAPI即可完成不新增任何依賴修改代碼、運(yùn)行測(cè)試最后額外執(zhí)行一次bash scripts/scan-deps.sh確認(rèn)依賴安全。scan-deps.sh內(nèi)容可以這樣寫#!/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. 檢查許可證合規(guī)示例只打印實(shí)際按項(xiàng)目策略決定是否失敗 pip-licenses --formatplain --ordercount || true echo 依賴安全檢查完成無(wú)阻斷問(wèn)題。6.3 運(yùn)行結(jié)果驗(yàn)證如果所有命令退出碼為 0控制臺(tái)大概長(zhǎng)這樣 1. 使用 osv-scanner 掃描已知漏洞 Scanned 5 lockfile packages, found 0 vulnerabilities. 2. 使用 pip-audit 檢查 Python 依賴漏洞 Found 0 known vulnerabilities in 5 dependencies. 3. 檢查許可證合規(guī)示例只打印實(shí)際按項(xiàng)目策略決定是否失敗 Licenses: fastapi BSD-3-Clause uvicorn BSD-3-Clause pydantic MIT requests Apache-2.0 ... 依賴安全檢查完成無(wú)阻斷問(wèn)題。這個(gè)任務(wù)本身不復(fù)雜但注意一個(gè)細(xì)節(jié)Agent 沒(méi)有被要求“不得使用新庫(kù)”而是被要求“如果需要新增依賴先說(shuō)明原因再走腳本”。這樣它就會(huì)傾向于復(fù)用現(xiàn)有依賴而不是一上來(lái)就引入新庫(kù)。這正是規(guī)則文件帶來(lái)的行為改變。7. 常見(jiàn)問(wèn)題與排查思路在給團(tuán)隊(duì)推行這套方案時(shí)有幾個(gè)問(wèn)題是反復(fù)出現(xiàn)的整理成表格方便排查。問(wèn)題現(xiàn)象可能原因排查方式解決方案Agent 不讀取 AGENTS.md還是擅自裝包工具版本過(guò)舊或未配置“讀取項(xiàng)目規(guī)則文件”檢查 IDE / CLI 的 Agent 文檔確認(rèn)規(guī)則文件名是否正確統(tǒng)一規(guī)則文件名在啟動(dòng)命令中顯式--memory指定規(guī)則文件路徑AGENTS.md 寫了禁止列表Agent 仍然視而不見(jiàn)禁止列表是自然語(yǔ)言Agent 解析有歧義用結(jié)構(gòu)化策略文件JSON/YAML替代純文本參考上文 security-policy.json在 AGENTS.md 中引用文件路徑pip-audit報(bào)出漏洞Agent 擅自執(zhí)行升級(jí)規(guī)則里沒(méi)有寫明“發(fā)現(xiàn)有漏洞后必須停下”檢查 AGENTS.md 中的漏洞處理指令是否明確增加“發(fā)現(xiàn)高危漏洞時(shí)禁止自行升級(jí)必須向用戶報(bào)告并等待指示”Agent 從非官方源下載依賴規(guī)則文件未明確“只能使用官方源”或系統(tǒng)全局源配置被污染檢查 pip / npm 的全局配置文件在規(guī)則文件和管理端固定源地址并在 CI 中禁止非官方源許可證檢查總是誤報(bào)檢測(cè)工具覆蓋了開(kāi)發(fā)依賴或工具鏈自帶的依賴查看許可證檢查器的過(guò)濾配置在掃描腳本里配置忽略 dev/test 類依賴或建立白名單CI 掃描通過(guò)率太低團(tuán)隊(duì)選擇刪除掃卡規(guī)則過(guò)于嚴(yán)格影響了正常迭代查看歷史失敗記錄區(qū)分阻斷策略先設(shè)為“warning”運(yùn)行一周再逐步收緊為“error”阻斷有一個(gè)經(jīng)驗(yàn)值得強(qiáng)調(diào)不要一開(kāi)始就把所有檢查設(shè)成“阻斷”。如果第一次推行就讓 CI 頻繁失敗團(tuán)隊(duì)很快就會(huì)把安全掃描當(dāng)作“狼來(lái)了”最后干脆關(guān)掉。建議先讓掃描結(jié)果進(jìn)入 MR 評(píng)論或人工檢查運(yùn)行一兩周確認(rèn)誤報(bào)率可控后再把危險(xiǎn)項(xiàng)升級(jí)為阻斷。8. 最佳實(shí)踐與工程建議方案跑通之后還要注意一些容易被忽略的細(xì)節(jié)。這里按“開(kāi)發(fā)者、Agent、CI/平臺(tái)”三個(gè)角色分別給出建議。8.1 開(kāi)發(fā)者側(cè)規(guī)則文件要“短而可執(zhí)行”規(guī)則文件不是越長(zhǎng)越好。從實(shí)踐效果看如果超過(guò) 50 行且包含大量泛泛而談的句子Agent 的執(zhí)行效果會(huì)明顯下降。更好的做法是規(guī)則文件保持精簡(jiǎn)只寫“必須做”和“不能做”用結(jié)構(gòu)化數(shù)據(jù)文件承載完整策略把“為什么這么規(guī)定”寫在給人類看的文檔里而不是塞進(jìn) AGENTS.md每季度根據(jù) Agent 的實(shí)際違規(guī)案例修訂一次規(guī)則。另外規(guī)則文件的命名盡量要兼容主流工具。Cursor 和 Copilot 支持AGENTS.mdClaude Code 支持CLAUDE.md。如果你同時(shí)使用多款工具可以保持同一份內(nèi)容復(fù)制到多個(gè)文件名盡量讓維護(hù)源只有一個(gè)。8.2 Agent 側(cè)升級(jí)依賴要遵循最小變更原則對(duì) AI coding agents 最該強(qiáng)調(diào)的一條鐵律是不要為了修復(fù)一個(gè)非阻斷問(wèn)題而升級(jí)整個(gè)依賴樹(shù)。最小變更原則在人工開(kāi)發(fā)里是常識(shí)在 Agent 場(chǎng)景里很容易被打破。所以規(guī)則文件里建議明確每次依賴變更只修改與任務(wù)直接相關(guān)的包升級(jí)前先說(shuō)明版本變化帶來(lái)的影響升級(jí)后跑測(cè)試和安全掃描確保無(wú)回歸如果測(cè)試失敗禁止通過(guò)“降級(jí)其他依賴”的方式繞過(guò)。8.3 CI / 平臺(tái)側(cè)安全掃描必須和 Agent 的執(zhí)行權(quán)限解耦這只是整條鏈路里的一個(gè)提醒即便團(tuán)隊(duì)里已經(jīng)有很成熟的 CI 安全卡點(diǎn)也不要給 Agent 開(kāi)放過(guò)高的本地執(zhí)行權(quán)限。Agent 在開(kāi)發(fā)者本機(jī)跑安裝命令時(shí)它不應(yīng)有向生產(chǎn)環(huán)境發(fā)布包的權(quán)限。安全邊界是分層的本機(jī)規(guī)則文件 封裝腳本倉(cāng)庫(kù)分支保護(hù) MR 審查CI依賴掃描 許可證檢查 SBOM 歸檔生產(chǎn)環(huán)境鏡像或制品發(fā)布前再做一次不可變審計(jì)。每一層的目標(biāo)都不是“讓 Agent 變乖”而是“即使 Agent 偶爾出錯(cuò)也有下一層兜底”。9. 總結(jié)與后續(xù)學(xué)習(xí)方向回到開(kāi)頭那個(gè)判斷AI coding agents 真正需要的不只是“更聰明的代碼生成”而是“更明確的工程約束”。庫(kù)安全這件事正好是檢驗(yàn)約束力的一塊試金石。規(guī)則文件、封裝腳本、CI 掃描三層配合就能讓 Agent 在快速產(chǎn)出的同時(shí)不把供應(yīng)鏈安全搞崩。如果你接下來(lái)想繼續(xù)深入這幾個(gè)方向值得關(guān)注嘗試用osv-scanner掃描現(xiàn)有項(xiàng)目的 lockfile看看歷史依賴?yán)锸欠翊嬖谝阎┒磳W(xué)習(xí) SPDX 和 CycloneDX 兩種 SBOM 格式了解依賴可審計(jì)性的具體標(biāo)準(zhǔn)如果你的 Agent 工具支持自定義工具調(diào)用可以考慮把“依賴掃描”作為 Agent 必須調(diào)用的一次工具關(guān)注 AI Agent 領(lǐng)域關(guān)于“可信執(zhí)行邊界”的討論這類框架會(huì)越來(lái)越成熟。希望這篇內(nèi)容能幫你少踩幾個(gè)依賴安全的坑。建議收藏備用下次給項(xiàng)目接入 AI 編程助手時(shí)直接把規(guī)則文件改一改就能用。