EmaIngestBot

1. Identità

Salvo che il cliente abbia aggiunto una propria nota — il paragrafo successivo la spiega — ogni richiesta di EmaIngestBot contiene esattamente questo header User-Agent:

EmaIngestBot/1.0 (+https://www.puglieseweb.com/crawler)

Per riconoscerci, confronta il product token, EmaIngestBot, e non l'intera stringa. Dalla propria console il cliente può aggiungere una breve nota all'interno del commento tra parentesi, in modo che il suo team operativo riconosca il traffico nei propri log. È un campo suo, non nostro: è limitato a 80 caratteri, parentesi, punti e virgola e caratteri di controllo vengono rimossi, e la nota è rifiutata se somiglia al nome di un altro crawler — ma nessuno da noi la esamina prima che finisca sulla rete, e preferiamo che tu lo sappia piuttosto che tu dia per scontato un passaggio di approvazione che non esiste. Ciò che una nota non può mai fare è sostituire il product token, la versione o il link a questa pagina.

Ad esempio, con una nota del cliente aggiunta:

EmaIngestBot/1.0 (+https://www.puglieseweb.com/crawler; site=example.com)

Non utilizziamo il crawler sotto altri nomi e non inviamo uno User-Agent simile a quello di un browser per mascherarlo.

2. Che cosa fa, e perché

Ema risponde alle email in entrata di un'azienda. Per rispondere in modo accurato ha bisogno del materiale pubblicato dall'azienda stessa — orari di apertura, condizioni di consegna, dettagli dei prodotti, politica dei resi — quindi EmaIngestBot scarica le pagine del sito di quell'azienda e ne passa il testo a Ema.

Richiede le pagine via HTTPS come farebbe un normale visitatore. Non effettua l'accesso, non invia moduli, non tenta di raggiungere contenuti protetti da autenticazione e non effettua ordini. Legge pagine web e sitemap XML e nient'altro: un PDF, un'immagine, un video o un endpoint JSON viene rifiutato in base al content type prima che il corpo della risposta venga scaricato.

Una scansione viene eseguita solo dopo che il cliente ha dimostrato di controllare il dominio, e lo stesso vale per il passaggio che la precede, quello che elenca le pagine del sito perché il cliente possa sceglierle. Due tipi di richiesta però raggiungono un dominio prima che qualcuno abbia dimostrato alcunché, e preferiamo dichiararli piuttosto che lasciarteli trovare nei log. Il primo è una singola richiesta HEAD, inviata quando un cliente salva un indirizzo web sul proprio account o modifica quello già presente: chiede soltanto se l'indirizzo si risolve e risponde, rinuncia dopo cinque secondi e qualunque risposta — compreso un 404 o un 500 — vale come risposta. Il secondo è la verifica stessa, che è il modo in cui la prova viene prodotta: una risoluzione DNS, la lettura del file token su /.well-known/ema-site-verification.txt oppure la lettura della tua homepage alla ricerca della riga che abbiamo emesso. Nessuna delle due richieste è una scansione. La richiesta HEAD non scarica alcuna pagina; le letture di verifica si fermano al primo kilobyte di un file token o ai primi 512 KB di una homepage, e nulla di ciò che vedono viene conservato, indicizzato o usato per rispondere alla domanda di qualcuno. Che cosa fanno queste due richieste rispetto a robots.txt lo dice la sezione 4: non lo consultano.

3. Autorizzazione: verifichiamo prima il controllo del dominio

Il Regno Unito non prevede alcuna eccezione commerciale per il text and data mining. La sezione 29A del Copyright, Designs and Patents Act 1988 copre esclusivamente la ricerca non commerciale. La base giuridica per copiare un sito web su scala commerciale è quindi la licenza concessa dal titolare del diritto d'autore, che per noi è il cliente. Quella licenza non vale nulla se il cliente non controlla davvero il dominio che ha inserito nel nostro modulo di attivazione: per questo verifichiamo, invece di fidarci sulla parola.

La scansione di un dominio inizia solo dopo che uno dei seguenti elementi è stato registrato sull'account. Il controllo è applicato nell'unico punto attraverso cui passano sia il pulsante di scansione della console sia la pianificazione notturna, quindi non esiste una strada che avvii una scansione aggirandolo, e anche il passaggio di elenco delle pagine è subordinato alla stessa registrazione. In tutto questo, example.com e www.example.com sono trattati come un solo dominio:

Un record DNS TXT

Pubblicato sull'apice del dominio, oppure su _ema-verify.<domain>, contenente il token che emettiamo. Lo cerchiamo su entrambi i nomi, tramite resolver pubblici DNS-over-HTTPS:

; at the apex of the domain
example.com.             IN  TXT  "ema-site-verification=<token>"

; or on a dedicated host
_ema-verify.example.com. IN  TXT  "ema-site-verification=<token>"

Un file token

Il token che emettiamo, servito come testo semplice dal dominio stesso. Leggiamo il primo kilobyte del file, esclusivamente via HTTPS e seguendo al massimo due redirect:

https://example.com/.well-known/ema-site-verification.txt

Un token nella tua homepage

Una riga che emettiamo noi, incollata nella homepage del dominio — come meta tag nell'<head> oppure come semplice testo in un punto qualsiasi della pagina. È la strada per un'attività che non ha una casella di posta sul proprio dominio né accesso al DNS, situazione ordinaria per una piccola impresa il cui sito è su Wix, Squarespace o GoDaddy. È anche la prova più aderente a ciò che viene concesso in licenza: le altre due dimostrano il controllo del dominio, questa dimostra il controllo del contenuto che la scansione copia. Per cercarla leggiamo i primi 512 KB della homepage, ed è il motivo per cui consigliamo il meta tag: l'<head> rientra sempre in quel limite. La riga può essere rimossa una volta che l'abbiamo confermata.

Un'attestazione registrata dell'operatore

La quarta modalità, e l'unica che il cliente non può completare da sé. Quando l'autorizzazione esiste su carta anziché in un record DNS — ad esempio in uno statement of work firmato che copre il patrimonio digitale del cliente — un membro dello staff di PuglieseWeb la registra sull'account, e la registrazione indica chi ha attestato e dove è conservata l'autorizzazione. È anche il modo in cui sono stati regolarizzati tutti i domini già configurati per una scansione nel momento in cui questo controllo è stato introdotto: quei clienti avevano autorizzato la scansione quando ci hanno incaricati, prima che esistesse un token da pubblicare, e l'alternativa era interrompere le loro scansioni da un giorno all'altro senza avvisarli. Un'attestazione resta però una nostra dichiarazione ed è più debole di una prova pubblicata dal cliente, quindi continuiamo a chiedere una delle tre modalità precedenti.

La verifica viene registrata sull'account e la scansione legge quella registrazione, non ricontrolla la prova. Non risolviamo di nuovo il record DNS e non riscarichiamo il file prima di ogni scansione, e un controllo successivo che fallisce non rimuove una verifica già registrata: rimuovere il record, da solo, non ci ferma. Esiste inoltre una quarta modalità, che il cliente non può usare: un membro del nostro staff può registrare un'attestazione su un account la cui autorizzazione è conservata su carta, indicando chi l'ha attestata e dove si trova, ed è così che sono stati regolarizzati tutti i domini già configurati per una scansione quando questo controllo è stato introdotto. Se vuoi revocare un'autorizzazione, scrivicelo — l'indirizzo è nella sezione 7 — e sospenderemo la scansione di quel dominio entro un giorno lavorativo, eliminando su richiesta i contenuti che ne abbiamo acquisito.

4. robots.txt

Rispettiamo robots.txt per il nostro product token, per scelta di policy, su ogni dominio che leggiamo — incluso il dominio del cliente stesso. Se un cliente autorizza la scansione del proprio sito ma il suo robots.txt ci vieta l'accesso, prevale il robots.txt e non leggiamo nulla. Il comportamento quando non riusciamo a leggere il tuo robots.txt è deliberatamente asimmetrico, ed è la parte che vale la pena conoscere: un 404 o un 410 è il tuo sito che risponde di non avere alcuna policy, quindi tutto è consentito, ed è ciò che stabilisce la sezione 2.3.1.3 dell'RFC 9309; qualsiasi altra risposta — un 5xx, un 403, un 429, un timeout, una connessione rifiutata — è il tuo sito che non risponde, quindi consideriamo vietato l'intero dominio e non scarichiamo nulla, secondo la sezione 2.3.1.4. I siti meno in grado di servire un robots.txt non devono essere quelli che scansioniamo più intensamente.

Va però detto con chiarezza che cos'è robots.txt: non è una concessione di accesso. Una regola Allow non è una licenza per copiare un sito e l'assenza di una regola Disallow non è un consenso. La nostra facoltà di effettuare la scansione deriva dal controllo verificato del dominio e da un contratto con il titolare del diritto d'autore, mai da un file che chiunque può pubblicare. Lo scriviamo qui perché nessuno sia tratto in inganno sulle basi su cui operiamo.

Per impedire a EmaIngestBot di scansionare il tuo sito, aggiungi questo al tuo robots.txt:

User-agent: EmaIngestBot
Disallow: /

Per consentirlo esplicitamente — utile se il tuo robots.txt vieta per impostazione predefinita gli agenti sconosciuti:

User-agent: EmaIngestBot
Allow: /

Scarichiamo robots.txt una volta sola, prima dell'inizio di ogni scansione, quindi una modifica ha effetto sulla scansione successiva e non a metà di quella in corso. Due tipi di richiesta non lo consultano, e li dichiariamo qui invece di lasciarteli scoprire: la singola richiesta HEAD che verifica un indirizzo appena salvato o appena modificato da un cliente, e le richieste che cercano un token di verifica in /.well-known/ema-site-verification.txt o nella homepage. Nessuna di queste richieste fa parte di una scansione. La richiesta HEAD non scarica alcuna pagina; le richieste di verifica leggono solo quanto basta per trovare la riga che abbiamo emesso — il primo kilobyte del file token oppure i primi 512 KB di una homepage — e non ne conservano nulla. La sezione 2 descrive entrambe dall'altro lato.

5. Limiti di frequenza e comportamento del crawler

Limiti concreti, perché «effettuiamo scansioni in modo educato» non è qualcosa che si possa inserire in una regola di firewall:

• Le richieste verso un singolo host vengono effettuate una alla volta all'interno di una scansione, e sono cadenzate: almeno un secondo di distanza durante una scansione e almeno mezzo secondo durante la più breve fase di elenco delle pagine che la precede. La cadenza è un'unica impostazione per l'intero servizio e regola ogni singolo processo anziché sincronizzarli fra loro: una scansione e un elenco pagine avviati a breve distanza non vengono quindi distanziati l'uno dall'altro.
• Ogni richiesta ha un timeout, diverso a seconda della fase: 30 secondi per una pagina durante una scansione, 6 secondi durante l'elenco delle pagine, 8 secondi per la lettura della homepage che verifica un token di verifica e 5 secondi per il controllo una tantum che un indirizzo appena salvato risponda. Una richiesta che supera il proprio timeout viene abbandonata e la pagina registrata come non riuscita.
• Una scansione memorizza al massimo 60 pagine, e di richieste ne fa di più: se stai facendo un riscontro con il tuo access log, conta le richieste e non le pagine memorizzate. Una scansione dell'intero sito scarica fino a circa 120 pagine prima che il suo budget la fermi; una scansione di un elenco di pagine compilato a mano scarica fino a 60 pagine elencate, più al massimo altre 20 lette soltanto per le coppie domanda-risposta che contengono. In aggiunta, in entrambi i casi: un robots.txt e fino a cinque richieste di sitemap. Il limite di 60 pagine è fissato nel prodotto e non viene alzato su accordo.
• In caso di HTTP 429 o 503 — le due risposte che significano «più tardi» e non «no» — attendiamo e riproviamo la stessa pagina al massimo altre due volte, raddoppiando ogni volta l'attesa a partire dal ritardo di base e senza mai attendere più di 12 secondi. Dopodiché la pagina è registrata come non riuscita e la scansione passa alla successiva. Un 404 è una risposta, non un contrattempo, e non viene mai ritentato.
• Una scansione resta sul dominio verificato: i link verso altri host non vengono seguiti, gli URL con una query string non vengono scaricati affatto e il corpo di una risposta viene abbandonato una volta superati i 2 MB. Dalla console di un cliente si possono avviare al massimo cinque scansioni al giorno di un dominio, e una scansione pianificata rientra in quelle cinque. Il nostro staff non è soggetto a quel limite — una richiesta di assistenza non è un caso di abuso — quindi, se ti serve un tetto su cui fare affidamento, è quello delle 60 pagine, non quello delle cinque esecuzioni.

Se questi limiti sono comunque superiori a quanto la tua infrastruttura può assorbire, scrivicelo. Possiamo ridurre l'ambito per il tuo dominio — un elenco di pagine più breve, oppure una scansione solo su richiesta anziché pianificata — e possiamo rallentare il crawler, anche se la cadenza è un'unica impostazione per l'intero servizio e non una manopola per singolo dominio. In entrambi i casi è più rapido che bloccarci e, per entrambi, più semplice di un incidente.

6. Verificare che il traffico sia davvero nostro

L'header User-Agent da solo non dimostra nulla. Qualsiasi client può inviare qualsiasi stringa e i crawler che preferiscono non essere identificati adottano abitualmente l'identità di quelli che invece lo sono. Se stai osservando traffico aggressivo che dichiara di essere EmaIngestBot, è del tutto possibile che non sia nostro: bloccare in base alla sola stringa ferma i bot educati e nessuno di quelli scorretti.

Se hai bisogno di certezza, inviaci il dominio interessato, gli orari con il relativo fuso orario e gli indirizzi IP di origine presenti nei tuoi log. Ogni scansione che eseguiamo scrive una propria registrazione: quando è stata richiesta e da chi, l'host per cui è stata eseguita, se quell'host risultava verificato in quel momento e quale delle quattro prove era agli atti. Possiamo quindi dirti se in quella finestra stavamo scansionando il tuo dominio e con quale autorizzazione. Ciò che non possiamo fare è confrontare le tue righe di log con le nostre una richiesta alla volta — non registriamo l'indirizzo da cui esce ciascuna richiesta — quindi la risposta che otterrai riguarda la finestra temporale, non la singola riga.

Al momento non pubblichiamo un elenco di indirizzi IP di uscita per l'inserimento in allowlist. Se il tuo ambiente ne ha bisogno, chiedicelo.

7. Come fermarci del tutto

Tre modalità. Ne basta una:

• robots.txt — aggiungi il blocco Disallow della sezione 4. Ha effetto dalla scansione successiva.
• Una regola di firewall, CDN o WAF — blocca il product token o gli indirizzi di origine. Non tenteremo di aggirare un blocco: non ruotiamo gli indirizzi, non modifichiamo il nostro User-Agent e non riproviamo da altrove per superarlo.
• Scrivici — sospenderemo la scansione e, se ce lo chiedi, elimineremo i contenuti già acquisiti dal tuo dominio.

8. Pagine correlate

Altre due pagine rispondono alle domande che di solito seguono questa:

• Fiducia e sicurezza — Hosting, sub-responsabili del trattamento, crittografia, conservazione, notifica delle violazioni e segnalazione delle vulnerabilità.
• Informativa sulla privacy — Quali dati personali raccogliamo, le basi giuridiche su cui ci fondiamo e i tuoi diritti ai sensi del UK GDPR.