Como Interceptar Tráfego HTTPS no Android Sem Certificados e Configuração Manual de Proxy

Todo desenvolvedor Android já perdeu pelo menos meio dia de trabalho configurando um depurador de rede em algum momento. O cenário é sempre o mesmo: você precisa ver o que o app está enviando para o backend, e em vez disso recebe SSLHandshakeException.

Então o ritual começa. Primeiro, você gera um certificado CA autoassinado. Depois tenta instalá-lo na loja de certificados confiáveis no seu dispositivo de teste. A partir do Android 7.0 (API 24), o sistema ignora certificados de usuário por padrão, então você precisa modificar network_security_config.xml, configurar trust-anchors para builds de debug e recompilar o APK. Se o seu projeto tiver SSL Pinning configurado ou se você estiver testando no Android 14, onde o tratamento de certificados do sistema ficou ainda mais restritivo, uma simples verificação de cabeçalho de resposta se transforma em uma tarefa de engenharia separada.

A biblioteca atlantis-android da equipe Proxyman resolve radicalmente essa dor de cabeça: elimina a necessidade de configurar um proxy e mexer nos certificados do sistema do dispositivo.

Qual é a ideia por trás do Atlantis

Ferramentas tradicionais como Charles, Fiddler ou o próprio Proxyman geralmente funcionam usando um esquema de Man-in-the-Middle (MitM). O dispositivo redireciona todo o tráfego para o endereço IP do computador, e o aplicativo desktop intercepta as requisições, descriptografa-as com seu próprio certificado e as encaminha. É exatamente por isso que problemas de confiança de certificados e configuração de proxy Wi-Fi se tornam problemáticos.

O Atlantis funciona de forma diferente. É uma biblioteca Kotlin compacta que se嵌入式 diretamente no build de debug do app como um interceptor de cliente de rede. O interceptor lê os parâmetros de requisição e resposta no momento em que o app já os formou ou acabou de descriptografá-los. A biblioteca então serializa esses dados, comprime-os via GZIP e os transmite diretamente para o app Proxyman no macOS através de um socket local separado.

Como resultado, você obtém um log detalhado da atividade de rede sem nenhuma intervenção nas configurações do Android, sem modificações no manifest e sem manipulação de certificados.

O que a biblioteca pode fazer

O Atlantis cobre a maioria das tarefas diárias de depuração de rede:

• Interceptar requisições HTTP e HTTPS regulares diretamente do OkHttp.
• Registrar eventos WebSocket: abertura de conexão, envio de mensagens, pacotes recebidos e fechamento de sessão.
• Compatibilidade total com clientes de rede populares, incluindo Retrofit 2.9+ e Apollo Kotlin 3.x/4.x.
• Descoberta automática de uma instância do Proxyman em execução na rede local via Network Service Discovery (mDNS).

Se você estiver executando o projeto no emulador Android oficial, a biblioteca pode se conectar diretamente à máquina host, ignorando a descoberta de rede.

Como integrar ao seu projeto

A biblioteca requer Android com API 26 (Android 8.0) ou superior, OkHttp versão 4.x ou 5.x e Kotlin versão 1.9 ou superior.

Primeiro, adicione o repositório JitPack ao seu arquivo settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

Depois disso, adicione a dependência ao build.gradle.kts do seu app. É melhor adicioná-la estritamente via debugImplementation para garantir que o código de debug não termine nos builds de release:

dependencies {
    debugImplementation("com.github.ProxymanApp:atlantis-android:v1.0.0")
}

A biblioteca também está disponível no Maven Central sob o artifact com.proxyman:atlantis-android:1.0.0.

Início rápido

A integração leva apenas algumas linhas de código. Primeiro, inicialize o Atlantis na sua classe Application:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        if (BuildConfig.DEBUG) {
            Atlantis.start(this)
        }
    }
}

Depois adicione o interceptor à sua configuração de OkHttpClient:

val okHttpClient = OkHttpClient.Builder()
    .addInterceptor(Atlantis.getInterceptor())
    .build()

Se você estiver usando Retrofit, passe esta instância de okHttpClient para Retrofit.Builder(), e todas as requisições aparecerão automaticamente na janela do Proxyman.

Trabalhando com WebSocket

Se seu app usa websockets, o interceptor padrão do OkHttp não será suficiente, já que as mensagens são transmitidas dentro de uma conexão já aberta. Para esses casos, a biblioteca fornece um wrapper especial para o listener:

val originalListener = object : WebSocketListener() {
    override fun onOpen(webSocket: WebSocket, response: Response) {
        // обработка открытия
    }
    override fun onMessage(webSocket: WebSocket, text: String) {
        // входящее сообщение
    }
}

val wrappedListener = Atlantis.wrapWebSocketListener(originalListener)
okHttpClient.newWebSocket(request, wrappedListener)

Agora você pode observar frames de entrada e saída em tempo real no cliente desktop.

O que tem por dentro

O código-fonte da biblioteca é minimalista e aberto sob a licença Apache 2.0. O repositório quase não tem dependências pesadas de terceiros.

A arquitetura consiste em vários módulos claros:

• AtlantisInterceptor e AtlantisWebSocketListener interceptam dados no nível da pilha de rede.
• GzipCompression e Base64Utils empacotam corpos de requisição e payloads binários, reduzindo a carga no canal de comunicação entre o celular e o computador.
• NsdServiceDiscovery é responsável por descobrir o serviço _proxyman._tcp na rede local via API Android NSD.
• Transporter abre uma conexão TCP com o aplicativo desktop e encaminha pacotes estruturados.

Graças à compressão de tráfego, a depuração praticamente não impacta o desempenho do app.

Limitações que vale a pena conhecer

Antes de integrar a biblioteca, há duas coisas a considerar.

Primeiro, o Atlantis está vinculado ao cliente desktop Proxyman. Se sua equipe está acostumada a usar Wireshark ou Charles exclusivamente, você não poderá encaminhar dados para lá através desse interceptor.

Segundo, a biblioteca intercepta tráfego apenas de clientes onde você adicionou explicitamente o interceptor. Se um SDK de terceiros no seu app faz chamadas de rede através do próprio HttpURLConnection ou Cronet, o Atlantis não verá essas requisições. Para análise completa de binários de terceiros, você ainda precisará usar um proxy MitM clássico.

Vale a pena experimentar

Se sua máquina principal de desenvolvimento roda macOS e você já usa o Proxyman para depurar iOS ou backend, o atlantis-android economiza muito tempo. Você esquece para sempre de configurar proxy Wi-Fi em celulares de teste, resetar certificados e modificar network_security_config. Basta compilar um APK de debug, abrir o app no seu celular, e toda a troca de rede aparece imediatamente na sua tela.