# Variáveis de ambiente de proxy: audite o tráfego de API dos agentes Variáveis de ambiente de proxy são instruções executáveis de roteamento, não preferências inofensivas do shell. Se um agente de programação de IA herdar `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` ou `NO_PROXY`, uma solicitação que parecia uma chamada direta para uma API interna pode seguir por outro caminho de rede antes que o agente faça qualquer trabalho útil. Já vi equipes passarem dias revisando o escopo dos tokens e as listas de permissões de endpoints, para depois descobrirem que o executor do agente havia herdado um proxy de depuração local do shell de um desenvolvedor. As credenciais eram válidas, o cliente de API se comportava exatamente como configurado e, ainda assim, o tráfego ia para um lugar que ninguém pretendia. Audite o ambiente do processo antes de conceder a um agente acesso a serviços internos. ## As variáveis de proxy mudam a rota, não apenas as configurações de conexão Uma variável de proxy diz a um cliente compatível para entregar a solicitação a um intermediário. No HTTP comum, o cliente geralmente envia a URL completa de destino para esse intermediário. No HTTPS, o cliente normalmente pede ao proxy que abra um túnel `CONNECT` até o host de destino e, em seguida, executa o TLS por esse túnel. Essa diferença importa porque um proxy pode afetar disponibilidade, controle do destino, comportamento do DNS e observabilidade mesmo quando não consegue descriptografar o HTTPS. Um proxy pode recusar uma conexão, redirecioná-la na camada TCP, registrar o host e a porta solicitados ou se tornar o único caminho que um agente pode usar para chegar a um serviço. Trate estas variáveis como parte da autoridade de saída do agente: - `HTTP_PROXY` e `http_proxy` normalmente afetam URLs `http://`. - `HTTPS_PROXY` e `https_proxy` normalmente afetam URLs `https://`. - `ALL_PROXY` e `all_proxy` funcionam como fallback nos clientes que oferecem suporte a elas. - `NO_PROXY` e `no_proxy` normalmente isentam destinos do uso do proxy. A palavra «normalmente» é importante. Variáveis de ambiente são uma convenção, não um padrão de rede que todos os runtimes implementam da mesma forma. Um agente pode chamar um cliente de linha de comando, usar uma biblioteca HTTP de uma linguagem, executar um gerenciador de pacotes ou iniciar um processo auxiliar. Cada camada pode tomar uma decisão própria sobre o proxy. Uma variável não definida também não comprova a existência de uma rota direta. Um cliente pode ler um arquivo de configuração, usar uma configuração de proxy do sistema, obedecer a um arquivo PAC ou chamar explicitamente um relay local. Este artigo se concentra nas variáveis de ambiente porque elas são fáceis de herdar, difíceis de perceber em um ambiente de processo cheio e frequentemente tratadas como temporárias mesmo depois de se tornarem permanentes. ## O launcher decide o que o agente herda Um agente só recebe variáveis que existem no próprio ambiente de processo ou que um processo pai transmite. O terminal em que você executou `env` pode não ter nenhuma relação com o processo que realmente executa o agente. No macOS, é especialmente fácil errar. Um processo iniciado por um shell interativo herda as variáveis exportadas pelo shell. Um app gráfico iniciado pelo Finder ou um serviço iniciado pelo `launchd` segue outro caminho de herança. Uma IDE pode iniciar o terminal integrado com um ambiente e o host de extensões com outro. Um agente em segundo plano iniciado ontem pode manter um valor antigo de proxy muito depois de a variável desaparecer do shell. Mapeie a cadeia de execução antes de alterar as configurações. Faça quatro perguntas concretas: 1. Qual processo inicia o agente? 2. O agente inicia shells, ferramentas de pacotes, executores de testes ou auxiliares remotos? 3. Quais desses processos fazem chamadas HTTP? 4. Qual ponto de inicialização fornece cada variável de ambiente? Não aceite «o agente roda no meu terminal» como resposta, a menos que você consiga identificar o processo pai e reproduzir a execução a partir desse terminal. O agente pode ser filho de um editor, de um executor de tarefas ou de um serviço de automação que usa um ambiente salvo. Um proxy injetado por um processo pai chega a todos os filhos, a menos que um filho o remova. Por isso, uma única exportação no shell pode alterar silenciosamente chamadas feitas por instalação de pacotes, auxiliares de controle de código-fonte, CLIs de nuvem, automação de navegador e fixtures de teste. A solicitação afetada pode não ser aquela que você tinha em mente ao iniciar o agente. ## A semântica das variáveis de proxy varia entre os clientes Não existe uma interpretação única de `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY`. Qualquer revisão de segurança que presuma que o comportamento de um cliente vale para outro está incompleta. A documentação do curl registra uma exceção importante que muita gente ignora: o curl aceita apenas `http_proxy` em minúsculas para a configuração de proxy HTTP. A documentação explica que isso evita um problema de CGI, no qual um cabeçalho de entrada `Proxy:` pode se transformar em uma variável de ambiente `HTTP_PROXY`. O curl aceita variantes em maiúsculas para várias outras variáveis de proxy, mas essa exceção do HTTP é intencional. O Go documenta `http.ProxyFromEnvironment` como uma função que lê `HTTP_PROXY`, `HTTPS_PROXY` e `NO_PROXY`, com alternativas em minúsculas. Seu comportamento também inclui proteção para CGI: quando um ambiente CGI contém `REQUEST_METHOD`, o Go se recusa a usar `HTTP_PROXY`, pois um cabeçalho de solicitação pode tê-lo fornecido. Essa proteção não torna um processo Go seguro. `HTTPS_PROXY`, as formas em minúsculas, configurações explícitas de transporte e contextos que não são CGI ainda precisam ser revisados. Muitos aplicativos JavaScript complicam ainda mais o cenário. O runtime Node.js historicamente não impôs uma política universal de proxy por ambiente para suas APIs HTTP integradas. Aplicativos e suas dependências costumam adicionar suporte a proxy por conta própria. Um comando pode respeitar `HTTPS_PROXY`, outro comando na mesma execução do agente pode ignorá-lo e um terceiro pode ler uma opção personalizada. Não resolva isso com uma planilha de conhecimentos informais sobre runtimes. Identifique cada executável capaz de fazer rede e teste-o. Registre a versão do executável, sua invocação, a URL de destino, as variáveis relevantes e se ele se conectou diretamente ou pelo proxy pretendido. Mantenha o resultado junto das notas de implantação do agente, porque uma atualização de dependência pode mudar o comportamento. Uma distinção útil costuma desaparecer: ter *consciência* de proxy não é o mesmo que ter *imposição* de proxy. Um cliente que respeita uma variável de proxy pode ser roteado quando a variável existe. Ainda assim, ele pode se conectar diretamente quando a variável está ausente, malformada, ignorada por `NO_PROXY` ou não é lida por um processo auxiliar. Se você precisa impedir a saída direta, imponha isso no limite da rede, em vez de esperar que todas as bibliotecas leiam uma variável de ambiente. ## NO_PROXY exige testes explícitos para nomes internos `NO_PROXY` é uma lista de exceções, e uma lista malformada pode enviar tráfego interno por um proxy ou enviar tráfego diretamente quando você esperava inspeção. Não é seguro presumir que nenhum desses resultados acontecerá. A maioria das implementações aceita entradas separadas por vírgulas. Além disso, os detalhes divergem. Os clientes podem tratar `registry.corp.example`, `.corp.example`, `corp.example`, `10.20.0.0/16`, `10.20.30.40`, `localhost` e `*` de formas diferentes. Uma correspondência por sufixo que funciona em um cliente pode ser ampla demais ou falhar completamente em outro. Entradas que especificam uma porta também não se comportam de maneira uniforme. Evite entradas amplas até que um teste prove seu significado. Um sufixo de domínio simples pode isentar hosts que você não pretendia incluir. Um asterisco pode desativar o proxy de forma muito mais ampla do que o revisor espera. O suporte a CIDR é útil quando existe, mas não deve ser presumido como portátil. Nomes de hosts internos exatos são pouco empolgantes, e isso é útil neste caso. Comece com uma lista curta de serviços nomeados que precisam se conectar diretamente, como um host interno de código-fonte, um registro de artefatos e um endpoint de descoberta de serviços. Adicione um sufixo de domínio apenas depois de confirmar que o cliente faz a correspondência desejada e que todos os hosts sob esse sufixo merecem a mesma rota. Também separe a correspondência de nomes da resolução de nomes. Um cliente frequentemente decide se `NO_PROXY` se aplica antes de se conectar. Se sua lista contém um nome de host, a correspondência pode funcionar mesmo que o host seja resolvido para um endereço fora do intervalo esperado. Se sua lista contém um intervalo de IP, o cliente pode precisar resolver o nome antes de decidir. A implementação controla essa sequência. Um teste de exceção precisa usar um destino que você controle e consiga identificar nos logs. Não use uma API de produção e deduza que tudo funcionou a partir de uma resposta 200. Um endpoint de teste interno deve informar o endereço remoto ou emitir um identificador de solicitação no log de acesso. Depois, compare uma solicitação feita com a entrada de exceção presente com outra feita sem ela. Você precisa de evidências do caminho da conexão, não de um palpite baseado na saída da aplicação. ## HTTPS oculta o conteúdo, mas um proxy ainda recebe dados relevantes Um túnel HTTPS `CONNECT` normalmente protege os cabeçalhos e os corpos das solicitações contra um proxy de encaminhamento convencional. Isso não torna o proxy irrelevante. O proxy vê o host e a porta indicados na solicitação `CONNECT`, o momento da conexão, a quantidade de bytes e frequentemente o endereço de origem. Dependendo do cliente e da rede, o tráfego de DNS relacionado pode revelar mais informações. O proxy pode ler credenciais de API descriptografadas se o cliente confiar em uma autoridade certificadora usada pelo proxy para interceptar o TLS. Isso acontece em algumas redes corporativas gerenciadas e configurações de depuração. A presença de um certificado raiz local confiável é uma decisão de limite de segurança, não uma simples configuração de conveniência. Se um processo de agente confia nessa raiz, o operador do proxy pode inspecionar o tráfego para qualquer host ao qual a política de interceptação se aplique. O HTTP simples é pior. Um proxy de encaminhamento pode receber a URL completa e os cabeçalhos da solicitação, incluindo tokens bearer ou autenticação básica. Não permita que um agente use HTTP sem criptografia para APIs internas autenticadas porque «a rede é privada». Variáveis de ambiente de proxy são uma das várias formas pelas quais suposições sobre redes privadas deixam de ser verdadeiras. Uma falha menos óbvia envolve uma URL de proxy com credenciais embutidas, como `http://user:password@proxy.example:8080`. Esse valor pode aparecer em saídas de diagnóstico, relatórios de falha, histórico do shell, inspeção de processos ou logs que registram o ambiente. A autenticação do proxy deve usar um mecanismo gerenciado apropriado ao seu ambiente, e uma revisão de segurança deve tratar as credenciais do proxy como segredos por direito próprio. Se você não consegue identificar o operador do proxy, o endereço de escuta do proxy e se a interceptação TLS é possível, não encaminhe tráfego privilegiado do agente por ele. Isso não é paranoia. O proxy já se tornou parte do caminho entre um processo automatizado e um serviço sensível. ## Audite o processo em execução sem despejar seus segredos Comece com um inventário que mostre nomes de variáveis e endpoints de proxy, evitando uma ampla descarga do ambiente. Em um shell que possa iniciar o agente, execute: ```sh env | grep -Ei '(^|_)(http|https|all|no)_proxy=' ``` O formato da saída deve ser parecido com este: ```text HTTPS_PROXY=http://127.0.0.1:8888 NO_PROXY=localhost,127.0.0.1,registry.corp.example ``` Se a URL do proxy contiver informações de usuário, não cole a saída original em um chamado. Registre o esquema, o host e a porta depois de remover as credenciais. Um endereço de loopback não é automaticamente seguro. Proxies locais costumam pertencer a ferramentas legítimas de depuração, mas malware e softwares indesejados também podem escutar no loopback. Verifique qual processo é dono da porta de escuta. No macOS, inspecione um listener com: ```sh lsof -nP -iTCP:8888 -sTCP:LISTEN ``` Um resultado normal identifica um comando e um ID de processo. Se nenhum processo esperado for dono da porta, pare e investigue. Não permita que um agente encaminhe credenciais para um listener apenas porque o endereço começa com `127.0.0.1`. Em seguida, inspecione o processo real do agente. `ps` pode exibir o ambiente de um processo no macOS, mas também pode expor segredos sem relação com o proxy. Restrinja o acesso ao proprietário da máquina ou a um administrador, colete apenas o necessário e não cole o resultado em um chat ou log compartilhado. ```sh ps eww -p "$AGENT_PID" | tr ' ' '\n' | grep -Ei '(^|_)(http|https|all|no)_proxy=' ``` Defina `AGENT_PID` como o ID do processo do agente em execução. Esse comando ainda pode mostrar credenciais sensíveis do proxy, caso existam, por isso use-o em um terminal confiável e faça a redação antes de salvar as evidências. Se a saída for diferente do inventário do shell, o processo pai injetou ou removeu variáveis. Para processos iniciados pelo `launchd`, examine a definição do job e o launcher, em vez de depender do seu terminal. `launchctl getenv HTTPS_PROXY` pode revelar uma variável no domínio atual do `launchd`, mas a ausência dela não elimina um job específico. Um job pode definir seu próprio ambiente, e um script wrapper pode exportar variáveis imediatamente antes de iniciar o agente. ## Comprove a rota com uma solicitação inofensiva Uma revisão de configuração informa o que deveria acontecer. Uma solicitação controlada informa o que aconteceu. Você precisa das duas coisas. Crie ou use um endpoint sem dados sensíveis que registre o endereço do peer e o caminho da solicitação. Depois faça uma solicitação com saída detalhada da conexão. O curl é útil porque mostra se está se conectando ao proxy e se envia uma solicitação `CONNECT`. ```sh HTTPS_PROXY=http://127.0.0.1:8888 \\ NO_PROXY= \\ curl -v --connect-timeout 5 https://probe.corp.example/agent-proxy-check ``` Quando o curl usa o proxy para HTTPS, sua saída detalhada normalmente inclui linhas deste formato: ```text * Uses proxy env variable HTTPS_PROXY == 'http://127.0.0.1:8888' * Establish HTTP proxy tunnel to probe.corp.example:443 > CONNECT probe.corp.example:443 HTTP/1.1 ``` Depois faça deliberadamente a comparação direta: ```sh HTTPS_PROXY=http://127.0.0.1:8888 \\ NO_PROXY=probe.corp.example \\ curl -v --connect-timeout 5 https://probe.corp.example/agent-proxy-check ``` Uma execução direta deve mostrar uma conexão com o destino, em vez de uma solicitação `CONNECT` ao proxy. Confirme o resultado nos logs do servidor de teste. Se o curl disser que ignorou o proxy, mas o servidor observar uma origem inesperada ou a solicitação falhar, investigue separadamente o DNS, o roteamento e qualquer proxy de rede transparente. Isso prova o comportamento do curl, não o do seu agente. Repita o teste pelo caminho exato de execução do agente. Se ele invoca um script, execute esse script. Se usa uma dependência para chamar uma API, adicione uma URL de teste temporária por meio dessa mesma configuração. Se inicia um processo auxiliar, colete as evidências da rota desse auxiliar. Testar um cliente diferente serve apenas como pista. Não use um serviço público de «qual é meu IP?» para esse trabalho. Isso transforma uma revisão de roteamento interno em uma divulgação externa desnecessária e não informa qual política de proxy interno foi aplicada. ## Ambientes de inicialização limpos são melhores que exports permanentes no shell Não coloque exports de proxy corporativo em um perfil universal do shell esperando que ferramentas autônomas façam exceções com segurança. Exports globais são populares porque fazem um comando bloqueado funcionar uma vez. Eles também se espalham para todos os processos filhos cuja existência você acaba esquecendo. Use um launcher explícito para o agente. Comece com um ambiente conhecido, passe apenas as variáveis necessárias para a execução e torne o uso do proxy visível no comando de inicialização ou no wrapper. Em um shell Unix, `env -i` limpa as variáveis herdadas, portanto você precisa restaurar o básico exigido pelo programa: ```sh env -i \\ PATH="$PATH" \\ HOME="$HOME" \\ LANG="${LANG:-en_US.UTF-8}" \\ NO_PROXY="localhost,127.0.0.1,registry.corp.example" \\ agent-command ``` Este exemplo intencionalmente não define um proxy. Se o agente precisar de um, adicione a variável de proxy ao launcher depois de identificar seu responsável e testar seu comportamento. Não copie um valor de proxy de um perfil do shell para um script sem verificar se ele contém credenciais ou aponta para um serviço local antigo. Um ambiente limpo pode quebrar ferramentas que dependiam de variáveis como locais de certificados, perfis de nuvem, sockets de agentes SSH ou caches de pacotes. Essa quebra é uma informação útil. Adicione de volta apenas as variáveis de que o agente precisa, uma por vez, e documente por que cada uma está presente. Um launcher de agente deve ser suficientemente restrito para que outro engenheiro consiga lê-lo e entender para onde suas solicitações irão. Os controles de rede devem dar suporte a isso. Se um agente precisa alcançar apenas alguns serviços internos, use regras de firewall, um proxy de saída com política imposta ou um segmento de rede dedicado adequado ao seu ambiente. Variáveis de ambiente escolhem uma rota para clientes cooperativos. Elas não impedem que um processo comprometido ou uma biblioteca que não as respeite abra um socket direto. ## Mantenha as credenciais fora do processo que escolhe a rota A higiene de proxy reduz redirecionamentos acidentais, mas não torna prudente entregar tokens de API a um agente autônomo. Se o ambiente do agente contém um token bearer, todo processo com acesso a esse ambiente passa a fazer parte do caminho de exposição do segredo. O Sallyport estabelece um limite diferente: o agente solicita uma ação HTTP ou SSH por meio do MCP shim, enquanto as credenciais permanecem no cofre criptografado do app e o app executa a ação. Isso limita o que um vazamento de variável de proxy no processo do agente pode expor, porque o agente nunca recebe a credencial de API ou SSH em texto simples. Não exagere esse limite. Um gateway de credenciais não define magicamente um comportamento seguro de proxy para todos os comandos executados pelo agente e não torna um destino perigoso inofensivo. Você ainda precisa controlar quais destinos e ações são permitidos, revisar o processo do aplicativo que faz a chamada de rede e preservar evidências do caminho da solicitação. A separação útil é entre custódia do segredo e roteamento de rede. A custódia responde quem pode ler a credencial. O roteamento responde qual intermediário trata a solicitação. As equipes frequentemente resolvem um desses pontos e presumem que resolveram os dois. Não resolveram. ## Trate o uso inexplicado de proxy como um incidente a ser contido Se um agente privilegiado fez solicitações por meio de um proxy desconhecido, interrompa a execução antes de investigar dentro do mesmo ambiente contaminado. Registre o ID do processo do agente, seu processo pai, o endereço do proxy, os nomes dos destinos afetados e a janela de tempo. Preserve os logs relevantes do agente e do proxy de acordo com o processo de incidentes. Depois remova a variável na origem. Excluí-la do terminal atual corrige apenas os futuros filhos desse terminal. Verifique perfis do shell, configurações de tarefas da IDE, launch agents, configuração de CI, scripts wrapper e qualquer gerenciamento de configuração que escreva definições de ambiente. Reinicie o processo afetado depois de corrigir o ponto de inicialização. Avalie as credenciais de acordo com o protocolo. Se o tráfego afetado era HTTP sem criptografia e continha autenticação, altere a credencial exposta. Se era HTTPS por meio de um proxy, determine se o endpoint validou o TLS normal e se o agente confiava em um certificado de interceptação. Não presuma que HTTPS significa que o evento não precisa de revisão e não faça uma rotação indiscriminada deixando o mesmo caminho de injeção aberto. Por fim, adicione uma verificação de pré-execução no ponto em que o agente começa. Interrompa a execução ou exija uma revisão explícita quando surgir uma variável de proxy inesperada. A verificação deve informar o nome da variável e o endpoint sanitizado, compará-los com a rota aprovada para aquele job e deixar um registro de que a verificação foi executada. O primeiro proxy sem explicação é um alerta. O segundo é um defeito de implantação que você decidiu manter.