HTTP Toolkit Intercept

Utilise cette compétence quand tu as besoin de preuves irréfutables de ce que ton programme a envoyé à une API distante et ce qu'il a reçu en retour, tout en vérifiant une modification de code. Fonctionne avec n'importe quel runtime — Node.js, Bun, Deno, Python, Go, Ruby, Java/JVM, .NET, PHP, Rust, scripts shell, etc. — tant que le processus respecte un proxy.

Le modèle fiable est :

1. Démarrer HTTP Toolkit correctement.
2. Lancer le programme via le proxy en mode qui produit un journal lisible par machine (par ex. --output-format json, debug logging, ou stdout structuré).
3. Exporter les requêtes HTTP sortantes depuis HTTP Toolkit.
4. Associer l'export HTTP sortant avec le journal de session entrant du programme.

Ne te fie pas aux seules captures d'écran TUI quand la question porte sur les charges utiles de requête, les en-têtes d'authentification, ou le comportement au niveau du fil.

Prérequis / Lancement connu pour fonctionner

Démarrer HTTP Toolkit

Sur les environnements Linux/headless, le simple httptoolkit échoue souvent à cause de problèmes de sandbox/X11. Préfère :

xvfb-run --auto-servernum httptoolkit --no-sandbox

Si un ancien serveur s'exécute déjà sur les ports 45456/45457, arrête-le d'abord :

pkill -f "HTTP Toolkit Server|httptoolkit|xvfb-run --auto-servernum httptoolkit" || true

Vérifier que le proxy est accessible

# L'API d'administration d'HTTP Toolkit vit sur le port 45456/45457 par défaut.
# Traite 200/401/403 comme « accessible » ; seul l'échec de connexion signifie que le serveur est mort.
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:45456/config

Démarrage rapide

1. Lancer ton programme avec les variables d'env du proxy

Les variables d'env canoniques que la plupart des runtimes honorent :

HTTP_PROXY="http://127.0.0.1:8000" \
HTTPS_PROXY="http://127.0.0.1:8000" \
ALL_PROXY="http://127.0.0.1:8000" \
NO_PROXY="" \
<your-program> <args>

Certains runtimes demandent une variable d'env ou un drapeau supplémentaire — voir la « matrice de proxy runtime » ci-dessous.

Si l'AC HTTP Toolkit n'est pas approuvée par ton runtime, la vérification TLS échouera. Voir « TLS Safety » ci-dessous. Désactiver la vérification TLS n'est approprié que pour le débogage local contrôlé.

2. Capturer le journal de session entrant

Si ton programme supporte un mode de sortie lisible par machine (par ex. --output-format stream-json, --json, --log-level debug, stdout structuré, ou écriture dans un fichier), redirige-le vers un fichier :

<your-program> exec --output-format stream-json "your input" \
  > /tmp/session-stdout.log 2> /tmp/session-stderr.log

3. Exporter HTTP sortant depuis HTTP Toolkit

Soit :

• Utilise l'export GUI d'HTTP Toolkit (File → Export → JSON / HAR), soit
• Frappe l'API d'administration directement. L'endpoint exact dépend de ta version d'HTTP Toolkit ; inspecte DevTools dans l'UI d'HTTP Toolkit pour voir les requêtes qu'elle fait.

4. Croiser les deux flux

• HTTP sortant (depuis HTTP Toolkit) : autoritaire pour les corps de requête, les en-têtes, les jetons d'authentification, les délais de relance.
• Journal de session entrant (depuis le programme) : autoritaire pour la façon dont ton code a réagi aux réponses.

Ensemble, ils répondent : « qu'avons-nous envoyé ? » et « qu'avons-nous fait avec la réponse ? »

Ce qui a finalement fonctionné pour la vérification de charge utile

Les chemins critiques corrects qui se sont avérés fiables étaient :

1. Utiliser un mode non-interactif / exec, pas la TUI, quand tu vérifies les charges utiles

   • Les TUI interactives sont plus lentes et beaucoup plus difficiles à analyser.
   • Utilise ce que ton programme offre pour les scripts (--output-format, --json, --headless, --batch).

2. Traiter sortant et entrant comme des sources de preuve distinctes

   • HTTP Toolkit donne les requêtes HTTP sortantes.
   • Le journal de session du programme donne le comportement assistant/tool/application entrant.
   • Tu as besoin des deux pour répondre : « qu'a retourné la distance ? » et « qu'a réellement fait le programme avec ça ? »

3. Définir les variables d'env du proxy que ton runtime spécifique honore

   • HTTP_PROXY/HTTPS_PROXY couvrent la plupart des runtimes, mais certains (par ex. Bun, Java) demandent des variables ou drapeaux supplémentaires.
   • Voir la « matrice de proxy runtime » ci-dessous.

4. Désactiver la vérification TLS seulement pour le débogage local contrôlé quand nécessaire

   • Si l'AC HTTP Toolkit n'est pas approuvée localement, utilise l'échappatoire spécifique au runtime pour sauter la vérification.
   • Préfère faire confiance à l'AC dans ta boutique de confiance OS / langage à la place.
   • Ne désactive jamais TLS dans les repros de production.

5. Garder les exécutions bornées

   • Les sessions longues et lourdes en réseau peuvent prendre du temps.
   • Si tu dois seulement prouver la forme de la requête, exporte après que la requête pertinente soit observée — tu n'as pas toujours besoin d'attendre la fin.

Faits clés

• Les variables d'env du proxy sont spécifiques au runtime — sache quelles celles que ton runtime honore
• L'API d'administration HTTP Toolkit est orientée requête — HTTP sortant vient d'HTTP Toolkit, le comportement entrant vient du journal du programme
• TLS est vérifié par défaut — les drapeaux de saut spécifiques au runtime sont des échappatoires locales pour le dev seulement

Matrice de proxy runtime

Préfère faire confiance à l'AC HTTP Toolkit dans ta boutique de confiance runtime/OS plutôt que de désactiver la vérification. Les drapeaux de contournement ne doivent être que pour le dev local.

Garde-fous de sécurité TLS

• Garde la vérification TLS activée autant que possible.
• Préfère faire confiance à l'AC HTTP Toolkit dans ta boutique de confiance locale plutôt que de désactiver la vérification.
• Utilise les drapeaux de contournement TLS spécifiques au runtime seulement pour le débogage local contrôlé en développement.
• Ne désactive jamais TLS quand tu interceptes du trafic de production.

Inspecter les journaux capturés

Filtrer sur les événements pertinents seulement

Si ton programme émet du JSON délimité par des nouvelle lignes, utilise jq :

jq -c 'select(.type == "tool_call" or .type == "message")' /tmp/session-stdout.log

Ajuste le filtre pour correspondre à ton schéma d'événements du programme. Pour les journaux en texte brut, utilise les patterns rg/grep.

Associer HTTP sortant aux événements entrants

Trie les deux flux par timestamp, puis intercale-les. La séquence ressemble généralement à :

outbound POST /api/endpoint        (from HTTP Toolkit)
inbound  event received             (from program log)
inbound  follow-up action           (from program log)
outbound POST /api/endpoint        (next request)

Si un journal du programme montre une requête sortante que HTTP Toolkit n'a pas capturée, c'est un bug de configuration du proxy.

Dépannage