安装并配置 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 和配置凭据之前，请确保已使用所需的 API 和权限正确设置目标 Google Cloud 项目。

必需的 API

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

1. Agent Platform API (aiplatform.googleapis.com) - 支持活跃会话的流式传输和管理。
2. Cloud Resource Manager API (cloudresourcemanager.googleapis.com) - 验证用户身份验证状态和项目元数据。

建议的预定义 IAM 角色

如需运行 CLI 命令，用户应被分配以下 IAM 角色：

• Agent Platform User (roles/aiplatform.user) - 允许用户创建、流式传输和管理活跃会话。

下载并安装 CodeMender CLI

CodeMender CLI 二进制文件托管在 Artifact Registry 中。选择与您的操作系统对应的标签页，下载并安装 CLI。

配置 Google Cloud 凭证和项目

由于 CodeMender CLI 通过 Interactions API 与云托管的推理引擎进行交互，因此您必须配置 Google Cloud 应用默认凭证 (ADC)，并在环境中指定目标项目。

1. 如需进行身份验证，请运行以下命令并按照登录提示操作：

   gcloud auth application-default login
   

2. 将 GOOGLE_CLOUD_PROJECT 环境变量设置为您的 Google Cloud 项目 ID：

   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   

   或者，配置活跃的 gcloud CLI 项目：

   gcloud config set project PROJECT_ID
   

   请将 PROJECT_ID 替换为您的 Google Cloud 项目 ID。

初始化工作区

配置凭证和目标项目后，下一步是在本地环境中初始化 CodeMender。初始化 CodeMender 会创建状态跟踪文件并建立与云托管推理引擎的连接设置，从而准备好本地工作区。

从代码库的根目录运行 cm init，以创建本地状态跟踪文件并建立基准配置：

cm init

使用 --verify 标志测试与云托管推理引擎的连接性，并验证工作区设置：

cm init --verify

检查服务连接性和权限

如需在不启动扫描或修改工作区的情况下验证凭据、配置、网络可达性和 IAM 权限，请运行 cm health：

cm health

cm health 命令会运行四项依序检查，并在遇到第一个失败层时停止。您可以在任何目录中运行 cm health，甚至可以在运行 cm init 之前运行。它不会写入磁盘，也不会消耗模型配额。

对于自动化 CI/CD 预检检查或预定的合成监控，请使用 --strict 在跳过项目级 IAM 检查时失败，并使用 --json 输出机器可读的 JSON 报告：

cm health --strict --json

下表介绍了 cm health 退出代码：

cm health 支持以下标志：

配置参数 (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 等命令时，本地客户端会读取此文件，以设置安全参数、应用系统绕过，并指定要忽略的文件或目录。

核心默认设置

以下是核心默认参数的含义：

• tools.confirm_commands: true

  • 含义：默认情况下，CodeMender 会在终端中提示您输入 [Y/n] 进行确认，然后再执行 shell 命令 (run_command)。当 cm find 在启用操作系统级沙盒 (sandbox.enabled: true) 和默认网络隔离 (permissive-closed) 的情况下运行时，工作区会以只读方式装载，并且系统会自动跳过命令确认提示。
  • 为什么这是默认设置：CodeMender 可能会在验证和修补过程中运行构建命令、测试套件或漏洞利用脚本。在工作区可写或未沙盒化时要求确认，有助于防止在本地环境中意外执行命令。
  • 绕过：为单次运行传递 -y（或 --yes），或在 config.yaml 中为非交互式 CI/CD 流水线设置 tools.confirm_commands: false。

• tools.confirm_writes: true

  • 含义：在 CodeMender 智能体向磁盘写入或修改文件（write_to_file 和 search_and_replace）之前，在终端中提示您进行 [Y/n] 确认。
  • 为什么这是默认设置：要求手动确认可防止代理在 cm fix 或 cm verify 期间对源文件进行推测性或意外修改。仅在隔离的一次性环境或自动化 CI/CD 流水线中运行时，才应将此值设置为 false（或传递 -y / --yes）。

• execution.interactive_mode: true

  • 含义：在工具执行期间启用交互式终端提示。在未连接终端的无头 CI/CD 环境中，请将此参数设置为 false（或传递 -y / --yes）。

• scan.extensions.include: [".py", ".java", ".go", ".js", ".jsx", ".mjs", ".cjs", ".ts", ".tsx", ".c", ".cc", ".cpp", ".cxx", ".h", ".hh", ".hpp", ".hxx", ".inl", ".ipp", ".cs", ".rs", ".kt", ".kts", ".rb", ".php", ".sol", ".tf", ".hcl"]

  • 含义：定义您授权 CodeMender 在扫描工作区时注入和分析的文件扩展名的明确列表。CodeMender 会自动跳过代码库中扩展名未在此列表中指定的所有文件。
  • 为什么这是默认设置：此列表默认包含主要编程语言，以最大限度地提高扫描效率，并防止智能体在不相关的文本文件、构建工件或二进制文件上浪费时间和 token。不过，由于现代应用经常在部署配置或自动化工具中嵌入漏洞，因此您可以在 config.yaml 中手动扩展此默认列表，以包含配置文件、脚本格式和 IaC 文件（例如 shell 脚本、XML、YAML、属性和 JSON 文件），这样 CodeMender 就不会默默忽略它们。

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

  • 含义：CodeMender 在工作区扫描和代码分析期间会跳过这些目录。以 / 开头的条目（例如 /target、/obj 和 /build）仅在扫描根目录中匹配，因此不会跳过具有这些名称的嵌套源代码包。
  • 为什么这是默认设置：大型依赖项或 build 文件夹会触发严重的延迟和 token 惩罚。默认情况下，这些文件会被排除，以确保高性能和快速响应。您可以在 config.yaml 中自定义此列表，以根据项目结构包含或排除特定目录。

• project_paths: []

  • 含义：CodeMender 在执行工具期间可以访问（读取/写入）的目录路径列表。
  • 为什么这是默认设置：默认情况下，此设置为空，这会将代理限制在封闭的项目根目录（或扫描目标目录）中。如果您的构建或测试流程需要访问项目根目录之外的文件，请在此处添加这些路径，或为单次运行传递 --allow-all-paths。系统始终会屏蔽对 .git、.hg 和 .codemender 的写入操作。
  • 制品目录：智能体还可以写入每个会话的制品目录（~/.codemender/artifacts/<session_id>/，或 $CM_HOME 下的等效目录）。
  • 临时文件：启用沙盒后，主机 /tmp 目录始终会被屏蔽，即使您将 /tmp 添加到 project_paths 也是如此。遵循 TMPDIR 的工具会改为使用工件目录中的临时目录。

• sandbox：

  • 含义：进程级沙盒环境的配置块。
  • 子参数：
    • enabled: true：（布尔值）启用或停用沙盒。如果您将其设置为 true（默认），智能体将在本地沙盒中运行工具。如果您将其设置为 false（或传递 --sandbox=false），智能体将直接在主机系统上运行工具，而无需操作系统级隔离。
    • mounts：（对象）
      • target_dir: "."：（字符串）要在沙盒内作为活跃工作区装载的目录。CLI 会根据工作区根目录解析相对路径。
    • network：（对象）
      • profile: "permissive-closed"：（字符串）沙盒内的出站网络访问配置文件。目前尚不支持对特定网域或网址格式进行精细许可名单设置。支持的配置文件：
        • permissive-closed（默认）：完全网络隔离；沙盒会阻止所有出站连接。
        • permissive-open：允许完整的出站网络访问。

• security：

  • 含义：安全政策的配置块。
  • 子参数：
    • protected_files: []：（字符串列表）主机系统上您希望在沙盒内以只读方式装载的其他文件或目录，以防止它们被修改。支持路径扩展 (~) 和通配符 (*)。即使 protected_files 为空，沙盒也始终会将 .git/hooks、.git/config、.hg/hgrc 和 .codemender 保护为只读，并排除常见凭据目录（~/.ssh、~/.gnupg、~/.aws、~/.config/gcloud、~/.config/gh、~/.kube、~/.docker）。

• 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 是默认选项，因为它是版本控制跟踪的业界标准，可确保无缝的差异集成和回滚安全性。

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

  • 含义：定义 CodeMender 执行的确切 shell 命令，用于编译和构建项目，以及运行单元测试和回归测试。
  • 为什么这是默认设置：设置构建和测试命令对于验证工作流至关重要。这样，CodeMender 就可以在隔离的沙盒环境中编译您的项目并运行现有测试套件，以证明生成的安全补丁成功缓解了漏洞，而不会破坏现有的应用逻辑。

确认提示

CodeMender 会在运行 shell 命令 (tools.confirm_commands) 和写入文件 (tools.confirm_writes) 之前请求确认。这两项设置相互独立，默认值均为 true。以下设置会关闭这些提示（按优先顺序排列）：

1. -y 或 --yes：无论 config.yaml 如何提示，都批准一次运行的所有命令和文件写入提示。
2. config.yaml 中的 execution.interactive_mode: false：在每次运行时关闭命令和文件写入提示。
3. config.yaml 中的 tools.confirm_commands: false 或 tools.confirm_writes: false：针对每次运行关闭命令提示符或文件写入提示，彼此独立。

如果这些设置都不适用，并且没有人可以回答提示（例如在没有终端的 CI/CD 作业中），CodeMender 不会运行命令或写入文件。

除了这些提示之外，CLI 还会警告您，代理可以修改文件并在系统上运行命令，并要求您确认该警告。-y 不会跳过此警告。如需跳过此步骤，请传递 --bypass-warning。在没有 --bypass-warning 的非交互式环境中，cm 会失败并显示 warning not acknowledged。如果使用默认 permissive-closed 网络配置文件启用沙盒，cm find 会跳过警告。

命令政策 (command_policy.yaml)

除了操作系统级沙盒之外，您还可以在 ~/.codemender/command_policy.yaml（全局）和 <project>/.codemender/command_policy.yaml（项目专用）中定义命令拒绝清单。如果两个文件都存在，CodeMender 会合并它们的规则。

首次运行时，CodeMender 会在 ~/.codemender/command_policy.yaml 处创建一个注释掉的模板。您可以在两个键下取消注释或添加规则：

• block：要在所有 shell 管道、子 shell 和命令替换中屏蔽的二进制文件名称列表（例如 curl、wget、ssh、sudo、rm）。
• block_patterns：与每个命令段匹配的正则表达式列表（例如 '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b'）。

如需在单个命令调用中绕过 command_policy.yaml 强制执行，请传递 --allow-all-commands 标志。

• output: { plain: false }
  • 含义：控制 CodeMender CLI 是否在 CLI 输出和格式化报告中将表情符号、Unicode 符号和终端颜色替换为 ASCII 文本。
  • 为什么这是默认设置：丰富的终端样式和状态图标使交互式扫描和导出的报告更易于扫描。对于 CI/CD 日志、屏幕阅读器或极简终端，请将 plain 设置为 true。如需了解优先级规则和标志替换，请参阅配置纯文本输出。

执行沙盒

为防止工作站发生意外的文件修改或工具副作用，CodeMender CLI 默认在操作系统级沙盒中运行。您可以在配置中永久停用沙盒，也可以使用 CLI 标志针对每个命令绕过沙盒。

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

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

沙盒行为

当沙盒处于活跃状态时：

1. 文件系统隔离：代理只能访问允许目录中的文件。在 cm find 期间，工作区和允许的根目录会以只读方式装载，因此命令只能写入每个会话的工件目录。在所有命令（包括 cm verify 和 cm fix）中，.git/hooks、.git/config、.hg/hgrc 和 .codemender 均以只读方式装载，因此沙盒化命令无法安装 Git 或 Mercurial 钩子，也无法修改 CodeMender 配置。
2. 网络隔离：沙盒默认会阻止出站网络访问 (sandbox.network.profile: "permissive-closed")。这可以防止智能体（或其调用的构建工具）建立意外的外部连接或将数据传输到工作区之外。
3. 凭证和密钥隔离：沙盒会排除常见的主机凭证目录（~/.ssh、~/.gnupg、~/.aws、~/.config/gcloud、~/.config/gh、~/.kube、~/.docker 等），并在执行命令之前剥离与密钥模式（*_TOKEN、*_SECRET、*_KEY、*_PASSWORD、*_CREDENTIALS 和类似后缀）匹配的环境变量。

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

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

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

处理网络依赖项

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

• 预取依赖项：在运行 cm 命令之前，在主机系统上安装所有必需的依赖项，这样构建命令就不需要网络访问权限。

• 在沙盒中启用网络访问权限：更改 config.yaml 中的网络配置文件，以允许出站连接：

  sandbox:
    network:
      profile: "permissive-open"
  

• 为某次运行停用沙盒：运行带有 --sandbox=false 标志的命令，为该次执行停用操作系统级沙盒（包括网络隔离）。

沙盒配置

您可以使用以下选项配置和控制沙盒和安全边界：

• 永久性配置（config.yaml 和 command_policy.yaml）：在 config.yaml 和 command_policy.yaml 中自定义沙盒行为、文件系统装载、网络访问和命令拒绝清单。如需了解详情，请参阅配置参数和命令政策。
• 控制操作系统级沙盒 (--sandbox)：通过将 --sandbox=true 或 --sandbox=false 传递给 cm find、cm verify、cm fix 或 cm session resume，为单次运行显式启用或停用操作系统级沙盒。
• 绕过路径边界 (--allow-all-paths)：针对单次运行停用工作区路径边界检查，以便智能体工具可以访问项目根目录和已配置的 project_paths 之外的路径（与 --sandbox=false 结合使用可访问未装载到沙盒中的主机路径）。
• 绕过命令政策 (--allow-all-commands)：针对单次运行，停用 command_policy.yaml 屏蔽名单强制执行。

选择隔离级别

您可以根据自己的安全要求和开发环境，选择适当的隔离级别来运行 CodeMender CLI。

配置纯文本输出

默认情况下，CodeMender CLI 会在交互式输出和格式化报告中使用表情符号、Unicode 符号和终端颜色。如需在 CI/CD 日志、屏幕阅读器或最小终端中使用仅限 ASCII 的输出，请启用纯文本模式。CodeMender CLI 会按照从高到低的优先级顺序检查这些设置：

1. 将 --plain 标志传递给任何 cm 命令以运行一次，或传递 --plain=false 以替换环境和配置设置：

   cm --plain find .
   

2. 将 CM_PLAIN 环境变量设置为 true 或 1，以在各个命令中启用纯文本输出，或将其设置为 false 或 0 以将其关闭：

   export CM_PLAIN=true
   

3. 在 ~/.codemender/config.yaml 文件中将 output.plain 设置为 true：

   output:
     plain: true
   

4. 在终端中运行交互式会话，其中 TERM=dumb 会自动启用纯文本输出。

纯文本模式会将状态表情符号替换为 ASCII 标记，例如 [OK]、[INFO]、[WARN]、[ERROR]、[PASS] 和 [FAIL]。CodeMender 还会关闭动画旋转图标和就地行重写，并呈现 ASCII 表格边框。在 cm report 中，纯文本模式会从 table、md 和 html 格式中移除界面表情符号，而不会更改 json 或 sarif 输出或代码差异。

重定向的文件和非交互式 CI/CD 流默认将 plain 设置为 false，以便导出的 Markdown 和 HTML 报告保留状态图标。如需在 CI/CD 日志中移除表情符号和 Unicode 符号，请设置 CM_PLAIN=true、传递 --plain 或设置 output.plain: true。在非交互式流中以及设置 NO_COLOR 环境变量时，系统会自动省略终端颜色转义。

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