安裝及設定 CLI

CodeMender 是自主 AI 程式碼安全代理，可掃描、驗證及修補程式碼集中的深層網路安全漏洞。執行 CodeMender 前，請先下載 CLI 並初始化工作區選項。

架構和安全性模型

CodeMender 採用本機優先執行模式：

• 託管推論引擎：代理推論、威脅建模和自動調度邏輯會在 Gemini Enterprise Agent Platform 上安全執行。 Cloud de Confiance by S3NS
• 本機執行 CLI：原始碼絕不會大量離開工作站或 CI/CD 容器。本機 cm CLI 工具會在本機沙箱中執行檔案讀取、本機建構檢查和概念驗證 (PoC) 漏洞驗證，並透過 Gemini Enterprise Agent Platform 上的 Interactions API，僅將精確的程式碼片段和工具執行結果傳送至雲端後端。

環境設定

如要開始使用 CodeMender，請設定 Cloud de Confiance 專案、下載並安裝 CLI、設定憑證和目標專案，然後初始化工作區。

專案設定和 IAM 權限

下載 CLI 和設定憑證前，請確認目標 Cloud de Confiance 專案已正確設定必要的 API 和權限。

必要 API

確認專案已啟用下列 API： Cloud de Confiance by S3NS

1. Agent Platform API (aiplatform.googleapis.com)：用於串流及管理進行中的工作階段。
2. Cloud Resource Manager API (cloudresourcemanager.googleapis.com)：驗證使用者驗證狀態和專案中繼資料。

建議的預先定義 IAM 角色

如要執行 CLI 指令，使用者必須具備下列 IAM 角色：

• Agent Platform 使用者 (roles/aiplatform.user)：可建立、串流及管理有效工作階段。

下載並安裝 CodeMender CLI

CodeMender CLI 二進位檔託管於 Artifact Registry。選擇作業系統對應的分頁標籤，下載並安裝 CLI。

設定 Cloud de Confiance 憑證和專案

由於 CodeMender CLI 會透過 Interactions API 與雲端主控的推論引擎互動，您必須設定 Cloud de Confiance by S3NS 應用程式預設憑證 (ADC)，並在環境中指定目標專案。

1. 如要進行驗證，請執行下列指令，然後按照登入提示操作：

   gcloud auth application-default login
   

2. 將 GOOGLE_CLOUD_PROJECT 環境變數設為 Cloud de Confiance 專案 ID：

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   或者，您也可以設定有效的 gcloud CLI 專案：

   gcloud config set project PROJECT_ID
   

   將 PROJECT_ID 替換為 Cloud de Confiance 專案 ID。

初始化工作區

設定憑證和目標專案後，下一步是在本機環境中初始化 CodeMender。初始化 CodeMender 會建立狀態追蹤檔案，並建立與雲端主控推論引擎的連線設定，藉此準備本機工作區。

從程式碼集的根目錄執行 cm init，建立本機狀態追蹤檔案，並建立基準設定：

cm init

使用 --verify 旗標測試與雲端主控推理引擎的連線，並驗證工作區設定：

cm init --verify

設定參數 (config.yaml)

config.yaml 的主要目標是確保 CodeMender 代理的行為符合本機系統的安全性、環境限制和效能需求。

由於代管式 AI 代理會使用本機精靈用戶端執行本機指令 (例如建構程式碼、執行測試或編輯檔案)，因此這個設定檔會做為界線，定義代理可執行的動作。

用量

• 位置：根據預設，CLI 會從 ~/.codemender/config.yaml 讀取這個檔案。您可以設定 CM_HOME 環境變數 (例如 CM_HOME=/path/to/custom/dir，讀取 /path/to/custom/dir/config.yaml)，覆寫工作區和設定目錄。
• 執行：執行 cm find、cm verify 或 cm fix 等指令時，本機用戶端會讀取這個檔案，設定安全參數、套用系統略過機制，以及指定要忽略的檔案或目錄。

核心預設設定

以下是核心預設參數的意義：

• human_confirmation: true (或 require_confirmation: true)

  • 說明：根據預設，CodeMender 無法修改磁碟上的任何檔案，也無法執行殼層指令，除非在終端機中明確提示您確認 [Y/n]。
  • 預設為關閉的原因：CodeMender 可能會生成推測性修補程式，或嘗試執行漏洞利用指令碼來驗證安全漏洞。強制要求人工確認，有助於防止系統發生意外變更，或在本機環境中執行未經授權的程式碼。
  • 略過：如果是互動式 CI/CD 管道，可以設為 false。

• confirm_writes: false

  • 意義：停用檔案修改的互動式提示，讓 CodeMender 代理程式直接將安全性修補程式寫入本機磁碟，並修改來源檔案，不必等待人工核准。
  • 為什麼這是預設值：根據預設，CodeMender 會將這項安全防護機制設為 true，強制執行「人工介入迴路」工作流程。由於 CodeMender 會對本機程式碼集採取行動，因此需要手動確認 (例如 Write? [Y/n])，可避免代理程式對來源檔案進行推測性、不正確或破壞性修改。只有在獨立、可拋棄式沙箱或自動化無頭 CI/CD 管道中執行時，才應將此項切換為 false。

• include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php"]

  • 說明：明確定義 CodeMender 在掃描工作區時，可擷取及分析的副檔名清單。CodeMender 會自動略過存放區中副檔名未列於此清單的檔案。
  • 預設原因：這份清單預設為主要程式設計語言，可盡量提高掃描效率，並防止代理浪費時間和權杖，處理不相關的文字檔案、建構構件或二進位檔案。不過，由於現代應用程式通常會在部署設定或自動化工具中嵌入安全漏洞，因此您可以在 config.yaml 中手動擴充這個預設清單，納入設定檔、指令碼格式和 IaC 檔案 (例如殼層指令碼、XML、YAML、屬性和 JSON 檔案)，避免 CodeMender 默默忽略這些檔案。

• exclude_dirs: ["node_modules", "vendor", "dist", "bin", "target", "obj", "build", ".gradle"]

  • 說明：CodeMender 掃描工作區及分析程式碼時，會完全略過這些目錄。
  • 預設原因：大型依附元件或建構資料夾會導致延遲時間大幅增加，並耗用大量權杖。根據預設，系統會排除這些項目，確保高效能和快速回應。您可以在 config.yaml 中自訂這份清單，根據專案結構納入或排除特定目錄。

• project_paths: []

  • 說明：CodeMender 在執行工具時可存取 (讀取/寫入) 的目錄路徑清單。
  • 預設原因：預設為空白，因此代理程式只能掃描目標目錄。如果建構或測試程序需要存取掃描目標目錄以外的檔案，請在這裡新增這些路徑。
  • 構件目錄：代理也可以寫入每個工作階段的構件目錄 (~/.codemender/artifacts/<session_id>/ 或 $CM_HOME 下的對等項目)。
  • 暫時檔案：啟用沙箱後，即使將 /tmp 新增至 project_paths，主機 /tmp 目錄一律會遭到封鎖。遵循 TMPDIR 的工具會改用構件目錄中的暫存目錄。

• sandbox：

  • 意義：程序層級沙箱環境的設定區塊。
  • 子參數：
    • enabled: true：(布林值) 啟用或停用沙箱。如果設為 true (預設)，代理會在本地沙箱執行工具。如果設為 false，代理會直接在主機系統上執行工具，不會隔離。
    • mounts：(物件)
      • target_dir: "."：(字串) 要在沙箱中掛接為有效工作區的目錄。CLI 會根據工作區根目錄解析相對路徑。
    • network：(物件)
      • profile: "permissive-closed"：(字串) 沙箱內的外送網路存取設定檔。目前不支援精細地將特定網域或網址模式加入許可清單。支援的設定檔：
        • permissive-closed (預設)：完全隔離網路，沙箱會封鎖所有輸出連線。
        • permissive-open：允許完整的傳出網路存取權。

• security：

  • 意義：安全性政策的設定區塊。
  • 子參數：
    • protected_files: []：(字串清單) 主機系統上的檔案或目錄，您希望在沙箱中以唯讀方式掛接，以防止修改 (例如 ["~/.ssh/*"])。支援路徑展開 (~) 和萬用字元 (*)。

• model: "gemini-3.8-flash"

  • 說明：預設的智慧引擎，負責驅動後端推論迴圈。
  • 為何這是預設模型： gemini-3.8-flash 在速度、成本和分析推理方面取得最佳平衡，可建議修補程式。(使用者可視需要覆寫這項設定，改用 gemini-4-argon (Gemini 4 Argon) 進行更深入、更複雜的推論)。

• vcs: { type: "git" }

  • 意義：透過 vcs 鍵定義專案使用的版本管控系統類型。如果未設定，工具會嘗試自動識別 Git 或 Mercurial 存放區。如果將 vcs 設為 none，CLI 會輸出警告，但會繼續執行，不使用 VCS 功能。CodeMender 會根據這項設定管理推測性安全修正、追蹤程式碼庫修改內容，以及與本機存放區整合。
  • 為何這是預設設定：CodeMender 支援 Git、Mercurial 或自訂 VCS 設定。Git 是版本管控追蹤的業界標準，因此預設為 Git，可確保無縫整合差異，並安全復原。

• build: { command: "make build && make test" }

  • 意義：定義 CodeMender 執行的確切殼層指令，用於編譯及建構專案，以及執行單元和迴歸測試。
  • 預設原因：設定建構和測試指令對驗證工作流程至關重要。CodeMender 可以在隔離的沙箱環境中編譯專案，並執行現有的測試套件，證明生成的安全性修補程式能成功緩解安全漏洞，且不會破壞現有的應用程式邏輯。

執行沙箱

根據預設，CodeMender CLI 會在 OS 層級沙箱中執行，保護工作站免受意外檔案修改或工具副作用影響。您可以在設定中永久停用沙箱，也可以使用 CLI 標記，針對每個指令略過沙箱。

雖然這個沙箱機制可在工作站上提供初步防禦，但安全防護力不如在完全隔離的虛擬機器 (VM) 中執行代理程式：

• Linux：使用核心命名空間 (CLONE_NEWNS、CLONE_NEWUSER 等) 和 seccomp 篩選器，隔離掛接點並限制系統呼叫。
• macOS：使用內建的 sandbox-exec (Seatbelt) 機制。
• Windows (實驗功能)：使用 AppContainer 隔離和存取控制清單 (ACL)。Windows 上的沙箱功能目前處於實驗階段，可能需要管理員權限，或與某些系統設定不相容。

沙箱行為

沙箱啟用後：

1. 檔案系統隔離：代理只能在允許的目錄中讀取及寫入檔案。沙箱會將這些目錄以外的任何寫入作業重新導向至暫時的記憶體內檔案系統 (tmpfs)，不會影響主機系統。
2. 網路隔離：沙箱預設會封鎖傳出網路存取。這樣一來，代理程式 (或其叫用的建構工具) 就不會建立非預期的外部連線，或將資料傳輸到工作區外部。

建構和驗證期間的網路存取權

由於沙箱預設會啟用網路隔離功能 (sandbox.network.profile 預設為 permissive-closed)，因此代理在執行工具時無法存取網際網路。

如果專案需要在建構或驗證步驟中擷取外部依附元件 (例如在 build.command 期間執行 npm install、pip install 或 go get)，就會受到限制。如果建構程序嘗試存取外部 Web 服務，就會失敗。

處理網路依附元件

如果專案需要網路存取權才能建構或測試，可以採取下列做法：

• 預先擷取依附元件：執行 cm 指令前，請先在主機系統上安裝所有必要依附元件，這樣建構指令就不需要網路存取權。

• 在沙箱中啟用網路存取權：變更 config.yaml 中的網路設定檔，允許對外連線：

  sandbox:
    network:
      profile: "permissive-open"
  

• 略過沙箱：使用 --unrestricted 旗標執行指令，在該次執行中完全停用沙箱和檔案系統邊界。

沙箱設定

您可以使用下列選項設定及控管沙箱：

• 持續性設定 (config.yaml)：您可以在 config.yaml 檔案中新增 sandbox、execution 和 security 區塊，自訂沙箱行為、檔案系統掛接、網路存取權和安全性政策。詳情請參閱「設定參數」。
• 使用 CLI (--sandbox) 控制沙箱：您可以將 --sandbox=true 或 --sandbox=false 傳遞至 cm find、cm verify 或 cm fix，明確啟用或停用單次執行的沙箱。
• 使用 CLI (--unrestricted) 略過隔離程序：您可以傳遞 --unrestricted 旗標，暫時略過單次執行的所有沙箱保護措施。這會停用檔案系統路徑界線 (允許代理程式存取主機上的任何路徑)，並完全停用 OS 層級的容器隔離 (包括網路隔離)。

選擇隔離等級

您可以根據安全性需求和開發環境，選擇適當的隔離層級來執行 CodeMender CLI。

遙測

為監控及提升產品健康狀態，我們會透過 CLI 收集匿名遙測資料。我們會將所有蒐集的資料完全去識別化，包括基本使用情況指標和效能診斷。遙測功能絕不會收集或傳輸原始碼、檔案內容、發現項目、修補程式或使用者身分。

遙測功能預設為啟用。如要停用遙測功能，請將 CM_TELEMETRY_OPT_OUT 環境變數設為 1 或 true。

更新 CLI

CodeMender 內建更新機制，可確保您執行的是最新版本的 CLI。

自動更新檢查

根據預設，CodeMender CLI 會在您執行指令時，自動在背景檢查更新：

• 節流：為盡可能減少負擔，自動檢查每 24 小時最多執行一次。
• 需要互動式終端機 (TTY)：CLI 只會在互動式終端機中執行時檢查更新，並提示您。在非互動式環境 (例如 CI/CD 管道或指令碼) 中，系統會略過檢查，並每天最多記錄一次警告至 stderr。
• 提示：如果有新版本，系統會在 stderr 提示您： none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): 如果選擇「是」(y 或 yes)，CodeMender 會下載更新、取代二進位檔，然後結束。您必須再次執行指令，才能使用新版本。如果選擇「否」，系統會略過更新，並執行原始指令。
• 離線容錯：如果您處於離線狀態或無法連線至發布存放區，系統會自動略過檢查，CodeMender 則會繼續執行指令。
• 略過：您可以將 --yes 或 -y 旗標傳遞至任何指令，略過自動更新檢查。

手動更新 (cm update)

您可以執行 update 指令，強制 CodeMender 立即檢查及套用更新：

cm update

cm update 指令：

• 忽略 24 小時調節。
• 立即下載並套用更新，不顯示提示 (非互動式)。
• 不需要互動式終端機 (適用於指令碼和設定管理)。

如果 CLI 安裝在需要提高權限的系統目錄中，請使用 sudo 執行更新：

sudo cm update