🔍 Capture et inspection

• Intercepte le trafic HTTP et HTTPS (avec prise en charge du certificat CA MITM).
• Affiche toutes les métadonnées, en-têtes et corps des requêtes et réponses.
• Prend en charge la troncature pour les corps très volumineux.

💾 Persistance

• Les captures et les règles de couleur sont stockées dans captures.json (ou un fichier spécifié).
• Recharge automatiquement l'état au démarrage et enregistre périodiquement sur le disque.
• Les règles de couleur par défaut sont générées lors de la première exécution si aucune n'existe.

🖥️ Interface utilisateur Web

• Interface web embarquée et réactive (servie par le proxy lui-même).
• Affiche les captures dans une liste défilante avec des indicateurs de couleur.
• Panneau de détails montrant :
  • En-têtes/corps de la requête et de la réponse
  • Répartitions temporelles
  • Notes modifiables
  • Graphique de performance de type Gantt pour les phases de connexion

🎨 Règles de couleur

• Définir des surlignages conditionnels pour les captures en utilisant une syntaxe de filtre flexible :
  • Exemple : status:4 status:5 → surligne les erreurs HTTP
  • Exemple : url:/api/ → surligne les requêtes API
  • Exemple : /\.css$/ → correspondance regex sur l'URL
• Chaque règle comprend :
  • Nom, couleur, expression de correspondance, priorité et note
• La correspondance avec la priorité la plus élevée l'emporte.
• Gérée de manière interactive via une interface modale avec aperçus en direct.
• Persistée entre les sessions.

⏸️ Contrôle de la capture

• Bouton Pause/Reprendre permettant d'arrêter la collecte de nouvelles captures sans arrêter le proxy.
• Utile pour se concentrer sur un ensemble de données fixe ou isoler un comportement spécifique.

📈 Visualisation des performances

• Chaque capture comprend une temporisation détaillée de la connexion :
  • Résolution DNS
  • Connexion TCP
  • Établissement TLS
  • Traitement serveur
  • Lecture de la réponse
• Affichée sous forme de diagramme de Gantt dans le panneau de détails.
• L'échelle s'arrondit automatiquement à la seconde la plus proche pour plus de lisibilité.

🧭 Filtrage et recherche

• Boîte de filtrage en temps réel prenant en charge :
  • Filtres basés sur des champs (method:GET, status:404, header:Content-Type=application/json)
  • Expressions régulières (/login/)
  • Termes combinés avec une sémantique ET/OU
• Correspondance partielle et insensible à la casse.
• Le filtre s'applique à la fois à la liste des captures et au surlignage coloré.
• L'historique de recherche est stocké localement dans le navigateur.

🧹 Gestion

• Supprimer des captures individuelles ou effacer toutes les captures via l'interface.
• Les règles et les notes sont persistées avec les captures.

🧩 Utilitaires d'exportation

• Copier une capture sous forme de :
  • Commande curl (formatée pour le terminal)
  • Extrait de code python requests (représentation JSON propre)
• Télécharger les corps de réponse directement depuis l'interface.

Utilisation en ligne de commande

Démarrage rapide

Construction (à partir des sources)

Cela produit un exécutable unique contenant le proxy compilé et les ressources de l'interface utilisateur embarquée.

Exécution (par défaut)

Par défaut, le binaire écoute sur 127.0.0.1:8080 pour le proxy (et optionnellement l'interface — voir les options CLI). Ouvrez l'interface dans un navigateur pour inspecter les captures.

Exemple : utilisation du proxy avec curl

Le trafic capturé apparaîtra dans l'interface web.

Arguments de ligne de commande

Utilisez ./http-breakout-proxy -h pour lister les options disponibles et les descriptions d'utilisation.

Aperçu de l'interface Web

L'interface est optimisée pour les flux de travail d'investigation.

• Barre d'outils supérieure : champ de filtre global (prend en charge les regex et les préfixes clés), boutons Pause/Reprendre la capture, Effacer, et Aide sur le filtrage (s'ouvre dans un nouvel onglet).
• Panneau gauche : liste chronologique des captures (les plus récentes en premier). Chaque élément affiche le nom de la capture ; par défaut il s'agit de METHODE URL [STATUS] mais un nom personnalisé peut être attribué.
• Panneau droit : détails de la capture sélectionnée :
  • Aperçu : métadonnées, en-têtes et corps (JSON formaté le cas échéant).
  • Onglets Requête / Réponse : corps formatés bruts.
  • Onglet Brut : JSON complet de la capture.
• Actions sur les lignes : copier en tant que curl, copier en tant que requests Python, télécharger le corps de la réponse, renommer, supprimer.

Langage de filtrage (référence rapide)

• Jeton simple : correspond partout (méthode, URL, statut, hôte, en-têtes, corps).
• Préfixes : method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
• Syntaxe regex : /motif/drapeaux (par exemple /bearer\\s+\\S+/i).
• Spécification d'en-tête : header:nom=valeur où nom ou valeur peuvent être des regex.
• Les termes sont combinés avec un ET logique par défaut (séparés par des espaces). Passez en OU si souhaité en modifiant la logique client.

Exemples :

• method:POST status:2 host:api.example.com
• /token\\s*[:=]\\s*\\S+/i
• req.header:authorization=/bearer/i
• body:/\\"success\\"\\s*:\\s*true/i

Interception HTTPS (MITM)

Lorsque le mode Homme du Milieu est activé :

1. Le proxy génère une paire de clés CA RSA et un certificat racine, et les stocke dans -ca (par défaut ./ca).
2. Pour inspecter le trafic HTTPS, vous devez ajouter le certificat CA généré (ca.pem ou similaire) au magasin de confiance du client (ou du système) émettant les requêtes. Sur de nombreuses plateformes, cela nécessite des privilèges administratifs.
3. Le proxy effectue l'interception TLS en émettant des certificats feuilles signés par l'autorité de certification locale pour chaque nom d'hôte demandé par le client.

Note de sécurité : Installez l'autorité de certification uniquement dans des environnements contrôlés. Ne faites pas confiance à cette autorité de certification dans des systèmes où vous lisez du trafic sensible non lié.

Persistance

Si la persistance est activée (via -f ou un chemin configuré) :

• Les captures sont périodiquement écrites sur le disque (par exemple captures.json).
• Au démarrage, l'application tente de charger les captures précédentes depuis le fichier de persistance dans le tampon mémoire (en préservant l'ordre).
• Les renommages et suppressions sont synchronisés avec le stockage persistant lors des opérations de sauvegarde ; envisagez d'invoquer un vidage immédiat pour les opérations critiques.

Format de stockage

Les éléments capturés sont sérialisés en JSON et contiennent les champs suivants (liste non exhaustive) :

• id — identifiant unique de séquence
• time — horodatage (ISO 8601)
• method, url
• request_headers, response_headers
• request_body, response_body — tronqués à -max-body si nécessaire
• response_status, duration_ms
• name — étiquette utilisateur optionnelle
• notes, deleted — métadonnées de contrôle pour les événements SSE et l'état de l'interface

Aides à l'exportation et à la relecture

• Copier en tant que cURL : construit une commande curl sécurisée pour le shell, incluant les en-têtes et le corps (omet les en-têtes saut-par-saut).
• Copier en tant que Python : produit un petit extrait requests avec url, headers, et éventuellement data.
• Téléchargement : enregistre le corps de la réponse dans un fichier ; l'extension est déduite du Content-Type lorsque c'est possible.

Considérations de conception :

• Les en-têtes saut-par-saut (par exemple Host, Content-Length, Connection) sont omis des commandes de relecture générées.
• Les corps de réponse binaires (images, PDF) sont téléchargeables en utilisant des blobs binaires. Si les réponses sont stockées encodées en Base64, le client les décodera avant le téléchargement.

API : Points de terminaison REST (pour l'automatisation)

• GET /api/captures — lister les captures (tableau JSON).
• DELETE /api/captures — effacer toutes les captures.
• GET /api/captures/{id} — récupérer une capture spécifique.
• DELETE /api/captures/{id} — supprimer une capture spécifique.
• PATCH /api/captures/{id} — mettre à jour les métadonnées d'une capture ; exemple de corps : { "name": "Mon étiquette" }.
• GET /api/pause — renvoie { "paused": true|false }.
• POST /api/pause — définir l'état de pause ; exemple de corps : { "paused": true }.
• GET /events — flux d'événements envoyés par le serveur (SSE) pour les notifications de capture en direct et les événements de contrôle.

Notes d'implémentation (pour les développeurs)

• Embarquement de l'interface : utiliser //go:embed ui/* et fs.Sub pour servir les fichiers statiques. Cela produit un artefact déployable unique.
• Décompression : le code de capture vérifie Content-Encoding et tente de décompresser les corps gzip et deflate avant l'affichage. Les octets originaux sont conservés pour la transparence du proxy.
• Concurrence : le magasin de captures utilise un verrouillage interne pour fournir des opérations d'ajout/liste/obtention/mise à jour thread-safe. Dans la mesure du possible, des booléens atomiques sont utilisés pour les drapeaux de bascule (par exemple pause/reprise).
• SSE : un courtier léger diffuse les ajouts, suppressions, renommages et événements de contrôle aux clients de l'interface connectés.
• Mise en mémoire tampon : les corps de capture sont lus à l'aide de io.LimitReader pour détecter la troncature et protéger l'utilisation de la mémoire.

Empaquetage et distribution

Modèle de distribution recommandé :

1. Construire des binaires statiques et allégés pour les plateformes cibles (CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
2. Produire des archives (.tar.gz pour Unix, .zip pour Windows) et inclure README.md et LICENSE.
3. Fournir des sommes de contrôle SHA-256 et attacher les artefacts aux versions GitHub.
4. Utiliser éventuellement goreleaser pour automatiser les constructions multiplateformes et les artefacts de version.

Exemples de commandes de construction :

Exécution en tant que service

Unité systemd (exemple Linux)

launchd (agent utilisateur macOS)

Créez un plist dans ~/Library/LaunchAgents et chargez-le avec launchctl.

Dépannage

• Le corps capturé apparaît comme du charabia binaire
  Le corps est compressé (par exemple gzip). Assurez-vous d'exécuter une version qui inclut la décompression automatique ; l'interface affiche le JSON/texte décompressé lorsqu'il est disponible.

• Le trafic HTTPS ne s'affiche pas / erreurs de connexion
  Le client ne fait pas confiance à l'autorité de certification générée. Installez ca/ca.pem dans le magasin de confiance du client/système et marquez-le comme approuvé pour l'interception TLS.

• L'interface affiche une sélection obsolète après avoir effacé les captures
  Mettez à niveau vers un client qui efface selectedId lors des événements SSE cleared ou invoquez le point de terminaison GET /api/captures pour rafraîchir l'état.

• 405 sur DELETE /api/captures
  Assurez-vous que le gestionnaire de serveur accepte DELETE pour /api/captures et que vous ne rencontrez pas de problème de barre oblique finale.

Sécurité et confidentialité

Cet outil effectue une interception TLS lorsque le mode MITM est activé. Utilisez-le uniquement dans des environnements contrôlés où vous êtes explicitement autorisé à inspecter le trafic. L'autorité de certification générée est puissante : traitez sa clé privée avec la même confidentialité que toute autre clé privée d'autorité de certification racine. N'installez pas l'autorité de certification dans les magasins de confiance partagés ou de production.

Contribution

Les contributions sont les bienvenues. Veuillez ouvrir des tickets pour les bogues ou les demandes de fonctionnalités. Pour les contributions de code :

1. Forkez le dépôt.
2. Créez une branche de fonctionnalité.
3. Exécutez les tests unitaires et les linters le cas échéant.
4. Soumettez une pull request décrivant le changement, la justification et toute préoccupation de rétrocompatibilité.

Licence

Ce projet est distribué sous la licence MIT. Voir LICENSE pour plus de détails.

Attribution et contact

Auteur : John Southerland (GitHub : jbsouthe)
Projet : http-breakout-proxy — destiné au débogage, au développement et à l'apprentissage du comportement HTTP.