本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

安全性原則

受支援的版本

只有最新的次要版本線會收到安全性修補。在針對較舊版本線回報弱點之前，請先升級到目前的次要版本。

回報弱點

我們認真看待安全性。若你發現弱點，請負責任地回報：

1. 私下聯絡：使用 AutomatosX 聯絡管道 要求機密的安全性回報路線。不要在公開社群訊息中包含漏洞利用細節或憑證。
2. Discord：在我們的 Discord 回報：https://discord.gg/gf9UyPxaN2

我們會在 6 個工作天內確認你的回報，並讓你知道修正進度。

**注意：**我們不接受 AI 產生的安全性報告。提交這類報告會導致被禁止參與專案。請確保報告包含具體的重現步驟，並展示真實影響。

威脅模型

概觀

ax-code 是在你的電腦上本機執行的 AI 程式開發助手。它提供 agent 系統，可使用包括 shell 執行、檔案操作與網頁存取在內的強力工具。

執行環境隔離的預設是 full-access（沙盒關閉），檔案系統寫入與網路存取不受限。這是給受信任本機專案的方便態勢，不是安全邊界。在把 AX Code 用於不受信任的儲存庫或無人值守工作負載之前，請選擇 workspace-write 或 read-only。

執行隔離沙盒

ax-code 內建執行隔離沙盒，限制 AI agent 可以存取的範圍。有三種模式：

關鍵性質：

• 預設行為 — AX Code 以 full-access 啟動，除非 --sandbox、AX_CODE_ISOLATION_MODE 或設定指定不同模式
• 建議的受限模式 — 對不受信任或團隊儲存庫使用 workspace-write；它把寫入限制在工作區，並預設停用網路
• 工具層強制執行 — 所有變更工具（bash、edit、write、apply_patch）與網路工具（webfetch、websearch、codesearch）都會在執行前檢查隔離原則
• 受保護路徑 — .git 與 .ax-code 目錄一律受寫入保護，即使在工作區寫入模式也是如此
• 升級提示 — 在受限模式中，隔離違規會顯示核准對話框，而不是安靜失敗；使用者可以允許被阻擋的操作一次，而不更改設定
• CLI 控制 — --sandbox read-only、--sandbox workspace-write、--sandbox full-access
• 環境變數 — AX_CODE_ISOLATION_MODE

隔離後端

{
  "isolation": {
    "mode": "workspace-write",
    "network": false,
    "backend": "auto"
  }
}

或設定 AX_CODE_ISOLATION_BACKEND=os|auto|app。

bash 的作業系統隔離會拒絕工作區根目錄以外的寫入，並在 network: false 時拒絕網路。應用程式層檢查仍然始終執行。在沒有 Seatbelt／bubblewrap 的平台上，請使用 backend: "app" 或容器／虛擬機器。

伺服器安全性

• 預設只限 localhost — 伺服器繫結到 127.0.0.1，無法從網路存取
• 網路存取需要密碼 — 繫結到 0.0.0.0 或任何非 localhost 位址時，必須設定 AX_CODE_SERVER_PASSWORD；沒有它伺服器會拒絕啟動
• 強制基本驗證 — 設定 AX_CODE_SERVER_PASSWORD 時，所有 API 端點都需要 HTTP Basic Auth
• CORS 可設定 — 可透過 --cors 指定額外允許的來源

憑證儲存

供應商 API 金鑰在靜態時以 AES-256-GCM 加密，使用 PBKDF2 金鑰衍生，並存在本機 AX Code 資料目錄（~/.local/share/ax-code/），檔案權限僅限使用者（0600）。

加密金鑰衍生自本機機器屬性（主機名稱、平台、架構）。這可防止隨意的離線揭露（例如意外分享檔案），但不能防止能存取主機的堅決攻擊者。它不等於作業系統鑰匙圈或硬體支援的祕密儲存。

MCP OAuth 權杖、用戶端祕密，以及帳號存取／重新整理權杖也以相同機制在靜態時加密。非敏感中繼資料（伺服器 URL、到期時間戳、電子郵件、帳號 ID）仍為明文。

發行成品驗證

Bash 安裝程式（install）與 Windows PowerShell 安裝程式（install.ps1）都會在解壓縮前用 minisign 驗證下載的 GitHub 發行封存。發行封存與 PowerShell 安裝程式指令稿本身都帶有分離簽章。釘選的 AX Code 發行公開金鑰是：

RWSlDu++afxCz01OqhYWhfo8+L8pVbSYXJBEb2zoWBuK0WACIzbGVZRO

每個安裝程式都會為所選封存下載相符的 .minisig 資產，並在驗證失敗時失敗即關閉。若 minisign 尚未在 PATH 上，安裝程式會從 https://download.ax-code.com/vendor/minisign/0.12/ 下載釘選的官方 minisign 0.12 封存，檢查封存 SHA-256，並在快取前再次檢查解出的可執行檔。PATH 上已有的 minisign 二進位檔是操作者的工具，不會重新計算雜湊。只有在你刻意接受無法驗證的發行下載時，才設定 AX_CODE_SKIP_MINISIGN_VERIFY=1。

方便的一行指令 irm …/install.ps1 | iex 不會在執行前驗證安裝程式指令稿。對於安全敏感的安裝，請下載 install.ps1 與 install.ps1.minisig，用 minisign 驗證指令稿，然後在本機執行（見安裝與執行環境通道）。

維護者應保持 minisign 祕密金鑰加密。在 macOS 上進行本機發行簽署時，請把通行片語存在 Keychain，而不是明文檔：

security add-generic-password -U -a ax-release -s ax-minisign -w

當未設定 AX_CODE_MINISIGN_PASSWORD 時，發行工具會自動讀取該 Keychain 項目。

由標籤驅動的 GitHub 發行工作流程會在上傳前簽署封存。它需要 這些儲存庫祕密：

AX_CODE_MINISIGN_SECRET_KEY_B64
AX_CODE_MINISIGN_PASSWORD

AX_CODE_MINISIGN_SECRET_KEY_B64 必須是已加密的 ax.minisign.key minisign 祕密金鑰內容的 base64 編碼（本機路徑可以是指向 ax.sec 的符號連結）。工作流程會把它寫到 暫存的 0600 金鑰檔，驗證釘選的公開金鑰，簽署每個發行 封存，並把相符的 .minisig 資產與封存一起上傳。

對於 macOS CLI 封存，工作流程需要並匯入 Apple Developer ID 憑證，使用這些儲存庫祕密：

APPLE_CERTIFICATE
APPLE_CERTIFICATE_PASSWORD
APPLE_TEAM_ID
APPLE_API_KEY_B64
APPLE_API_KEY_ID
APPLE_API_ISSUER

在該路徑中，隨附的原生程式庫會以匯入的 Developer ID Application 身分簽署，macOS ZIP 會提交到 Apple 的公證服務， 然後未變更的 ZIP 再由分離的 minisign 簽章保護。ZIP 封存無法裝訂公證票，因此公證必須發生在成品上傳之前， 也必須在產生 .minisig 之前。任何 Apple 簽署或公證憑證缺少時，發行建置會失敗即關閉。

發行簽署金鑰歷史

發行簽署金鑰最近一次輪替是 2026-07-19。安裝程式 與發行工作流程只釘選目前金鑰，因此用已退役 金鑰簽署的封存會無法通過簽章驗證。輪替之後，維護者必須用 script/resign-release-assets.ts 重新簽署 歷史發行封存，使每個 已發布的發行都能對釘選金鑰驗證，而不信任已退役的金鑰。

若要以目前金鑰重新簽署並重新上傳既有發行的 .minisig 資產：

tsx script/resign-release-assets.ts --tag v5.5.0 --key-dir ~/signkey

範圍

範圍內

範圍外

企業安全性能力

AX Code 為企業使用而設計，具有下列強化功能：

• 細緻權限：依 agent 與模式的規則集（allow／deny／ask）。安全性 agent 預設唯讀。規則會跨專案、agent 與已核准清單評估。
• 工作階段稽核軌跡：每次工具呼叫、權限決定與檔案變更都記錄在 SQLite 中並附快照。支援重放、分叉與匯出，供合規檢閱。
• 確定性重構（DRE）：impact_analyze、refactor_plan 與 refactor_apply（影子 worktree 加上 lint／型別檢查／測試）提供可稽核、可還原的變更。
• 憑證管理：所有金鑰／權杖都使用 AES-256-GCM 加密。透過 InstanceState 做依目錄隔離。
• 選擇加入的沙盒強制執行：應用程式層隔離，並解析 bash 指令（tree-sitter）。選擇 workspace-write 或 read-only 以強制沙盒邊界；受保護路徑（.git、.ax-code）適用於沙盒模式。
• 伺服器強化：預設只限 localhost；遠端存取以密碼保護並使用 Basic Auth。
• 程式碼情報與掃描：內建祕密／硬編碼偵測，以及相依性影響分析。

CodeQL 輔助的程式開發回饋

儲存庫把 CodeQL 當作提取請求、推送到 dev、排程掃描與手動分派的背景安全性分析層來執行。CodeQL 不是 即時 LSP 或程式碼情報路徑的一部分；它是較慢、較深的證據 來源，適合在來源變更穩定之後處理資料流、汙點與安全性品質發現。

目前的工作流程分析：

• JavaScript 與 TypeScript 的執行環境、TUI、SDK、整合與指令稿程式碼。
• GitHub Actions 工作流程與本機複合動作。
• crates/ 下的 Rust crate，並以手動 Cargo 建置，使原生附加元件與 TUI 程式碼被一致地擷取。

預定的開發者體驗是：

1. 提取請求作者在 GitHub 程式碼掃描中收到 CodeQL 警示，與既有的 型別檢查、確定性測試、OSV 相依性掃描與儲存庫結構 防護並列。
2. 維護者在把 CodeQL 當成硬性合併 閘門之前，先分類最初結果，使新發現有用而不是吵雜。
3. 未來的 AX Code 檢閱／除錯流程可以把 CodeQL SARIF 或 GitHub 程式碼 掃描警示當作明確的安全性證據納入，並帶有來源欄位，例如 source: "codeql"、規則 id、嚴重性、檔案、行、資料流追蹤，以及 已分析的提交 SHA。
4. CodeQL 證據應顯示在本機 security_scan、 hardcode_scan、LSP 診斷與圖支援的影響分析旁邊，而不是 悄悄取代其中任何一項。

加入自訂 CodeQL 查詢時，偏好儲存庫專屬的安全 邊界，而不是廣泛的 lint 風格檢查。高價值目標包括沙盒 逃逸路徑、帶有未清理引數的指令執行、圍繞工作區侷限的路徑遍歷、 祕密／環境傳播到子行程， 以及缺少的伺服器路由驗證。

完整的企業治理（RBAC、原則即程式碼、SIEM 匯出、密碼學稽核）請與 AX Trust 整合（路線圖項目）。

隔離設定與執行環境行為見 沙盒指南。