Documentation de Fisherboy

Cette page documente le fonctionnement de Fisherboy de bout en bout : les concepts fondamentaux, l’interface web, les capacités de téléchargement, les API REST et MCP, et la configuration avancée.

Concepts

Le job et l’enveloppe

Tout ce que fait Fisherboy est un job. Vous soumettez un job (une URL plus des options), il est mis en file sur Redis, un worker exécute le pipeline, et le résultat est stocké sous forme d’enveloppe — un unique objet contenant le contenu extrait (content_md), les enregistrements structurés, l’arbre d’exploration, les liens découverts et les métadonnées. Vous interrogez le job jusqu’à ce que son statut soit ok.

Récupération à plusieurs niveaux (ne monte en puissance que lorsqu’elle est bloquée)

Fisherboy ne recourt jamais à un navigateur lourd avant d’y être contraint. Il essaie la méthode la moins coûteuse en premier et ne monte d’un cran que lorsqu’un gate détecte un blocage ou un CAPTCHA :

Niveau 0 — HTTP statique avec httpx. Rapide et peu coûteux ; fonctionne pour la plupart des pages statiques.
Niveau 1 — empreinte TLS avec curl_cffi, afin que la requête ressemble à celle d’un véritable navigateur au niveau réseau.
Niveau 2 — navigateur furtif (Camoufox / Patchright) pour les pages riches en JavaScript et anti-bot ; ce niveau pilote aussi la capture d’API cachée.
Niveau 3 — un véritable navigateur (nodriver / Playwright) en dernier recours.

Le niveau gagnant est mis en cache par domaine (TIER_CACHE_TTL_S), de sorte que la prochaine requête vers le même site démarre là où elle a réussi la dernière fois. Les niveaux élevés sont importés à la demande — l’image de base reste légère, et chaque niveau ne s’active que si sa bibliothèque est installée. Le plafond d’escalade se définit avec MAX_FETCH_TIER, et tier_hint sur un job peut suggérer un point de départ.

Capture d’API cachée

Les applications monopages et les grilles dynamiques s’affichent à partir du JSON qu’elles récupèrent via XHR/fetch. Plutôt que de lutter contre le HTML rendu, Fisherboy peut surveiller ces réponses réseau et conserver le JSON que la page consomme déjà — généralement la source la plus fiable et la plus complète des données. Activez-la par job avec capture_api.

Modes de confidentialité

Le mode de confidentialité est choisi par job et borné par le rôle (défini dans privacy_matrix.yaml, jamais codé en dur). Le pipeline est fail-closed : si l’anonymisation échoue, rien de brut n’est livré.

opaque (opaco) — chaque entité devient un marqueur typé stable tel que «PERSON_1» ou «ID_2». Le LLM raisonne sur des marqueurs et ne voit jamais les données personnelles ; l’original n’est pas récupérable.
réversible (reversible) — le même masquage, mais une table chiffrée associant token et valeur est conservée afin que vous puissiez la réhydrater plus tard via POST /api/revert (à usage unique, liée au rôle). La table est chiffrée avec une clé Fernet (REVERSIBLE_KEY) et expire après REVERSIBLE_TTL_S.
direct (directo) — sortie brute, uniquement pour des données non sensibles.

Une passe regex déterministe s’exécute toujours pour les données personnelles à haut risque (numéro national, e-mail, IP, carte valide selon Luhn, téléphone). Lorsque ANONIMAL_URL pointe vers une instance Anonimal, une reconnaissance d’entités nommées complète s’exécute par-dessus ; en mode autonome, le système se rabat sur la seule passe regex intégrée.

Si un rôle n’autorise pas le mode demandé, la passerelle renvoie un 403 — elle ne rétrograde jamais silencieusement.

Rôles

Fisherboy dispose de trois niveaux d’accès, chacun avec son propre mot de passe et ses limites de capacités (quels niveaux, proxys, capture d’API, solveur de captcha, exploration et tarentule sont autorisés). Les rôles sont appliqués à la fois sur REST et MCP.

Rôle	opaque	réversible	direct
`humano`	oui	—	—
`angel`	oui	oui	—
`dios`	oui	oui	oui

En gros : humano obtient les niveaux peu coûteux et aucune « arme » onéreuse ; angel ajoute le navigateur, le proxy et la capture (mais pas le solveur de captcha) ; dios a tout. La tarentule et la lecture des cookies du navigateur sont interdites en mode sidekick.

Utiliser l’interface web

En mode standalone, Fisherboy monte sa propre interface web à l’URL du service (par ex. http://localhost:8000). Après vous être connecté avec un mot de passe de rôle, vous :

Collez une URL et choisissez la sortie (markdown, llms_txt ou json) et le mode de confidentialité autorisé par votre rôle.
Activez éventuellement des extras — pagination, capture d’API, une profondeur d’exploration, tarentule, un proxy, des cookies.
Lancez le job ; le résultat s’ouvre dans un éditeur modal.

L’éditeur intégré

Le résultat s’ouvre dans un éditeur modal avec trois onglets :

Markdown — une barre d’outils avec aperçu en direct.
JSON — un éditeur avec validation.
Tableau — un tableau modifiable ; passer du JSON au tableau, c’est juste changer d’onglet.

Vous pouvez télécharger le résultat au format .md, .json ou .csv. Vous pouvez télécharger l’enveloppe entière, seulement les données (contenu + enregistrements + arbre + liens), ou un tableau plat d’enregistrements. Un clic envoie le résultat vers Escriba pour une conversion, anonymisation, segmentation et exportation supplémentaires.

Téléchargements

Au-delà du texte de la page, Fisherboy peut récupérer des médias et des données de plateformes :

Fichiers — téléchargements directs de fichiers.
Vidéo — via yt-dlp (YouTube, Vimeo et bien d’autres). ffmpeg, embarqué dans l’image, multiplexe vidéo + audio en mp4 haute qualité ; sans lui, les téléchargements se rabattent sur le meilleur fichier unique progressif.
Galeries / images — via gallery-dl (Instagram, X, Reddit, Pinterest, Tumblr, Flickr, DeviantArt et plus).
Commentaires / données de plateformes — multi-plateformes ; les commentaires de publications Instagram et les données d’abonnés/abonnements utilisent instaloader, qui nécessite un cookie de session (IG_SESSIONID) et est restreint au rôle dios.

API REST

POST /api/jobs            # valide le schéma, rôle × mode de confidentialité, callback & proxy (SSRF) ; met en file → 202
GET  /api/jobs/{job_id}   # statut et résultat (l'« enveloppe »)
POST /api/proxy/test      # achemine une requête via un proxy ; renvoie IP de sortie + pays + latence
POST /api/revert          # réhydrate le contenu pseudonymisé (mode réversible)
POST /api/login           # connexion par rôle (session par cookie)
GET  /healthz             # liveness
GET  /metrics             # métriques Prometheus

Soumettez un job et interrogez-le :

curl -X POST http://localhost:8000/api/jobs \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/article","rol":"angel","privacy_mode":"opaco"}'
# → { "job_id": "…", "status": "pendiente" }

curl http://localhost:8000/api/jobs/<job_id>
# → l'enveloppe avec content_md anonymisé une fois que status == "ok"

Champs du job

Champ	Notes
`url`	La page à récupérer.
`rol`	`humano` / `angel` / `dios`.
`privacy_mode`	`opaco` / `reversible` / `directo` (borné par le rôle).
`output_format`	`markdown` / `llms_txt` / `json`.
`tier_hint`	Niveau de départ suggéré, `0`–`3`.
`crawl_depth`	Profondeur pour l’exploration spider.
`max_pages`	Budget de pages (plafonné par `CRAWL_MAX_PAGES`).
`paginate`	Balayer la pagination.
`capture_api`	Capturer le JSON XHR/fetch caché.
`tarantula`	Capturer le contenu + l’API de chaque nœud dans un arbre de données.
`extract_schema`	JSON Schema pour l’extraction structurée (avec `output_format=json`).
`proxy`	Remplacement du proxy par job.
`cookies`	Cookies de session pour la requête.
`callback_url`	Webhook pour recevoir l’enveloppe à l’achèvement.

MCP

Le même pipeline est exposé en tant qu’outils MCP (submit_job, get_job, revert) afin que n8n, Claude Code ou Escriba puissent mettre en file sans écrire le HTTP à la main :

python -m app.mcp_server      # nécessite fastmcp

Le plafond de rôle du serveur MCP est défini par MCP_ROLE (il ne fait pas confiance à un rôle revendiqué par l’appelant).

Configuration avancée

Proxys

Collez un proxy dans n’importe quel format — host:port, host:port:user:pass, user:pass@host:port ou une URL complète — et Fisherboy le normalise (socks5 pris en charge). Le bouton Test (ou POST /api/proxy/test) achemine une requête à travers lui et renvoie votre IP de sortie + pays + latence, avec une indication exploitable s’il ne parvient pas à se connecter. Configurez un pool avec PROXIES, choisissez la rotation avec PROXY_ROTATION (round_robin / random / sticky), et ajustez PROXY_COOLDOWN_S et PROXY_ATTEMPTS. Un job peut remplacer le pool avec son propre proxy.

Cookies

Utilisez des pages derrière une authentification ou une région sans extension de navigateur. Collez des cookies au format Netscape cookies.txt, JSON ou paires name=value, ou lisez-les directement depuis votre navigateur local (Chrome / Firefox / Edge / Brave). La lecture des cookies du navigateur est uniquement en mode standalone et interdite en mode sidekick.

CAPTCHA

La stratégie anti-CAPTCHA par défaut est la prévention par escalade (CAPTCHA_SOLVER=none) : le gate de récupération détecte un CAPTCHA et monte d’un niveau. En option, un solveur d’API externe peut être configuré avec CAPTCHA_SOLVER=external, CAPTCHA_SOLVER_URL et CAPTCHA_SOLVER_KEY (soumis au rôle).

Pagination

Définissez paginate sur un job pour balayer des listes multi-pages. Fisherboy gère les schémas courants — postbacks ASP.NET, liens « next » et motifs de requête ?page=. Le total est borné par max_pages et le plafond strict CRAWL_MAX_PAGES.

Niveaux navigateur

Pour les niveaux 2 et 3, ajustez le navigateur sans interface avec BROWSER_HEADLESS, BROWSER_SETTLE_S (attente après chargement), BROWSER_SCROLL (déclenche le chargement différé), BROWSER_LOCALE et BROWSER_USER_AGENT.

Spider & tarentule (exploration profonde)

Spider — suit les liens internes pour former un arbre (avec restriction par section) jusqu’à crawl_depth, éventuellement combiné avec la pagination.
Tarentule — le mode profond : elle parcourt chaque nœud et capture à la fois son contenu et son API cachée dans un unique arbre de données. La tarentule est réservée aux rôles élevés et interdite en mode sidekick.

L’exploration multi-pages respecte robots.txt lorsque RESPECT_ROBOTS=1.

Sécurité et limites

Fisherboy est fail-closed et durci : anti-SSRF (DNS résolu ; plages privées/loopback/link-local/ métadonnées cloud bloquées, revalidées à chaque saut de redirection et à chaque requête navigateur, y compris le remplacement de proxy), nettoyage des secrets par job (identifiants de proxy, clé captcha, cookies n’apparaissent jamais dans l’enveloppe ou le webhook), contrôle par rôle sur REST et MCP, limitation de débit (MAX_JOBS_PER_MIN), plafonds stricts de pages et d’octets (CRAWL_MAX_PAGES, JOB_MAX_TOTAL_BYTES), et un conteneur non-root. Consultez la checklist de production avant de l’exposer — ne définissez jamais ALLOW_PRIVATE_TARGETS=1 ni FISHERBOY_OPEN_GOD=1 en production.

Persistance et observabilité optionnelles

La persistance Postgres + pgvector est optionnelle (DATABASE_URL, plus EMBEDDINGS_ENABLED pour un magasin de vecteurs) ; sans elle, le système fonctionne sur Redis seul et se dégrade en douceur. Une stack Prometheus + Loki + Grafana est disponible via docker-compose.observability.yml.