Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

安裝及設定 CLI

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

架構和安全模型

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

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

環境設定

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

專案設定和 IAM 權限

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

必要 API

確認專案已啟用下列 API： Google Cloud

Vertex AI API (aiplatform.googleapis.com) - 支援串流及管理現有工作階段。
Cloud Resource Manager API (cloudresourcemanager.googleapis.com)：驗證使用者驗證狀態和專案中繼資料。

建議的預先定義 IAM 角色

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

Vertex AI User (roles/aiplatform.user)：允許使用者建立、串流及管理有效工作階段。

下載並安裝 CodeMender CLI

CodeMender CLI 二進位檔會託管在 Artifact Registry 中。選擇作業系統的分頁，下載並安裝 CLI。

Linux x86_64

如要下載並安裝 Linux (x86_64) 版 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-amd64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"

安裝 CLI：

unzip cm-linux-amd64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

Linux ARM64

如要下載並安裝適用於 Linux (ARM64) 的 CodeMender CLI，請按照下列指示操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-linux-arm64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"

安裝 CLI：

unzip cm-linux-arm64.zip
chmod +x cm
sudo mv cm /usr/local/bin/cm

macOS Intel

如要下載並安裝 macOS (Intel) 適用的 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-amd64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"

安裝 CLI：

unzip cm-darwin-amd64.zip
chmod +x cm
mv cm /usr/local/bin/cm

macOS Apple 晶片

如要下載及安裝 macOS (Apple 晶片) 專用的 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：執行下列指令：

gcloud artifacts generic download \
  --project=cmoc-prod \
  --location=us \
  --repository=codemender-cli-production \
  --package=cm \
  --version=stable \
  --name=cm-darwin-arm64.zip \
  --destination=./

curl：執行下列指令：

curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"

安裝 CLI：

unzip cm-darwin-arm64.zip
chmod +x cm
mv cm /usr/local/bin/cm

Windows x86_64

如要下載並安裝 Windows 版 (x86_64) CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：在 PowerShell 中執行下列指令：

gcloud artifacts generic download `
  --project=cmoc-prod `
  --location=us `
  --repository=codemender-cli-production `
  --package=cm `
  --version=stable `
  --name=cm-windows-amd64.zip `
  --destination=./

PowerShell：執行下列指令：

Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip

安裝 CLI：

Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
# Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

如要下載並安裝 Windows (ARM64) 適用的 CodeMender CLI，請按照下列步驟操作：

使用下列任一方法下載套件：

gcloud CLI：在 PowerShell 中執行下列指令：

gcloud artifacts generic download `
  --project=cmoc-prod `
  --location=us `
  --repository=codemender-cli-production `
  --package=cm `
  --version=stable `
  --name=cm-windows-arm64.zip `
  --destination=./

PowerShell：執行下列指令：

Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip

安裝 CLI：

Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
# Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

設定 Google Cloud 憑證

由於 CodeMender CLI 會透過 Interactions API 與雲端代管的推論引擎互動，因此您必須在環境中設定 Google Cloud 應用程式預設憑證 (ADC)。

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

gcloud auth application-default login

初始化工作區

完成驗證後，下一步是在本機環境中初始化 CodeMender。初始化 CodeMender 會建立狀態追蹤檔案，並建立與雲端代管推論引擎的連線設定，藉此準備本機工作區。

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

cm init

使用 --verify 旗標測試與雲端代管推論引擎的連線能力，並驗證工作區設定：

cm init --verify

設定參數 (`config.yaml`)

config.yaml 的主要目標是根據本機系統的安全性、環境限制和效能需求，調整 CodeMender 代理的行為。

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

用量

位置：根據預設，CLI 會在初始化的工作區 (通常是 .codemender/config.yaml 或 ~/.config/codemender/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", ".ts", ".c", ".cc", ".cpp", ".h", ".rb", ".php"]
- 意義：定義明確的檔案副檔名清單，授權 CodeMender 在掃描工作區時擷取及分析這些檔案。如果存放區中的檔案副檔名不在這個清單中，CodeMender 會自動略過。
- 為什麼這是預設設定：這份清單預設為主要程式設計語言，可盡量提高掃描效率，並避免代理程式將時間和權杖浪費在不相關的文字檔、建構構件或二進位檔。不過，由於現代應用程式通常會在部署設定或自動化工具中嵌入安全漏洞，因此強烈建議您手動擴充這個預設清單，納入設定檔、指令碼格式和 IaC 檔案 (例如 Shell 指令碼、XML、YAML、屬性和 JSON 檔案)，避免 CodeMender 默默忽略這些檔案。
exclude_paths: ["node_modules", "vendor", "dist", "bin"]
- 影響：CodeMender 在掃描工作區和分析程式碼時，會完全略過這些目錄。
- 為什麼這是預設值：大型依附元件或建構資料夾會觸發大量延遲和權杖懲罰。預設排除這些項目可確保高效能和快速回應時間。
project_paths: []
- 說明：CodeMender 在工具執行期間可存取 (讀取/寫入) 的目錄路徑清單。
- 為何這是預設值：根據預設，這個值為空白，這會將代理程式限制在掃描目標目錄、.codemender 工作區目錄和 /tmp 中。如果建構或測試程序需要存取這些目錄以外的檔案，您必須在此新增這些路徑。
sandbox：
- 意義：程序層級沙箱環境的設定區塊。
- 子參數：
  - enabled: true：(布林值) 啟用或停用沙箱。如果將這個選項設為 true (預設值)，代理程式會在本地沙箱中執行工具。如果設為 false，代理程式會在主機系統上直接執行工具，不會隔離。
  - mounts：(物件)
    - target_dir: "."：(字串) 要掛接為沙箱內有效工作區的目錄。CLI 會根據工作區根目錄解析相對路徑。
  - network：(物件)
    - profile: "permissive-closed"：(字串) 沙箱內的輸出網路存取設定檔。系統目前不支援針對特定網域或網址模式進行精細的允許清單設定。支援的設定檔：
      - permissive-closed (預設)：完全隔離網路，沙箱會封鎖所有輸出連線。
      - permissive-open：允許完整的外送網路存取權。
security：
- 意義：安全性政策的設定區塊。
- 子參數：
  - protected_files: []：(字串清單) 要在沙箱內唯讀掛接的主機系統檔案或目錄，可防止修改 (例如 ["~/.ssh/*"])。支援路徑擴展 (~) 和萬用字元 (*)。
model: "gemini-3.5-flash"
- 意義：為後端推理迴圈提供支援的預設智慧引擎。
- 為何這是預設模型： gemini-3.5-flash 在速度、成本和分析推理方面取得最佳平衡，可建議修補程式。(如有需要，使用者可以覆寫這項設定，gemini-3.1-pro進行更深入、更複雜的推論)。
vcs: { type: "git" }
- 意義：透過 vcs 鍵定義專案使用的版本管控系統類型。如果未設定此選項，工具會嘗試自動識別 Git 或 Mercurial 存放區。如果將 vcs 設為 none，CLI 會輸出警告，但會繼續執行，不會使用 VCS 功能。CodeMender 會根據這項設定管理推測性安全性修正、追蹤程式碼集修改內容，以及與本機存放區整合。
- 為何這是預設設定：CodeMender 支援 Git、Mercurial 或自訂 VCS 設定。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 沙箱目前處於實驗階段，可能需要管理員權限，或與某些系統設定不相容。

沙箱行為

沙箱啟用時：

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

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

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

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

處理網路依附元件

如果專案需要網路存取權才能建構或測試，請使用下列選項：

預先擷取依附元件：在主機系統上安裝所有必要依附元件，然後再執行 cm 指令，這樣建構指令就不需要網路存取權。
在沙箱中啟用網路存取權：變更 config.yaml 中的網路設定檔，允許對外連線：
```
sandbox:
  network:
    profile: "permissive-open"
```
注意：系統目前不支援特定網域或網址模式的精細許可清單 (例如只允許 npmjs.org)；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 標記，暫時略過單次執行的所有沙箱保護措施。這會停用檔案系統路徑界線 (允許代理程式存取主機上的任何路徑)，並完全停用作業系統層級的容器隔離 (包括網路隔離)。

選擇隔離等級

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

方法	說明	優點	缺點
內建沙箱 (作業系統層級)	這項功能預設為啟用，您可以在 `config.yaml` 檔案中停用，或使用 CLI 旗標略過。使用內建的 OS 功能 (命名空間/seccomp、`sandbox-exec`、`AppContainer` (實驗版)) 隔離執行作業。	輕量級：啟動零負擔；可直接存取本機工作區工具，並進行精細控制。建議用於日常本機開發作業。	安全性取決於 OS 核心功能；隔離程度不如完整 VM；Windows 支援功能處於實驗階段，可能需要管理員權限，或與某些設定不相容。
容器	在容器 (例如 Docker) 中執行代理程式。	隔離效果良好；標準化環境。	需要容器執行階段；可能很耗用資源；不允許直接與本機電腦上的工具互動。
完整 VM	在專用 VM 中執行代理程式。	最高安全性；完全隔離。	資源負荷高、啟動緩慢，且無法直接與本機上的工具互動。

遙測

為協助我們監控及改善產品健康狀態，我們會透過 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

安裝及設定 CLI 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

架構和安全模型

環境設定

專案設定和 IAM 權限

必要 API

建議的預先定義 IAM 角色

下載並安裝 CodeMender CLI

Linux x86_64

Linux ARM64

macOS Intel

macOS Apple 晶片

Windows x86_64

Windows ARM64

設定 Google Cloud 憑證

初始化工作區

設定參數 (config.yaml)

用量

核心預設設定

執行沙箱

沙箱行為

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

處理網路依附元件

沙箱設定

選擇隔離等級

遙測

更新 CLI

自動檢查更新

手動更新 (cm update)

安裝及設定 CLI

設定參數 (`config.yaml`)

手動更新 (`cm update`)