安装并配置 CLI

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

架构和安全模型

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

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

环境设置

如需开始使用 CodeMender，请设置您的 Cloud de Confiance 项目、下载并安装 CLI、配置凭据和目标项目，并初始化工作区。

项目设置和 IAM 权限

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

必需的 API

确保在项目中启用以下 Cloud de Confiance by S3NS 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。

配置 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 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 无法 修改磁盘上的任何文件或执行 shell 命令，而无需在终端中明确提示您进行 [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 文件（例如 shell 脚本、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 目录始终会被屏蔽，即使您将 /tmp 添加到 project_paths 中也是如此。遵循 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 是默认设置，因为它是版本控制跟踪的业界标准，可确保无缝差异集成和回滚安全性。

• 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 上的沙盒功能处于实验阶段，可能需要管理员权限，或者与某些系统配置不兼容。

沙盒行为

当沙盒处于活跃状态时：

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

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

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

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

处理网络依赖项

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

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

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

  sandbox:
    network:
      profile: "permissive-open"
  

• 绕过沙盒：运行带有 --unrestricted 标志的命令，以完全停用该执行的沙盒和文件系统边界。

沙盒配置

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

• 永久配置 (config.yaml) ：您可以通过将 sandbox、execution 和 security 块添加到 config.yaml 文件来自定义沙盒行为、文件系统装载、网络访问和安全政策。如需了解详情，请参阅配置参数。
• 使用 CLI 控制沙盒 (--sandbox)：您可以通过将 --sandbox=true 或 --sandbox=false 传递给 cm find、cm verify 或 cm fix，为单次运行显式启用或停用沙盒。
• 使用 CLI 绕过隔离 (--unrestricted) ：您可以通过传递 --unrestricted 标志，为单次运行暂时绕过所有沙盒保护。这会停用文件系统路径边界（允许智能体访问主机上的任何路径），并完全停用操作系统级容器隔离（包括网络隔离）。

选择隔离级别

您可以根据安全要求和开发环境，选择适合运行 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