O Claude Code 2.1.221 agora permite que usuários de Linux e WSL2 mascarem arquivos de credenciais antes que um comando em sandbox possa lê-los. O recurso fornece ao comando uma cópia sentinela inofensiva e substitui pelo segredo real apenas quando uma requisição permitida passa por um proxy.

Como funciona o fluxo de mascaramento

  1. Cópia sentinela – Quando um arquivo é marcado para mascaramento, o Claude Code cria uma duplicata que contém uma string de placeholder em vez do segredo real.
  2. Troca via proxy – A sandbox é executada atrás de um proxy com terminação TLS. Se a sandbox emitir uma requisição que corresponda a uma entrada na lista injectHosts, o proxy substitui o placeholder pelo token real antes que a requisição saia da máquina.
  3. Tratamento de erros – Se a regex de extração falhar ao encontrar um segredo, a sandbox pode abortar em vez de prosseguir com o arquivo original exposto.

A abordagem funciona apenas em Linux e WSL2; o macOS atualmente utiliza, por padrão, um bloqueio total (hard deny), o que significa que a sandbox não consegue ler o arquivo de forma alguma.

Checklist para uma implementação segura

Verifique a versão

  • Confirme se você está executando o Claude Code 2.1.221 ou superior. A string de versão no terminal é o único método confiável; arquivos de lock de pacotes podem induzir ao erro.

Use tokens descartáveis

  • Nunca faça experimentos com suas credenciais principais do GitHub ou da nuvem. Crie um token de curta duração que aponte para um endpoint "canary" (canário) inofensivo e revogue-o instantaneamente se algo der errado.

Escolha o modo de mascaramento correto

Modo Quando usar
File Deny Bloqueio total; qualquer tentativa de leitura falha.
Whole-File Mask O arquivo contém um único segredo (ex: uma chave de API em texto simples).
Structured Mask O arquivo mistura segredos com outros dados (JSON, YAML, .netrc). Use o modo extract e uma regex que capture o segredo no grupo 1. Isso mantém a sintaxe ao redor válida para o programa cliente.

Defina regras de erro rigorosas

  • Defina onExtractNoMatch como error. Se a regex não coincidir, a sandbox para. Deixar no padrão warn pode permitir que o arquivo original passe despercebido.

Habilite a terminação TLS

  • O proxy deve realizar a terminação TLS para efetuar a troca. Sem a terminação TLS, o proxy não consegue ver o payload da requisição e a substituição nunca ocorre.

Restrinja o escopo dos hosts

  • Preencha o injectHosts com nomes de host explícitos de seus allowedDomains. Evite wildcards como *.example.com; padrões amplos aumentam a superfície de ataque e anulam o propósito do mascaramento.

Verifique o resultado

  • Verifique logs, argumentos de processo e mensagens de erro em busca de qualquer aparição do token real. O sentinela deve ser o único valor que apareça nesses artefatos.

Os limites que você deve ter em mente

O mascaramento protege o token apenas da visão do sistema de arquivos do comando em sandbox. Ele não impede o comando de fazer chamadas de rede arbitrárias, nem protege contra as ferramentas integradas do Claude que possam ter acesso privilegiado.

Resumo

O recurso de mascaramento de credenciais do Claude Code 2.1.221 oferece aos desenvolvedores de Linux e WSL2 uma maneira prática de manter segredos fora de processos em sandbox.