Charles Proxy

O Charles Proxy facilita a depuração de requisições HTTP atuando como um proxy man-in-the-middle, capturando e permitindo a inspeção e a modificação de todo o tráfego de rede entre um aplicativo cliente e os servidores de destino.

O Charles Proxy funciona como um servidor proxy HTTP local, permitindo que desenvolvedores e engenheiros de QA observem, interceptem e manipulem a comunicação de rede. Esse recurso é essencial para entender as interações cliente-servidor, diagnosticar problemas de integração, testar casos extremos e verificar o comportamento de APIs, especialmente ao trabalhar com ou desenvolver serviços que interagem com um proxy upstream.

Configurando o Charles Proxy

Instalação e primeira execução

Baixe e instale o Charles Proxy pelo site oficial. Na primeira execução, o Charles normalmente tenta se configurar como proxy do sistema. Aceite esse aviso para permitir que o Charles intercepte o tráfego de aplicativos que respeitam as configurações de proxy do sistema.

Configurando as definições de proxy do sistema

Quando o Charles está em execução, ele define automaticamente as configurações de proxy HTTP/HTTPS do sistema para 127.0.0.1 (localhost) na porta 8888 (padrão). A maioria dos aplicativos, incluindo navegadores web, respeita essas configurações.

Para verificar ou configurar manualmente:
* macOS: Ajustes do Sistema > Rede > Wi-Fi/Ethernet > Detalhes > Proxies. Confirme que "Web Proxy (HTTP)" e "Secure Web Proxy (HTTPS)" estão ativados e apontam para 127.0.0.1:8888.
* Windows: Configurações > Rede e Internet > Proxy > Configuração manual de proxy. Confirme que "Usar um servidor proxy" está ativado com 127.0.0.1 e porta 8888.
* Linux (GNOME): Configurações > Rede > Proxy de rede. Defina o método como "Manual" e configure o proxy HTTP/HTTPS para 127.0.0.1:8888.

Configurando aplicativos clientes

Alguns aplicativos, em especial ferramentas de linha de comando ou SDKs específicos, podem não respeitar as configurações de proxy do sistema. Nesses casos, configure o aplicativo diretamente.

Exemplo: curl com proxy

curl -x http://127.0.0.1:8888 https://api.example.com/data

Exemplo: Node.js axios com proxy

const axios = require('axios');

axios.get('https://api.example.com/data', {
  proxy: {
    host: '127.0.0.1',
    port: 8888
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

SSL Proxying para tráfego HTTPS

Para inspecionar tráfego HTTPS, o Charles Proxy precisa executar SSL (ou TLS) proxying. Isso envolve o Charles gerar e assinar certificados para os domínios de destino, apresentá-los ao cliente e então estabelecer sua própria conexão segura com o servidor real.

Instalando o certificado raiz do Charles

O aplicativo cliente precisa confiar no certificado raiz do Charles para que o SSL proxying funcione sem avisos de segurança.

• Navegadores/sistema desktop:
  • Acesse Help > SSL Proxying > Install Charles Root Certificate. Siga as instruções específicas do sistema operacional para instalá-lo no repositório de certificados raiz confiáveis do sistema.
• Dispositivos móveis:
  • Configure o dispositivo móvel para usar o Charles como proxy HTTP (por exemplo, your_mac_ip:8888).
  • No dispositivo, acesse chls.pro/ssl e siga as instruções para baixar e instalar o certificado.

Ativando o SSL Proxying para hosts específicos

Depois de instalar o certificado raiz, ative o SSL proxying para os hosts específicos que você quer inspecionar.

1. Vá em Proxy > SSL Proxying Settings....
2. Clique em "Add".
3. Informe o Host (por exemplo, api.example.com, *.example.com para um curinga, ou * para todos os hosts) e a Port (normalmente 443 para HTTPS, ou * para todas as portas).
4. Clique em "OK" e depois em "OK" novamente.

O tráfego para os hosts especificados passará a ser descriptografado e ficará visível no Charles.

Principais recursos de depuração

Monitoramento e filtragem de tráfego

As visões "Structure" e "Sequence" exibem as requisições capturadas.
* Visão Sequence: mostra as requisições em ordem cronológica.
* Visão Structure: organiza as requisições por host e caminho.

Para focar no tráfego relevante:
* Campo de filtro: use o campo de filtro no topo da janela do Charles para casar URLs, hosts ou conteúdo.
* Ferramenta Focus: clique com o botão direito em uma requisição e selecione "Focus" para ocultar todos os outros hosts da visão atual.
* Botão de gravação: alterne o botão de gravação (círculo vermelho) para iniciar/parar a captura de tráfego.

Breakpoints

Os breakpoints permitem pausar e modificar requisições antes de serem enviadas ao servidor, ou respostas antes de serem entregues ao cliente.

1. Vá em Proxy > Breakpoints Settings....
2. Clique em "Add" para requisições ou respostas.
3. Especifique o Host e o Path (por exemplo, /login).
4. Quando uma requisição/resposta corresponder, o Charles pausa e uma aba "Breakpoints" aparece.
5. Modifique cabeçalhos, parâmetros de query ou o corpo.
6. Clique em "Execute" para enviar a requisição/resposta modificada.

Ferramenta Rewrite

A ferramenta Rewrite fornece modificações automatizadas e persistentes em requisições e respostas. É útil para simular comportamentos específicos do servidor ou condições do cliente sem intervenção manual.

1. Vá em Tools > Rewrite....
2. Ative o Rewrite e adicione um novo "Set".
3. Adicione "Locations" (URLs às quais as regras se aplicam) usando Host e Path.
4. Adicione "Rules" dentro do set:
   • Add Header/Remove Header: modifica cabeçalhos HTTP.
   • Change Query Parameter: modifica parâmetros de query da URL.
   • Body Replace: localiza e substitui texto no corpo da requisição/resposta.
   • URL Replace: modifica partes da URL da requisição.

Exemplo: modificando o corpo de uma resposta de API
Uma regra de Rewrite pode substituir {"status": "active"} por {"status": "maintenance"} em uma resposta JSON para testar como o cliente lida com estados diferentes.

Map Local / Map Remote

Essas ferramentas redirecionam requisições para fontes diferentes.

• Map Local: serve um arquivo local no lugar de uma resposta remota.

  1. Vá em Tools > Map Local....
  2. Ative o Map Local e adicione uma nova entrada.
  3. Especifique o Host e o Path da URL remota.
  4. Selecione o caminho do File local a ser servido.
     Isso é útil para testar rapidamente mudanças de UI ou simular respostas de API específicas sem alterar o backend.

• Map Remote: redireciona uma requisição de uma URL para uma URL totalmente diferente.

  1. Vá em Tools > Map Remote....
  2. Ative o Map Remote e adicione uma nova entrada.
  3. Especifique o Host e o Path da requisição original.
  4. Especifique o novo Host e Path para a requisição redirecionada.
     Útil para redirecionar chamadas de API para um ambiente de staging ou um servidor de desenvolvimento local.

Throttling

O throttling simula condições de rede lentas, ajudando a identificar gargalos de desempenho ou problemas de UI relacionados ao carregamento lento de dados.

1. Vá em Proxy > Throttle Settings....
2. Ative "Enable Throttling".
3. Configure os parâmetros Bandwidth, Utilisation e Latency.
4. Opcionalmente, selecione "Only for selected hosts" e adicione hosts específicos para limitar.

Repeat / Advanced Repeat

Esses recursos permitem reenviar requisições.

• Repeat: clique com o botão direito em uma requisição e selecione "Repeat" para enviá-la novamente de imediato.
• Advanced Repeat: clique com o botão direito em uma requisição e selecione "Advanced Repeat" para enviá-la várias vezes com concorrência e número de iterações personalizáveis. É útil para testes de carga ou para verificar condições de corrida.

Depurando interações com proxy upstream

Quando seu aplicativo cliente está configurado para usar o Charles, e o próprio Charles está configurado para usar um proxy upstream (por exemplo, um proxy corporativo), o Charles atua como intermediário.

Para configurar o Charles para usar um proxy upstream:
1. Vá em Proxy > External Proxy Settings....
2. Ative "Use external proxy".
3. Informe o Host, a Port e qualquer Username/Password exigido pelo seu proxy upstream.
4. Ative "SOCKS proxy" se o seu proxy upstream for um proxy SOCKS.

Nessa configuração, o Charles captura o tráfego do seu cliente e então o encaminha ao proxy upstream. Isso permite inspecionar o tráfego antes de ele chegar ao proxy upstream, o que é crucial para diagnosticar casos em que o proxy upstream pode estar modificando requisições ou bloqueando determinados endpoints.

Problemas comuns e solução de problemas

| Problema | Solução no Charles Proxy CHARLES PROXY: DEPURANDO REQUISIÇÕES HTTP ATRAVÉS DE PROXY

O Charles Proxy depura requisições HTTP atuando como um proxy man-in-the-middle, capturando todo o tráfego de rede entre um aplicativo cliente e os servidores de destino, o que permite inspeção e modificação detalhadas.

Visão geral

O Charles Proxy é um proxy HTTP (HTTP/HTTPS/SOCKS) e um monitor HTTP que roda na sua máquina local. Ele permite visualizar todo o tráfego HTTP e HTTPS entre a sua máquina e a Internet. Ao depurar serviços que interagem com um proxy upstream, o Charles pode ser configurado para ficar entre o cliente e o proxy upstream, dando visibilidade das requisições exatas que seu aplicativo envia e recebe.

Configuração inicial

Instalação

Baixe e instale o Charles Proxy pelo site oficial (charlesproxy.com). O Charles é compatível com macOS, Windows e Linux.

Configuração do proxy do sistema

Ao iniciar, o Charles normalmente pede para se configurar como proxy do sistema. Aceitar isso permite que o Charles intercepte automaticamente o tráfego de aplicativos configurados para usar as definições de proxy do sistema (por exemplo, a maioria dos navegadores web, aplicativos Java e aplicativos .NET).

Para verificar ou configurar manualmente:
* Endereço padrão do proxy HTTP/HTTPS: 127.0.0.1
* Porta padrão do proxy HTTP/HTTPS: 8888

Para ambientes em que o Charles precisa se conectar a um proxy externo (upstream):
1. Acesse Proxy > External Proxy Settings....
2. Marque "Use external proxy".
3. Informe o Host e a Port do proxy upstream.
4. Forneça Username e Password se o proxy upstream exigir.
5. Marque "SOCKS proxy" se o proxy upstream for um proxy SOCKS.

Essa configuração garante que o Charles capture o tráfego do seu cliente e depois o roteie pelo proxy externo especificado, permitindo inspecionar o que é enviado ao proxy externo e recebido dele.

SSL Proxying para tráfego HTTPS

O tráfego HTTP Secure (HTTPS) é criptografado, o que impede a inspeção direta. O Charles usa SSL Proxying (ataque man-in-the-middle) para descriptografar e inspecionar o tráfego HTTPS.

Instalação do certificado raiz do Charles

Para executar o SSL Proxying, o Charles gera certificados SSL dinâmicos para cada domínio HTTPS. Seu aplicativo cliente precisa confiar no certificado raiz do Charles para evitar erros de SSL.

• Sistemas desktop (macOS/Windows/Linux):
  1. Vá em Help > SSL Proxying > Install Charles Root Certificate.
  2. Siga as instruções do sistema operacional para instalar o certificado no repositório de certificados raiz confiáveis.
• Dispositivos móveis (iOS/Android):
  1. Configure as definições de Wi-Fi do dispositivo móvel para usar o Charles como proxy HTTP (endereço IP do Charles e porta 8888).
  2. No dispositivo móvel, abra um navegador e acesse chls.pro/ssl.
  3. Siga as instruções para baixar e instalar o certificado raiz do Charles como credencial confiável.

Ativando o SSL Proxying para hosts específicos

Depois de instalar o certificado raiz, especifique quais hosts HTTPS o Charles deve descriptografar.
1. Vá em Proxy > SSL Proxying Settings....
2. Clique em "Add".
3. Informe o Host (por exemplo, api.yourdomain.com, *.yourdomain.com, ou * para todos os hosts) e a Port (normalmente 443, ou * para todas as portas).
4. Clique em "OK".

Funcionalidades centrais de depuração

Captura e filtragem de tráfego

O Charles exibe o tráfego capturado em duas visões principais:
* Sequence: lista cronológica de requisições.
* Structure: visão hierárquica agrupada por host e caminho de pasta.

Para localizar requisições específicas:
* Campo de filtro: use a barra de filtro no topo para buscar por host, caminho da URL ou conteúdo.
* Ferramenta Focus: clique com o botão direito em uma requisição e selecione "Focus" para ocultar todos os outros hosts da visão atual.
* Botão de gravação: alterne o ícone de círculo vermelho para iniciar/parar a captura de tráfego.

Breakpoints

Os breakpoints permitem interceptação e modificação manuais de requisições antes do envio, ou de respostas antes de chegarem ao cliente.

1. Vá em Proxy > Breakpoints Settings....
2. Clique em "Add" para breakpoints de "Request" ou "Response".
3. Especifique padrões de Host e Path para a URL de destino.
4. Quando ocorrer uma requisição/resposta correspondente, o Charles pausa e exibe uma aba "Breakpoints".
5. Modifique o conteúdo de Headers, Query Parameters ou Body.
6. Clique em "Execute" para prosseguir com a transação modificada.

Ferramenta Rewrite

A ferramenta Rewrite automatiza modificações em requisições e respostas com base em regras predefinidas. É útil para cenários de teste consistentes sem intervenção manual.

1. Vá em Tools > Rewrite....
2. Ative o Rewrite e adicione um novo "Set".
3. Defina "Locations" (URLs onde as regras se aplicam) usando Host e Path.
4. Adicione "Rules" dentro do set:
   • Type: Add Header, Remove Header, Change Query Parameter, Host, Path, URL, Body.
   • Action: especifique Value ou Regex para a modificação.

Exemplo: simulando uma mudança de versão de API
Uma regra de Rewrite pode alterar o cabeçalho Accept de application/json;v=1 para application/json;v=2 em todas as requisições a um endpoint de API específico.

Map Local / Map Remote

Esses recursos redirecionam requisições para recursos alternativos.

• Map Local: serve um arquivo local no lugar da resposta de um servidor remoto.

  1. Vá em Tools > Map Local....
  2. Ative o Map Local e adicione uma nova entrada.
  3. Especifique o Host e o Path da URL remota a ser mapeada.
  4. Selecione o Local Path do arquivo que o Charles deve servir.
     Isso é útil no desenvolvimento frontend para testar mudanças de UI com dados fictícios específicos sem alterar o backend.

• Map Remote: redireciona uma requisição de uma URL para uma URL totalmente diferente.

  1. Vá em Tools > Map Remote....
  2. Ative o Map Remote e adicione uma nova entrada.
  3. Especifique o Host e o Path da requisição original.
  4. Especifique o Host e o Path da nova URL de destino.
     Isso é útil para redirecionar chamadas de API de produção para um ambiente de staging ou um servidor de desenvolvimento local.

Throttling

O throttling simula várias condições de rede (por exemplo, dial-up, 3G, velocidades personalizadas) para testar o desempenho e a responsividade do aplicativo sob conectividade de rede ruim.

1. Vá em Proxy > Throttle Settings....
2. Marque "Enable Throttling".
3. Selecione um Preset ou configure Bandwidth, Utilisation e Latency manualmente.
4. Opcionalmente, marque "Only for selected hosts" e adicione hosts específicos para limitar.

Repeat / Advanced Repeat

Essas funções permitem reenviar requisições.
* Repeat: clique com o botão direito em uma requisição na sessão do Charles e selecione "Repeat" para reenviá-la uma vez.
* Advanced Repeat: clique com o botão direito em uma requisição e selecione "Advanced Repeat" para configurar múltiplas repetições, concorrência e atrasos, útil para testes de carga básicos ou para verificar idempotência.

Solução de cenários comuns

| Problema | Solução