Documentazione di Fisherboy

Questa pagina documenta il funzionamento di Fisherboy dall’inizio alla fine: i concetti fondamentali, l’interfaccia web, le capacità di download, le API REST e MCP, e la configurazione avanzata.

Concetti

Il job e l’envelope

Tutto ciò che Fisherboy fa è un job. Invii un job (un URL più delle opzioni), viene accodato su Redis, un worker esegue la pipeline e il risultato viene memorizzato come envelope — un singolo oggetto che contiene il contenuto estratto (content_md), i record strutturati, l’albero del crawl, i link scoperti e i metadati. Interroghi il job finché il suo stato è ok.

Fetch a livelli (scala solo quando viene bloccato)

Fisherboy non ricorre mai a un browser pesante finché non è necessario. Prova prima il metodo più economico e sale solo quando un gate rileva un blocco o un CAPTCHA:

• Livello 0 — HTTP statico con httpx. Veloce ed economico; funziona per la maggior parte delle pagine statiche.
• Livello 1 — impronta TLS con curl_cffi, così la richiesta sembra quella di un browser reale a livello di rete.
• Livello 2 — browser stealth (Camoufox / Patchright) per pagine ricche di JavaScript e anti-bot; questo livello guida anche la cattura delle API nascoste.
• Livello 3 — un browser reale (nodriver / Playwright) come ultima risorsa.

Il livello vincente viene messo in cache per dominio (TIER_CACHE_TTL_S), così la richiesta successiva allo stesso sito parte da dove è riuscita l’ultima volta. I livelli alti sono importati in modo lazy — l’immagine base resta leggera, e ogni livello si attiva solo se la sua libreria è installata. Il tetto dell’escalation si imposta con MAX_FETCH_TIER, e tier_hint su un job può suggerire un punto di partenza.

Cattura delle API nascoste

Le single-page app e le griglie dinamiche vengono renderizzate dal JSON che recuperano tramite XHR/fetch. Invece di combattere contro l’HTML renderizzato, Fisherboy può osservare quelle risposte di rete e conservare il JSON che la pagina consuma già — di solito la fonte di dati più affidabile e completa. Abilitala per job con capture_api.

Modalità di privacy

La modalità di privacy viene scelta per job ed è delimitata dal ruolo (definito in privacy_matrix.yaml, mai hardcoded). La pipeline è fail-closed: se l’anonimizzazione fallisce, non viene consegnato nulla di grezzo.

• opaca (opaco) — ogni entità diventa un marcatore tipizzato stabile come «PERSON_1» o «ID_2». L’LLM ragiona sui marcatori e non vede mai le PII; l’originale non è recuperabile.
• reversibile (reversible) — lo stesso mascheramento, ma viene conservata una mappa cifrata token-valore per poter reidratare in seguito tramite POST /api/revert (a uso singolo, legata al ruolo). La mappa è cifrata con una chiave Fernet (REVERSIBLE_KEY) e scade dopo REVERSIBLE_TTL_S.
• diretta (directo) — output grezzo, solo per dati non sensibili.

Un passaggio regex deterministico viene sempre eseguito per le PII ad alto rischio (documento d’identità nazionale, email, IP, carta valida secondo Luhn, telefono). Quando ANONIMAL_URL punta a un’istanza di Anonimal, il NER completo viene eseguito al di sopra; in modalità standalone si ricade solo sul passaggio regex integrato.

Se un ruolo non consente la modalità richiesta, il gateway restituisce 403 — non effettua mai silenziosamente un downgrade.

Ruoli

Fisherboy ha tre livelli di accesso, ciascuno con la propria password e limiti di capacità (quali livelli, proxy, cattura delle API, risolutore captcha, crawl e tarantola sono consentiti). I ruoli sono applicati su entrambe le interfacce REST e MCP.

Ruolo	opaca	reversibile	diretta
humano	sì	—	—
angel	sì	sì	—
dios	sì	sì	sì

In generale: humano ottiene i livelli economici e nessuna costosa “arma”; angel aggiunge browser, proxy e cattura (ma niente risolutore captcha); dios ha tutto. Tarantola e la lettura dei cookie del browser sono vietate in modalità sidekick.

Usare l’interfaccia web

In modalità standalone Fisherboy monta la propria interfaccia web all’URL del servizio (es. http://localhost:8000). Dopo aver effettuato il login con una password di ruolo, puoi:

1. Incollare un URL e scegliere l’output (markdown, llms_txt o json) e la modalità di privacy consentita dal tuo ruolo.
2. Opzionalmente abilitare degli extra — paginazione, cattura delle API, una profondità di crawl, tarantola, un proxy, i cookie.
3. Eseguire il job; il risultato si apre in un editor modale.

L’editor integrato

Il risultato si apre in un editor modale con tre schede:

• Markdown — una barra degli strumenti con anteprima live.
• JSON — un editor con validazione.
• Tabella — una tabella modificabile; JSON ↔ tabella è semplicemente cambiare scheda.

Puoi scaricare il risultato come .md, .json o .csv. Puoi scaricare l’intera envelope, solo i dati (contenuto + record + albero + link), oppure un array piatto di record. Un clic invia il risultato a Escriba per ulteriore conversione, anonimizzazione, suddivisione in chunk ed esportazione.

Download

Oltre al testo della pagina, Fisherboy può recuperare media e dati delle piattaforme:

• File — download diretti di file.
• Video — tramite yt-dlp (YouTube, Vimeo e molti altri). ffmpeg, incluso nell’immagine, combina video + audio in mp4 di alta qualità; senza di esso, i download ricadono sul miglior file progressivo singolo.
• Gallerie / immagini — tramite gallery-dl (Instagram, X, Reddit, Pinterest, Tumblr, Flickr, DeviantArt e altri).
• Commenti / dati delle piattaforme — multi-piattaforma; i commenti dei post di Instagram e i dati su follower/seguiti usano instaloader, che necessita di un cookie di sessione (IG_SESSIONID) ed è limitato al ruolo dios.

API REST

POST /api/jobs            # valida lo schema, ruolo × modalità di privacy, callback e proxy (SSRF); accoda → 202
GET  /api/jobs/{job_id}   # stato e risultato (l'"envelope")
POST /api/proxy/test      # instrada una richiesta attraverso un proxy; restituisce IP di uscita + paese + latenza
POST /api/revert          # reidrata il contenuto pseudonimizzato (modalità reversibile)
POST /api/login           # login del ruolo (sessione con cookie)
GET  /healthz             # liveness
GET  /metrics             # metriche Prometheus

Invia un job e interrogalo:

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'envelope con content_md anonimizzato una volta che status == "ok"

Campi del job

Campo	Note
url	La pagina da recuperare.
rol	humano / angel / dios.
privacy_mode	opaco / reversible / directo (delimitato dal ruolo).
output_format	markdown / llms_txt / json.
tier_hint	Livello di partenza suggerito, 0–3.
crawl_depth	Profondità per il crawl spider.
max_pages	Budget di pagine (limitato da CRAWL_MAX_PAGES).
paginate	Scorri la paginazione.
capture_api	Cattura il JSON XHR/fetch nascosto.
tarantula	Cattura il contenuto + le API di ogni nodo in un albero di dati.
extract_schema	JSON Schema per l’estrazione strutturata (con output_format=json).
proxy	Override del proxy per il singolo job.
cookies	Cookie di sessione per la richiesta.
callback_url	Webhook che riceve l’envelope al completamento.

Nota

I valori di job e stato usano gli identificatori spagnoli originali del progetto (es. rol, i valori di privacy_mode opaco/reversible/directo, e lo stato pendiente/ok).

MCP

La stessa pipeline è esposta come strumenti MCP (submit_job, get_job, revert) così n8n, Claude Code o Escriba possono accodare senza scrivere a mano l’HTTP:

python -m app.mcp_server      # richiede fastmcp

Il tetto del ruolo del server MCP è impostato da MCP_ROLE (non si fida di un ruolo dichiarato dal chiamante).

Configurazione avanzata

Proxy

Incolla un proxy in qualsiasi formato — host:port, host:port:user:pass, user:pass@host:port o un URL completo — e Fisherboy lo normalizza (socks5 supportato). Il pulsante Test (o POST /api/proxy/test) instrada una richiesta attraverso di esso e restituisce il tuo IP di uscita + paese + latenza, con un suggerimento utile se non riesce a connettersi. Configura un pool con PROXIES, scegli la rotazione con PROXY_ROTATION (round_robin / random / sticky), e regola PROXY_COOLDOWN_S e PROXY_ATTEMPTS. Un job può sovrascrivere il pool con il proprio proxy.

Cookie

Usa pagine dietro un login o una regione senza un’estensione del browser. Incolla i cookie come Netscape cookies.txt, JSON o coppie name=value, oppure leggili direttamente dal tuo browser locale (Chrome / Firefox / Edge / Brave). La lettura dei cookie del browser è solo standalone ed è vietata in modalità sidekick.

CAPTCHA

La strategia anti-CAPTCHA predefinita è la prevenzione tramite escalation (CAPTCHA_SOLVER=none): il gate di fetch rileva un CAPTCHA e sale di un livello. Opzionalmente, può essere configurato un risolutore esterno via API con CAPTCHA_SOLVER=external, CAPTCHA_SOLVER_URL e CAPTCHA_SOLVER_KEY (delimitato dal ruolo).

Paginazione

Imposta paginate su un job per scorrere gli elenchi multi-pagina. Fisherboy gestisce gli schemi comuni — postback ASP.NET, link “next” e pattern di query ?page=. Il totale è limitato da max_pages e dal limite massimo CRAWL_MAX_PAGES.

Livelli con browser

Per i livelli 2 e 3, regola il browser headless con BROWSER_HEADLESS, BROWSER_SETTLE_S (attesa dopo il caricamento), BROWSER_SCROLL (attiva il lazy-load), BROWSER_LOCALE e BROWSER_USER_AGENT.

Spider e tarantola (crawl profondo)

• Spider — segue i link interni in un albero (con delimitazione per sezione) fino a crawl_depth, opzionalmente combinato con la paginazione.
• Tarantola — la modalità profonda: percorre ogni nodo e cattura sia il suo contenuto sia la sua API nascosta in un unico albero di dati. La tarantola è riservata ai ruoli alti ed è vietata in modalità sidekick.

Il crawling multi-pagina rispetta robots.txt quando RESPECT_ROBOTS=1.

Sicurezza e limiti

Fisherboy è fail-closed e indurito: anti-SSRF (DNS risolto; intervalli privati/loopback/link-local/ metadati cloud bloccati, ri-validati a ogni hop di redirect e a ogni richiesta del browser, incluso l’override del proxy), scrubbing dei segreti per job (credenziali del proxy, chiave captcha, cookie non compaiono mai nell’envelope o nel webhook), gating dei ruoli su REST e MCP, limitazione di frequenza (MAX_JOBS_PER_MIN), limiti massimi di pagine e byte (CRAWL_MAX_PAGES, JOB_MAX_TOTAL_BYTES), e un container non-root. Esamina la checklist di produzione prima di esporlo — non impostare mai ALLOW_PRIVATE_TARGETS=1 o FISHERBOY_OPEN_GOD=1 in produzione.

Persistenza e osservabilità opzionali

La persistenza Postgres + pgvector è opzionale (DATABASE_URL, più EMBEDDINGS_ENABLED per uno store vettoriale); senza di essa il sistema gira sul solo Redis e degrada con grazia. Uno stack Prometheus + Loki + Grafana è disponibile tramite docker-compose.observability.yml.