Recensione di Katana: `-jc` e `-headless` trovano endpoint diversi e nessun singolo comando li copre entrambi

Katana è il crawler di ProjectDiscovery per la discovery degli endpoint: un binario Go con licenza MIT che prende un target e restituisce URL ed endpoint da passare allo strumento successivo in una pipeline. Può fare il crawling in modalità HTTP senza browser oppure con -headless, che controlla Chromium. La documentazione ufficiale presenta la modalità headless come quella con copertura migliore; questo test mostra perché conta tantissimo anche il tipo di endpoint, non solo il numero.

Ho creato un piccolo sito con tre classi di endpoint volutamente diverse e ho misurato quale modalità trovava ciascuna di esse su v1.6.1 con -d 4. L’HTML tradizionale ha portato a casa 4/4 link e l’intera catena a tre livelli in tutte e quattro le configurazioni. La differenza è emersa negli endpoint esposti tramite sorgenti JavaScript e tramite modifiche runtime al DOM.

Su questo test, la modalità headless ha trovato la classe basata sul DOM a runtime che le modalità senza browser non vedevano, mentre la modalità standard con -jc ha trovato i literal nei file JavaScript che entrambe le esecuzioni headless hanno mancato. Nessuna riga della matrice a quattro comandi copriva entrambe le classi. Scope, resume e comportamento dei known files definivano gli altri limiti pratici.

Cos’è davvero katana

Il crawler katana — projectdiscovery/katana su GitHub — è scritto in Go e rilasciato con licenza MIT. Ho testato v1.6.1 il 27 luglio 2026; la versione conta perché i risultati su copertura e known files riportati sotto sono osservazioni legate alla build.

Qui la categoria è più importante del solito. Un endpoint-discovery crawler non è uno strumento di estrazione dati. Se cerchi un go web crawler che ti restituisca nomi prodotto e prezzi in JSON strutturato, katana è il reparto sbagliato: ti dirà volentieri che esiste /products/1138, ma non ti dirà nulla su cosa contiene quella pagina. È progettato così, e giudicarlo per l’estrazione sarebbe come recensire un metal detector in base alla sua capacità di valutare i gioielli.

Il suo terreno naturale è la reconnaissance per offensive security e le pipeline di automazione: STDIN in ingresso, URL in uscita, poi verso lo strumento successivo. Da qui la premessa ovvia ma fondamentale: ogni misura qui è stata eseguita su un fixture su 127.0.0.1 che ho scritto io stesso. Usate katana solo su host che possedete o per i quali avete un’autorizzazione esplicita al test, e su nient’altro. Non si tratta di aggirare difese di qualcuno; si tratta di capire quanta superficie di endpoint un certo comando riesca davvero a enumerare.

Le tre modalità e ciò che ciascuna vede

La modalità standard usa un client HTTP in Go. Scarica le pagine, analizza l’HTML, segue gli href e non avvia mai un browser. È veloce, economica e cieca verso tutto ciò che esiste solo dopo l’esecuzione di JavaScript.

-jc (-js-crawl) aggiunge un parser JavaScript al percorso senza browser. Scarica i file .js collegati ed estrae dal sorgente le stringhe che sembrano URL. Nessuna esecuzione, solo lettura. Esiste anche -jsl (jsluice), descritto nel README come parser più pesante e più esigente in memoria — non l’ho testato, quindi non posso dire se cambi il quadro della copertura.

-headless controlla Chromium ed esegue gli script della pagina. In questo fixture, è stata l’unica modalità testata di Katana a recuperare il percorso costruito da frammenti e inserito nel DOM a runtime. Questo risultato non dimostra cosa possano recuperare tutti i parser o eventuali future modalità di Katana.

Poi c’è il modello di scope, la parte che interiorizzerei prima di digitare qualsiasi cosa in produzione.

L’ordine non è cosmetico: decide se una regex sugli host amplia il crawl o lo svuota senza avvisi.

Setup: un binario, un asterisco

Tre modi per installarlo, e solo uno richiede una toolchain:

Il mio è finito in ~/go/bin/katana e ha mostrato Current version: v1.6.1 a ogni esecuzione. Fin qui la solita storia piacevole del mondo Go: un file, niente runtime.

L’asterisco è la modalità headless, dove il browser è un prerequisito separato dal binario:

Su un server minimale questa comodità sparisce. Bisogna mettere a budget anche un browser, non solo un binario, non appena -headless entra nella command line.

Un dettaglio utile se lo usate in CI: katana esegue all’avvio una chiamata di controllo versione verso GitHub. -duc la disabilita. Su un laptop è rumore; su un runner air-gapped o soggetto a rate limit è un round trip di rete per ogni run che non avete chiesto. Nei miei test di timing ho passato -duc così i numeri misurano il crawling e non il callback verso casa.

Come l’ho testato

Tre classi di endpoint, scelte apposta perché separano le modalità. Tutto vive in un server di fixture locale, e la verità di base è stata annotata prima di qualsiasi crawl, così il recall viene misurato rispetto a un set fisso e non a ciò che katana ha deciso di stampare.

• Classe A — HTML normale. /page/a, /page/b, /page/c, più una catena a tre salti /depth/1 → /depth/2 → /depth/3. Qualunque crawler dovrebbe prenderli.
• Classe B — literal nei file JavaScript. /api/js-endpoint-7 e /api/js-endpoint-8 esistono solo come stringhe dentro un /static/app.js collegato. Leggibili senza browser, se qualcuno si prende la briga di leggere il JS.
• Classe C — solo DOM a runtime. Un percorso assemblato a runtime da frammenti ('endpoint' + (6 * 7)) e inserito nel DOM dallo script. La stringa /runtime-only/endpoint42 non appare mai in modo contiguo in nessun byte inviato dal server — né nell’HTML, né nel sorgente JS. Solo l’esecuzione la rende visibile.

In più: robots.txt, sitemap.xml con due endpoint <loc> che non compaiono da nessun’altra parte, una route che restituisce 500, un dead link e un link fuori scope che punta a un secondo server su un hostname diverso.

Anche lo strumento di misura conta quanto il fixture: il server registra ciò che è stato davvero richiesto, quindi le affermazioni su scope e resume si basano sui hit reali e non sullo stdout di katana. I run grezzi sono salvati nel repo del benchmark se volete verificare i conti.

Il divario di copertura che nessuno quantifica

La matrice, modalità per classe di endpoint, con -d 4:

Guardate insieme le ultime due colonne e il problema salta fuori. La classe B è stata trovata da una sola configurazione: modalità standard con -jc. La classe C è stata trovata da due sole configurazioni: entrambe le esecuzioni headless. Non esiste una riga con un risultato positivo in entrambe le colonne. La matrice completa è in discovery-summary.json, dove il campo calcolato headless_jc_covers_both risulta false.

La conseguenza pratica è che “usa semplicemente headless per avere più copertura” è una semplificazione incompleta per questo test. Headless non ha aggiunto la classe B al risultato standard; ha recuperato la classe C ma perdendo la classe B. Coprire tutte le classi inserite in questo fixture ha richiesto due crawl e un merge:

katana -u https://target.example -jc -d 4 -silent -o pass-jc.txt
katana -u https://target.example -headless -d 4 -silent -o pass-headless.txt
sort -u pass-jc.txt pass-headless.txt > endpoints.txt

La riga -headless -jc è quella su cui vorrei di più una risposta upstream. Aggiungere il parser JavaScript alla run headless non ha recuperato nulla di nuovo — ancora 0/2 sulla classe B, in ogni run, compresa una riproduzione pulita. Sto riportando il comportamento, non sostenendo di averne tracciato il meccanismo; non ho strumentato gli internals di katana per capire perché il percorso browser smetta di contribuire ai literal nei file JS. Consideratelo un’osservazione riproducibile e un buon issue GitHub, non una diagnosi. (Vale la pena notare che la combinazione -hl -jc si è completata correttamente con return code 0 su v1.6.1 su macOS ARM, cosa che storicamente non è sempre stata vera.)

La documentazione ufficiale descrive headless come una modalità con copertura migliore, e qui effettivamente lo è stata per la classe renderizzata a runtime. La guida verificata non spiegava però questa separazione tra source literal e runtime DOM, quindi prendete la matrice come motivo per testare entrambi i percorsi sulle vostre classi di endpoint, non come tassonomia universale.

Quanto costa headless in tempo reale

Tre run sequenziali per modalità su una macchina altrimenti inattiva:

È un rapporto di 5,1x con intervalli che non si sovrappongono nemmeno lontanamente: la mia esecuzione standard più lenta (13,17s) ha comunque battuto la mia esecuzione headless più veloce (66,78s) di oltre 53 secondi (cost-summary.json). Non è rumore di misura.

Un caveat su quei 13 secondi: il mio fixture include volutamente una route che restituisce 500 e un dead link, e la modalità standard attende il tail di retry predefinito -timeout 10 su entrambi. Non ho ritoccato il timeout per rendere più bella la modalità veloce, il che significa che un run standard ottimizzato probabilmente amplierebbe il divario invece di ridurlo.

Il rapporto è un segnale locale di capacità, non una previsione di produzione. I target reali variano per latenza, errori, lavoro degli script e scheduling, mentre questo fixture include un tail di timeout predefinito. Usate la differenza misurata di 5,1x per decidere se headless merita un budget separato e un sottoinsieme di target, poi verificate quel piano su host rappresentativi e autorizzati.

Scope rispettato, ma un flag non ha fatto nulla in silenzio

Il test di scope ha usato due server: il principale su 127.0.0.1 e un secondo raggiungibile come localhost su una porta diversa, che serve un path esistente solo lì. Quindi un hit su quel path è prova del fatto che l’host fuori scope è stato davvero richiesto, non semplicemente stampato.

La disciplina dello scope è una buona notizia: di default katana è rimasto nel perimetro, e per allargarlo è servita un’azione esplicita. È il comportamento giusto per uno strumento che viene puntato sull’infrastruttura di altri.

La riga interessante è -cs localhost. Non ha ampliato il crawl al secondo host — e ha anche emesso zero URL in assoluto. Siccome -cs filtra dentro lo field scope, e il field scope era ancora quello dell’host primario, la regex non ha trovato nulla e il crawl ha restituito un insieme vuoto invece di un errore. Se avete mai scritto una regex di scope nominando un host che volevate includere e vi siete ritrovati a fissare un file di output vuoto, è questo il meccanismo (scope-summary.json). Per aggiungere un host, usate -fs. Per restringere all’interno degli host già inclusi, usate -cs/-cos.

Il resume è più grossolano di quanto suggerisca il flag

Il README descrive il flag come -resume string resume scan using resume.cfg, che fa pensare a un file lasciato nella directory di lavoro. Non è così. Sulla mia macchina il checkpoint è stato scritto in ~/.config/katana/resume-<xid>.cfg — misurato, non ricavato da una pagina di documentazione, perché i docs non indicano alcun path.

Il contenuto è la sorpresa più importante. Il file conteneva una mappa InFlightUrls con esattamente una cosa: la seed URL. Non l’insieme delle pagine visitate, non la frontier. Ecco cosa è successo quando ho interrotto un crawl con SIGINT dopo tre secondi e poi l’ho ripreso:

Il resume ha raggiunto lo stesso insieme finale di endpoint, quindi non è rotto. Ma la granularità del checkpoint è per seed di input, non per URL — il filtro di deduplica in memoria non viene mai persistito, quindi riprendere un crawl con una sola seed significa rifare da zero quella seed (resume-summary.json). Se date in pasto a katana una lista di 500 host, il resume dovrebbe salvarvi quelli che erano già stati completati; questo comportamento multi-seed deriva dal modo in cui lo stato viene salvato, ma io ho misurato solo il caso a singola seed. Se state lavorando su un sito enorme, il resume vi aiuta sulla correttezza, non sul tempo.

Known files: richiesti, poi abbandonati

-kf all -d 3 ha effettivamente richiesto entrambi i file — robots.txt e sitemap.xml sono comparsi nel log dei hit del server — ma poi ha recuperato 0 su 2 degli endpoint elencati negli elementi <loc> di quella sitemap. Recall 0.0.

Prima di attribuire il problema allo strumento ho provato a renderlo colpa mia. Ogni variante ha recuperato esattamente lo stesso risultato:

Il requisito documentato — usare -kf, andare almeno a profondità tre — è stato rispettato ogni volta. Non è una storia di flag mancanti.

La decisione utile viene prima: su questo fixture con IP letterale, non assumete che richiedere i known files significhi che i loro URL <loc> siano entrati nel crawl. Verificate il recall, oppure estraeteli e usateli come seed voi stessi.

Il percorso di v1.6.1 è coerente con l’osservazione, ma durante l’esecuzione non l’ho strumentato. In sitemapxml.go su v1.6.1, NewNavigationRequestURLFromResponse costruisce le richieste di navigazione per i <loc> a partire da una response senza RootHostname valorizzato. La richiesta arriva poi a ValidateScope; in scope.go su v1.6.1, il ramo per host con IP letterale confronta l’host dell’URL con quella root vuota e può rifiutarlo. Il comando personalizzato -fs '(127.0.0.1|localhost)' ha preso un ramo diverso del validation test sullo scope, quindi è un salvataggio prevedibile dal sorgente, non un workaround misurato per -kf. Un tentativo di conferma è stato bloccato da problemi intermittenti di dialing nel client dei known files su questo host; il risultato riportato resta quindi 0/2.

In produzione, finché qualcuno non conferma il flag, farei così: scaricare la sitemap, estrarre gli URL <loc> e passarli a katana come lista di seed. Due righe di shell, nessuna validazione di scope in mezzo.

Una cosa però ha funzionato esattamente come dichiarato e merita una frase: la route 500 e il dead link sono stati richiesti, registrati e saltati. Ogni run senza browser è terminato con return code 0. Un crawler che si blocca al primo response errato è inutile se lasciato a sé stesso, e katana non lo fa.

Un controllo di copertura specifico per il target prima del deploy

La matrice del fixture è più utile come modello per testare i vostri target autorizzati. Definite le classi di endpoint prima di eseguire Katana: link normali, literal nei script collegati, route create solo dopo l’esecuzione e voci provenienti dai known files sono quattro gruppi di partenza ragionevoli. Tenete un piccolo campione di ground truth per ciascuna classe. Senza quella lista preliminare, un output stdout più grande può sembrare una copertura migliore anche quando una classe è sparita.

Eseguite prima come misure separate i percorsi senza browser e quelli headless. Salvate i comandi esatti, la versione di Katana, la build del browser, i return code e gli output. Normalizzate e confrontate i set di endpoint, invece di fermarvi al numero di righe. Se il solo -jc standard non aggiunge nulla di unico al vostro campione, una policy solo headless può bastare; se i set divergono come qui, tenete separati i due passaggi e fate il merge dopo la raccolta. Aggiungere entrambi i flag a un solo comando non va considerato automaticamente equivalente all’unione finché il diff specifico del target non lo dimostra.

Validate lo scope con evidenze esterne allo stdout di Katana. Mettete una canary URL su un host che dovrebbe restare escluso e controllate il log delle richieste di quel server. Testate anche un secondo host previsto, se il crawl dovrebbe allargarsi. Il run -cs localhost qui ha prodotto un output vuoto perché il content-scope filtering non ha esteso il field scope; l’invocazione custom -fs '(127.0.0.1|localhost)' ha invece contattato il secondo server. Registrare la regex esatta è importante perché un solo carattere può cambiare la regex e non solo la sua presentazione.

Testate l’interruzione e i known files separatamente dal recall della discovery. Per il resume, interrompete una seed rappresentativa dopo alcune pagine, salvate il path del checkpoint generato e contate quante URL già completate vengono richieste di nuovo. Per -kf, verificate sia che robots/sitemap siano stati richiesti sia che gli URL <loc> inseriti siano stati davvero schedulati. Sono affermazioni diverse. In questo fixture i file venivano richiesti mentre i due endpoint della sitemap erano assenti, quindi servivano sia i log delle richieste sia l’output degli endpoint per vedere il confine.

Infine, stabilite un baseline locale di costo usando run sequenziali su una macchina altrimenti inattiva, poi ripetete sui target rappresentativi. Conservate minimo, massimo e mediana, non solo un moltiplicatore. Il fattore 5,1x qui include il comportamento di failure e timeout del fixture; vi dice che headless merita un budget separato, non quanto impiegherà un inventario di produzione.

Pro e contro

Pro:

• Recall perfetto sull’HTML normale in ogni modalità — 4/4 link e tutta la catena 3/3, senza configurazioni speciali.
• -jc funziona davvero senza browser: 2/2 endpoint recuperati da literal in un file JS collegato, senza costo headless.
• -headless è l’unica cosa che ha trovato un endpoint assemblato a runtime — una classe, per costruzione, invisibile al parsing del sorgente.
• I default di scope sono conservativi. L’host fuori scope non è mai stato richiesto con default, -fs fqdn o -cs.
• Un solo binario Go, licenza MIT, build precompilate e immagine Docker, I/O pensato per le pipeline.
• Robusto sugli errori: i 500 e i dead link non fermano il crawl.

Contro:

• Nessuna singola invocazione ha coperto sia gli endpoint nei file JS sia quelli nel DOM runtime. Per la copertura completa servono due run e un merge.
• -jc non ha aggiunto nulla sotto -headless — 0/2 sulla classe B in ogni run headless.
• Headless costa 5,1x in tempo reale (66.82s contro 13.08s di p50, con range non sovrapposti).
• -resume ricrawlizza le pagine già completate dentro una seed. Ripristina il set di endpoint, non il tempo già speso.
• I known files hanno richiesto robots.txt e sitemap.xml ma hanno recuperato 0/2 endpoint <loc> della sitemap contro un target con IP.
• Headless richiede silenziosamente Chromium già presente sulla macchina; la storia del “solo un binario” finisce al browser.
• Solo discovery. Nessuna estrazione strutturata, nessuna conversione del contenuto, nessuno schema dei campi.

Non testato, e quindi fuori da ciò che coprono questi numeri: -jsluice, un test dedicato di cutoff della profondità a -d 1/-d 2, resume multi-seed, compilazione automatica di form e qualsiasi sito reale pesante in JavaScript o protetto. Tutti i numeri provengono da una sola macchina (macOS arm64) su un fixture locale.

Per chi è, e chi dovrebbe saltarlo

Se il vostro lavoro è produrre un inventario di endpoint per infrastrutture su cui avete autorizzazione a operare, katana ha la forma giusta per una pipeline: collegamenti STDIN/STDOUT, un binario distribuibile e modalità sia senza browser sia con browser. Il merge a due passaggi era necessario per le classi inserite in questo fixture; se i vostri target richiedono davvero entrambi i passaggi è qualcosa da stabilire su pagine rappresentative.

Saltatelo se volete dati e non indirizzi. Katana non vi darà mai una tabella di prodotti; vi dà gli URL dove i prodotti potrebbero trovarsi, e qualcos’altro fa l’estrazione. Saltatelo anche se vi serve un solo comando completo — il merge a due passaggi va benissimo in una pipeline, ma è scomodo da terminale. E se la vostra enumerazione si basa sugli endpoint <loc> delle sitemap mentre state targettando IP, verificate cosa state davvero ottenendo prima di fidarvi dell’output, perché nel mio fixture quel percorso non ha restituito nulla.

Alternative e confine con l’estrazione

Katana è gratuito, con licenza MIT e self-hosted. Tiene discovery, selezione della modalità, deployment del browser e merge dei risultati dalla vostra parte del confine.

Nel mondo open source, i confronti utili sono per lavoro più che per linguaggio. Colly è l’altra opzione Go, ma è una libreria che compilate con callback vostre e non esegue affatto JavaScript. Crawl4AI usa un browser vero e produce Markdown per pipeline LLM, quindi un output completamente diverso. Se state valutando più strumenti insieme, il nostro open-source scraper roundup mette le categorie una accanto all’altra.

Disclosure: Thunderbit è il prodotto dell’editore e non è stato testato in questo fixture di Katana. Si colloca a valle, nella categoria dell’estrazione gestita, trasformando pagine in testo o record strutturati invece di enumerare la superficie degli endpoint di un target autorizzato. Un workflow può usare entrambe le categorie, ma questa recensione fornisce evidenze solo sul comportamento di discovery di Katana.

Prova Thunderbit per l’estrazione di dati web

Verdetto

Usate katana quando il deliverable è una lista di endpoint per target che siete autorizzati a esplorare e potete verificare la copertura delle modalità su quei target. In questo fixture, il -jc standard ha recuperato i literal JavaScript inseriti, mentre headless ha recuperato l’endpoint nel DOM runtime; le modalità browserless testate di Katana non hanno recuperato quel percorso runtime. Lo scope predefinito ha anche lasciato il secondo host non richiesto, e le run senza browser hanno continuato oltre il 500 e il dead link.

I caveat sono operativi: per classi di endpoint misti può servire un merge a due passaggi, headless ha impiegato circa cinque volte il tempo locale, il resume su una sola seed ha richiesto di nuovo i path già completati e il recall dei known files è stato 0/2 contro il target IP. Sono risultati del fixture su v1.6.1, non garanzie per ogni sito. Bastano però per definire i controlli che una valutazione in produzione dovrebbe ripetere.

Prova Thunderbit per l’estrazione di dati web Get Started Free

FAQ

Dove salva katana il file di resume e il resume salta le pagine già crawlate? Il checkpoint è finito in ~/.config/katana/resume-<xid>.cfg, non in un resume.cfg nella directory di lavoro come suggerisce l’help del flag. E no, non salta le pagine già completate: il file memorizza solo le seed URL in flight, quindi un crawl ripreso su una sola seed ha richiesto di nuovo tutti gli 11 path del baseline, compresi i 10 già finiti. Ottenete lo stesso insieme finale di endpoint, ma non il tempo risparmiato.

Perché -kf all ha richiesto il mio sitemap.xml ma non ha crawllato gli URL al suo interno? Contro un target con IP, quello è un confine di validazione dello scope più che un errore di flag. Il parser sitemap di Katana costruisce ogni richiesta <loc> senza portarsi dietro il RootHostname, e poi il controllo DNS-scope per host con IP letterale confronta l’host dell’URL con quella root vuota, fallisce il confronto e scarta l’URL. È rimasto a 0 recall in tutte le varianti di flag, profondità e seed che ho provato. Una regex host personalizzata con -fs prende un ramo diverso di validazione ed è la correzione che il sorgente suggerisce — ma non sono riuscito a confermarla con -kf sulla mia macchina, quindi trattatela come non testata. Estrarre voi stessi gli URL <loc> e passarli a katana come seed è l’approccio che oggi mi fiderei a usare.

Cosa dovrei conservare quando riporto un test di copertura di Katana? Annotate la versione esatta di Katana e il comando, compresa l’espressione -fs byte per byte; definite le classi di endpoint prima della run; conservate i log lato server oltre allo stdout; e separate il comportamento misurato dalle ipotesi basate sul sorgente. Per le run headless, registrate anche la build del browser — questo test non l’ha fatto, e limita la riproducibilità.

Devo usare -jc, -headless o entrambi? Scegliete in base alle classi di endpoint che vi servono. In questo fixture, il -jc standard ha trovato i literal memorizzati in un file JavaScript, mentre headless ha trovato l’endpoint inserito nel DOM runtime. Nessuna delle due modalità copriva entrambe le classi da sola, quindi un run a due passaggi seguito da deduplicazione era la scelta difendibile per target misti.

Un singolo URL andato in errore ferma il crawl? Non è successo in questa esecuzione controllata. Katana ha continuato dopo una response 500 e un dead link, restituendo comunque gli altri path raggiungibili. Questo però non sostituisce il conteggio degli errori in produzione: tenete i log delle richieste fallite e definite una soglia di errore accettabile, così un crawl solo parzialmente riuscito non venga scambiato per copertura completa.