O CodeMender rastreia cada verificação, validação e tentativa de correção como uma sessão com estado, apoiada por um banco de dados SQLite local (state.db). É possível inspecionar sessões ativas, retomar tarefas pausadas e exportar relatórios detalhados de descobertas.
Gerenciamento de sessões
A CLI do CodeMender mantém sessões de execução com estado localmente, permitindo que você acompanhe tarefas ativas, retome fluxos de trabalho interrompidos e exporte relatórios de segurança.
Listar sessões ativas e anteriores
Execute o comando a seguir para listar todas as sessões, os status delas (RUNNING, WAITING_FOR_TOOL, COMPLETED, FAILED, CANCELLED, BUDGET_EXCEEDED) e os caminhos de destino:
cm session list
Retomar uma sessão interrompida
Se uma sessão for pausada devido a uma interrupção de rede ou falha de etapa, retome-a na última etapa do checkpoint:
cm session resume SESSION_ID
É possível transmitir --yes (-y), --duration (--timeout), --sandbox, --allow-all-paths, --allow-all-commands e --bypass-warning para cm session resume para controlar as solicitações de confirmação, os limites de duração da execução, o sandbox e os limites de política para a execução retomada. As sessões que terminam com COMPLETED, FAILED, CANCELLED ou BUDGET_EXCEEDED são terminais e não podem ser retomadas.
Cancelar uma sessão em execução
Para encerrar uma sessão ativa e interromper a execução da computação do agente de back-end:
cm session cancel SESSION_ID
Ver relatórios e exportar patches
Exiba as descobertas da sessão, os status de verificação e os detalhes do patch usando cm report.
Formatos de saída
Tabela de terminal (padrão)
Lista resumida de descobertas.
cm reportRelatório HTML
Gerar um relatório HTML formatado. Use --open (ou -o) para iniciar automaticamente no navegador padrão.
cm report --format html --open
Markdown
Gera um relatório Markdown no estilo do GitHub.
cm report --format md
JSON
Exportar todos os detalhes das descobertas da sessão como JSON bruto.
cm report --format json
SARIF
Exporte as descobertas no formato SARIF padrão (v2.1.0) para integração com outras ferramentas de segurança.
cm report --format sarif
CSV
Exporte as descobertas como valores separados por vírgulas (CSV) para usar em planilhas. Para evitar que uma planilha execute uma célula como uma fórmula, as células que começam com =, +, - ou @ recebem um prefixo de aspas simples.
cm report --format csv
Sinalizações de filtragem e classificação
- Mostrar patches de código propostos (
--patches): inclua diffs unificados completos das correções geradas no relatório.bash cm report --patches - Filtrar por gravidade (
--severity): veja as descobertas que correspondem a um nível (CRITICAL,HIGH,MEDIUM,LOW).bash cm report --severity HIGH - Filtrar por status (
--status): veja as descobertas que correspondem a um estado (OPEN,FIXED,DISMISSED,REOPENED).bash cm report --status OPEN - Filtrar por sessão (
--session): confira as descobertas de um prefixo de ID de sessão específico.cm report --session SESSION_ID_PREFIX
- Mostrar artefatos do agente (
--artifacts): inclua caminhos para artefatos de execução gerados pelo agente (como registros, scripts de exploit).bash cm report --artifacts - Classificar descobertas (
--sort): classifique os resultados porseverity(padrão) outime.bash cm report --sort time - Filtrar por ID da descoberta: transmita um ID (ou prefixo) de descoberta específico como um argumento posicional para ver detalhes de uma única descoberta.
cm report FINDING_ID_PREFIX
Estados de descoberta de vulnerabilidades
O CodeMender rastreia as descobertas nos seguintes estados de vulnerabilidade:
OPEN- O que significa: a vulnerabilidade foi detectada durante uma verificação (ou importada de uma ferramenta de terceiros), mas ainda não foi verificada, corrigida ou marcada como inativa.
- Como é tratada: esse é o estado inicial de qualquer falha de segurança recém-descoberta. As vulnerabilidades no estado
OPENsão colocadas ativamente na fila para verificação (cm verify) ou aplicação de patch (cm fix).
FIXED- O que isso significa: o CodeMender gerou um patch para a vulnerabilidade, aplicou o diff à base de código local e compilou e executou com sucesso testes de verificação para provar que o exploit não funciona mais.
- Como é tratado: depois que um patch é confirmado para resolver o problema
sem quebrar a lógica do código atual, o CodeMender faz a transição da descoberta
para
FIXED. Ele vai permanecer nesse estado, a menos que uma verificação futura detecte uma regressão.
DISMISSED- O que isso significa: a vulnerabilidade é designada como inativa, porque foi identificada como um falso positivo ou já foi corrigida, ou a descoberta não tem confiança suficiente para confirmar como explorável (incluindo contra o modelo de ameaças do seu projeto, se um tiver sido fornecido durante a integração).
- Como é tratado: marcar um item como
DISMISSEDsilencia alertas futuros e exclui a descoberta da saída ativa da CLI comcm report --status OPEN. A nova execução decm verifyem uma descoberta dispensada reexamina ou restaura os itens dispensados.
REOPENED- O que significa: uma vulnerabilidade que foi marcada anteriormente como
FIXEDouDISMISSEDfoi detectada novamente em uma verificação subsequente da base de código. - Como é tratado: esse estado indica uma regressão (como uma mesclagem de git incorreta que reverte o patch) ou uma estratégia de mitigação com falha. Ele sinaliza o problema para reavaliação imediata e exige que os desenvolvedores revisem o processo de aplicação de patches.
- O que significa: uma vulnerabilidade que foi marcada anteriormente como
Níveis de gravidade de vulnerabilidade
O CodeMender categoriza as descobertas nos seguintes níveis de gravidade:
CRITICAL- O que significa: a vulnerabilidade representa um risco imediato e grave para o aplicativo ou a infraestrutura subjacente, o que pode levar ao comprometimento total do sistema.
- Por que é categorizada como crítica: ela atende aos limites de impacto de alta consequência (como execução remota de código ou gravações no nível raiz), é diretamente acessível de limites não confiáveis sem pré-requisitos e é respaldada por uma análise de fluxo de contaminação de alta confiança ou uma prova de conceito (PoC) validada executada no sandbox do CodeMender.
HIGH- O que isso significa: a vulnerabilidade representa uma falha de segurança grave que pode levar ao controle não autorizado do sistema, ao escalonamento de privilégios ou à exposição significativa de dados, mas requer condições específicas para ser executada.
- Por que é categorizado como alto: embora o impacto da exploração seja alto (por exemplo, leituras arbitrárias de banco de dados ou sequestro administrativo), a capacidade de exploração é um pouco restrita. Pode exigir que um invasor tenha autenticação de usuário padrão, dependa de uma configuração de sistema específica ou exija uma cadeia de ações altamente precisa.
MEDIUM- O que significa: a vulnerabilidade apresenta um risco moderado, geralmente expondo dados restritos ou permitindo interrupções localizadas, mas é de baixo risco para o sistema host.
- Por que é categorizada como média: a exploração é fortemente limitada por acessibilidade ou complexidade. Geralmente, ela requer interação ativa do usuário (como clicar em um link mal-intencionado), privilégios profundos ou condições complexas para ignorar as camadas de defesa, e a área afetada final é restrita.
LOW- O que significa: a descoberta representa um risco de segurança menor ou uma falta geral de higiene de defesa em profundidade que não apresenta uma ameaça imediata por si só.
- Por que é categorizada como baixa: ela apresenta uma capacidade de exploração extremamente baixa ou um impacto mínimo. A descoberta normalmente é usada por invasores para reconhecimento ou impressão digital de configuração, em vez de comprometimento direto, e não pode ser usada para executar código arbitrário ou exfiltrar dados sensíveis do aplicativo.
Monitorar o uso de tokens
O CodeMender grava registros de sessão por invocação localmente em
~/.codemender/logs/sessions/. Use cm stats para inspecionar o uso de tokens off-line,
as taxas de ocorrência em cache, as contagens de sondagem e as durações de execução em comandos ou em uma
sessão individual sem fazer chamadas de back-end.
- Resumir atividade recente (
--since): confira o uso de tokens agrupado por tipo de comando em uma janela recente (padrão168hou 7 dias).bash cm stats cm stats --since 24h - Inspecionar uma sessão específica (
--session): confira o uso de tokens por turno para um ID de sessão ou prefixo de ID de sessão exclusivo, incluindo execuções de vários workerscm find --deepecm find --diff.cm stats --session SESSION_ID_PREFIX
- Exportar JSON (
--jsone--jsonl): emita JSON recuado com--jsonou emita JSON de linha única com--jsonlpara ingestão de registros estruturados. A saída JSON incluimodel(oumodelsquando vários modelos aparecem) eteam_id(outeam_idsquando várias equipes são agregadas).cm stats --json cm stats --jsonl cm stats --session SESSION_ID_PREFIX --jsonl
- Atribuir o uso por equipe (
--team-idouCM_TEAM_ID): defina um identificador de equipe (de 1 a 63 caracteres correspondentes a[A-Za-z0-9._-]) ao executar verificações ou correções com a flag--team-id, a variável de ambienteCM_TEAM_IDouteam_idem~/.codemender/config.yaml. As sessões executadas sem uma equipe configurada permanecem sem atribuição na saída JSONcm stats. Quando a janela consultada não tem registros de sessão,--team-id,CM_TEAM_IDouconfig.yamlfornece o rótuloteam_idde nível superior.CM_TEAM_ID=TEAM_ID cm find . cm stats --jsonl
Para jobs do Cloud Run e etapas do Cloud Build em que os arquivos de registro locais não são mantidos, consulte Exportar telemetria de token para o Cloud Logging.
Coletar dados de diagnóstico para o suporte
Se você entrar em contato com o suporte sobre um problema com o CodeMender, execute
cm support-bundle para coletar os dados de diagnóstico necessários em um
único arquivo .tar.gz. O comando lê arquivos locais e verifica suas
credenciais, configuração e conexão com o CodeMender. Ele não faz upload de nada: você analisa o arquivo e o anexa ao caso de suporte.
Para coletar dados de sessões específicas, transmita os IDs ou prefixos de ID delas. Para encontrar
IDs de sessão, execute cm session list. Você pode repetir --session:
cm support-bundle --session SESSION_ID
Sem --session, o comando coleta atividades das últimas 72 horas. Para
mudar a janela, use --since:
cm support-bundle --since 24h
O comando grava cm-support-bundle-TIMESTAMP.tar.gz no diretório atual e mostra o caminho dele. Para escolher o caminho, use --output (ou -o).
O que o arquivo contém
Por padrão, o arquivo deixa de fora o código-fonte, as diferenças e as entradas e saídas de ferramentas. Ele contém os seguintes itens:
- A versão da CLI, o sistema operacional e uma lista do que foi coletado.
- Variáveis de ambiente do
CM_*e configurações de projeto e proxy. - Os resultados das verificações de credenciais, configuração e conectividade.
- Seu arquivo de configuração e política de comando.
- O status, o modelo e o destino de cada sessão selecionada.
- Tempo por turno, uso de tokens e nomes e durações das chamadas de ferramentas.
Os dados da sessão ainda podem conter caminhos de arquivos e diretórios, os argumentos de cada
comando cm, títulos de descobertas e mensagens de erro da ferramenta.
Se o suporte pedir mais detalhes, adicione --include-content. Isso também coleta
descobertas, patches gerados e os registros de depuração da CLI, que registram os argumentos
de cada chamada de ferramenta. Esses arquivos podem conter código-fonte do seu repositório.
Por isso, revise o arquivo antes de compartilhá-lo.
cm support-bundle --session SESSION_ID --include-content
Em ambos os modos, o comando oculta tokens de acesso, chaves de API, chaves privadas, cabeçalhos de autorização e campos de senha.
Para pular as verificações de credenciais, configuração e conectividade, por exemplo, ao executar o comando sem acesso à rede, use --skip-health.
Manutenção do espaço de trabalho
Para redefinir os arquivos de rastreamento de estado local e limpar os caches de execução temporários, execute:
cm clean