Recettes CLI pour l'automatisation de navigateur : exemples pratiques de commandes

Introduction

Les flags CLI de BotBrowser offrent un contrôle précis sur les profils d'empreintes numériques, le routage proxy, les paramètres de locale, la configuration du rendu et le comportement d'automatisation. Avec des dizaines de flags disponibles, savoir lesquels combiner pour des scénarios spécifiques fait gagner un temps de configuration considérable.

Cet article rassemble des recettes prêtes à l'emploi pour les cas d'usage courants. Chaque recette inclut la commande exacte, une explication de la raison d'être de chaque flag et des notes sur quand l'utiliser ou le modifier. Toutes les recettes supposent que vous disposez d'un binaire BotBrowser et de fichiers de profils .enc provenant des versions GitHub.

Pourquoi les recettes CLI sont importantes

Le système de configuration de BotBrowser est flexible par conception. Vous pouvez remplacer presque n'importe quel paramètre de profil au moment de l'exécution, router le trafic via des proxys avec identifiants intégrés, contrôler le comportement de rendu et gérer plusieurs instances depuis la ligne de commande. Cette flexibilité signifie qu'il existe de nombreuses configurations valides, et trouver la bonne combinaison pour votre scénario peut nécessiter la lecture de la Référence complète des flags CLI.

Les recettes comblent le fossé entre la compréhension des flags individuels et leur combinaison efficace. Elles codifient des configurations testées qui gèrent les cas limites courants, comme s'assurer que chaque instance concurrente dispose de son propre répertoire de données utilisateur, ou associer les paramètres de proxy avec les bons remplacements de locale.

Le système de priorité de configuration rend les recettes CLI particulièrement puissantes. Les flags CLI --bot-config-* ont la priorité la plus élevée, remplaçant les paramètres du profil sans modifier le fichier de profil chiffré. Cela signifie que vous pouvez maintenir un petit ensemble de profils de base et les personnaliser au lancement pour différents scénarios.

Contexte technique

Catégories de flags

Les flags BotBrowser se répartissent en plusieurs catégories :

Les flags principaux (--bot-profile, --bot-profile-dir) contrôlent quel profil d'empreinte charger. Chaque session BotBrowser commence par l'un d'entre eux.

Les flags proxy (--proxy-server, --proxy-ip, --proxy-bypass-rgx) contrôlent le routage réseau. BotBrowser étend le flag proxy standard de Chromium pour prendre en charge les identifiants intégrés dans l'URL.

Les flags de remplacement de configuration (--bot-config-*) remplacent des valeurs spécifiques du profil chargé. Le fuseau horaire, la locale, les langues, la marque du navigateur, les dimensions d'écran et les paramètres de rendu sont tous configurables.

Les interrupteurs de comportement (--bot-disable-debugger, --bot-always-active, --bot-inject-random-history, etc.) contrôlent le comportement à l'exécution qui n'est pas lié à une valeur de profil spécifique.

Les flags de personnalisation (--bot-title, --bot-cookies, --bot-bookmarks, --bot-script) ajoutent des données spécifiques à la session ou des scripts d'automatisation.

Détection automatique

BotBrowser dérive automatiquement les paramètres de fuseau horaire, de locale et de langue à partir de l'IP de votre proxy. Dans la plupart des recettes, vous n'avez pas besoin de spécifier ces valeurs manuellement. Ne les remplacez que lorsque vous avez besoin d'une configuration différente de ce que l'IP suggère.

Flags Chromium standard

BotBrowser prend également en charge tous les flags Chromium standard. Les plus courants incluent --headless, --user-data-dir, --remote-debugging-port et --window-size. Ceux-ci sont documentés dans la référence des lignes de commande Chromium.

Recettes

Recette 1 : Lancement minimal

La configuration BotBrowser la plus simple possible :

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --headless

Cela charge le profil et s'exécute en mode headless. Le fuseau horaire, la locale et les langues sont détectés automatiquement à partir de l'IP de votre machine. Utilisez ceci pour les tests locaux et le développement.

Recette 2 : Lancement en production avec proxy

chromium-browser \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

Le proxy gère le routage géographique tandis que BotBrowser dérive automatiquement le fuseau horaire et la locale à partir de l'IP de sortie du proxy. Un --user-data-dir unique empêche les conflits avec d'autres instances. Le port de débogage permet le contrôle programmatique via CDP.

Recette 3 : Locale et fuseau horaire explicites

Lorsque vous avez besoin de paramètres régionaux spécifiques indépendamment de l'emplacement de votre proxy :

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-config-timezone="Europe/Berlin" \
  --bot-config-locale="de-DE" \
  --bot-config-languages="de-DE,de,en-US" \
  --bot-config-location="52.5200,13.4050" \
  --headless

Cela remplace les valeurs détectées automatiquement par une configuration allemande explicite. Utile lorsque l'IP de votre proxy ne reflète pas précisément la région souhaitée.

Recette 4 : Déploiement multi-instances

#!/bin/bash
PROFILES_DIR="/opt/profiles/windows-chrome"
BASE_PORT=9222

for i in $(seq 1 5); do
  chromium-browser \
    --bot-profile-dir="${PROFILES_DIR}" \
    --bot-title="Worker ${i}" \
    --user-data-dir="/tmp/bb-worker-${i}" \
    --remote-debugging-port=$((BASE_PORT + i)) \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --headless &
done

Chaque instance obtient un profil aléatoire du répertoire, son propre répertoire de données utilisateur, un port de débogage unique et un titre descriptif pour l'identification. Le --bot-title apparaît dans le titre de la fenêtre et la barre des tâches, facilitant l'identification d'instances spécifiques.

Recette 5 : Changement de marque de navigateur

Se présenter comme Microsoft Edge au lieu de Chrome :

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-browser-brand="edge" \
  --headless

Valeurs de marque disponibles : chrome, chromium, edge, brave, opera, webview. BotBrowser ajuste le User-Agent, les en-têtes Client Hints et les valeurs API associées pour correspondre à la marque sélectionnée.

Recette 6 : Session avec cookies et historique

Pré-remplir le navigateur avec des données de session :

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"},{"name":"pref","value":"dark","domain":".example.com"}]' \
  --bot-bookmarks='[{"title":"Dashboard","type":"url","url":"https://example.com/dashboard"}]' \
  --bot-inject-random-history \
  --bot-always-active \
  --user-data-dir="/data/persistent-session" \
  --headless

--bot-cookies définit les cookies initiaux. --bot-bookmarks ajoute des entrées de favoris. --bot-inject-random-history crée un historique de navigation synthétique pour l'authenticité de la session. --bot-always-active maintient les fenêtres actives même lorsqu'elles n'ont pas le focus.

Recette 7 : Chargement de cookies depuis un fichier

Pour les grands ensembles de cookies, chargez depuis un fichier JSON :

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --headless

Le préfixe @ indique à BotBrowser de lire les cookies depuis le chemin de fichier spécifié au lieu d'analyser la valeur comme du JSON en ligne.

Recette 8 : Bruit déterministe pour la reproductibilité

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --headless

--bot-noise-seed rend le bruit Canvas, WebGL, audio, des métriques de texte et ClientRect déterministe. La même graine produit le même hash d'empreinte à chaque fois. --bot-time-seed fournit une diversité de timing d'exécution déterministe à travers les opérations du navigateur. --bot-time-scale comprime les intervalles performance.now() pour réduire les signaux de pistage basés sur le timing.

Recette 9 : Enregistrement Canvas pour analyse

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --bot-noise-seed=12345 \
  --headless

Enregistre tous les appels API Canvas 2D, WebGL et WebGL2 dans un fichier JSONL. La graine de bruit est fixée pour que la sortie enregistrée soit reproductible. Utilisez ceci pour l'analyse forensique et le débogage du comportement d'empreinte lié au Canvas.

Recette 10 : Automatisation sans framework

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --bot-disable-debugger \
  --bot-disable-console-message \
  --headless

Exécute un fichier JavaScript avec un accès CDP direct via chrome.debugger. Pas besoin de Node.js ni de npm. --bot-disable-debugger empêche les pages de suspendre l'exécution avec des instructions debugger. --bot-disable-console-message supprime la sortie console exposée via CDP.

Recette 11 : Headless avec taille de fenêtre spécifique

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-window="1920x1080" \
  --bot-config-screen="2560x1440" \
  --window-size=1920,1080 \
  --headless

Définit à la fois les dimensions de fenêtre/écran au niveau du profil et la taille de fenêtre Chromium. Les flags --bot-config-window et --bot-config-screen contrôlent ce que les API JavaScript signalent, tandis que --window-size définit le viewport réel.

Recette 12 : Protection de la vie privée WebRTC avec STUN personnalisé

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice contrôle quels points de terminaison STUN/TURN sont exposés via WebRTC, empêchant la fuite d'IP locale. --bot-local-dns conserve la résolution DNS en local au lieu de s'appuyer sur le DNS du fournisseur de proxy.

Recette 13 : En-têtes HTTP personnalisés

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-custom-headers='{"X-Requested-With":"com.example.app","X-Custom-Auth":"token123"}' \
  --headless

Injecte des en-têtes personnalisés dans toutes les requêtes HTTP sortantes. Utile pour l'authentification API et le routage des requêtes.

Recette 14 : Protection des ports

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-port-protection \
  --headless

Empêche les pages distantes de détecter quels services tournent sur localhost en bloquant le scan de ports sur les ports courants de développement et d'accès distant.

Recette 15 : Débogage et dépannage

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-internal --v=1 \
  --enable-logging=stderr \
  --headless

Active la journalisation interne de BotBrowser (--bot-internal --v=1) et la journalisation stderr de Chromium pour une sortie de diagnostic détaillée. Utilisez ceci pour résoudre les problèmes de configuration.

Vérification

Après avoir appliqué une recette, vérifiez le résultat en naviguant vers un outil de test d'empreintes :

# Vérification rapide avec une URL de test
chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-noise-seed=42 \
  --remote-debugging-port=9222 \
  --headless

Connectez-vous ensuite via CDP et naviguez vers CreepJS ou BrowserLeaks pour confirmer que votre configuration produit une empreinte cohérente et réaliste. Voir Comment vérifier la protection de votre empreinte de navigateur pour une méthodologie de test détaillée.

Bonnes pratiques

Commencez minimaliste, ajoutez des flags selon les besoins. Démarrez avec la recette 1 et ajoutez des flags uniquement lorsque vous avez un besoin spécifique. Les flags inutiles ajoutent de la complexité sans bénéfice.

Laissez la détection automatique fonctionner. Si vous utilisez un proxy, BotBrowser gère automatiquement le fuseau horaire, la locale et la langue. Ne remplacez que lorsque les valeurs détectées automatiquement ne correspondent pas à vos besoins.

Utilisez --user-data-dir pour chaque instance concurrente. Sans répertoires de données séparés, les instances partagent cookies, cache et données de profil, provoquant un comportement imprévisible.

Utilisez --bot-title pour l'identification. Lors de l'exécution de plusieurs instances, le titre facilite l'identification de chaque instance dans les logs et les listes de processus.

Préférez --bot-config-* à la modification du profil. Les flags CLI ont la priorité la plus élevée et ne nécessitent pas de modifier des fichiers chiffrés.

Journalisez tout en développement. Utilisez --bot-internal --v=1 pendant le développement et les tests. Désactivez la journalisation verbose en production pour les performances.

Questions fréquentes

Puis-je combiner --bot-profile et --bot-profile-dir ?

Non. Si les deux sont spécifiés, --bot-profile-dir prend le dessus. Utilisez --bot-profile pour les identités persistantes et --bot-profile-dir pour la rotation aléatoire.

Que se passe-t-il si je spécifie des flags contradictoires ?

Les flags CLI ont la priorité la plus élevée. Si un flag contredit une valeur du profil, le flag l'emporte. Si deux flags se contredisent, le dernier spécifié prend généralement effet.

Comment savoir quels flags sont pris en charge par mon niveau de licence ?

Les flags nécessitant un niveau spécifique sont indiqués dans la Référence des flags CLI avec des labels comme (PRO), (ENT Tier1), (ENT Tier2), etc. Utiliser un flag sans le niveau requis n'a aucun effet.

Puis-je sauvegarder des combinaisons de flags dans un fichier ?

Oui. Créez un script shell ou un fichier de configuration avec vos combinaisons de flags. Pour Playwright/Puppeteer, définissez votre tableau d'arguments dans un module de configuration partagé.

Quel est le nombre maximum de flags utilisables ?

Il n'y a pas de limite pratique au nombre de flags. Cependant, gardez votre configuration aussi simple que possible. Chaque flag inutile est un point de confusion potentiel lors du débogage.

Comment revenir au comportement par défaut ?

Lancez sans aucun flag --bot-config-* pour utiliser les valeurs par défaut du profil. Lancez sans --bot-profile pour exécuter Chromium standard.

Ces recettes sont-elles multiplateforme ?

Oui. Les mêmes flags fonctionnent sur Windows, macOS et Linux. Adaptez le nom du binaire (chromium-browser, chrome, chrome.exe) et le format de chemin pour votre plateforme.

Résumé

Ces recettes couvrent les configurations BotBrowser les plus courantes, du lancement minimal en développement aux déploiements multi-instances en production. Commencez par la recette la plus simple qui répond à vos besoins et ajoutez des flags progressivement à mesure que les exigences augmentent.

Pour des approfondissements sur des sujets spécifiques, consultez Gestion des profils pour l'organisation des profils, Configuration serveur headless pour la configuration de serveurs Ubuntu, Guide de déploiement Docker pour les déploiements conteneurisés, et Automatisation Bot Script pour l'automatisation sans framework.