Para governar agentes de código, torne o fluxo de desenvolvimento autorizado testável: identifique quem e o que pode agir, configure políticas nos pontos de controle disponíveis, verifique o comportamento em operações delimitadas e forneça evidências úteis à operação. Uma implantação só está pronta para se expandir quando seu responsável consegue identificar quais caminhos foram avaliados, o que cada controle realmente fez e quem trata exceções ou evidências ausentes.
O pilar de governança de agentes de código define os requisitos para o trabalho de desenvolvimento delegado. Este guia transforma esses requisitos em um piloto com critérios explícitos de aceite. Todo o exemplo é um desenho hipotético de teste, não um experimento concluído nem uma receita de integração da KonaSense.
Inventarie a superfície de agentes de código
Escolha uma equipe, um repositório de teste descartável e uma tarefa restrita: gerar uma nota de documentação a partir de arquivos de código sintéticos e enviá-la a um receptor simulado executado localmente. O receptor proposto apenas registraria localmente notas de fixture com identificadores, sem publicação externa nem ação de negócio. Esse desenho não exige credenciais reais ou conteúdo sensível de repositório.
Liste como a equipe poderia realizar essa tarefa. Examine separadamente as ferramentas habilitadas no editor, o agente de terminal e qualquer caminho de execução remota. Para cada caminho, registre a implementação e a versão, onde executa, como está configurado, as operações que expõe e a pessoa responsável por sua instalação. Inclua ferramentas alcançadas indiretamente, como uma solicitação de build que inicia trabalho sob outra identidade.
Escolha quais caminhos o piloto vai exercitar. Se o piloto incluir a integração do editor, mas a equipe souber apenas da existência de um runner remoto, marque esse runner como fora do piloto. Se suas permissões ou observações estiverem indisponíveis, registre também essa incerteza. Uma entrada no inventário não comprova monitoramento ou controle; a ausência de uma superfície na lista não é evidência de que ninguém a utiliza.
O resultado desta etapa é um inventário delimitado que a liderança da equipe e o responsável pela plataforma consigam conferir com a configuração real. Resolva as diferenças antes de usá-lo como denominador de uma afirmação sobre cobertura.
Identifique usuários, ambientes e responsáveis
Associe o solicitante humano, a sessão do agente e a identidade de execução de cada caminho selecionado. Use identidades de teste quando o piloto precisar de comportamento autenticado. Registre qual revisão do repositório, workspace, configuração de runner e receptor local pertencem ao caso. Evite identificar um ambiente apenas por um nome de exibição que possa ser reutilizado.
Atribua decisões a pessoas capazes de agir sobre elas. A liderança de desenvolvimento responde pela tarefa permitida e pela utilidade do fluxo de trabalho. O responsável pela plataforma controla o executor e as restrições do ambiente. Security Engineering responde pelo comportamento esperado das políticas e pelas evidências de validação. Um revisor designado decide as aprovações, e a liderança do SOC responde pela fila de recebimento e pelo procedimento de triagem. Uma pessoa pode acumular papéis; nenhuma decisão necessária deve ficar sem responsável.
Defina uma condição concreta de interrupção para esses responsáveis. Por exemplo, se o piloto alcançar um recurso excluído por política, o responsável pela plataforma deve poder pausar o caminho de teste afetado enquanto Security Engineering investiga. Acorde quem pode autorizar essa pausa e como a equipe vai verificá-la. Um nome de contato sem uma ação disponível deixa a passagem para a operação incompleta.
Estabeleça as permissões que a tarefa realmente recebe
Para cada executor, examine acesso a arquivos, recursos montados, programas disponíveis, destinos de rede e mecanismos de credenciais. Compare essas permissões com a tarefa de documentação sintética. A necessidade de ler código de fixture e escrever uma nota não justifica acesso a um repositório não relacionado, uma credencial de release ou um destino externo de publicação.
Use a configuração do próprio ambiente e inspeções adequadas em modo somente leitura para estabelecer as permissões efetivas. Um prompt que diz “use apenas este diretório” documenta uma instrução; não estabelece uma restrição do processo. Resolva divergências restringindo o ambiente ou alterando explicitamente o escopo aprovado do piloto antes de prosseguir.
Registre referências da configuração junto à operação permitida. Se um script, servidor de ferramentas, identidade ou runner mudar, o resultado anterior pode deixar de descrever o caminho em teste. Esse registro permite ao responsável pela plataforma identificar qual validação precisa ser repetida, sem reconstruir todo o piloto a cada edição não relacionada.
Observe prompts e sessões quando for tecnicamente possível
Determine quais sinais de sessão a implementação selecionada pode fornecer. A solicitação de tarefa, o início da sessão, a referência ao prompt e a mensagem de conclusão podem vir de mecanismos diferentes ou estar indisponíveis. Teste as observações disponíveis com a tarefa sintética antes de descrevê-las como parte da visibilidade do piloto.
Escolha o que o piloto precisa reter. Uma referência à entrada fixa de fixture pode estabelecer o contexto do teste sem armazenar cada prompt ou arquivo de código. Se o conteúdo sintético completo for necessário para depurar um caso, atribua a essa captura uma finalidade explícita, uma política de acesso e um prazo de retenção. Não deixe que um exercício bem-sucedido com fixtures autorize silenciosamente a coleta de conteúdo equivalente em sessões reais de desenvolvedores.
O responsável pelas evidências deve conseguir distinguir uma sessão observada, um sinal não suportado, uma falha de coleta e um caminho que não foi avaliado. Uma tela de atividade vazia não resolve esses estados. Mantenha a observação ausente vinculada à sua superfície e ao responsável, para que a lacuna possa ser tratada.
Acompanhe solicitações de ferramentas pelo caminho de execução selecionado
Antes de testar uma política, torne o caminho benigno observável. No desenho do receptor local, associe à nota sintética identificadores únicos de caso e tentativa. Prepare observações na solicitação de ferramenta proposta, no ponto de envio do executor e no receptor. Estabeleça qual fonte registra cada evento e se o registro descreve uma solicitação, um envio ou um recebimento.
Exercite um caso de fixture permitido para verificar se o caminho de observação consegue capturar os identificadores e o resultado local do receptor. Se os registros não puderem ser associados de forma confiável, corrija a instrumentação do piloto antes de tirar conclusões de um caso negado.
Documente qualquer transformação entre a solicitação e o envio, incluindo argumentos alterados ou um executor remoto. O guia de arquitetura oferece o modelo de componentes para esse mapeamento. O piloto precisa do caminho real das ferramentas instaladas, não de um diagrama presumido como representação de todo IDE ou runner.
Defina políticas em termos que o piloto possa avaliar
Escreva o comportamento esperado da política antes de executar os casos. Neste desenho hipotético, o receptor possui três destinos de fixture: uma área de rascunho permitida para a tarefa, uma área de revisão que exige aprovação designada e uma área excluída que não deve receber a nota pelo caminho controlado. As três continuam sendo fixtures locais inofensivas. Elas representam condições distintas de autorização sem exercitar uma operação sensível real.
Para cada regra, identifique a identidade que age, a operação, o destino e a evidência de escopo da tarefa da qual ela depende. Separe a permissão rotineira de uma exceção. O desenvolvedor deve conseguir concluir o fluxo aprovado de rascunho sem uma nova decisão manual a cada edição; uma solicitação para usar a área de revisão deve explicitar a condição adicional.
Documente o que acontece quando o contexto necessário ou o avaliador está indisponível. A organização pode exigir que a solicitação afetada permaneça retida ou aceitar um período delimitado de observação com continuidade da execução. São políticas diferentes. Se o mecanismo instalado não consegue implementar o comportamento exigido, altere o mecanismo, reduza o escopo do piloto ou registre uma limitação aprovada. Não apresente continuidade da execução como bloqueio demonstrado.
Mantenha juntos as definições dos casos, as entradas de fixture, a configuração e o método de avaliação. O NIST AI RMF Playbook MEASURE 2.1 orienta documentar conjuntos de teste, métricas e ferramentas usados em teste, avaliação, validação e verificação. Esse registro ajuda outro revisor a repetir a avaliação e compreender os limites do resultado. NIST MEASURE 2.1, em inglês.
Valide controles de pré-execução onde forem suportados
Identifique o ponto capaz de impedir o envio da solicitação selecionada. Confirme como o host instalado recebe e aplica a resposta desse ponto. Uma política cadastrada na interface de administração não estabelece que o editor, o agente de terminal ou o executor remoto a consulte.
Use a tabela a seguir como plano de validação do receptor sintético. Ela apresenta comportamento esperado e evidências a buscar, não resultados medidos. Escolha a política de falha antes de testá-la.
| Caso | Comportamento esperado no piloto | Evidência necessária para avaliá-lo |
|---|---|---|
| Destino de rascunho permitido | A solicitação autorizada pode ser enviada | Solicitação, decisão, envio e resultado do receptor correlacionados |
| Destino de fixture excluído | A solicitação é interrompida antes do envio pelo caminho controlado | Negativa aplicada, observação do executor e observação completa do receptor para aquela tentativa |
| Aprovação necessária, nenhuma concedida | A solicitação permanece pendente | Estado pendente e ausência de envio da solicitação pendente |
| Avaliador indisponível | Aplica-se a política de falha escolhida previamente | Falha simulada, comportamento real do executor e eventual atividade resultante no receptor |
| Caminho conhecido fora do controle | Seu comportamento é avaliado separadamente | Identidade do caminho e observação do receptor, sem inferir que o controle selecionado o governou |
Em um caso negado, verifique o observador além da decisão. Use um novo identificador de tentativa, estabeleça que a coleta está ativa e defina quando a tentativa terminou ou já não pode produzir um envio. Considere filas, novas tentativas e registros atrasados antes de encerrar a janela de observação. Combine a evidência do executor de que o envio foi impedido com a observação completa do receptor para aquele caso delimitado.
A ausência de recibo, isoladamente, é apenas silêncio. Se o observador parou, a correlação está ausente ou a solicitação ainda pode estar na fila, marque o resultado como desconhecido. Mesmo um caso bem instrumentado permite concluir algo sobre aquele caminho e aquela janela de observação, não sobre a inexistência de qualquer efeito em outras partes do ambiente.
Para a falha do avaliador, use um stub local ou um mecanismo de teste suportado no ambiente descartável. Não interrompa um serviço compartilhado para simular essa condição. Para o caminho fora do controle, use uma rota benigna declarada no teste; sua finalidade é revelar o limite de cobertura, não demonstrar uma exploração.
A orientação de autorização da OWASP recomenda testar a lógica de autorização e verificar o comportamento em falhas. Isso sustenta a avaliação de condições normais e anormais, enquanto um piloto pequeno ainda deixa comportamentos sem teste. OWASP Authorization Cheat Sheet, em inglês. Use os contratos mais detalhados de decisão e falha da governança de IA em runtime como referência ao interpretar divergências.
Transforme a aprovação em uma etapa operacional testável
Use a fixture de revisão para testar o encaminhamento a uma pessoa autorizada. O revisor deve ver a operação proposta, o destino, a referência ao conteúdo relevante, a identidade que age e o motivo pelo qual a solicitação excede a permissão rotineira de rascunho. A afirmação do agente de que houve aprovação não substitui o registro do mecanismo de aprovação.
Comece sem aprovação e confirme o comportamento de pendência. Depois planeje casos separados para rejeição e aprovação aplicável. Antes de uma solicitação retida prosseguir, verifique se a aprovação ainda se aplica à identidade, ao alvo, aos argumentos e às condições daquela solicitação. Mudar o destino da fixture não deve reutilizar silenciosamente a decisão da solicitação anterior.
Defina o que acontece quando o revisor está indisponível. O trabalho pode continuar pendente ou seguir um processo de exceção explicitamente autorizado; esperar não é uma aprovação. No piloto, mantenha esses desfechos locais e benignos. Operações de maior impacto em produção precisam de sua própria avaliação de risco e autorização, em vez de serem usadas como casos de teste convenientes.
Registre evidências que um revisor consiga conferir
Em cada caso, preserve o comportamento esperado separadamente do que foi observado. Relacione a tarefa e a configuração aprovadas à tentativa, à decisão, à resposta aplicada e à observação do receptor. Se o caso divergir da expectativa, registre a divergência e seu responsável, em vez de transformar o resultado esperado em um status de sucesso.
A orientação de logging da OWASP enfatiza atributos de evento com finalidade definida, correlação de interações, exclusão de valores sensíveis e verificação do próprio mecanismo de logging. Use essa orientação para tornar o registro interpretável sem coletar conteúdo irrestrito. OWASP Logging Cheat Sheet, em inglês.
Neste piloto, o revisor precisa do destino da fixture e da referência à nota, não de uma credencial real ou de um arquivo de código privado do desenvolvedor. Preserve o significado original de cada estado ao combinar registros. Um Allow do avaliador não é o sucesso do receptor, e um recibo não estabelece que uma ação externa de negócio solicitada ocorreu. O receptor simulado não possui esse tipo de ação de negócio para reportar.
Peça a um revisor que não configurou o caso que o reconstrua a partir do registro. Ele consegue identificar qual caminho instalado foi testado, o que era esperado, o que realmente aconteceu e o que continua sem resolução? Se a resposta depender da memória de quem implementou, melhore o conjunto de evidências antes de ampliar a implantação.
Entregue as evidências à operação de SOC e SIEM
Acorde com a equipe do SOC o contrato do evento operacional antes de adicionar um alerta. No piloto, o evento deve identificar o caso ou a tarefa, o caminho de execução, a identidade relevante, a decisão de política, o resultado observado e as evidências ainda sem resolução. Decida onde ele será entregue, quem poderá acessá-lo e como o analista chegará ao registro de origem. O transporte e a integração precisam ser selecionados e verificados para os sistemas reais envolvidos.
Envie um evento sintético pela rota de teste aprovada e compare o registro de origem com o que o sistema receptor exibe. Confirme que a normalização preserva distinções como negado, pendente, avaliação indisponível e resultado desconhecido. O recebimento em um SIEM comprova a entrega por aquele caminho; não comprova a aplicação do controle pelo host do agente.
Defina respostas diferentes para cada tipo de achado. Um caso rotineiro de fixture negada pode ser mantido como evidência de validação. Um resultado inesperado no receptor exige investigação pelo responsável pelo controle. Uma observação ausente exige acompanhamento pelo responsável pela telemetria. Se um incidente operacional justificar contenção, identifique a ação autorizada e como seu efeito será confirmado; a entrega de um alerta não é contenção.
Planeje também a interrupção do fluxo de evidências. A liderança do SOC e o responsável pela plataforma devem acordar como reconhecer a ausência de eventos de teste esperados, identificar os caminhos afetados e decidir se eles podem continuar sob a política operacional aprovada. Um painel sem atividade não deve ser o único sinal de que a coleta parou.
Antes de incluir outra equipe ou executor, peça aos responsáveis que revisem os registros dos casos concluídos, as lacunas não resolvidas, o impacto sobre os desenvolvedores e a prontidão da triagem. Declare exatamente qual configuração e qual fluxo de trabalho estão aceitando. Uma nova ferramenta, identidade de runner ou destino exige avaliar as condições alteradas; os resultados da primeira equipe não estabelecem cobertura de toda a empresa.
Avalie a integração da KonaSense dentro deste piloto
O adaptador Claude Code PreToolUse revisado para o Kona for Agents oferece um caminho específico para avaliar uma operação de ferramenta proposta e construir uma negativa, um pedido de aprovação ao usuário ou argumentos alterados. Erros de avaliação retornam Allow. O tratamento dessa resposta pelo host instalado precisa ser verificado separadamente.
Esse caminho pode ser objeto da avaliação do piloto. Ele não estabelece o receptor hipotético, um conector SOC/SIEM, isolamento de processo ou controle de cada subprocesso e runner remoto. Selecione casos de validação compatíveis com a integração e seu comportamento real em falhas, e mantenha os caminhos não verificados visíveis na decisão de ampliar a implantação.