Réseau22 septembre 2025

En-têtes HTTP personnalisés : contrôler les en-têtes de requête avec BotBrowser

Apprenez à définir des en-têtes HTTP personnalisés au niveau du moteur navigateur avec le flag --bot-custom-headers de BotBrowser et l'API CDP pour une identité de requête cohérente.

Introduction

Les en-têtes HTTP font partie de chaque requête envoyée par le navigateur. Des en-têtes tels que User-Agent, Accept-Language, Sec-CH-UA et Referer constituent une part importante de l'identité réseau du navigateur. Lorsque ces en-têtes ne correspondent pas au profil d'empreinte, ou lorsque vous devez injecter des en-têtes spécifiques à l'application pour l'authentification et le routage, les API standards du navigateur sont insuffisantes.

BotBrowser fournit un contrôle des en-têtes au niveau du moteur via le flag --bot-custom-headers et la commande CDP BotBrowser.setCustomHeaders. Contrairement aux extensions qui interceptent les requêtes après leur formation, BotBrowser modifie les en-têtes avant que la requête ne quitte la pile réseau du navigateur, couvrant tous les types de requêtes sans décalage temporel.

Impact sur la vie privée

Les en-têtes HTTP révèlent beaucoup d'informations sur l'environnement du navigateur. La chaîne User-Agent identifie la version du navigateur et le système d'exploitation. Accept-Language révèle les préférences de langue et, par extension, la région géographique probable. Les Client Hints (Sec-CH-UA, Sec-CH-UA-Platform, Sec-CH-UA-Mobile) fournissent des données structurées sur la marque du navigateur, la plateforme et le type d'appareil.

Lorsque ces en-têtes ne s'alignent pas avec d'autres aspects de l'empreinte, l'incohérence est remarquable. Un navigateur annonçant Accept-Language: de-DE mais avec un fuseau horaire américain, ou Sec-CH-UA-Platform: "Windows" mais des propriétés navigator spécifiques à macOS, crée des divergences que les systèmes de tracking peuvent corréler.

Les profils BotBrowser alignent automatiquement tous les en-têtes standards sur l'identité du profil. User-Agent, tous les Sec-CH-UA-* et Accept-Language sont dérivés des paramètres de navigateur, de plateforme et de locale du profil. Les en-têtes personnalisés ajoutés via --bot-custom-headers étendent cette baseline sans perturber l'ensemble standard.

Contexte technique

Comment les navigateurs construisent les en-têtes

Lorsque le navigateur envoie une requête HTTP, il construit les en-têtes à partir de plusieurs sources :

En-têtes intégrés : User-Agent, Accept, Accept-Encoding, Accept-Language sont ajoutés par le moteur en fonction des paramètres internes.
Client Hints : Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform sont envoyés par défaut. Les hints à haute entropie comme Sec-CH-UA-Full-Version-List sont envoyés uniquement si le serveur les demande via Accept-CH.
En-têtes applicatifs : en-têtes définis par JavaScript via fetch() ou XMLHttpRequest.
En-têtes injectés par extensions : en-têtes ajoutés par des extensions via l'API webRequest.

L'ordre et la composition de ces en-têtes créent un motif cohérent pour chaque navigateur. Chrome, Edge et Firefox produisent des agencements et combinaisons différents.

Cohérence basée sur le profil

Lorsque BotBrowser charge un profil d'empreinte, il configure tous les en-têtes standards pour correspondre à l'identité du profil :

User-Agent correspond à la version du navigateur et à la plateforme du profil
Sec-CH-UA contient les tokens de marque corrects dans le bon ordre
Sec-CH-UA-Platform correspond au système d'exploitation du profil
Accept-Language reflète la locale et les préférences de langue configurées

Ces en-têtes sont définis au niveau du moteur et s'appliquent à toutes les requêtes, y compris la requête de navigation initiale, le chargement des sous-ressources et les requêtes initiées par JavaScript. Il n'y a pas de fenêtre temporelle où des en-têtes incorrects pourraient être observés.

En-têtes personnalisés vs en-têtes standards

Les en-têtes personnalisés (ceux commençant par X- ou des noms spécifiques à l'application) servent un objectif différent des en-têtes standards. Ils véhiculent des données spécifiques à l'application : tokens d'authentification, identifiants de session, marqueurs de version ou indications de routage. Le flag --bot-custom-headers de BotBrowser ajoute ces en-têtes personnalisés sans modifier les en-têtes standards gérés par le profil.

Approches courantes et leurs limites

Modification d'en-têtes via extension

Les extensions peuvent modifier les en-têtes via webRequest.onBeforeSendHeaders. Cette approche présente plusieurs inconvénients :

Problèmes de timing : la première requête de navigation peut se produire avant l'enregistrement complet du listener de l'extension
Couverture incomplète : les requêtes de service worker, les pré-requêtes CORS et certaines requêtes internes peuvent ne pas déclencher le listener
Artefacts détectables : les extensions qui modifient les en-têtes laissent des traces dans la surface API des extensions
Surcharge de performance : chaque requête passe par le gestionnaire JS de l'extension, ajoutant de la latence

Annulements via CDP

Puppeteer et Playwright proposent des APIs d'override via CDP :

// Puppeteer - limited approach
await page.setExtraHTTPHeaders({ 'X-Custom': 'value' });

Cela fonctionne au niveau de la page mais a des limites :

Les en-têtes ainsi définis s'appliquent seulement à la page spécifique
Les service workers et shared workers peuvent ne pas recevoir ces en-têtes
La commande CDP Network.setExtraHTTPHeaders nécessite Network.enable, ce qui peut lui-même affecter le fingerprinting

En-têtes Fetch/XHR en JavaScript

Définir des en-têtes sur des appels fetch() ou XMLHttpRequest individuels ne couvre que les requêtes initiées par JS. Les requêtes de navigation, les chargements d'images, feuilles de style et autres requêtes initiées par le navigateur ne sont pas couvertes.

Approche BotBrowser

Le flag --bot-custom-headers

Le flag --bot-custom-headers de BotBrowser (PRO) injecte des en-têtes personnalisés au niveau du moteur :

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-Custom-Header":"value","X-Auth-Token":"abc123"}' \
       --user-data-dir="$(mktemp -d)"

Comme la modification a lieu à l'intérieur de la pile réseau de Chromium, les en-têtes personnalisés sont ajoutés à :

Requêtes de navigation initiale
Requêtes de sous-ressources (images, scripts, styles, fonts)
Requêtes XHR et Fetch
Requêtes d'upgrade WebSocket
Requêtes de Service Worker

Il n'y a pas de lacunes temporelles ni de types de requêtes manquants.

La commande CDP BotBrowser.setCustomHeaders

Pour la gestion en runtime, BotBrowser fournit une commande CDP qui peut être envoyée à la session au niveau du navigateur :

Puppeteer :

const cdpSession = await browser.target().createCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
  headers: { 'x-requested-with': 'com.example.app' }
});

Playwright :

const cdpSession = await browser.newBrowserCDPSession();
await cdpSession.send('BotBrowser.setCustomHeaders', {
  headers: { 'x-requested-with': 'com.example.app' }
});

Important : cette commande doit être envoyée à la session CDP de niveau navigateur, pas à la session de page. L'envoyer à la target de page retournera ProtocolError: 'BotBrowser.setCustomHeaders' wasn't found.

Configuration au niveau du profil

Les en-têtes personnalisés peuvent également être définis dans la configuration du profil via configs.customHeaders. Utile lorsque vous souhaitez intégrer les en-têtes dans le profil plutôt que de les spécifier au lancement.

Configuration et usage

CLI avec en-têtes personalizados

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-App-Version":"2.1.0","X-Session-ID":"sess_abc123"}' \
       --proxy-server=socks5://user:pass@proxy:1080 \
       --user-data-dir="$(mktemp -d)"

Intégration Playwright

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--bot-custom-headers={"X-Auth":"token123","X-Client":"webapp"}',
    ],
    headless: true,
  });

  const context = await browser.newContext();
  const page = await context.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Intégration Puppeteer

const puppeteer = require('puppeteer-core');

(async () => {
  const browser = await puppeteer.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
      '--bot-custom-headers={"X-Auth":"token123"}',
    ],
    headless: true,
    defaultViewport: null,
  });

  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
})();

Citation des guillemets en JavaScript

Lors du passage de --bot-custom-headers depuis JavaScript, n'incluez pas de guillemets shell à l'intérieur de la valeur :

// Correct
const headers = { 'X-Custom': 'value', 'X-Auth': 'token' };
args.push('--bot-custom-headers=' + JSON.stringify(headers));

// Incorrect - les quotes simples deviennent partie du JSON
args.push(`--bot-custom-headers='${JSON.stringify(headers)}'`);

Mises à jour runtime via CDP

Pour workflows qui doivent changer les en-têtes pendant la session :

const { chromium } = require('playwright-core');

(async () => {
  const browser = await chromium.launch({
    executablePath: '/path/to/botbrowser/chrome',
    args: [
      '--bot-profile=/path/to/profile.enc',
    ],
    headless: true,
  });

  const cdpSession = await browser.newBrowserCDPSession();

  // Set initial headers
  await cdpSession.send('BotBrowser.setCustomHeaders', {
    headers: { 'x-requested-with': 'com.example.app' }
  });

  const page = await (await browser.newContext()).newPage();
  await page.goto('https://example.com');

  // Update headers mid-session
  await cdpSession.send('BotBrowser.setCustomHeaders', {
    headers: { 'x-requested-with': 'com.example.app', 'x-session': 'refreshed' }
  });

  await page.goto('https://example.com/dashboard');
  await browser.close();
})();

Vérification

Après avoir lancé BotBrowser avec des en-têtes personnalisés, vérifiez qu'ils sont appliqués :

Ouvrez une page qui renvoie les en-têtes reçus (par ex. https://httpbin.org/headers)
Confirmez que vos en-têtes personnalisés figurent dans la réponse
Vérifiez l'onglet Network dans DevTools pour voir les en-têtes sur tous les types de requêtes
Vérifiez que les en-têtes standards (User-Agent, Sec-CH-UA) correspondent toujours au profil

const page = await context.newPage();
await page.goto('https://httpbin.org/headers');
const headersText = await page.textContent('body');
console.log('Request headers:', headersText);

Bonnes pratiques

Utilisez --bot-custom-headers pour les en-têtes statiques. Si les en-têtes ne changent pas pendant la session, le flag CLI est plus simple que CDP.
Utilisez BotBrowser.setCustomHeaders pour les en-têtes dynamiques. Quand il faut faire pivoter des tokens d'authentification, utilisez la commande CDP.
Ne remplacez pas les en-têtes gérés par le profil. Les en-têtes personnalisés doivent ajouter des champs, pas remplacer User-Agent ou Sec-CH-UA.
Évitez les noms d'en-têtes courants d'extensions. Des en-têtes comme X-Forwarded-For ou X-Real-IP peuvent entrer en conflit avec l'infrastructure proxy ; préférez des noms spécifiques à l'application.
Testez avec httpbin.org/headers. Cet endpoint renvoie les en-têtes reçus, facilitant la validation.
Utilisez toujours une session CDP à l'échelle du navigateur pour setCustomHeaders. Les sessions au niveau de la page renverront une erreur.

FAQ

Les en-têtes personnalisés se appliquent-ils à toutes les requêtes o sólo a la navegación? Ils s'appliquent à toutes les requêtes. BotBrowser ajoute des en-têtes personnalisés au niveau moteur, couvrant navigation, subrecursos, XHR, Fetch, WebSocket et Service Worker.

Puis-je définir des en-têtes différents par context? Le flag --bot-custom-headers s'applique à tous les contexts. Pour des en-têtes par context, utilisez BotBrowser.setCustomHeaders et mettez-les à jour entre les opérations de context.

Les en-têtes personnalisés affectent-ils le fingerprint? Les en-têtes non standards (comme X-Custom-Header) n'affectent pas le fingerprint ; ce sont des champs supplémentaires dans la requête.

Puis-je retirer un en-tête standard? BotBrowser ne permet pas de supprimer des en-têtes standards via des en-têtes personnalisés. Les en-têtes gérés par le profil restent présents pour maintenir la cohérence d'empreinte.

--bot-custom-headers fonctionne-t-il avec --proxy-server? Oui. Les en-têtes s'ajoutent indépendamment de la configuration de proxy ; le proxy verra l'ensemble complet.

Y a-t-il un nombre maximal d'en-têtes personnalisés? Pas de limite explicite. Trop d'en-têtes peuvent augmenter la taille de la requête et déclencher des limites côté serveur.

Puis-je utiliser --bot-custom-headers pour les cookies? Pour la gestion des cookies, utilisez --bot-cookies. Il gère correctement le domaine et l'expiration.

Résumé

Le contrôle des en-têtes HTTP est essentiel pour maintenir une identité de navigateur cohérente. BotBrowser fournit une gestion des en-têtes au niveau moteur via les profils (pour les en-têtes standards), le flag --bot-custom-headers (pour les en-têtes personnalisés statiques) et la commande CDP BotBrowser.setCustomHeaders (pour les en-têtes dynamiques). Ensemble, ces outils garantissent que chaque requête transporte des en-têtes complets et cohérents.

Sujets liés : Proxy Configuration et User Agent Control and Client Hints. Pour la gestion d'identités multi-comptes, voir Multi-Account Browser Isolation.

Pourquoi le controle des en-tetes est important

Les en-tetes HTTP comme User-Agent, Accept-Language et Sec-CH-UA font partie de l'identite de votre navigateur. BotBrowser gere automatiquement tous les en-tetes standard via les profils et vous permet d'ajouter des en-tetes personnalises au niveau du moteur.

Coherence des en-tetes basee sur les profils

Lors du chargement d'un profil d'empreinte avec --bot-profile, BotBrowser aligne automatiquement tous les en-tetes standard avec l'identite du profil.

chrome --bot-profile="/path/to/profile.enc" \
       --bot-config-locale="de-DE" \
       --bot-config-languages="de-DE,de,en-US,en" \
       --user-data-dir="$(mktemp -d)"

Ajouter des en-tetes personnalises

Le flag --bot-custom-headers permet de definir des en-tetes HTTP supplementaires au niveau du moteur :

chrome --bot-profile="/path/to/profile.enc" \
       --bot-custom-headers='{"X-Custom-Header":"value","Another-Header":"value2"}' \
       --user-data-dir="$(mktemp -d)"

Les cas d'utilisation incluent les jetons d'authentification, les identifiants specifiques aux applications et les en-tetes de prevention du suivi.

Modification au niveau du moteur

Les modifications s'appliquent a toutes les requetes : chargements de page initiaux, sous-ressources, XHR/Fetch et WebSocket.

Exemple Puppeteer

const puppeteer = require('puppeteer-core');

const browser = await puppeteer.launch({
  executablePath: '/path/to/botbrowser/chrome',
  args: [
    '--bot-profile=/path/to/profile.enc',
    '--bot-custom-headers={"X-Auth":"token123"}',
  ],
  headless: true,
  defaultViewport: null,
});

const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

Verification

Ouvrez DevTools et verifiez les en-tetes dans l'onglet Network
Verifiez que les en-tetes personnalises apparaissent sur tous les types de requete
Confirmez que les en-tetes standard correspondent au profil charge

Pour commencer

Telechargez BotBrowser depuis GitHub
Chargez un profil avec --bot-profile
Ajoutez des en-tetes avec --bot-custom-headers
Verifiez la coherence sur tous les types de requete

#http-headers#custom-headers#network#privacy#request