O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Instalar e configurar a CLI

O CodeMender é um agente autônomo de segurança de código de IA que verifica, confirma e corrige vulnerabilidades profundas de segurança cibernética na sua base de código. Antes de executar o CodeMender, faça o download da CLI e inicialize as opções do espaço de trabalho.

Arquitetura e modelo de segurança

O CodeMender usa um modelo de execução local:

Mecanismo de raciocínio hospedado: o raciocínio de agentes, a modelagem de ameaças e a lógica de orquestração são executados com segurança em Google Cloud na Gemini Enterprise Agent Platform.
CLI de execução local: o código-fonte nunca sai da sua estação de trabalho ou do contêiner de CI/CD em massa. A ferramenta de linha de comando cm local executa leituras de arquivos, verificações de build local e verificações de exploração de prova de conceito (PoC) na sua sandbox local, enviando apenas snippets de código cirúrgicos e resultados de execução de ferramentas para o back-end da nuvem pela API Interactions na plataforma do agente do Gemini Enterprise.

configuração do ambiente

Para começar a usar o CodeMender, configure seu projeto do Google Cloud , faça o download e instale a CLI, configure suas credenciais e inicialize seu espaço de trabalho.

Configuração do projeto e permissões do IAM

Antes de baixar a CLI e configurar as credenciais, verifique se o projeto Google Cloud de destino está configurado corretamente com as APIs e permissões necessárias.

APIs necessárias

Verifique se as seguintes APIs Google Cloud estão ativadas no seu projeto:

API Vertex AI (aiplatform.googleapis.com): alimenta o streaming e o gerenciamento de sessões ativas.
API Cloud Resource Manager (cloudresourcemanager.googleapis.com): valida estados de autenticação do usuário e metadados do projeto.

Papel predefinido recomendado do IAM

Para executar os comandos da CLI, os usuários precisam ter o seguinte papel do IAM atribuído:

Usuário da Vertex AI (roles/aiplatform.user): permite que os usuários criem, transmitam e gerenciem sessões ativas.

Baixar e instalar a CLI do CodeMender

Os binários da CLI do CodeMender são hospedados no Artifact Registry. Escolha a guia do seu sistema operacional para fazer o download e instalar a CLI.

Linux x86_64

Para fazer o download e instalar a CLI do CodeMender para Linux (x86_64):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando:

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

curl:execute o seguinte comando:

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"

Instale a CLI:

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

Linux ARM64

Para fazer o download e instalar a CLI do CodeMender para Linux (ARM64):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando:

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

curl:execute o seguinte comando:

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"

Instale a CLI:

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

macOS Intel

Para fazer o download e instalar a CLI do CodeMender para macOS (Intel):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando:

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

curl:execute o seguinte comando:

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"

Instale a CLI:

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

macOS Apple Silicon

Para fazer o download e instalar a CLI do CodeMender para macOS (Apple Silicon):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando:

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

curl:execute o seguinte comando:

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"

Instale a CLI:

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

Windows x86_64

Para fazer o download e instalar a CLI do CodeMender para Windows (x86_64):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando no 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:execute o seguinte comando:

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

Instale a 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

Para fazer o download e instalar a CLI do CodeMender para Windows (ARM64):

Faça o download do pacote usando um dos seguintes métodos:

CLI gcloud:execute o seguinte comando no 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:execute o seguinte comando:

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

Instale a 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)

Configurar credenciais do Google Cloud

Como a CLI do CodeMender interage com o mecanismo de raciocínio hospedado na nuvem pela API Interactions, é necessário configurar as Google Cloud Application Default Credentials (ADC) no seu ambiente.

Para fazer a autenticação, execute o comando a seguir e siga as instruções de login:

gcloud auth application-default login

Inicializar o espaço de trabalho

Depois de autenticar, a próxima etapa é inicializar o CodeMender no seu ambiente local. A inicialização do CodeMender prepara seu espaço de trabalho local criando arquivos de rastreamento de estado e estabelecendo configurações de conexão com o mecanismo de raciocínio hospedado na nuvem.

Execute cm init no diretório raiz da sua base de código para criar arquivos de rastreamento de estado local e estabelecer configurações de base:

cm init

Use a flag --verify para testar a conectividade com o mecanismo de raciocínio hospedado na nuvem e verificar as configurações do espaço de trabalho:

cm init --verify

Parâmetros de configuração (`config.yaml`)

O objetivo principal do config.yaml é alinhar os comportamentos do agente do CodeMender com a segurança, as restrições de ambiente e as necessidades de performance do seu sistema local.

Como o agente de IA hospedado executa comandos locais (como criar código, executar testes ou editar arquivos) usando seu cliente daemon local, esse arquivo de configuração atua como o limite que define o que o agente pode e não pode fazer.

Uso

Localização:por padrão, a CLI procura esse arquivo no espaço de trabalho inicializado (geralmente .codemender/config.yaml ou um diretório de configuração global, como ~/.config/codemender/config.yaml).
Execução:quando você executa comandos como cm find, cm verify ou cm fix, o cliente local lê esse arquivo para configurar parâmetros de segurança, aplicar bypasses do sistema e especificar quais arquivos ou diretórios ignorar.

Configurações padrão principais

Confira o que significam os parâmetros padrão principais:

human_confirmation: true (ou require_confirmation: true)
- O que isso significa:por padrão, o CodeMender não pode modificar nenhum arquivo no seu disco nem executar comandos do shell sem pedir explicitamente uma confirmação [Y/n] no terminal.
- Por que essa é a opção padrão:o CodeMender pode gerar patches especulativos ou tentar executar scripts de exploração para verificar uma vulnerabilidade. Forçar a confirmação humana ajuda a evitar mudanças acidentais no sistema ou a execução de código não autorizada no seu ambiente local.
- Substituição:para pipelines de CI/CD não interativos, isso pode ser definido como false.
confirm_writes: false
- O que isso significa:desativa os comandos interativos para modificações de arquivos, permitindo que o agente do CodeMender grave patches de segurança e modifique arquivos de origem diretamente no disco local sem esperar aprovação humana.
- Por que esse é o padrão:por padrão, o CodeMender define essa proteção de segurança como true para aplicar um fluxo de trabalho "Human-in-the-Loop". Como o CodeMender age na sua base de código local, exigir confirmação manual (por exemplo, Write? [Y/n]) impede que o agente faça modificações especulativas, incorretas ou destrutivas nos seus arquivos de origem. Você só deve mudar para false ao executar em sandboxes isoladas e descartáveis ou em pipelines de CI/CD automatizados e sem interface gráfica.
include: [".py", ".java", ".go", ".js", ".ts", ".c", ".cc", ".cpp", ".h", ".rb", ".php"]
- O que isso significa:define a lista explícita de extensões de arquivo que você autoriza o CodeMender a ingerir e analisar ao verificar seu espaço de trabalho. O CodeMender pula automaticamente qualquer arquivo no repositório com uma extensão não especificada nessa lista.
- Por que essa é a configuração padrão:essa lista usa as principais linguagens de programação para maximizar a eficiência da verificação e evitar que o agente gaste tempo e tokens em arquivos de texto, artefatos de build ou arquivos binários irrelevantes. No entanto, como os aplicativos modernos geralmente incorporam vulnerabilidades em configurações de implantação ou ferramentas de automação, recomendamos que você expanda manualmente essa lista padrão para incluir arquivos de configuração, formatos de script e arquivos IaC (por exemplo, scripts shell, XML, YAML, propriedades e arquivos JSON) para que o CodeMender não os ignore silenciosamente.
exclude_paths: ["node_modules", "vendor", "dist", "bin"]
- O que isso significa:o CodeMender vai ignorar completamente esses diretórios durante a verificação do espaço de trabalho e a análise de código.
- Por que essa é a configuração padrão:pastas grandes de dependência ou build causam uma latência e uma penalidade de token enormes. Manter esses itens excluídos por padrão garante alto desempenho e tempos de resposta rápidos.
project_paths: []
- O que isso significa:uma lista de caminhos de diretório que o CodeMender pode acessar (leitura/gravação) durante a execução da ferramenta.
- Por que esse é o padrão:por padrão, ele está vazio, o que restringe o agente ao diretório de destino da verificação, ao diretório do espaço de trabalho .codemender e a /tmp. Se o processo de build ou teste exigir acesso a arquivos fora desses diretórios, adicione esses caminhos aqui.
sandbox:
- Significado:bloco de configuração para o ambiente de sandbox no nível do processo.
- Subparâmetros:
  - enabled: true: (booleano) ativa ou desativa o sandbox. Se você definir como true (padrão), o agente vai executar ferramentas no sandbox local. Se você definir como false, o agente vai executar ferramentas diretamente no sistema host sem isolamento.
  - mounts: (objeto)
    - target_dir: ".": (string) o diretório a ser montado como o espaço de trabalho ativo dentro do sandbox. A CLI resolve caminhos relativos em relação à raiz do espaço de trabalho.
  - network: (objeto)
    - profile: "permissive-closed": (string) perfil de acesso à rede de saída dentro da sandbox. Ainda não há suporte para a lista de permissão granular de domínios ou padrões de URL específicos. Perfis compatíveis:
      - permissive-closed (padrão): isolamento completo da rede. O sandbox bloqueia todas as conexões de saída.
      - permissive-open: permite acesso total à rede de saída.
security:
- O que significa:bloco de configuração para políticas de segurança.
- Subparâmetros:
  - protected_files: []: (lista de strings) arquivos ou diretórios no sistema host que você quer montar como somente leitura dentro do sandbox para protegê-los contra modificações (por exemplo, ["~/.ssh/*"]). Compatível com expansão de caminho (~) e caracteres curinga (*).
model: "gemini-3.5-flash"
- O que significa:o mecanismo de inteligência padrão que alimenta os loops de raciocínio de back-end.
- Por que esse é o padrão:gemini-3.5-flash oferece o equilíbrio ideal de velocidade, custo e raciocínio analítico necessário para sugerir patches. Os usuários podem substituir essa opção por gemini-3.1-pro para um raciocínio mais profundo e complexo quando necessário.
vcs: { type: "git" }
- O que significa:define o tipo de sistema de controle de versões que seu projeto usa pela chave vcs. Se você deixar essa opção sem configuração, a ferramenta tentará identificar automaticamente os repositórios do Git ou do Mercurial. Se você definir vcs como none, a CLI vai gerar um aviso, mas continuará a execução sem a funcionalidade do VCS. O CodeMender depende dessa configuração para gerenciar correções de segurança especulativas, rastrear modificações na base de código e se integrar ao seu repositório local.
- Por que essa é a opção padrão:o CodeMender é compatível com configurações do Git, Mercurial ou VCS personalizadas. O Git é o padrão do setor para rastreamento de controle de versões, garantindo integração de diff e segurança de rollback sem problemas.
build: { command: "make build && make test" }
- O que significa:define o comando de shell exato que o CodeMender executa para compilar e criar seu projeto, além de executar seus testes de unidade e regressão.
- Por que essa é a opção padrão:definir um comando de build e teste é essencial para o fluxo de trabalho de verificação. Ele permite que o CodeMender compile seu projeto e execute o conjunto de testes atual no ambiente de sandbox isolado para provar que o patch de segurança gerado mitiga a vulnerabilidade sem interromper a lógica do aplicativo atual.

Sandbox de execução

Para proteger sua estação de trabalho contra modificações não intencionais de arquivos ou efeitos colaterais inesperados de ferramentas, a CLI do CodeMender é executada em uma sandbox no nível do SO por padrão. É possível desativar o sandboxing de forma permanente na configuração ou ignorá-lo por comando usando flags da CLI.

Embora esse isolamento em sandbox ofereça uma camada inicial de defesa na sua estação de trabalho, ele oferece uma proteção de segurança mais fraca do que executar o agente em uma máquina virtual (VM) totalmente isolada:

Linux: usa namespaces do kernel (CLONE_NEWNS, CLONE_NEWUSER etc.) e filtros seccomp para isolar pontos de montagem e restringir chamadas de sistema.
macOS: usa o mecanismo sandbox-exec (Seatbelt) integrado.
Windows (experimental): usa isolamento AppContainer e listas de controle de acesso (ACLs). O isolamento em sandbox no Windows é experimental e pode exigir privilégios de administrador ou ser incompatível com algumas configurações do sistema.

Comportamento do sandbox

Quando o sandbox está ativo:

Isolamento do sistema de arquivos: o agente só pode ler e gravar arquivos em diretórios permitidos. O sandbox redireciona todas as gravações fora desses diretórios para um sistema de arquivos temporário na memória (tmpfs) sem afetar o sistema host.
Isolamento de rede: o sandbox bloqueia o acesso de rede de saída por padrão. Isso impede que o agente (ou as ferramentas de build que ele invoca) faça conexões externas inesperadas ou transmita dados fora do espaço de trabalho.

Acesso à rede durante a criação e validação

Como a sandbox ativa o isolamento de rede por padrão (sandbox.network.profile é definido como permissive-closed), o agente não pode acessar a Internet durante a execução da ferramenta.

Isso introduz limitações para projetos que exigem a busca de dependências externas durante as etapas de build ou verificação (por exemplo, executar npm install, pip install ou go get como parte do build.command). Se o processo de build tentar acessar serviços da Web externos, ele vai falhar.

Como processar dependências de rede

Se o projeto exigir acesso à rede para builds ou testes, você terá as seguintes opções:

Pré-busca de dependências: instale todas as dependências necessárias no sistema host antes de executar os comandos cm para que o comando de build não precise de acesso à rede.
Ative o acesso à rede no sandbox: mude o perfil de rede no seu config.yaml para permitir conexões de saída:
```
sandbox:
  network:
    profile: "permissive-open"
```
Observação:ainda não é possível criar uma lista de permissão granular de domínios ou padrões de URL específicos (como permitir apenas npmjs.org). O permissive-open concede acesso total de saída ao sandbox.
Ignorar a sandbox: execute o comando com a flag --unrestricted para desativar completamente a sandbox e os limites do sistema de arquivos para essa execução.

Configuração do sandbox

É possível configurar e controlar a sandbox usando as seguintes opções:

Configuração persistente (config.yaml): é possível personalizar o comportamento da sandbox, as montagens do sistema de arquivos, o acesso à rede e as políticas de segurança adicionando blocos sandbox, execution e security ao arquivo config.yaml. Consulte Parâmetros de configuração para mais detalhes.
Controlar a sandbox usando a CLI (--sandbox): é possível ativar ou desativar explicitamente a sandbox para uma única execução transmitindo --sandbox=true ou --sandbox=false para cm find, cm verify ou cm fix.
Ignorar o isolamento usando a CLI (--unrestricted): é possível ignorar temporariamente todas as proteções da sandbox em uma única execução transmitindo a flag --unrestricted. Isso desativa os limites do caminho do sistema de arquivos (permitindo que o agente acesse qualquer caminho no host) e desativa completamente o isolamento do contêiner no nível do SO (incluindo o isolamento de rede).

Como escolher um nível de isolamento

Dependendo dos seus requisitos de segurança e ambiente de desenvolvimento, escolha o nível de isolamento adequado para executar a CLI do CodeMender.

Método	Descrição	Vantagens	Desvantagens
Sandbox integrado (no nível do SO)	Ativado por padrão. É possível desativar no arquivo `config.yaml` ou ignorar usando flags da CLI. Usa recursos integrados do SO (namespaces/seccomp, `sandbox-exec`, `AppContainer` [experimental]) para isolar a execução.	Leve, sem sobrecarga de inicialização e com acesso direto às ferramentas do espaço de trabalho local com controle refinado. Recomendado para desenvolvimento local diário.	A segurança depende dos recursos do kernel do SO. É menos isolada do que uma VM completa. O suporte do Windows é experimental e pode exigir privilégios administrativos ou ser incompatível com algumas configurações.
Contêineres	Executar o agente em um contêiner (por exemplo, Docker).	Bom isolamento; ambiente padronizado.	Exige um ambiente de execução de contêineres, pode ser pesado e não permite interação direta com ferramentas na máquina local.
VMs completas	Executar o agente em uma VM dedicada.	Segurança máxima; isolamento total.	Alto consumo de recursos, inicialização lenta e não permite interação direta com ferramentas na máquina local.

Telemetria

Para nos ajudar a monitorar e melhorar a integridade do produto, coletamos dados de telemetria anônimos pela CLI. Tornamos anônimos todos os dados coletados, incluindo métricas básicas de uso e diagnósticos de desempenho. A telemetria nunca coleta nem transmite código-fonte, conteúdo de arquivos, descobertas, patches ou identidades de usuários.

Por padrão, a telemetria está ativada. Se quiser desativar a telemetria, defina a variável de ambiente CM_TELEMETRY_OPT_OUT como 1 ou true.

Como atualizar a CLI

O CodeMender tem um mecanismo de atualização integrado para garantir que você esteja executando a versão mais recente da CLI.

Verificações automáticas de atualizações

Por padrão, a CLI do CodeMender verifica automaticamente se há atualizações em segundo plano quando você executa comandos:

Limitação: para minimizar a sobrecarga, a verificação automática é executada no máximo uma vez a cada 24 horas.
Terminal interativo (TTY) obrigatório: a CLI só verifica atualizações e solicita quando executada em um terminal interativo. Em ambientes não interativos (como pipelines ou scripts de CI/CD), a verificação é ignorada, e um aviso é registrado em stderr no máximo uma vez por dia.
Solicitação: se uma nova versão estiver disponível, você vai receber uma solicitação em stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Se você escolher "Sim" (y ou yes), o CodeMender vai baixar a atualização, substituir o binário e sair. Execute o comando novamente para usar a nova versão. Se você escolher "Não", a atualização será ignorada e o comando original será executado.
Tolerância a falhas off-line: se você estiver off-line ou o repositório de lançamento estiver inacessível, a verificação vai falhar silenciosamente, e o CodeMender vai continuar executando seu comando.
Ignorar: é possível ignorar a verificação automática de atualizações transmitindo a flag --yes ou -y para qualquer comando.

Atualizações manuais (`cm update`)

Para forçar o CodeMender a verificar e aplicar atualizações imediatamente, execute o comando update:

cm update

O comando cm update:

Ignora a limitação de 24 horas.
Faz o download e aplica a atualização imediatamente sem solicitação (não interativo).
Não requer um terminal interativo (seguro para scripts e gerenciamento de configuração).

Se a CLI estiver instalada em um diretório do sistema que exige permissões elevadas, execute a atualização com sudo:

sudo cm update

Instalar e configurar a CLI Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Arquitetura e modelo de segurança

configuração do ambiente

Configuração do projeto e permissões do IAM

APIs necessárias

Papel predefinido recomendado do IAM

Baixar e instalar a CLI do CodeMender

Linux x86_64

Linux ARM64

macOS Intel

macOS Apple Silicon

Windows x86_64

Windows ARM64

Configurar credenciais do Google Cloud

Inicializar o espaço de trabalho

Parâmetros de configuração (config.yaml)

Uso

Configurações padrão principais

Sandbox de execução

Comportamento do sandbox

Acesso à rede durante a criação e validação

Como processar dependências de rede

Configuração do sandbox

Como escolher um nível de isolamento

Telemetria

Como atualizar a CLI

Verificações automáticas de atualizações

Atualizações manuais (cm update)

Instalar e configurar a CLI

Parâmetros de configuração (`config.yaml`)

Atualizações manuais (`cm update`)