Gerenciar sessões e exportar relatórios

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 report

Relató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 por severity (padrão) ou time. 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 OPEN sã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 DISMISSED silencia alertas futuros e exclui a descoberta da saída ativa da CLI com cm report --status OPEN. A nova execução de cm verify em uma descoberta dispensada reexamina ou restaura os itens dispensados.
  • REOPENED
    • O que significa: uma vulnerabilidade que foi marcada anteriormente como FIXED ou DISMISSED foi 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.

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ão 168h ou 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 workers cm find --deep e cm find --diff.
    cm stats --session SESSION_ID_PREFIX
  • Exportar JSON (--json e --jsonl): emita JSON recuado com --json ou emita JSON de linha única com --jsonl para ingestão de registros estruturados. A saída JSON inclui model (ou models quando vários modelos aparecem) e team_id (ou team_ids quando 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-id ou CM_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 ambiente CM_TEAM_ID ou team_id em ~/.codemender/config.yaml. As sessões executadas sem uma equipe configurada permanecem sem atribuição na saída JSON cm stats. Quando a janela consultada não tem registros de sessão, --team-id, CM_TEAM_ID ou config.yaml fornece o rótulo team_id de 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