Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

安装并配置 CLI

CodeMender 是一款自主 AI 代码安全智能体，可扫描、验证和修补代码库中的深层网络安全漏洞。在运行 CodeMender 之前，请下载 CLI 并初始化工作区选项。

架构和安全模型

CodeMender 采用本地优先执行模型：

托管式推理引擎：智能体推理、威胁建模和编排逻辑在 Gemini Enterprise Agent Platform 上安全运行。 Google Cloud
本地执行 CLI：源代码绝不会批量离开您的工作站或 CI/CD 容器。本地 cm CLI 工具可在本地沙盒中执行文件读取、本地 build 检查和概念验证 (PoC) 漏洞验证，并通过 Gemini Enterprise Agent Platform 上的 Interactions API 仅将精确的代码段和工具执行结果发送到云后端。

环境设置

如需开始使用 CodeMender，请设置 Google Cloud 项目、下载并安装 CLI、配置凭据，然后初始化工作区。

项目设置和 IAM 权限

在下载 CLI 并配置凭据之前，请确保目标 Google Cloud 项目已正确设置，并具有所需的 API 和权限。

必需的 API

确保您的项目已启用以下 Google Cloud API：

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 silicon

如需下载并安装适用于 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] 确认的情况下修改磁盘上的任何文件或执行 shell 命令。
- 为什么这是默认设置：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 在扫描工作区和分析代码时会完全跳过这些目录。
- 为何这是默认值：大型依赖项或 build 文件夹会触发巨大的延迟和令牌惩罚。默认情况下排除这些广告系列可确保高效果和快速响应时间。
project_paths: []
- 具体含义：CodeMender 在工具执行期间可以访问（读取/写入）的目录路径列表。
- 为何这是默认值：默认情况下，此值为空，这会将代理限制为扫描目标目录、.codemender 工作区目录和 /tmp。如果您的 build 或测试流程需要访问这些目录之外的文件，您必须在此处添加相应路径。
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 是默认设置，因为它是版本控制跟踪的业界标准，可确保无缝的 diff（差异比较）集成和回滚安全性。
build: { command: "make build && make test" }
- 含义：定义 CodeMender 为编译和构建项目以及运行单元测试和回归测试而执行的确切 shell 命令。
- 为什么这是默认设置：设置构建和测试命令对于验证工作流至关重要。这样一来，CodeMender 就可以在隔离的沙盒环境中编译您的项目并运行现有的测试套件，以证明生成的安全补丁成功缓解了漏洞，而不会破坏现有的应用逻辑。

执行沙盒

为了保护工作站免遭意外的文件修改或意外的工具副作用影响，CodeMender CLI 默认在操作系统级沙盒中运行。您可以在配置中永久停用沙盒，也可以使用 CLI 标志按命令绕过沙盒。

虽然这种沙盒机制可在工作站上提供初始防御层，但与在完全隔离的虚拟机 (VM) 中运行代理相比，其安全性较弱：

Linux：使用内核命名空间（CLONE_NEWNS、CLONE_NEWUSER 等）和 seccomp 过滤器来隔离装载点并限制系统调用。
macOS：使用内置的 sandbox-exec（安全带）机制。
Windows（实验性）：使用 AppContainer 隔离和访问控制列表 (ACL)。Windows 沙盒功能尚处于实验阶段，可能需要管理员权限，或者与某些系统配置不兼容。

沙盒行为

当沙盒处于有效状态时：

文件系统隔离：代理只能读取和写入允许目录中的文件。沙盒会将这些目录之外的任何写入操作重定向到临时内存文件系统 (tmpfs)，而不会影响您的主机系统。
网络隔离：沙盒默认会阻止出站网络访问。这样可以防止代理（或其调用的构建工具）建立意外的外部连接或将数据传输到工作区外部。

构建和验证期间的网络访问

由于沙盒默认启用网络隔离（sandbox.network.profile 默认为 permissive-closed），因此代理在工具执行期间无法访问互联网。

这会给在构建或验证步骤中需要提取外部依赖项的项目（例如，在 build.command 中运行 npm install、pip install 或 go get）带来限制。如果您的构建流程尝试访问外部 Web 服务，将会失败。

处理网络依赖项

如果您的项目需要网络访问权限才能进行 build 或测试，您可以选择以下选项：

预取依赖项：在运行 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 标志绕过它。使用内置的操作系统功能（命名空间/seccomp、`sandbox-exec`、`AppContainer` [实验性]）来隔离执行。	轻量级；启动开销为零；可直接访问本地工作区工具，并进行精细控制。建议用于日常本地开发。	安全性依赖于操作系统内核功能；隔离程度不如完整虚拟机；Windows 支持处于实验阶段，可能需要管理员权限，或者与某些配置不兼容。
容器	在容器（例如 Docker）中运行代理。	隔离效果好；环境标准化。	需要容器运行时；可能占用大量资源；不允许直接与本地机器上的工具互动。
完整虚拟机	在专用虚拟机中运行代理。	最高安全性；完全隔离。	资源开销高；启动缓慢；不允许直接与本地机器上的工具互动。

Telemetry

为了帮助我们监控和改进产品健康状况，我们会通过 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 silicon

Windows x86_64

Windows ARM64

配置 Google Cloud 凭据

初始化工作区

配置参数 (config.yaml)

用法

核心默认设置

执行沙盒

沙盒行为

构建和验证期间的网络访问

处理网络依赖项

沙盒配置

选择隔离级别

Telemetry

更新 CLI

自动更新检查

手动更新 (cm update)

安装并配置 CLI

配置参数 (`config.yaml`)

手动更新 (`cm update`)