HTTPS-verkeer onderscheppen op Android zonder certificaten en handmatige proxy-configuratie

Iedere Android-ontwikkelaar heeft ooit minstens een halve werkdag besteed aan het instellen van een netwerkdebugger. Het scenario is altijd hetzelfde: je wilt zien wat de app naar de backend stuurt, maar in plaats daarvan krijg je SSLHandshakeException.

Dan begint het ritueel. Eerst genereer je een zelfondertekend CA-certificaat. Vervolgens probeer je het te installeren in de vertrouwde certificatenopslag op je testapparaat. Vanaf Android 7.0 (API 24) negeert het systeem standaard gebruikerscertificaten, dus je moet network_security_config.xml aanpassen, trust-anchors configureren voor debug-builds en de APK opnieuw bouwen. Als je project SSL-pinning heeft geconfigureerd of als je test op Android 14, waar de systeemcertificaatverwerking nog restrictiever is gemaakt, verandert een simpele responsheadercontrole in een aparte technische taak.

De atlantis-android-bibliotheek van het Proxyman-team lost deze hoofdpijn radicaal op: het elimineert de noodzaak om een proxy te configureren en de systeemcertificaten van het apparaat aan te raken.

Wat is het idee achter Atlantis

Traditionele tools zoals Charles, Fiddler of Proxyman zelf werken meestal volgens een Man-in-the-Middle (MitM)-schema. Het apparaat leidt al het verkeer om naar het IP-adres van de computer, en de desktop-applicatie onderschept de verzoeken, ontsleutelt ze met zijn eigen certificaat en stuurt ze door. Dit is precies waarom certificaatvertrouwensproblemen en Wi-Fi-proxy-configuratie problematisch worden.

Atlantis werkt anders. Het is een compacte Kotlin-bibliotheek die direct wordt ingebed in de debug-build van de app als een netwerkclient-interceptor. De interceptor leest de parameters van verzoek en antwoord op het moment dat de app ze al heeft gevormd of zojuist heeft ontsleuteld. De bibliotheek serialiseert deze gegevens vervolgens, comprimeert ze via GZIP en verzendt ze rechtstreeks naar de Proxyman-app op macOS via een aparte lokale socket.

Het resultaat is een gedetailleerd logboek van netwerkactiviteit zonder enige tussenkomst in Android-instellingen, zonder manifestwijzigingen en zonder certificaatmanipulatie.

Wat de bibliotheek kan doen

Atlantis dekt de meeste dagelijkse netwerkdebugging-taken:

• Onderschepping van reguliere HTTP- en HTTPS-verzoeken rechtstreeks vanuit OkHttp.
• Loggen van WebSocket-evenementen: het openen van verbindingen, het verzenden van berichten, inkomende pakketten en het sluiten van sessies.
• Volledige compatibiliteit met populaire netwerkclients, waaronder Retrofit 2.9+ en Apollo Kotlin 3.x/4.x.
• Automatische detectie van een draaiende Proxyman-instantie op het lokale netwerk via Network Service Discovery (mDNS).

Als je het project uitvoert op de officiële Android-emulator, kan de bibliotheek rechtstreeks verbinding maken met de hostmachine, waarbij netwerkdetectie wordt omzeild.

Hoe te integreren in je project

De bibliotheek vereist Android met API 26 (Android 8.0) of hoger, OkHttp versie 4.x of 5.x en Kotlin versie 1.9 of hoger.

Voeg eerst de JitPack-repository toe aan je settings.gradle.kts-bestand:

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

Voeg daarna de afhankelijkheid toe aan de build.gradle.kts van je app. Het is het beste om dit strikt via debugImplementation toe te voegen om ervoor te zorgen dat debug-code niet in release-builds terechtkomt:

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

De bibliotheek is ook beschikbaar in Maven Central onder de artifact com.proxyman:atlantis-android:1.0.0.

Snelle start

Integratie kost slechts een paar regels code. Initialiseer eerst Atlantis in je Application-klasse:

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

Voeg vervolgens de interceptor toe aan je OkHttpClient-configuratie:

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

Als je Retrofit gebruikt, geef dan deze okHttpClient-instantie door aan Retrofit.Builder(), en alle verzoeken verschijnen automatisch in het Proxyman-venster.

Werken met WebSocket

Als je app websockets gebruikt, is de standaard OkHttp-interceptor niet voldoende, aangezien berichten worden verzonden binnen een reeds geopende verbinding. Voor zulke gevallen biedt de bibliotheek een speciale wrapper voor de 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)

Nu kun je inkomende en uitgaande frames in realtime observeren in de desktop-client.

Wat zit erin

De broncode van de bibliotheek is minimaal en open onder de Apache 2.0-licentie. De repository heeft vrijwel geen zware externe afhankelijkheden.

De architectuur bestaat uit verschillende duidelijke modules:

• AtlantisInterceptor en AtlantisWebSocketListener onderscheppen gegevens op het niveau van de netwerkstack.
• GzipCompression en Base64Utils verpakken request-bodies en binaire payloads, waardoor de belasting op het communicatiekanaal tussen telefoon en computer wordt verminderd.
• NsdServiceDiscovery is verantwoordelijk voor het detecteren van de _proxyman._tcp-service op het lokale netwerk via de Android NSD API.
• Transporter opent een TCP-verbinding met de desktop-applicatie en stuurt gestructureerde pakketten door.

Dankzij verkeerscompressie heeft debugging vrijwel geen impact op de prestaties van de app.

Beperkingen om rekening mee te houden

Voordat je de bibliotheek integreert, zijn er twee zaken om te overwegen.

Ten eerste is Atlantis gekoppeld aan de Proxyman desktop-client. Als je team gewend is om uitsluitend Wireshark of Charles te gebruiken, kun je via deze interceptor geen gegevens naar daar doorsturen.

Ten tweede onderschept de bibliotheek alleen verkeer van clients waar je de interceptor expliciet aan hebt toegevoegd. Als een SDK van derden in je app netwerkoproepen maakt via zijn eigen HttpURLConnection of Cronet, zal Atlantis die verzoeken niet zien. Voor complete analyse van binaries van derden moet je nog steeds een klassieke MitM-proxy gebruiken.

Is het de moeite waard om te proberen

Als je hoofdontwikkelmachine macOS draait en je Proxyman al gebruikt voor het debuggen van iOS of backend, bespaart atlantis-android veel tijd. Je vergeet voor altijd het instellen van Wi-Fi-proxy op testtelefoons, het resetten van certificaten en het aanpassen van network_security_config. Bouw gewoon een debug-APK, open de app op je telefoon, en de volledige netwerkuitwisseling verschijnt onmiddellijk op je scherm.