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

プロジェクトで次の Google Cloud API が有効になっていることを確認します。

  1. Agent Platform API(aiplatform.googleapis.com)- アクティブなセッションのストリーミングと管理を強化します。
  2. Cloud Resource Manager API(cloudresourcemanager.googleapis.com)- ユーザー認証状態とプロジェクト メタデータを検証します。

CLI コマンドを実行するには、ユーザーに次の IAM ロールが割り当てられている必要があります。

  • Agent Platform ユーザー(roles/aiplatform.user)- ユーザーがアクティビティ セッションを作成、ストリーミング、管理できるようにします。

CodeMender CLI をダウンロードしてインストールする

CodeMender CLI バイナリは Artifact Registry でホストされています。オペレーティング システムのタブを選択して、CLI をダウンロードしてインストールします。

Linux x86_64

Linux(x86_64)用の CodeMender CLI をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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"
  2. CLI をインストールします。
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

Linux ARM64

Linux(ARM64)用の CodeMender CLI をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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"
  2. CLI をインストールします。
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

macOS(Intel)用の CodeMender CLI をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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"
  2. CLI をインストールします。
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

macOS Apple シリコン

macOS(Apple シリコン)用の CodeMender CLI をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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"
  2. CLI をインストールします。
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

Windows(x86_64)用の CodeMender CLI をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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
  2. 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 をダウンロードしてインストールするには:

  1. 次のいずれかの方法でパッケージをダウンロードします。
    • 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
  2. 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)を構成し、環境でターゲット プロジェクトを指定する必要があります。

  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

サービスの接続性と権限を確認する

スキャンを開始したり、ワークスペースを変更したりせずに、認証情報、構成、Network Reachability、IAM 権限を確認するには、cm health を実行します。

cm health

cm health コマンドは、4 つのチェックを順番に実行し、最初に失敗したレイヤで停止します。cm health は、cm init を実行する前でも、任意のディレクトリから実行できます。ディスクへの書き込みやモデルの割り当ての消費は行われません。

自動化された CI / CD プリフライト チェックまたはスケジュール設定された合成モニタリングでは、プロジェクト レベルの IAM チェックがスキップされたときに失敗するように --strict を使用し、機械で読み取り可能な JSON レポートを出力するように --json を使用します。

cm health --strict --json

次の表に、cm health 終了コードを示します。

終了コード 層 説明
0 — すべてのヘルスチェックに合格しました。
10 credentials CLI が有効な OAuth トークンまたはアプリケーションのデフォルト認証情報トークンを取得できなかったか、サーバーがトークンを拒否しました(401 Unauthorized)。
20 config ローカルの config.yaml ファイル、--team-id フラグ、または CM_TEAM_ID 環境変数が無効です。
30 reachability CLI が Agent Platform API エンドポイントに到達できなかった(DNS、TLS、プロキシ、VPC Service Controls の制限など)。
40 authorization サーバーにアクセスできましたが、呼び出し元またはプロジェクトに CodeMender スキャンを実行する権限がありません(roles/aiplatform.user 権限がないなど)。
50 — ヘルスチェックが --timeout の期間(デフォルトは 30s)を超えました。

cm health では、次のフラグがサポートされています。

フラグ デフォルト 説明
--json false status、exit_code、backend、endpoint、location、project_id、agent_id、duration_ms、layers、warnings(存在する場合)、error(存在する場合)を含む単一の JSON オブジェクトを標準出力に出力します。
--strict false ヘルスチェックの警告(未検証またはスキップされたプロジェクト レベルの IAM 権限チェックなど)を終了コード 40 の失敗として扱います。
--timeout 30s ヘルスチェック プローブの全体的なタイムアウトを設定します。

構成パラメータ(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 はシェルコマンド(run_command)を実行する前に、ターミナルで [Y/n] の確認を求めます。OS レベルのサンドボックスが有効(sandbox.enabled: true)で、デフォルトのネットワーク分離(permissive-closed)が有効な状態で cm find が実行されると、ワークスペースは読み取り専用でマウントされ、コマンド確認プロンプトは自動的にスキップされます。
    • デフォルトである理由: CodeMender は、検証とパッチ適用中にビルドコマンド、テストスイート、エクスプロイト スクリプトを実行することがあります。ワークスペースが書き込み可能またはサンドボックス化されていない場合に確認を必須にすることで、ローカル環境で意図しないコマンドが実行されるのを防ぐことができます。
    • バイパス: 1 回の実行で -y(または --yes)を渡すか、非インタラクティブな CI / CD パイプラインの場合は config.yaml で tools.confirm_commands: false を設定します。
  • tools.confirm_writes: true

    • 意味: CodeMender エージェントがディスク上のファイル(write_to_file と search_and_replace)を書き込みまたは変更する前に、ターミナルで [Y/n] の確認を求めます。
    • これがデフォルトである理由: 手動確認を必須にすることで、cm fix または cm verify 中にエージェントがソースファイルに推測的な変更や意図しない変更を加えることを防ぎます。この値を false に設定する(または -y / --yes を渡す)のは、分離された使い捨て環境または自動化された CI / CD パイプラインで実行する場合のみにしてください。
  • execution.interactive_mode: true

    • 意味: ツールの実行中にインタラクティブなターミナル プロンプトを有効にします。ターミナルが接続されていないヘッドレス CI / CD 環境では、これを false に設定します(または -y / --yes を渡します)。
  • execution.duration: ""

    • 意味: cm find、cm verify、cm fix、cm session resume で、コマンド呼び出しあたりのデフォルトの最大実時間("15m" や "1h" など)を設定します。時間制限がない場合は、空白のままにするか、"0" に設定します。この設定は、CM_DURATION 環境変数または --duration(または --timeout)フラグでオーバーライドできます。コマンドが期間の上限に達して停止すると、完了した結果が保存され、cm find --diff スキャンが --fail-on と一致する場合はステータス 1 で終了し、それ以外の場合はステータス 50 で終了します。
  • execution.stall_detection: false

    • 意味: true に設定されている場合(または CM_STALL_DETECTION=on の場合)、連続するツールターンで前進しないエージェント セッションを停止します。単一セッション コマンド(単一パスの cm find --quick、cm verify、cm fix、cm session resume)は、ステータス 50 で終了します。マルチセッションの --deep、--diff、--parallel スキャンでは、停止したセッションは失敗として記録され、スキャンは続行されます。
  • 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 は、このリストで指定されていない拡張子を持つリポジトリ内のファイルを自動的にスキップします。
    • これがデフォルトである理由: このリストは、スキャンの効率を最大化し、エージェントが無関係なテキスト ファイル、ビルド アーティファクト、バイナリ ファイルに時間とトークンを浪費しないように、デフォルトで主要なプログラミング言語に設定されています。ただし、最新のアプリケーションでは、デプロイ構成や自動化ツールに脆弱性が埋め込まれていることが多いため、config.yaml でこのデフォルト リストを手動で拡張して、構成ファイル、スクリプト形式、IaC ファイル(シェル スクリプト、XML、YAML、プロパティ、JSON ファイルなど)を含めることができます。これにより、CodeMender がこれらのファイルを無視しないようにできます。
  • scan.exclude_dirs: ["node_modules", "vendor", "dist", "/target", "/obj", "/build", ".gradle"]

    • 意味: CodeMender は、ワークスペースのスキャンとコード分析中にこれらのディレクトリをスキップします。/ で始まるエントリ(/target、/obj、/build など)は、スキャンルートでのみ一致するため、これらの名前を持つネストされたソース パッケージはスキップされません。
    • これがデフォルトである理由: 依存関係やビルドのフォルダが大きいと、レイテンシとトークンのペナルティが大きくなります。これらをデフォルトで除外することで、高いパフォーマンスと迅速なレスポンス時間を確保できます。このリストは config.yaml でカスタマイズして、プロジェクト構造に応じて特定のディレクトリを追加または除外できます。
  • project_paths: []

    • 意味: ツールの実行中に CodeMender がアクセス(読み取り / 書き込み)できるディレクトリ パスのリスト。
    • これがデフォルトである理由: デフォルトでは空です。これにより、エージェントは、囲まれたプロジェクト ルート(またはスキャン ターゲット ディレクトリ)に制限されます。ビルドまたはテストのプロセスでプロジェクト ルート外のファイルにアクセスする必要がある場合は、ここにパスを追加するか、1 回の実行で --allow-all-paths を渡します。.git、.hg、.codemender への書き込みは常にブロックされます。
    • アーティファクト ディレクトリ: エージェントは、セッションごとのアーティファクト ディレクトリ(~/.codemender/artifacts/<session_id>/、または $CM_HOME の同等のディレクトリ)に書き込むこともできます。
    • 一時ファイル: サンドボックスが有効になっている場合、/tmp を project_paths に追加しても、ホストの /tmp ディレクトリは常にブロックされます。TMPDIR を尊重するツールは、代わりにアーティファクト ディレクトリ内の一時ディレクトリを使用します。
  • sandbox:

    • 意味: プロセスレベルのサンドボックス環境の構成ブロック。
    • サブパラメータ:
      • enabled: true:(ブール値)サンドボックスを有効または無効にします。これを true(デフォルト)に設定すると、エージェントはローカル サンドボックス内でツールを実行します。false に設定する(または --sandbox=false を渡す)と、エージェントは OS レベルの分離を行わずに、ホストシステム上で直接ツールを実行します。
      • mounts:(オブジェクト)
        • target_dir: ".":(文字列)サンドボックス内でアクティブなワークスペースとしてマウントするディレクトリ。CLI は、ワークスペースのルートを基準として相対パスを解決します。
      • network:(オブジェクト)
        • profile: "permissive-closed":(文字列)サンドボックス内のアウトバウンド ネットワーク アクセス プロファイル。特定のドメインまたは URL パターンの詳細な許可リストはまだサポートされていません。サポートされているプロファイル:
          • 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)を除外します。
  • モデル: config.yaml はモデルを設定しません。モデルを選択するには、--model を cm find、cm verify、または cm fix に渡します。サポートされているモデルとデフォルトについては、モデルの指定をご覧ください。

  • 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 は、シェルコマンドを実行する前(tools.confirm_commands)とファイルを書き込む前(tools.confirm_writes)に確認を求めます。この 2 つの設定は独立しており、どちらもデフォルトは true です。これらのプロンプトを無効にする設定は、優先順位の高い順に次のとおりです。

  1. -y または --yes: config.yaml の内容に関係なく、1 回の実行ですべてのコマンドとファイル書き込みプロンプトを承認します。
  2. execution.interactive_mode: false(config.yaml 内): 実行ごとにコマンドとファイル書き込みプロンプトの両方をオフにします。
  3. config.yaml の tools.confirm_commands: false または tools.confirm_writes: false: 実行ごとにコマンド プロンプトまたはファイル書き込みプロンプトをオフにします。

これらの設定が適用されず、プロンプトに回答できるユーザーがいない場合(ターミナルのない CI / CD ジョブなど)、CodeMender はコマンドを実行せず、ファイルも書き込みません。

これらのプロンプトとは別に、CLI は、エージェントがシステム上のファイルを変更してコマンドを実行できることを警告し、警告を確認するよう求めます。-y はこの警告をスキップしません。スキップするには、--bypass-warning を渡します。--bypass-warning のない非インタラクティブ環境では、cm は warning not acknowledged で失敗します。cm find は、デフォルトの permissive-closed Network Profiler プロファイルでサンドボックスが有効になっている場合に警告をスキップします。

コマンド ポリシー(command_policy.yaml)

OS レベルのサンドボックスに加えて、~/.codemender/command_policy.yaml(グローバル)と <project>/.codemender/command_policy.yaml(プロジェクト固有)でコマンド拒否リストを定義できます。両方のファイルが存在する場合、CodeMender はルールをマージします。

最初の実行時に、CodeMender は ~/.codemender/command_policy.yaml にコメントアウトされたテンプレートを作成します。次の 2 つのキーの下にあるルールのコメント化を解除するか、ルールを追加できます。

  • block: すべてのシェル パイプライン、サブシェル、コマンド置換でブロックするバイナリ名のリスト(例: curl、wget、ssh、sudo、rm)。
  • block_patterns: 各コマンド セグメントと照合される正規表現のリスト(例: '\bgit\s+(push|commit|rebase|reset\s+--hard|clean)\b')。

1 つのコマンド呼び出しで command_policy.yaml の適用をバイパスするには、--allow-all-commands フラグを渡します。

  • output: { plain: false }
    • 意味: CodeMender CLI が、CLI 出力とフォーマットされたレポート全体で、絵文字、Unicode 記号、ターミナル カラーを ASCII テキストに置き換えるかどうかを制御します。
    • デフォルトである理由: 豊富なターミナル スタイルとステータス アイコンにより、インタラクティブなスキャンとエクスポートされたレポートを簡単にスキャンできます。CI / CD ログ、スクリーン リーダー、最小限のターミナルの場合は、plain を true に設定します。優先順位ルールとフラグのオーバーライドについては、書式なしテキスト出力を構成するをご覧ください。

実行サンドボックス

意図しないファイルの変更や予期しないツールの副作用からワークステーションを保護するため、CodeMender CLI はデフォルトで OS レベルのサンドボックス内で実行されます。サンドボックス化は、構成で永続的に無効にすることも、CLI フラグを使用してコマンドごとにバイパスすることもできます。

Google は、推奨される安全機能として CodeMender サンドボックスを提供しています。サンドボックス環境外で CodeMender を実行する場合は、サービス固有規約のセクション 20(j) に基づき、お客様の自己責任となります。

このサンドボックス化は、ワークステーションに初期の防御レイヤを提供しますが、完全に分離された仮想マシン(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 を実行するプロジェクト)に制限が導入されます。ビルドプロセスが外部ウェブサービスにアクセスしようとすると、失敗します。

ネットワーク依存関係の処理

プロジェクトでビルドまたはテストにネットワーク アクセスが必要な場合は、次のオプションがあります。

  • 依存関係をプリフェッチする: cm コマンドを実行する前に、必要な依存関係をすべてホストシステムにインストールします。これにより、ビルドコマンドでネットワーク アクセスが不要になります。
  • サンドボックスでネットワーク アクセスを有効にする: config.yaml のネットワーク プロファイルを変更して、アウトバウンド接続を許可します。

    sandbox:
      network:
        profile: "permissive-open"
    
  • 実行時にサンドボックスを無効にする: --sandbox=false フラグを指定してコマンドを実行すると、その実行で OS レベルのサンドボックス(ネットワーク分離を含む)が無効になります。

サンドボックスの構成

次のオプションを使用して、サンドボックスとセキュリティ境界を構成および制御できます。

  • 永続的な構成(config.yaml と command_policy.yaml): config.yaml と command_policy.yaml で、サンドボックスの動作、ファイル システムのマウント、ネットワーク アクセス、コマンドの拒否リストをカスタマイズします。詳細については、構成パラメータとコマンド ポリシーをご覧ください。
  • OS レベルのサンドボックス(--sandbox)を制御する: --sandbox=true または --sandbox=false を cm find、cm verify、cm fix、cm session resume に渡すことで、1 回の実行で OS レベルのサンドボックスを明示的に有効または無効にします。
  • パス境界をバイパスする(--allow-all-paths): 1 回の実行でワークスペース パス境界チェックを無効にして、エージェント ツールがプロジェクト ルートと構成済みの project_paths の外部のパスにアクセスできるようにします(--sandbox=false と組み合わせて、サンドボックス内にマウントされていないホストパスにアクセスします)。
  • コマンド ポリシーをバイパスする(--allow-all-commands): 1 回の実行で command_policy.yaml 拒否リストの適用を無効にします。

分離レベルの選択

セキュリティ要件と開発環境に応じて、CodeMender CLI を実行するための適切な分離レベルを選択できます。

メソッド 説明 利点 欠点
組み込みのサンドボックス(OS レベル) デフォルトで有効になっています。config.yaml ファイルで無効にするか、CLI フラグを使用してバイパスできます。組み込みの OS 機能(名前空間 / seccomp、sandbox-exec、AppContainer(試験運用版))を使用して実行を分離します。 軽量。起動オーバーヘッドはゼロ。きめ細かい制御でローカル ワークスペース ツールに直接アクセス。日常的なローカル開発におすすめです。 セキュリティは OS カーネル機能に依存します。完全な VM よりも分離性が低くなります。Windows のサポートは試験運用版であり、管理者権限が必要になる場合や、一部の構成と互換性がない場合があります。
コンテナ コンテナ(Docker など)でエージェントを実行する。 優れた分離、標準化された環境。 コンテナ ランタイムが必要。重くなる可能性がある。ローカルマシンのツールを直接操作できない。
フル VM 専用 VM でエージェントを実行する。 最大限のセキュリティ、完全な分離。 リソース オーバーヘッドが高い、起動が遅い、ローカルマシン上のツールを直接操作できない。

書式なしテキスト出力を構成する

デフォルトでは、CodeMender CLI は、インタラクティブな出力とフォーマットされたレポートで絵文字、Unicode 記号、ターミナル カラーを使用します。CI / CD ログ、スクリーン リーダー、最小限のターミナルで ASCII のみの出力を使用するには、書式なしテキストモードを有効にします。CodeMender CLI は、次の優先順位でこれらの設定を確認します。

  1. 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 が書式なしテキスト出力を自動的に有効にするターミナルで、インタラクティブ セッションを実行します。

書式なしテキストモードでは、ステータス絵文字が [OK]、[INFO]、[WARN]、[ERROR]、[PASS]、[FAIL] などの ASCII タグに置き換えられます。CodeMender は、アニメーション スピナーとインプレース行の書き換えをオフにし、ASCII テーブルの枠線を表示します。cm report では、書式なしテキストモードにより、json または sarif の出力やコード差分を変更することなく、table、md、html 形式から UI 絵文字が削除されます。

リダイレクトされたファイルと非インタラクティブな CI / CD ストリームでは、デフォルトで plain が false に設定されたままになるため、エクスポートされた Markdown レポートと HTML レポートでステータス アイコンが保持されます。CI / CD ログの絵文字と Unicode 記号を削除するには、CM_PLAIN=true を設定するか、--plain を渡すか、output.plain: true を設定します。ターミナルのカラー エスケープは、非インタラクティブ ストリームと NO_COLOR 環境変数を設定すると自動的に省略されます。

テレメトリー

プロダクトの健全性をモニタリングして改善するため、CLI は使用状況のテレメトリーを Google に送信します。これには、コマンドの開始時のイベント、終了時のイベント、報告されたエラーごとのイベントが含まれます。CLI が特定できる場合、イベントは CLI を実行する Google アカウントまたはサービス アカウントと、使用する Google Cloud プロジェクトを識別します。

テレメトリー イベントには、次のものが含まれます。

  • Google アカウント ID またはサービス アカウント ID、 Google Cloud プロジェクト ID、チーム ID(設定している場合)。
  • 各コマンドのランダムな ID、コマンド名、サーバー セッション ID、選択したモデル、CLI バージョン。
  • オペレーティング システム ファミリー、プラットフォーム、バージョン。
  • サンドボックスが有効になっているかどうか、および -y(--yes)が確認プロンプトをスキップするように設定されているかどうか。
  • 終了時: 期間、終了コード、結果、トークン数、スキャンされた行数、ファイル数、バイト数、検出された言語、重大度別の検出結果数、検証または修正の結果。
  • エラー時: エラーのカテゴリと理由、CLI 独自のコードのスタック トレース。

テレメトリーには、ソースコード、ファイルの内容、ファイルパス、プロンプト、検出結果、パッチ、エラー メッセージ テキストは含まれません。CLI は、グローバル Google エンドポイントにテレメトリーを送信します。テレメトリーは、Google Cloud のプライバシーに関するお知らせに記載されているサービスデータです。

デフォルトでは、テレメトリーは有効になっています。テレメトリーを無効にする場合は、CM_TELEMETRY_OPT_OUT 環境変数を 1 または true に設定します。

CLI の更新

CodeMender には、CLI を最新バージョンに保つための更新メカニズムが組み込まれています。

自動更新の確認

デフォルトでは、CodeMender CLI はコマンドの実行時にバックグラウンドで更新を自動的に確認します。

  • スロットリング: オーバーヘッドを最小限に抑えるため、自動チェックは 24 時間に 1 回だけ実行されます。
  • インタラクティブ ターミナル(TTY)が必要: CLI は、インタラクティブ ターミナルで実行されている場合にのみ、更新を確認してプロンプトを表示します。非対話型環境(CI / CD パイプラインやスクリプトなど)では、チェックはスキップされ、1 日に 1 回、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