Monitoramento em larga escala de código/espaço de trabalho compartilhado com Otel e Elastic

À medida que os assistentes de codificação de IA se tornam ferramentas padrão nos fluxos de trabalho de engenharia, as equipes de segurança enfrentam um novo desafio: como manter a visibilidade do que um agente de IA está fazendo (e por quê) em toda a organização? Quando esses agentes podem executar comandos de shell, ler arquivos, chamar APIs e interagir com sistemas internos por meio de conectores MCP, você precisa de observabilidade em tempo real para dar suporte à detecção de ameaças, resposta a incidentes e conformidade.

Este artigo descreve como a equipe de segurança da informação da Elastic construiu um pipeline de monitoramento para o Claude Code e o Claude Cowork usando seus recursos nativos de exportação do OpenTelemetry (OTel) e a infraestrutura de ingestão do OTel da própria Elastic. Abordamos o esquema de telemetria, a implementação do gateway, os mapeamentos personalizados do Elasticsearch e os pipelines de ingestão, a entrega de configuração gerenciada e os casos de uso de segurança possibilitados por esses dados.

Por que a equipe de segurança da informação da Elastic monitora agentes de IA?

Na Elastic, praticamos o que chamamos de "Cliente Zero". A equipe de segurança da informação é a primeira e mais exigente usuária dos produtos da Elastic, sempre utilizando as versões mais recentes em produção. Nosso objetivo é usar nossos próprios produtos para aprimorar nossa postura de segurança sempre que possível.

Claude Code e Cowork já estão em uso ativo em toda a organização de engenharia da Elastic. O Claude Code funciona localmente nas máquinas dos desenvolvedores como um assistente de codificação com IA baseado em linha de comando. O Cowork faz parte do aplicativo Claude Desktop e também funciona localmente. Ele pode ler arquivos, executar código em um ambiente isolado (sandbox), pesquisar na web e interagir com serviços conectados como Slack, GitHub, Jira e Google Calendar por meio de conectores MCP. Ambas as ferramentas suportam a conexão com sistemas internos, o que significa que operam dentro de um limite de confiança que as equipes de segurança precisam monitorar.

O que Claude Code e Cowork exportam via OpenTelemetry

Ambos os produtos exportam telemetria através de protocolos OpenTelemetry padrão, emitindo os mesmos cinco tipos de eventos:

api_request — modelo, custo, contagem de tokens, latência
tool_result — nome da ferramenta, servidor MCP e nome da ferramenta, sucesso/falha, duração
tool_decision — aprovado automaticamente vs aprovado pelo usuário
user_prompt — o que o usuário pediu ao agente para fazer
api_error — mensagem de erro, código de status

Cada evento inclui a identidade do usuário (user.email, organization.id), o contexto da sessão (session.id, prompt.id, event.sequence) e os campos de custo/token nos eventos de solicitação de API. A telemetria do Claude Code é opcional e oculta prompts e argumentos de ferramentas por padrão; habilite-os com OTEL_LOG_USER_PROMPTS=1 e OTEL_LOG_TOOL_DETAILS=1. O coworking é configurado centralmente no portal de administração da Anthropic e inclui automaticamente todos os detalhes.

Para obter o esquema completo de telemetria, consulte a documentação de Monitoramento de Código Claude e a documentação de Monitoramento de Coworking Claude.

Arquitetura: Obtendo os dados no Elasticsearch

Existem duas maneiras de inserir dados do Claude Code e do Cowork OTel no Elasticsearch. Implementamos primeiro a abordagem de gateway autogerenciado, mas os usuários do Elastic Cloud têm uma opção mais simples.

Opção 1: Gateway EDOT OTel (autogerenciado)

Essa é a abordagem que usamos internamente. Como a equipe de segurança da informação da Elastic executa clusters ECK (Elastic Cloud on Kubernetes) autogerenciados, implantamos uma Distribuição Elastic do Coletor OpenTelemetry (EDOT) como gateway. Tanto o Claude Code quanto o Cowork são executados localmente nas máquinas dos usuários e enviam OTLP/HTTP para o gateway, que autentica a solicitação e grava no Elasticsearch.

Usamos o gráfico Helm opentelemetry-collector com a imagem do coletor EDOT (docker.elastic.co/elastic-agent/elastic-otel-collector). A imagem EDOT fornece roteamento nativo de fluxo de dados Elastic, o que é importante para direcionar os logs para os fluxos de dados corretos sem configuração adicional.

O gateway é executado no modo de implantação e usa autenticação de token de portador por meio da extensãobearertokenauth .

Aqui está a configuração principal do coletor:

config:
  extensions:
    bearertokenauth:
      scheme: "Bearer"
      token: "${env:OTEL_GATEWAY_TOKEN}"
  receivers:
    otlp:
      protocols:
        http:
          endpoint: "0.0.0.0:4318"
          auth:
            authenticator: bearertokenauth
  processors:
    transform/route:
      log_statements:
        - context: log
          conditions:
            - resource.attributes["service.name"] == "claude-code"
          statements:
            - set(resource.attributes["data_stream.dataset"], "claude_code")
        - context: log
          conditions:
            - resource.attributes["service.name"] == "cowork"
          statements:
            - set(resource.attributes["data_stream.dataset"], "claude_cowork")
  exporters:
    elasticsearch:
      endpoints: ["https://your-elasticsearch:9200"]
      user: "${env:ES_USERNAME}"
      password: "${env:ES_PASSWORD}"
  service:
    extensions: [bearertokenauth]
    pipelines:
      logs:
        receivers: [otlp]
        processors: [transform/route]
        exporters: [elasticsearch]

Opção 2: Endpoint OTLP gerenciado na nuvem elástica (sem necessidade de gateway)

Se você estiver executando o Elastic Cloud (Serverless ou Hosted), poderá ignorar completamente o gateway. O endpoint Managed OTLP (mOTLP) da Elastic fornece uma camada de ingestão resiliente e com escalonamento automático que aceita dados OTLP diretamente — sem necessidade de implantar ou manter infraestrutura de coleta.

Para utilizá-lo, aponte o exportador OTLP de Claude Code diretamente para o seu endpoint mOTLP do Elastic Cloud:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<your-motlp-endpoint>"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey <your-api-key>"
export OTEL_RESOURCE_ATTRIBUTES="data_stream.dataset=claude_code"

O atributo de recurso data_stream.dataset é importante aqui; ele controla qual fluxo de dados recebe os registros. Sem isso, os dados chegam a um fluxo de dados genérico da OTel, onde seus modelos de índice personalizados e pipelines de ingestão não serão aplicados. Defina como claude_code ou claude_cowork para que os dados sejam encaminhados para os fluxos dedicados logs-claude_code.otel-* ou logs-claude_cowork.otel-* com os mapeamentos de campo corretos.

Com o mOTLP, você obtém ingestão OTLP nativa com roteamento automático de fluxo de dados, um armazenamento de falhas integrado para proteger os dados durante problemas de indexação e nenhuma exigência de servidor APM.

O endpoint gerenciado oferece suporte a todos os mesmos modelos de índice personalizados e pipelines de ingestão descritos abaixo; você simplesmente não precisa operar o gateway.

Para obter detalhes completos sobre a configuração, consulte a documentação do Elastic Cloud Managed OTLP.

Mapeamentos e pipelines de ingestão personalizados do Elasticsearch

Por padrão, os atributos OTel são indexados como palavras-chave no Elasticsearch. Isso funciona para filtragem e agrupamento, mas quebra as agregações numéricas. Não é possível somar ou calcular a média de um campo de palavra-chave. Criamos mapeamentos personalizados para corrigir os tipos de campo e um pipeline de ingestão para analisar campos de string JSON e convertê-los em objetos estruturados.

Modelo de componente

O modelo de componente substitui os mapeamentos de palavras-chave padrão para campos numéricos e booleanos e adiciona mapeamentos do tipo flattened para os parâmetros da ferramenta codificados em JSON:

PUT _component_template/logs-claude_code.otel@custom
{
  "template": {
    "mappings": {
      "properties": {
        "cost_usd":                  { "type": "float" },
        "duration_ms":               { "type": "long" },
        "input_tokens":              { "type": "long" },
        "output_tokens":             { "type": "long" },
        "cache_creation_tokens":     { "type": "long" },
        "cache_read_tokens":         { "type": "long" },
        "prompt_length":             { "type": "long" },
        "tool_result_size_bytes":    { "type": "long" },
        "success":                   { "type": "boolean" },
        "tool_parameters_flattened": { "type": "flattened" },
        "tool_input_flattened":      { "type": "flattened" }
      }
    }
  }
}

O tipo flattened é importante aqui. tool_parameters e tool_input chegam como strings JSON contendo chaves aninhadas como mcp_server_name, mcp_tool_name, bash_command ou command. Ao analisá-los em campos flattened , você pode consultar chaves individuais sem criar um número ilimitado de campos mapeados.

Uma melhoria futura consistirá em extrair campos de alto valor desses payloads JSON para campos mapeados dedicados — como nomes de servidores MCP, nomes de ferramentas e comandos bash — para direcionar análises, agregações e regras de detecção mais ricas diretamente nesses valores.

Modelo de índice

O modelo de índice inclui todos os modelos de componentes padrão do OTel, além de um modelo personalizado. Corresponde tanto a logs-claude_code.otel-* quanto a logs-claude_cowork.otel-* , portanto, ambos os fluxos de dados compartilham os mesmos mapeamentos de campo:

PUT _index_template/logs-claude_code.otel
{
  "index_patterns": [
    "logs-claude_code.otel-*",
    "logs-claude_cowork.otel-*"
  ],
  "composed_of": [
    "logs@mappings",
    "logs@settings",
    "otel@mappings",
    "otel@settings",
    "logs-otel@mappings",
    "semconv-resource-to-ecs@mappings",
    "logs@custom",
    "logs-otel@custom",
    "logs-claude_code.otel@custom",
    "ecs@mappings"
  ],
  "priority": 150,
  "data_stream": {},
  "allow_auto_create": true,
  "ignore_missing_component_templates": [
    "logs@custom",
    "logs-otel@custom"
  ]
}

Pipeline de ingestão

O pipeline de ingestão analisa tool_parameters e tool_input de strings JSON em objetos, gravando em campos de destino *_flattened separados para evitar conflitos com os atributos originais mapeados por palavras-chave:

PUT _ingest/pipeline/logs-claude_code.otel@custom
{
  "description": "Parse JSON string fields in Claude Code/Cowork OTel telemetry",
  "processors": [
    {
      "json": {
        "field": "attributes.tool_parameters",
        "target_field": "tool_parameters_flattened",
        "if": "ctx.attributes?.tool_parameters != null && ctx.attributes.tool_parameters.startsWith('{')",
        "ignore_failure": true
      }
    },
    {
      "json": {
        "field": "attributes.tool_input",
        "target_field": "tool_input_flattened",
        "if": "ctx.attributes?.tool_input != null && ctx.attributes.tool_input.startsWith('{')",
        "ignore_failure": true
      }
    }
  ]
}

Após a criação dos três recursos, os novos dados que fluem para os fluxos de dados logs-claude_code.otel-* e logs-claude_cowork.otel-* terão tipos de campo numéricos corretos e parâmetros de ferramenta estruturados pesquisáveis.

Configurando a exportação de telemetria

Claude Code e Cowork são configurados de forma diferente. Claude Code utiliza variáveis de ambiente padrão do OpenTelemetry. A exportação do Cowork OTel é configurada centralmente pelos administradores no portal de administração da Anthropic.

O Claude Code suporta configurações gerenciadas que são implementadas pela equipe de TI e não podem ser alteradas pelos usuários. A configuração é um arquivo JSON contendo um bloco env :

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_LOG_USER_PROMPTS": "1",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://your-otel-gateway:443",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token"
  }
}

Este arquivo de configurações gerenciadas pode ser entregue via MDM (Jamf, Intune), configurações gerenciadas pelo servidor através do Console de Administração do Claude.ai ou implantação baseada em arquivo. Consulte a documentação de configurações gerenciadas do Claude Code para obter a lista completa de mecanismos de entrega e suas propriedades de segurança.

Para testes locais, você pode colocar a mesma configuração em ~/.claude/settings.json em sua própria máquina antes de implementá-la em toda a organização.

Espaço de coworking

A exportação do Cowork OTel é configurada centralmente pelos administradores no portal de administração da Anthropic. Os administradores definem o endpoint OTLP e os cabeçalhos de autenticação no console de administração, e as instâncias do Cowork detectam automaticamente a configuração. O conteúdo da solicitação e os detalhes da ferramenta são incluídos por padrão, sem a necessidade de sinalizadores adicionais.

Como o Cowork é executado em um ambiente de sandbox, o endpoint do gateway OTel deve ser adicionado à lista de permissões para acesso de rede de saída do ambiente de sandbox. Sem isso, a exportação de telemetria falhará silenciosamente.

casos de uso de segurança

A combinação de tipos de eventos, campos de identidade e parâmetros de ferramentas cria um conjunto de dados abrangente para operações de segurança. A seguir, apresentamos os casos de uso para os quais estamos desenvolvendo capacidades de detecção e investigação.

Auditoria de invocação de ferramentas. Cada chamada de ferramenta é registrada com o nome da ferramenta e os parâmetros de entrada. Para ferramentas MCP, isso inclui o nome do servidor MCP e o nome da ferramenta (por exemplo, slack_send_message, github/search_issues). Você pode detectar acessos não autorizados a dados, comandos de shell incomuns ou interações inesperadas com o servidor MCP. Use os campos attributes.tool_name + attributes.tool_parameters .

Reconstrução da sessão. O campo session.id combinado com event.sequence fornece um contador monotonicamente crescente dentro de cada sessão. É possível reconstruir a sequência completa de uma sessão do Claude: o que o usuário perguntou, quais ferramentas foram executadas, quais dados foram acessados e quais APIs foram chamadas. Isso é valioso para a resposta a incidentes — se você detectar uma chamada de ferramenta suspeita, poderá obter o contexto completo da sessão.

Análise da decisão de autorização. Os eventos attributes.event.name: tool_decision fornecem informações sobre como cada uso de ferramenta foi aprovado. Isso permite detectar usuários que aprovam automaticamente categorias de ferramentas de risco ou identificar padrões de permissão incomuns em toda a frota.

Fonte de decisão	Significado
`config`	Permitido automaticamente pelas configurações ou pela política.
`hook`	Decidido por um script de gancho configurado
`user_temporary`	O usuário clicou em aceitar para esta invocação.
`user_permanent`	O usuário clicou em "sempre permitir" para esta ferramenta.
`user_abort`	O usuário encerrou a sessão.
`user_reject`	O usuário rejeitou explicitamente o uso da ferramenta.

Detecção de anomalias de custos. O campo cost_usd em cada evento api_request permite o rastreamento de custos por solicitação, por sessão e por usuário. Você pode receber alertas sobre sessões com custos de processamento incomuns ou identificar usuários com padrões de consumo excessivos.

Correlação com dados EDR. Se você estiver executando o Elastic Defend em seus endpoints, poderá correlacionar a telemetria OTel de Claude com os eventos de processo e arquivo do EDR para entender o panorama completo. Quando Claude Code executa um comando Bash, o evento OTel tool_result informa o que o agente decidiu executar e por quê (através do user_prompt precedente). O evento de processo correspondente no Elastic Defend informa exatamente o que aconteceu no host — processos filhos criados, arquivos gravados, conexões de rede estabelecidas. A combinação dessas duas fontes de dados por carimbo de data/hora e host fornece tanto a intenção (da telemetria do agente de IA) quanto o impacto (da telemetria do endpoint) em uma única investigação.

Monitoramento de acesso ao servidor MCP. À medida que as organizações conectam agentes de IA a sistemas internos por meio do MCP, o monitoramento de quais servidores são acessados e com quais ferramentas torna-se crucial. Os campos tool_parameters_flattened.mcp_server_name e tool_parameters_flattened.mcp_tool_name fornecem essa visibilidade.

Por exemplo, para ver as invocações de ferramentas para o Slack, você pode consultar tool_name: "mcp_tool" AND tool_parameters_flattened.mcp_tool_name:slack*.

Além da OTel: Registros de auditoria empresarial da Claude

A telemetria da Claude Code e da Cowork abrange a atividade do agente nos endpoints, mas não captura tudo. Para obter visibilidade completa, as organizações também devem coletar os registros de auditoria corporativa do Claude por meio da API de Conformidade. Esta é a única fonte de atividade na interface web (claude.ai) e de eventos tradicionais de auditoria de segurança, como atividade de login, alterações de permissões e administração em nível organizacional. A combinação de ambas as fontes de dados oferece às equipes de segurança uma visão completa de todos os produtos da Claude.

Conclusão

Assistentes de programação com IA e agentes autônomos estão se tornando parte do conjunto de ferramentas padrão das empresas. Se sua equipe de segurança não tem visibilidade do que essas ferramentas estão fazendo, existe uma lacuna. O Claude Code e o Cowork são fornecidos com suporte ao OpenTelemetry, que oferece exatamente o tipo de telemetria que as equipes de segurança precisam: identidade, contexto da sessão, detalhes de invocação da ferramenta, dados de custo e decisões de permissão. Os recursos nativos de ingestão de OTel da Elastic, seja por meio do endpoint Managed OTLP no Elastic Cloud ou do EDOT Collector em um ambiente autogerenciado, facilitam a entrada desses dados no Elasticsearch, onde você pode pesquisá-los, criar painéis e escrever regras de detecção.

Se você quiser começar, inscreva-se para um teste gratuito do Elastic Cloud e experimente o endpoint OTLP gerenciado ou instale o coletor EDOT OTel em seu ambiente existente.

Monitoramento em escala do Claude Code/Cowork com OTel no Elasticsearch.