Chute Dashboard

Chute Dashboard est une application macOS gratuite qui se connecte à un Chute en cours d'exécution — Chute iOS par Wi-Fi ou câble USB, Chute Android par le réseau ou adb, ou Chute Mac sur la même machine — et montre ce que fait cette instance : chaque connexion avec la règle et la politique qui l'ont décidée, la requête et la réponse déchiffrées pour les hôtes couverts par le déchiffrement HTTPS, les réponses DNS, les sessions UDP. Elle permet aussi de façonner le trafic pendant que vous l'observez : la liste des hôtes MitM et chaque famille de règles de réécriture et de réponse simulée se modifient en direct.

Ce n'est pas la Console web. La console est servie par le moteur lui-même et s'ouvre dans un navigateur ; Dashboard est une application distincte qui parle au moteur par son canal de contrôle binaire, et c'est pourquoi elle a besoin d'external-controller-access sur l'appareil plutôt que d'external-http-controller. Les deux se recouvrent, et chacune a des choses que l'autre n'a pas — voir Ce que Dashboard ne peut pas atteindre. Un Dashboard sur le même Mac que le moteur fait exception : il se connecte à un socket local que le moteur ouvre toujours, et n'a besoin d'aucune configuration.

L'interface de Dashboard est localisée dans les mêmes langues que ce manuel, sauf l'arabe ; sur un système en arabe elle s'affiche en anglais.

Autoriser Dashboard à se connecter

Rien n'écoute tant que l'appareil ne l'a pas dit.

Chute iOS — dans l'éditeur de configuration, ouvrez Contrôleur externe :

1. Activez Accès au contrôleur externe — l'interrupteur dont la note de bas de section indique Autoriser Chute Dashboard/Chute CLI à se connecter.
2. Définissez un Port et un Mot de passe. Le mot de passe ne peut pas être vide, et il doit être le vôtre : un écouteur joignable depuis le réseau refuse de démarrer avec un mot de passe vide ou par défaut.
3. Laissez Autoriser l'accès depuis le Wi-Fi désactivé sauf besoin. Désactivé est la valeur par défaut et signifie que l'écouteur reste sur le téléphone lui-même — un câble USB l'atteint encore, les autres appareils du Wi-Fi non. Activé signifie que quiconque sur le réseau connaît le mot de passe peut lire tout ce que cette exécution a vu.
4. Enregistrez, puis démarrez (ou redémarrez) le tunnel. Le panneau de configuration affiche désormais Port d'accès externe : <port> — cette ligne confirme que l'écouteur est en place.

Chute Mac — les trois mêmes valeurs se trouvent dans [General] :

[General]
external-controller-access = password@127.0.0.1:6170

127.0.0.1 le limite au Mac où vous êtes ; une adresse du réseau local ou 0.0.0.0 l'ouvre aux autres machines. La section Général de la fenêtre de configuration a des champs pour la même clé. Un Dashboard qui tourne sur ce même Mac n'a pas besoin de cette clé du tout — voir Se connecter à la machine locale ci-dessous.

Chute Android — dans l'éditeur de configuration, ouvrez Contrôleur externe et écrivez la même valeur dans Accès externe :

• password@127.0.0.1:6170 suffit pour Se connecter via USB : Dashboard lance adb forward pour ce port et se connecte par le câble, si bien que l'écouteur peut rester sur le téléphone lui-même. Il faut adb sur le Mac — Dashboard le cherche sous ANDROID_HOME et ANDROID_SDK_ROOT, dans le PATH, dans /usr/local/bin et /opt/homebrew/bin, et dans ~/Library/Android/sdk — ainsi que le débogage USB activé sur le téléphone, avec ce Mac autorisé.
• password@0.0.0.0:6170 l'ouvre au réseau pour Se connecter à une machine distante. Comme sur iOS, un écouteur joignable depuis le réseau refuse de démarrer avec un mot de passe vide ou par défaut.

Enregistrez, puis démarrez (ou redémarrez) le VPN. L'interrupteur Accès externe du panneau de configuration affiche alors l'adresse sur laquelle il écoute, et coupe ou relance l'écouteur tant que le VPN tourne.

Se connecter

Dashboard s'ouvre sur la fenêtre Nouveau tableau de bord ; chaque connexion a sa propre fenêtre, on peut donc ouvrir plusieurs appareils à la fois. Trois façons d'entrer :

Une machine distante n'est mémorisée que si vous l'enregistrez : Enregistrer garde l'hôte, le port et le mot de passe sous un nom que vous choisissez, et ce sont ces noms que l'onglet Machine enregistrée liste la fois suivante.

Si le mot de passe est faux, la fenêtre indique Mot de passe incorrect, en USB comme par le réseau. Si l'appareil est injoignable, la fenêtre s'ouvre quand même et affiche Connexion… : avec un iPhone en USB, elle y reste tant que Dashboard réessaie, jusqu'à ce que le téléphone réponde ou que vous cliquiez sur Fermer ; toute autre connexion finit sur Connexion fermée. Si l'appareil disparaît ensuite — tunnel arrêté, câble débranché, téléphone qui a changé de réseau — la fenêtre Dashboard signale Connexion fermée et propose Reconnecter.

La fenêtre

La barre d'outils bascule entre cinq vues — Récent, Actif, DNS, UDP et MitM — et son champ Filtrer, à droite, est une zone de recherche pour le motif d'hôte, partagée avec la barre de filtres. Cette barre n'apparaît d'elle-même que sur Récent et Actif, et reste masquée sur DNS, UDP et MitM. Le panneau en bas à gauche est la vitesse d'envoi et de réception en direct ; cliquez dessus pour déplier le graphique.

Les vues Récent et Actif portent chacune un bouton Recharger, et Récent un Effacer qui vide la liste. À côté d'eux se trouvent deux interrupteurs qui agissent sur le moteur en cours d'exécution, exactement comme ceux des applications :

• Activer la capture du trafic → Désactiver la capture du trafic : active la capture des corps de requête et de réponse (le réglage replica). Sans lui, les lignes apparaissent quand même avec leur routage, mais les onglets de données ne peuvent pas être sélectionnés. Le bouton affiche Capture du trafic tant que l'appareil n'a pas indiqué dans quel sens il est réglé.
• Activer MitM (N règles) → Désactiver MitM (N règles) : active le déchiffrement HTTPS pour les N hôtes de la liste MitM ; avec une liste vide, le nombre est omis. L'interrupteur ne fait rien d'utile tant que l'appareil n'a pas un CA approuvé et au moins un hôte — voir la page Déchiffrement HTTPS.

Aucun des deux interrupteurs ne modifie le fichier de configuration ; un redémarrage revient à ce que dit le fichier.

La barre latérale groupe les connexions par client : Tous les clients, puis Local pour les clients sur l'appareil lui-même et Distant pour les autres machines qui utilisent ce Chute comme proxy. En sélectionner un restreint toutes les listes. Quand l'appareil est Chute Mac, les clients locaux sont les applications, avec nom et icône, et le menu contextuel propose Afficher dans le Finder.

Actif et Récent

Actif est ce qui est ouvert en ce moment ; Récent est l'historique de l'appareil, relu depuis les enregistrements de l'exécution et classé par numéro de connexion — le plus récent en bas. Cliquez sur un en-tête de colonne pour trier par cette colonne. Les deux partagent les mêmes colonnes :

La colonne Indicateurs est le moyen le plus rapide de savoir si une règle que vous avez écrite s'applique :

B ne dépend que d'un changement du contenu du corps : un corps que Chute a seulement retenu pour le confronter aux règles, ou redécoupé en blocs ou recompressé sans en changer le contenu, n'est pas marqué.

Récent conserve jusqu'à 5 000 lignes ; Charger les plus anciens au bas de la liste récupère la page suivante depuis l'appareil, et la liste se rafraîchit d'elle-même toutes les quelques secondes. Quand la liste active est plus longue que ce qu'un paquet de contrôle peut porter, une note sous le tableau dit que le moteur l'a tronquée — les lignes sont bien sur l'appareil, et Récent les montrera une fois fermées.

Un clic droit sur une ligne propose Copier la commande curl, Exporter la sélection en HAR… / CSV…, Tout exporter en HAR… / CSV… et Filtrer sur <host> ; une ligne active propose en plus Fermer la connexion, qui la ferme sur l'appareil. Un clic droit à l'intérieur d'une sélection de plusieurs lignes la conserve, si bien que Exporter la sélection en HAR… / CSV… prennent toutes les lignes sélectionnées ; les entrées propres à une connexion agissent sur la ligne cliquée. Quatre autres entrées agissent sur les règles de l'appareil pour cet hôte, le plus court chemin entre une connexion que vous regardez et la règle qui la modifie : Ajouter une règle MitM pour, Activer MitM pour, Ajouter une réécriture d'en-tête pour et Ajouter une réécriture de corps pour <host>.

Remarque : Une ligne est une connexion, pas une requête. Une connexion keep-alive qui a porté plusieurs requêtes reste une seule ligne, et les données capturées contiennent tous ces messages à la suite ; les en-têtes affichés sont ceux d'une des requêtes. Un navigateur qui ouvre une page produit donc moins de lignes que la page n'a de ressources.

La barre de filtres

La barre de filtres restreint ce qui est affiché. Elle ne change pas ce que l'appareil enregistre — pour cela, utilisez [Replica] sur l'appareil.

Effacer les filtres revient à tout afficher.

Détail d'une connexion

Sélectionnez une ligne : son détail s'ouvre dans un panneau sous la liste. Les onglets, de gauche à droite :

Général — ce que montre la liste, avec de la place : le type de connexion et le code d'état ; le mode de sortie, la politique et la règle correspondante ; le volume et les vitesses de pointe ; les adresses locale et distante ; l'heure de début ; l'état SSL/MitM (Intercepté, En-tête modifié, Corps modifié, Simulé) ; et Règles déclenchées — les règles de réécriture et de réponse simulée qui ont modifié cette connexion, citées dans leurs propres termes. La liste est plafonnée aux deux bouts : le moteur ne retient que 16 déclenchements au plus par connexion, et Dashboard en affiche 8 puis ajoute … N de plus, si bien qu'une règle qui se déclenche sur chaque fragment évince les autres.

Chronologie — comment s'est répartie la mise en place de la connexion, telle que le moteur l'a mesurée :

Une ligne dont la valeur est zéro est omise plutôt qu'affichée à zéro : une connexion dont la règle n'avait besoin d'aucune adresse n'a donc pas de ligne Résolution DNS du tout. Une requête lente l'est généralement dans exactement une des autres, et laquelle indique où chercher : DNS dans la section DNS, Préparation du distant dans la politique ou le serveur derrière elle.

En-têtes requête / En-têtes réponse — les en-têtes en tableau, avec Paramètres de requête et Cookies séparés pour la requête et Cookies pour la réponse. Un en-tête modifié par une règle est mis en évidence. Copier la sélection copie les lignes sélectionnées.

Données requête / Données réponse — le corps capturé, en Hex, Texte, JSON (un arbre dépliable, avec recherche) ou Image (Ajuster / Taille réelle) ; il s'ouvre en Texte, quel que soit le corps, et les corps multipart sont découpés en leurs parties. Exporter en bin enregistre les octets bruts, et la vue Texte propose Ouvrir dans Sublime Text et Ouvrir dans VSCode quand l'un ou l'autre est installé. Les deux onglets ne peuvent être sélectionnés que s'il y a des données capturées : l'enregistrement était actif quand la connexion a eu lieu, et les filtres de [Replica] ont laissé passer l'hôte.

Remarque : Les corps sont affichés tels qu'ils ont été capturés. Une réponse compressée — Content-Encoding: gzip — n'est pas décompressée ici, ses vues Texte et JSON sont donc du bruit ; la vue Hex et Exporter en bin vous donnent les octets à décompresser ailleurs. L'appareil refuse de livrer un corps de plus de 2 MiB — l'onglet affiche alors Impossible de charger ce corps — et la vue Hex montre le premier MiB.

DNS et UDP

DNS est le cache du résolveur de l'appareil : chaque domaine avec les adresses vers lesquelles il a été résolu, le serveur qui a répondu en premier (Chute interroge tous les serveurs configurés à la fois — voir DNS), le TTL et la provenance de l'enregistrement. Cette dernière colonne est l'origine — Config, System ou Dynamic — et non un type d'enregistrement DNS. Le TTL est rapporté comme valant au moins 600 secondes ; un TTL plus court s'affiche donc à 600.

Clic droit pour Copier le domaine, Copier les IP, Copier le serveur DNS et Filtrer sur <domain> ; un enregistrement résolu dynamiquement propose en plus Supprimer l'enregistrement DNS de <domain>. Purger le cache DNS, en bas, vide complètement le cache. Ces deux dernières actions agissent sur le cache de l'appareil, pas sur la vue qu'en a Dashboard.

UDP liste les sessions UDP — hôte, serveur, politique et état. Il n'y a pas de corps pour l'UDP.

Outils MitM

La vue MitM gère les cinq familles de règles de l'appareil, dans cinq panneaux : Règles MitM, Réécriture d'en-tête, Réécriture de corps, Réponse simulée et Réécriture d'URL. Ce qui est vrai pour tous :

• La liste est la copie des règles du moteur en cours d'exécution, qui part de ce que le fichier de configuration a déclaré.
• Ajouter une règle l'envoie à l'appareil, qui l'analyse comme il analyserait une ligne de configuration ; une ligne qui ne s'analyse pas est refusée avec une erreur plutôt qu'enregistrée. Un hôte des Règles MitM fait exception — c'est un motif, pas une ligne de règle, et toute chaîne non vide est ajoutée telle quelle.
• Les changements ne vivent que dans le moteur en cours d'exécution. Ils ne sont pas écrits dans le fichier de configuration, et un rechargement ou un redémarrage ramène ce que dit le fichier. Servez-vous des panneaux pour trouver la règle qui marche, puis écrivez-la dans la configuration.
• Qu'une règle s'applique ou non se voit dans la colonne Indicateurs de la liste (R, K) et dans Règles déclenchées du panneau de détail.

Règles MitM — un motif d'hôte par règle, host[:port][/path], avec le préfixe - pour exclure : *.google.com, api.example.com:8443, api.example.com/v2/*, -*.apple.com. La même grammaire que la clé hostname de la page Déchiffrement HTTPS. Le nombre sur l'interrupteur MitM de la barre d'outils est la longueur de cette liste.

Réécriture d'en-tête — un formulaire : Regex d'URL, Requête ou Réponse, Ajouter / Remplacer / Supprimer / Remplacer (regex), Nom de l'en-tête, Valeur de l'en-tête ; avec Remplacer (regex) s'ajoute une Regex de la valeur, dont les correspondances dans la valeur de l'en-tête sont remplacées par le Remplacement. Dashboard compose la ligne de configuration pour vous ; la grammaire est sur la page Réécriture d'en-tête.

Réécriture de corps — une ligne de configuration, saisie comme vous l'écririez dans le fichier, dans n'importe laquelle des formes que lit le moteur : celle de Surge http-response url-regex pattern replacement (ou http-request), sa forme http-response-jq url-regex jq-program (ou http-request-jq), url-regex response regex pattern replacement (ou request) et url-regex jsonpath-response jsonpath $.path value (ou jsonpath-request). Voir Réécriture de corps.

Réponse simulée — Regex d'URL, le type du Corps de la réponse : file (un chemin ; Parcourir…), text, base64 ou tiny-gif (un GIF transparent 1×1 intégré, sans contenu), un Code de statut facultatif et des En-têtes de réponse facultatifs sous forme de paires Nom: Valeur séparées par |.

Remarque : Le chemin d'un file est lu par l'appareil qui exécute Chute, au moment de la requête. Un chemin sur votre Mac a un sens quand Dashboard est connecté à Chute Mac sur cette même machine, et n'en a aucun quand il est connecté à un iPhone — le téléphone n'a pas de /Users/…. Pour un appareil distant, choisissez text ou base64 pour que le contenu voyage dans la règle (voir Réponse simulée), ou servez le fichier depuis une URL et utilisez la réécriture d'URL.

Réécriture d'URL — Regex d'URL, Cible et Type : header réécrit la requête sur place (le Map Remote de Surge), 302 et 307 redirigent le client, et reject, reject-200, reject-img, reject-dict, reject-array, reject-tinygif répondent sans contacter le serveur. Voir Réécriture d'URL.

Exporter

• HAR — clic droit sur la liste : les lignes sélectionnées ou toutes, en fichier HAR 1.2 à ouvrir dans les outils de développement d'un navigateur (Réseau → importer), Charles ou Proxyman. Une entrée par ligne dont une requête HTTP a été capturée ; les autres — du TCP brut, par exemple — sont laissées de côté, et le commentaire du fichier dit combien. Les corps sont inclus si l'enregistrement était actif : Dashboard les récupère d'abord sur l'appareil, sous une feuille qui affiche Exportation en HAR… — Récupération des corps capturés depuis l'appareil. —, avec une barre de progression et Annuler, qui abandonne l'export. Un corps de plus de 512 KiB n'est consigné que par sa taille, et un export porte au plus 64 MiB de corps.
• CSV — un ensemble fixe de colonnes pour un tableur : ID,Method,URL,Status Code,Status,Duration,Upload,Download,Process,Start Time. Ce ne sont pas les colonnes de la liste ; il n'y a ni colonne Date, ni Client, ni Serveur, ni Politique, ni Indicateurs. Method est la méthode de la requête et URL l'URL complète, comme dans l'export HAR : du HTTPS passé par le proxy HTTP sans être déchiffré donne CONNECT et https://host. Une ligne sans requête HTTP — TCP simple, ou HTTPS que TUN a acheminé sans le déchiffrer — y donne à la place son type de connexion et son hôte.
• Copier la commande curl — un appel curl qui rejoue la requête depuis votre Mac, avec sa méthode, ses en-têtes et son corps ; le corps est d'abord récupéré sur l'appareil. Content-Length est laissé au calcul de curl. Une ligne qui n'est qu'un tunnel — un CONNECT non déchiffré, ou du TCP brut — ne donne que curl et l'URL.
• Exporter en bin — un corps, tel que capturé.

Dashboard construit son HAR à partir de la liste et des corps qu'il récupère sur l'appareil. Le moteur peut aussi en construire un lui-même — avec la règle correspondante, la politique et les réécritures déclenchées dans un objet _kl par entrée, et des temps d'envoi et de réception pris dans la capture — via Exporter en HAR de la console ou GET /api/connections/export?format=har.

Ce que Dashboard ne peut pas atteindre

Dashboard parle le canal de contrôle binaire du moteur, et une partie de ce que sait faire le moteur n'existe que sur l'API de contrôle HTTP. Pour cela, utilisez la console web ou l'API :

• l'ensemble de diagnostic, la santé, les compteurs de refus et les événements ;
• les totaux de déclenchement par règle de la page Règles de la console, et la réponse qu'ils donnent à cette règle s'est-elle jamais déclenchée ;
• le HAR du moteur, ci-dessus ;
• le journal.

Encore une chose à savoir avant de vous y fier :

• Sur iPhone, Apple TV et Android, le déchiffrement HTTPS et la capture des corps sont des fonctions sous licence. Sans licence, Dashboard se connecte quand même et montre chaque connexion avec sa règle et sa politique, mais les lignes HTTPS ne sont jamais déchiffrées — pas d'indicateur M — et les onglets de données ne peuvent pas être sélectionnés. Sur iPhone et Android, l'interrupteur MitM de l'application ne reste pas activé et une invite d'achat s'affiche à la place ; l'Apple TV n'a aucune ligne MitM sur son panneau de configuration. Voir Licence et activation.