Paramètres

Avertissement

Le système de paramètres est en cours de développement et peut évoluer.

Les options sont également configurables via des fichiers de paramètres. Voir le fichier JSON de paramètres pour la liste des options actuellement prises en charge.

Au démarrage, Maigret tente de charger sa configuration depuis les sources suivantes, exactement dans cet ordre :

# relative path, based on installed package path
resources/settings.json

# absolute path, system-wide policy set by an administrator
/etc/maigret/settings.json

# absolute path, configuration file in home directory
~/.maigret/settings.json

# relative path, based on current working directory
settings.json

L’absence de l’un de ces fichiers n’est pas une erreur. Si le fichier de paramètres suivant contient une option déjà connue, cette option est écrasée. Il est donc possible d’avoir une configuration différente selon les utilisateurs et les répertoires.

Mise à jour automatique de la base

Maigret est livré avec une base de sites embarquée, mais celle-ci se périme entre deux versions. Pour la garder à jour, Maigret vérifie automatiquement au démarrage si une mise à jour est disponible.

Comment cela fonctionne :

Au démarrage, Maigret regarde si plus de 24 heures se sont écoulées depuis la dernière vérification.
Si c’est le cas, il récupère depuis GitHub un fichier de métadonnées léger (environ 200 octets) pour savoir si une base plus récente est disponible.
S’il existe une base plus récente et compatible, Maigret la télécharge dans ~/.maigret/data.json et l’utilise à la place de la copie embarquée.
Si le téléchargement échoue ou si la nouvelle base est incompatible avec votre version de Maigret, la base embarquée sert de solution de repli.

La base téléchargée a une priorité supérieure à la base embarquée : elle la remplace, elle ne se superpose pas à elle.

Les messages d’état ne sont affichés que lorsqu’une action a lieu :

[*] DB auto-update: checking for updates...
[+] DB auto-update: database updated successfully (<N> sites)
[*] DB auto-update: database is up to date (<N> sites)
[!] DB auto-update: latest database requires maigret >= 0.6.0, you have 0.5.0

Forcer une mise à jour :

Utilisez l’option --force-update pour vérifier immédiatement les mises à jour, sans tenir compte de l’intervalle de vérification :

maigret username --force-update

La mise à jour a lieu au démarrage, puis la recherche se poursuit normalement avec la base fraîchement téléchargée.

Désactiver la mise à jour automatique :

Utilisez l’option --no-autoupdate pour ignorer complètement la vérification :

maigret username --no-autoupdate

Ou définissez-la de façon permanente dans ~/.maigret/settings.json :

{
    "no_autoupdate": true
}

C’est recommandé pour les conteneurs Docker, les pipelines d’intégration continue et les environnements isolés du réseau.

Options de configuration (dans settings.json) :

Paramètre	Valeur par défaut	Description
`no_autoupdate`	`false`	Désactive entièrement la mise à jour automatique
`autoupdate_check_interval_hours`	`24`	Fréquence de vérification des mises à jour (en heures)
`db_update_meta_url`	URL brute GitHub	URL du fichier de métadonnées (pour un miroir personnalisé)

Utiliser une base personnalisée avec --db désactive toujours la mise à jour automatique : vous choisissez explicitement votre source de données.

Cache des jetons d’activation

Quelques sites rejettent les requêtes anonymes tant qu’un jeton de courte durée n’a pas été obtenu : Twitter demande un jeton invité, Vimeo un JWT, Weibo et Wikimapia un cookie de session, OnlyFans une paire d’en-têtes signés, ProtonMail un jeton bearer. Maigret les génère en cours d’exécution, la première fois qu’un tel site répond par un défi plutôt que par une page de profil.

Les valeurs générées sont mises en cache dans :

~/.maigret/activation.json

de sorte que l’exécution suivante démarre avec un jeton déjà chaud et évite un aller-retour supplémentaire. Le fichier est créé avec les permissions 0600, car ces jetons sont des identifiants de session : traitez-le comme tel et ne le joignez pas à un rapport de bug.

Ce qui est stocké : uniquement les valeurs d’en-tête qui diffèrent de celles fournies par la base de sites. Stocker l’ensemble des en-têtes figerait les valeurs livrées, et une mise à jour ultérieure de la base ne pourrait plus jamais les modifier.

Peut-on le supprimer sans risque : oui. L’exécution suivante regénère ce dont elle a besoin ; cela ne coûte qu’une requête supplémentaire par site concerné.

Pourquoi il n’est pas conservé dans la base de sites : la base fait partie des données du paquet. Elle est versionnée, vérifiée par somme de contrôle et remplacée intégralement par la Mise à jour automatique de la base ; de plus, lors d’une installation à l’échelle du système (paquet de distribution, snap, /nix/store), son répertoire n’est pas du tout accessible en écriture. Les jetons, eux, sont un état propre à l’utilisateur, avec une durée de vie différente : ils vivent donc dans un fichier séparé.

Webgate Cloudflare

Avertissement

Expérimental. Le bloc cloudflare_bypass est en cours de développement actif ; les noms de champs, les valeurs par défaut et les règles de routage par protection déclenchante peuvent changer sans garantie de compatibilité ascendante.

Le bloc cloudflare_bypass de settings.json configure le contournement facultatif décrit dans Contournement du webgate Cloudflare. Ce même bloc est pris en compte par la ligne de commande, l’API Python et l’interface web (python -m maigret.web.app) : définissez enabled: true une fois et tous les points d’entrée feront passer les sites protégés par Cloudflare via le solveur.

Configuration FlareSolverr minimale. Démarrez le solveur dans Docker, puis déposez l’extrait suivant dans ~/.maigret/settings.json (ou dans l’un des chemins listés dans Paramètres) :

docker run -d -p 8191:8191 --name flaresolverr \
    ghcr.io/flaresolverr/flaresolverr:latest

{
    "cloudflare_bypass": {
        "enabled": true,
        "modules": [
            {
                "name": "flaresolverr",
                "method": "json_api",
                "url": "http://localhost:8191/v1",
                "max_timeout_ms": 60000
            }
        ]
    }
}

Cela suffit : session_prefix et trigger_protection reprennent des valeurs par défaut raisonnables (respectivement "maigret" et ["cf_js_challenge", "cf_firewall", "webgate"]). À l’exécution suivante, Maigret journalise Cloudflare webgate active: ... et fait passer les sites correspondants par le solveur.

Valeur par défaut (schéma complet, avec tous les champs pris en charge) :

{
    "cloudflare_bypass": {
        "enabled": false,
        "session_prefix": "maigret",
        "trigger_protection": ["cf_js_challenge", "cf_firewall", "webgate"],
        "modules": [
            {
                "name": "flaresolverr",
                "method": "json_api",
                "url": "http://localhost:8191/v1",
                "max_timeout_ms": 60000
            },
            {
                "name": "chrome_webgate",
                "method": "url_rewrite",
                "url": "http://localhost:8000/html?url={url}&retries=1"
            }
        ]
    }
}

Champs.

Champ	Description
`enabled`	Lorsqu’il vaut `true`, le contournement est actif à chaque exécution ; lorsqu’il vaut `false` (par défaut), il ne s’active qu’avec `--cloudflare-bypass`.
`trigger_protection`	Liste des valeurs de `site.protection` qui font passer une vérification par le webgate. Les sites dont la protection est vide, ou ne recoupe pas cette liste, utilisent le vérificateur par défaut (aiohttp / curl_cffi).
`session_prefix`	Préfixe du champ `session` de FlareSolverr. Maigret y ajoute le PID du processus pour que des exécutions concurrentes n’entrent pas en collision. Réutiliser une session met en cache le cf_clearance entre les vérifications d’un même domaine.
`modules`	Liste ordonnée des modules de backend. Le premier module joignable traite la vérification ; les suivants forment une chaîne de repli.

Méthodes des modules.

json_api — point d’entrée POST compatible FlareSolverr à l’adresse url. Préserve le vrai statut HTTP en amont, les en-têtes et l’URL finale. Le champ facultatif max_timeout_ms (60000 par défaut) est le budget par requête que le solveur peut consacrer au défi JavaScript.
url_rewrite — ancien point d’entrée CloudflareBypassForScraping. L”url doit contenir un emplacement {url} ; l’URL de sonde d’origine y est insérée après encodage. Ne renvoie que du HTML rendu : les vérifications checkType: status_code et response_url se déclenchent donc à tort avec cette méthode (un succès est traité comme un HTTP 200 synthétique).

Champ facultatif ``proxy`` (``json_api`` uniquement).

Un module peut porter une entrée proxy, par laquelle le solveur fait passer la requête en amont. C’est utile quand un site applique des règles d”ip_reputation qui bloquent la machine du solveur. Deux formes sont acceptées :

{ "proxy": "socks5://localhost:1080" }

{ "proxy": { "url": "http://gw.example:3128",
             "username": "u",
             "password": "p" } }

Seuls url/username/password sont transmis ; les autres clés sont ignorées. Une réponse Cloudflare Error 1015 / 1020 signale que l’IP est limitée en débit ou bannie : changez de proxy plutôt que de réessayer. .. _ai-analysis-settings:

Analyse par IA

L’option --ai (voir Analyse par IA (intégrée)) interroge une API de complétion de conversation compatible OpenAI. Trois paramètres contrôlent la façon dont cette requête est faite :

Paramètre	Valeur par défaut	Description
`openai_api_key`	`""` (vide)	Clé d’API. Si elle est vide, Maigret se rabat sur la variable d’environnement `OPENAI_API_KEY`.
`openai_model`	`gpt-4o`	Nom du modèle par défaut. Remplaçable à chaque exécution avec `--ai-model`.
`openai_api_base_url`	`https://api.openai.com/v1`	URL de base de l’API de complétion de conversation. Pointez-la vers n’importe quel service compatible OpenAI (Azure OpenAI, OpenRouter, un serveur local, etc.) pour l’utiliser à la place d’OpenAI.

Exemple d’extrait de ~/.maigret/settings.json utilisant un point d’entrée autre qu’OpenAI :

{
    "openai_api_key": "sk-...",
    "openai_model": "gpt-4o-mini",
    "openai_api_base_url": "https://openrouter.ai/api/v1"
}

L’ordre de résolution de la clé est settings.openai_api_key → variable d’environnement OPENAI_API_KEY ; la première valeur non vide l’emporte.

Note

--ai envoie au point d’entrée configuré l’intégralité du rapport Markdown interne, qui contient les données de profil collectées. N’utilisez donc que des fournisseurs et des comptes auxquels vous confiez ces données.