Charles Proxy

Charles Proxy erleichtert das Debuggen von HTTP-Anfragen, indem es als Man-in-the-Middle-Proxy fungiert, den gesamten Netzwerkverkehr zwischen einer Client-Anwendung und Zielservern erfasst und dessen Inspektion und Modifikation ermöglicht.

Charles Proxy fungiert als lokaler HTTP-Proxyserver, der es Entwicklern und QA-Ingenieuren ermöglicht, die Netzwerkkommunikation zu beobachten, abzufangen und zu manipulieren. Diese Fähigkeit ist entscheidend, um Client-Server-Interaktionen zu verstehen, Integrationsprobleme zu diagnostizieren, Grenzfälle zu testen und das API-Verhalten zu überprüfen, insbesondere bei der Arbeit mit oder der Entwicklung von Diensten, die mit einem Upstream-Proxy interagieren.

Charles Proxy einrichten

Installation und erster Start

Laden Sie Charles Proxy von der offiziellen Website herunter und installieren Sie es. Beim ersten Start versucht Charles normalerweise, sich als System-Proxy zu konfigurieren. Akzeptieren Sie diese Aufforderung, damit Charles den Datenverkehr von Anwendungen abfangen kann, die die System-Proxy-Einstellungen respektieren.

System-Proxy-Einstellungen konfigurieren

Wenn Charles läuft, setzt es die HTTP/HTTPS-Proxy-Einstellungen des Systems automatisch auf 127.0.0.1 (localhost) auf Port 8888 (Standard). Die meisten Anwendungen, einschließlich Webbrowser, respektieren diese Einstellungen.

Zur Überprüfung oder manuellen Konfiguration:
* macOS: Systemeinstellungen > Netzwerk > Wi-Fi/Ethernet > Details > Proxies. Stellen Sie sicher, dass "Web-Proxy (HTTP)" und "Sicherer Web-Proxy (HTTPS)" aktiviert sind und auf 127.0.0.1:8888 zeigen.
* Windows: Einstellungen > Netzwerk & Internet > Proxy > Manuelle Proxy-Einrichtung. Stellen Sie sicher, dass "Proxyserver verwenden" mit 127.0.0.1 und Port 8888 aktiviert ist.
* Linux (GNOME): Einstellungen > Netzwerk > Netzwerk-Proxy. Stellen Sie die Methode auf "Manuell" ein und konfigurieren Sie den HTTP/HTTPS-Proxy auf 127.0.0.1:8888.

Client-Anwendungen konfigurieren

Einige Anwendungen, insbesondere Kommandozeilen-Tools oder spezifische SDKs, respektieren möglicherweise keine systemweiten Proxy-Einstellungen. In diesen Fällen konfigurieren Sie die Anwendung direkt.

Beispiel: curl mit Proxy

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

Beispiel: Node.js axios mit 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 für HTTPS-Verkehr

Um HTTPS-Verkehr zu inspizieren, muss Charles Proxy SSL- (oder TLS-) Proxying durchführen. Dies beinhaltet, dass Charles Zertifikate für die Zieldomains generiert und signiert, diese dem Client präsentiert und dann seine eigene sichere Verbindung zum echten Server herstellt.

Charles Root-Zertifikat installieren

Die Client-Anwendung muss das Root-Zertifikat von Charles vertrauen, damit das SSL-Proxying ohne Sicherheitswarnungen funktioniert.

• Desktop-Browser/System:
  • Navigieren Sie zu Help > SSL Proxying > Install Charles Root Certificate. Befolgen Sie die OS-spezifischen Anweisungen, um es im Speicher für vertrauenswürdige Root-Zertifikate des Systems zu installieren.
• Mobile Geräte:
  • Konfigurieren Sie das mobile Gerät so, dass es Charles als HTTP-Proxy verwendet (z.B. ihre_mac_ip:8888).
  • Navigieren Sie auf dem Gerät zu chls.pro/ssl und folgen Sie den Anweisungen zum Herunterladen und Installieren des Zertifikats.

SSL-Proxying für bestimmte Hosts aktivieren

Nach der Installation des Root-Zertifikats aktivieren Sie das SSL-Proxying für die spezifischen Hosts, die Sie inspizieren möchten.

1. Gehen Sie zu Proxy > SSL Proxying Settings....
2. Klicken Sie auf "Add".
3. Geben Sie den Host (z.B. api.example.com, *.example.com für einen Wildcard oder * für alle Hosts) und den Port (typischerweise 443 für HTTPS oder * für alle Ports) ein.
4. Klicken Sie auf "OK" und dann erneut auf "OK".

Der Datenverkehr zu den angegebenen Hosts wird nun entschlüsselt und ist in Charles sichtbar.

Wichtige Debugging-Funktionen

Verkehrsüberwachung und -filterung

Die Ansichten "Structure" und "Sequence" zeigen erfasste Anfragen an.
* Sequence View: Zeigt Anfragen in chronologischer Reihenfolge an.
* Structure View: Organisiert Anfragen nach Host und Pfad.

Um sich auf relevanten Verkehr zu konzentrieren:
* Filterfeld: Verwenden Sie das Filterfeld oben im Charles-Fenster, um URLs, Hosts oder Inhalte abzugleichen.
* Fokus-Tool: Klicken Sie mit der rechten Maustaste auf eine Anfrage und wählen Sie "Focus", um alle anderen Hosts aus der aktuellen Ansicht auszublenden.
* Aufnahme-Button: Schalten Sie den Aufnahme-Button (roter Kreis) um, um die Erfassung des Datenverkehrs zu starten/stoppen.

Breakpoints

Breakpoints ermöglichen es Ihnen, Anfragen anzuhalten und zu modifizieren, bevor sie an den Server gesendet werden, oder Antworten, bevor sie an den Client gesendet werden.

1. Gehen Sie zu Proxy > Breakpoints Settings....
2. Klicken Sie auf "Add" für Anfragen oder Antworten.
3. Geben Sie den Host und Path an (z.B. /login).
4. Wenn eine Anfrage/Antwort übereinstimmt, hält Charles an und ein "Breakpoints"-Tab erscheint.
5. Modifizieren Sie Header, Abfrageparameter oder den Body.
6. Klicken Sie auf "Execute", um die modifizierte Anfrage/Antwort zu senden.

Rewrite-Tool

Das Rewrite-Tool bietet automatisierte, persistente Modifikationen von Anfragen und Antworten. Dies ist nützlich, um spezifische Serververhaltensweisen oder Client-Bedingungen ohne manuelles Eingreifen zu simulieren.

1. Gehen Sie zu Tools > Rewrite....
2. Aktivieren Sie Rewrite und fügen Sie ein neues "Set" hinzu.
3. Fügen Sie "Locations" (URLs, auf die Regeln angewendet werden sollen) unter Verwendung von Host und Path hinzu.
4. Fügen Sie "Rules" innerhalb des Sets hinzu:
   • Add Header/Remove Header: HTTP-Header modifizieren.
   • Change Query Parameter: URL-Abfrageparameter modifizieren.
   • Body Replace: Text innerhalb des Anfrage-/Antwort-Bodys suchen und ersetzen.
   • URL Replace: Teile der Anfrage-URL modifizieren.

Beispiel: Modifizieren eines API-Antwort-Bodys
Eine Rewrite-Regel könnte {"status": "active"} durch {"status": "maintenance"} in einer JSON-Antwort ersetzen, um zu testen, wie ein Client verschiedene Zustände verarbeitet.

Map Local / Map Remote

Diese Tools leiten Anfragen an verschiedene Quellen um.

• Map Local: Stellt eine lokale Datei anstelle einer Remote-Antwort bereit.

  1. Gehen Sie zu Tools > Map Local....
  2. Aktivieren Sie Map Local und fügen Sie einen neuen Eintrag hinzu.
  3. Geben Sie den Host und Path der Remote-URL an.
  4. Wählen Sie den lokalen File-Pfad aus, der bereitgestellt werden soll.
     Dies ist nützlich, um schnell UI-Änderungen zu testen oder spezifische API-Antworten zu simulieren, ohne das Backend zu modifizieren.

• Map Remote: Leitet eine Anfrage für eine URL an eine völlig andere URL um.

  1. Gehen Sie zu Tools > Map Remote....
  2. Aktivieren Sie Map Remote und fügen Sie einen neuen Eintrag hinzu.
  3. Geben Sie den Host und Path der ursprünglichen Anfrage an.
  4. Geben Sie den neuen Host und Path für die umgeleitete Anfrage an.
     Nützlich, um API-Aufrufe an eine Staging-Umgebung oder einen lokalen Entwicklungsserver umzuleiten.

Drosselung (Throttling)

Die Drosselung simuliert langsame Netzwerkbedingungen und hilft dabei, Leistungsengpässe oder UI-Probleme im Zusammenhang mit langsamem Datenladen zu identifizieren.

1. Gehen Sie zu Proxy > Throttle Settings....
2. Aktivieren Sie "Enable Throttling".
3. Konfigurieren Sie die Parameter Bandwidth, Utilisation und Latency.
4. Wählen Sie optional "Only for selected hosts" und fügen Sie spezifische Hosts hinzu, die gedrosselt werden sollen.

Wiederholen / Erweitertes Wiederholen

Diese Funktionen ermöglichen das erneute Senden von Anfragen.

• Wiederholen: Klicken Sie mit der rechten Maustaste auf eine Anfrage und wählen Sie "Repeat", um sie sofort erneut zu senden.
• Erweitertes Wiederholen: Klicken Sie mit der rechten Maustaste auf eine Anfrage und wählen Sie "Advanced Repeat", um sie mehrmals mit anpassbarer Parallelität und Iterationsanzahl zu senden. Dies ist nützlich für Lasttests oder die Überprüfung von Race Conditions.

Debugging von Upstream-Proxy-Interaktionen

Wenn Ihre Client-Anwendung für die Verwendung von Charles konfiguriert ist und Charles selbst für die Verwendung eines Upstream-Proxys (z.B. eines Unternehmens-Proxys) konfiguriert ist, fungiert Charles als Vermittler.

So konfigurieren Sie Charles für die Verwendung eines Upstream-Proxys:
1. Gehen Sie zu Proxy > External Proxy Settings....
2. Aktivieren Sie "Use external proxy".
3. Geben Sie den Host, Port und alle erforderlichen Username/Password für Ihren Upstream-Proxy ein.
4. Aktivieren Sie "SOCKS proxy", wenn Ihr Upstream-Proxy ein SOCKS-Proxy ist.

In dieser Konfiguration erfasst Charles den Datenverkehr von Ihrem Client und leitet ihn dann an den Upstream-Proxy weiter. Dies ermöglicht es Ihnen, den Datenverkehr zu inspizieren, bevor er den Upstream-Proxy erreicht, was entscheidend ist, um Probleme zu diagnostizieren, bei denen der Upstream-Proxy Anfragen modifizieren oder bestimmte Endpunkte blockieren könnte.

Häufige Probleme und Fehlerbehebung

| Problem | Lösung