Katanaレビュー: `-jc` と `-headless` で見つかるエンドポイントは別物。1つのコマンドでは両方を拾えなかった

Katana は ProjectDiscovery のエンドポイント発見用クローラーです。Go で書かれた MIT ライセンスのバイナリで、対象を指定すると URL やエンドポイントを返し、次のツールへつなぐパイプラインの起点になります。ブラウザなしの HTTP モードでも、Chromium を動かす -headless でもクロールできます。公式ガイドでは headless モードがより広い範囲を拾えるとされていますが、この検証環境では「数」だけでなく「どんな種類のエンドポイントか」が同じくらい重要だと分かりました。

私は、あえて性質の異なる 3 種類のエンドポイントを含む小さなサイトを用意し、v1.6.1 の -d 4 で各モードが何を見つけるかを測定しました。通常の HTML は 4/4 のリンクと、4 通りすべての構成で 3 ホップのチェーンを完走しました。差が出たのは、JavaScript ソース内にあるエンドポイントと、実行時に DOM が書き換わることで現れるエンドポイントです。

この検証では、headless は browserless の各モードが見逃した runtime-DOM 系を拾い、標準モードに -jc を付けた場合は、headless の 2 回の実行では拾えなかった JavaScript ファイル内のリテラルを見つけました。4 コマンドの表のどの行にも、両方のクラスを同時にカバーするものはありませんでした。scope、resume、known-files の挙動も、実運用上の境界として確認できました。

Katana は実際には何なのか

Katana のクローラー — GitHub の projectdiscovery/katana — は Go 製で MIT ライセンスです。私は 2026 年 7 月 27 日に v1.6.1 を検証しました。ここでバージョンが重要なのは、後述する coverage と known-files の結果がビルド依存の観察だからです。

ここではカテゴリ名の意味がいつも以上に重要です。エンドポイント発見用クローラー は、フィールド抽出器ではありません。Go の web crawler に「製品名と価格を構造化 JSON で返してほしい」と期待するなら、katana は完全に別の場所です。katana が得意なのは /products/1138 のようなパスの存在を教えることであって、そのページの中身については一切教えてくれません。それは設計通りですし、抽出性能で評価するのは、金属探知機に宝石鑑定を求めるようなものです。

主戦場は offensive security の調査と自動化パイプラインです。STDIN を入れ、URL を出し、次のツールへ流す。ここで当然の注意点を先に置いておくと、この検証はすべて私が用意した 127.0.0.1 上のローカル fixture に対して行いました。katana を使うのは、自分が所有している、または明確に許可を得てテストできるホストだけにしてください。これは防御の回避を目的にした話ではなく、あるコマンドがサイトのエンドポイント面をどれだけ列挙できるか、という話です。

3 つのモードと、それぞれが見える範囲

標準モードは Go の HTTP クライアントです。HTML を取得して解析し、href をたどり、ブラウザは起動しません。高速で安価ですが、JavaScript 実行後にしか現れないものは見えません。

-jc（-js-crawl）は、その browserless の流れに JavaScript パーサを追加します。リンクされた .js ファイルを取得し、ソース内から URL らしい文字列リテラルを抜き出します。実行はせず、読むだけです。-jsl（jsluice）もあり、README ではより重くメモリを使うパーサとされています。今回は試していないので、coverage が変わるかどうかは分かりません。

-headless は Chromium を動かし、ページスクリプトを実行します。この fixture では、断片から組み立てられ runtime DOM に挿入されるパスを回収できたのは、このモードだけでした。ただし、この結果から、すべてのパーサや将来の Katana モードでも同じものが取れる、ということまでは言えません。

その次に重要なのが scope の仕組みです。実運用で何か打ち込む前に、ここは頭に入れておきたい部分です。

順番は飾りではありません。どのホスト正規表現がクロールを広げるのか、それとも静かに空振りになるのかを決めるのはここです。

セットアップ: 1 バイナリ、ただし 1 つだけ注意点あり

導入方法は 3 通りありますが、ツールチェーンが必要なのは 1 つだけです。

私の環境では ~/go/bin/katana に入り、毎回 Current version: v1.6.1 と表示されました。ここまでは、いかにも Go らしい気持ちよさです。1 ファイルで、実行時依存が少ない。

ただし headless だけは別で、ブラウザがバイナリとは独立した前提条件になります。

素のサーバーでは、この手軽さは消えます。-headless をコマンドに入れた瞬間、バイナリだけでなくブラウザのコストも見込んでください。

CI で使うなら、もう 1 つ知っておくとよい点があります。katana は起動時に GitHub へバージョン確認をしに行きます。-duc でこれを止められます。ノート PC なら雑音ですが、ネットワーク隔離環境やレート制限のある runner では、毎回余計な往復が入ります。今回の計測では -duc を付け、クロール時間だけを測るようにしました。

どう検証したか

エンドポイントは 3 クラスに分けました。モード差が出るように意図して選んでいます。すべて ローカルの fixture サーバー 上にあり、ground truth はクロール前に書き出してあります。そのため recall は、katana がたまたま出力したものではなく、固定された一覧に対して測定しています。

• Class A — 素の HTML。 /page/a、/page/b、/page/c、それに /depth/1 → /depth/2 → /depth/3 の 3 ホップチェーン。どのクローラーでも拾うべきものです。
• Class B — JavaScript ファイル内のリテラル。 /api/js-endpoint-7 と /api/js-endpoint-8 は、リンクされた /static/app.js の文字列リテラルとしてだけ存在します。JavaScript を読む気があれば、ブラウザなしでも見つけられます。
• Class C — runtime-DOM のみ。 断片から実行時に組み立てられ ('endpoint' + (6 * 7))、スクリプトによって DOM に挿入される 1 パスです。文字列 /runtime-only/endpoint42 は、サーバーが送るどのバイト列にも連続では現れません。HTML にも JS ソースにもありません。実行して初めて見えます。

これに加えて、robots.txt、sitemap.xml にしか載っていない 2 つの <loc> エンドポイント、500 を返すルート、dead link、そして別ホストの 2 台目サーバーを指す out-of-scope リンクも置きました。

計測装置も fixture と同じくらい重要です。サーバーは 実際に取得されたもの を数えるので、scope や resume の主張は katana 自身の stdout ではなく、実際のヒットに基づきます。生の実行結果は、計算を確認したい人向けに benchmark リポジトリ に入れています。

誰も数値化していない coverage の分岐

-d 4 における、モード別・エンドポイントクラス別のマトリクスです。

最後の 2 列をセットで見ると、問題がはっきりします。Class B を拾えたのは、standard に -jc を付けた 1 通りだけ。Class C を拾えたのは、headless の 2 通りだけです。両方の列にヒットがある行はありません。全体のマトリクスは discovery-summary.json にあり、計算フィールド headless_jc_covers_both は false になっています。

実務上の意味は、「とりあえず headless で coverage を上げる」という考え方ではこの検証では不十分だった、ということです。headless は standard の結果に Class B を追加してはくれませんでした。その代わり Class C を回収しましたが、Class B は取りこぼしました。この fixture で植え込んだ全クラスをカバーするには、2 回クロールしてマージする必要がありました。

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

-headless -jc の組み合わせについては、上流にぜひ答えが欲しいところです。headless 実行に JavaScript パーサを足しても何も増えず、Class B は 0/2 のままでした。新しく再現し直しても同じです。ここでは挙動を報告しているのであって、なぜブラウザ側の経路が JS ファイルのリテラルを拾わなくなるのか、そのメカニズムを解析したとは言っていません。katana の内部を計測していないので、理由までは追っていません。再現可能な観察結果として、GitHub issue にするのがよいものだと考えてください。（あわせて書くと、v1.6.1 の macOS ARM では -hl -jc の組み合わせは return code 0 で正常終了しました。歴史的には常にそうだったわけではありません。）

公式ドキュメント では、headless はより良い coverage を与えると説明されていますし、この fixture では runtime-rendered のクラスを拾ってくれました。ただし、確認したガイドには source literal と runtime-DOM の分岐までは書かれていませんでした。したがって、このマトリクスは、自分の対象クラスに対して両方の経路を試すべき理由にはなりますが、普遍的な分類表だと思わないでください。

headless の wall time コスト

アイドル状態のマシンで、各モードを 3 回ずつ連続実行しました。

これは 5.1 倍 の差で、範囲もほぼ重なっていません。standard の最も遅い実行（13.17s）でも、headless の最速（66.78s）より 53 秒以上速い結果でした (cost-summary.json)。これは測定誤差ではありません。

ただし、この 13 秒について 1 点だけ注意があります。fixture にはあえて 500 ルートと dead link を含めてあり、standard モードは両方でデフォルトの -timeout 10 の再試行尾部を待ちます。速いモードに有利になるよう timeout を調整してはいません。つまり、調整済みの standard 実行なら差は縮むどころか、むしろ広がる可能性があります。

この倍率はローカル容量の目安であって、production の所要時間予測ではありません。実際の対象はレイテンシ、失敗率、スクリプトの重さ、スケジューリングが違いますし、この fixture にはデフォルト timeout の尻尾が含まれています。5.1 倍という実測差を使って、headless を別予算・別対象にするべきか判断し、その計画を代表的な許可済みホストでベンチマークしてください。

scope は守られたが、1 つのフラグは静かに何もしなかった

scope テストでは 2 台のサーバーを使いました。主対象は 127.0.0.1、もう 1 台は別ポートの localhost で、そこにしか存在しない パスを配信しています。したがって、そのパスのヒットは、scope 外ホストが単に出力に印字されたのではなく、実際に取得された証拠です。

scope の抑制は良いニュースです。デフォルトでは katana は勝手に外へ出ず、広げるには明示的な操作が必要でした。他人のインフラに向けるツールとして、それは正しいデフォルトです。

興味深いのは -cs localhost の行です。これは第 2 ホストへクロールを広げませんでしたし、URL を 1 つも出力しませんでした。-cs は field scope の内側だけを絞るため、field scope がまだ主ホストのままだと、正規表現は何にも一致せず、エラーではなく空集合が返ります。もし、含めたいホスト名を書いた crawl-scope の正規表現を渡して、空の出力ファイルを見つめたことがあるなら、それがこの仕組みです (scope-summary.json)。ホストを追加したいなら -fs を使います。既に持っているホストの中で絞るなら -cs / -cos です。

resume はフラグが示すより粗い

README ではこのフラグを -resume string resume scan using resume.cfg と説明しており、作業ディレクトリに resume.cfg が落ちるような印象です。しかし実際は違いました。私の環境では checkpoint は ~/.config/katana/resume-<xid>.cfg に書かれていました。これはドキュメントにパスが明記されていないため、ページを読むのではなく実測したものです。

もっと重要な驚きは中身です。ファイルには InFlightUrls の map が 1 つだけ入っており、その中身は seed URL 1 件だけでした。訪問済み集合でも frontier でもありません。そこで、3 秒後に SIGINT でクロールを止めてから resume したところ、こうなりました。

resume 後に同じ最終エンドポイント集合へ到達したので、壊れてはいません。ですが checkpoint の粒度は URL ごとではなく 入力 seed ごと です。メモリ上の重複排除フィルタは永続化されないため、1 seed のクロールを再開すると、その seed を最初から再クロールします (resume-summary.json)。もし 500 ホストのリストを katana に渡すなら、resume は最後まで終わったホストを節約してくれるはずです。その複数 seed の挙動は state の保存方法からそうなるのですが、私が測定したのは 1 seed の場合だけです。大きな 1 サイトを深く掘る用途では、resume がくれるのは時間短縮ではなく正しさです。

known files: 要求はしたが、その後落ちた

-kf all -d 3 は両方のファイルを確かに要求しました。robots.txt と sitemap.xml はサーバーのヒットログに出ています。ところが、その sitemap の <loc> 要素に書かれたエンドポイントは 2 件中 0 件 しか回収できませんでした。recall は 0.0 です。

これを制限だと断定する前に、自分のせいにできないか試しました。どの変化を加えても同じでした。

ドキュメント上の要件、つまり -kf を使い、少なくとも 3 階層深く掘ることは、毎回満たしていました。これはフラグの付け忘れではありません。

先に押さえるべき実務上の判断はこうです。この IP-literal の fixture では、known files を要求したからといって、その <loc> URL がクロールに入ったとは限りません。recall を確認するか、<loc> を抜いて自分で seed にしてください。

v1.6.1 のコードパスはこの観察と整合しますが、実行中に内部計測はしていません。v1.6.1 の sitemapxml.go では、NewNavigationRequestURLFromResponse が RootHostname を持たない response から <loc> の navigation request を作ります。その後 request は ValidateScope に渡され、v1.6.1 の scope.go では、IP-literal 分岐が URL の host と空の root を比較し、拒否することがあります。別の scope テストで使ったカスタムの -fs '(127.0.0.1|localhost)' は異なる scope 分岐に入りました。つまり、これはソースから予測される救済策であって、-kf に対して実測できた回避策ではありません。試行は、このホスト上の known-files クライアントで断続的な dialing の問題に阻まれました。そのため、報告結果は引き続き 0/2 のままです。

実運用で私なら、フラグについて誰かが確認するまでは、sitemap を自分で取得して <loc> URL を抜き出し、seed リストとして katana に渡します。シェル 2 行で済み、scope validation を挟みません。

1 つだけ、仕様どおりに動いていて言及に値するものがあります。500 ルートと dead link は取得され、ログに残り、そのまま飛び越えられました。browserless の全実行は return code 0 で終了しています。最初の bad response で死ぬクローラーは無人運用では使い物になりませんが、katana はそうではありません。

導入前に、対象ごとの coverage を確認する

この fixture のマトリクスは、自分の許可済み対象を試すテンプレートとして使うのが一番有用です。Katana を走らせる前に、エンドポイントのクラスを定義してください。素のリンク、リンク先 JS に埋め込まれたリテラル、実行後にだけ生成されるルート、known-file のエントリは、最初の 4 つの妥当な分類です。それぞれに小さな ground truth を用意しておきます。事前の一覧がなければ、stdout が増えたように見えても、実際にはあるクラスが消えていて coverage が悪化していることがあります。

まずは browserless と headless を別々の測定として実行してください。正確なコマンド、Katana のバージョン、ブラウザのビルド、return code、出力を保存します。行数比較ではなく、エンドポイント集合を正規化して diff してください。もし標準の -jc がサンプルで独自の追加を何も生まないなら headless 専用方針で十分かもしれません。逆に、ここで見たように集合が分かれるなら、2 回の実行を分けたままにして、収集後にマージします。1 コマンドに両方のフラグを足したからといって、対象固有の diff で確認するまでは和集合と同じだとは思わないでください。

scope は Katana の出力だけでなく、外部の証拠でも確認してください。除外したいホストに canary URL を置き、そのサーバーの request log を見ます。クロールを広げる想定なら、意図した第 2 ホストでも同じことを確認します。ここでの -cs localhost は、content-scope の絞り込みが field scope を広げなかったため空出力になりましたが、カスタムの -fs '(127.0.0.1|localhost)' は第 2 サーバーに接続しました。正確な正規表現を記録することが重要です。1 文字違うだけで、見た目だけでなく regex の意味自体が変わるからです。

resume と known-files は discovery recall とは別に試してください。resume では、代表的な seed を数ページ進んだところで中断し、生成された checkpoint のパスを保存し、完了済み URL が何件再取得されたか数えます。-kf では、robots/sitemap が要求されたことに加え、植え込んだ <loc> URL が本当にスケジュールされたかを確認します。これは別の主張です。この fixture ではファイルは取得されたのに sitemap の 2 つのエンドポイントは欠落していたので、境界を見るには request log と endpoint 出力の両方が必要でした。

最後に、アイドル状態のマシンで連続実行したローカルの cost ベースラインを作り、それを代表的な対象で繰り返してください。倍率だけでなく、最小値、最大値、中央値も残します。ここでの 5.1 倍は、この fixture の失敗と timeout の挙動を含んでいます。つまり、headless に別予算が必要だと分かるだけで、production の在庫調査が何分かかるかまでは分かりません。

長所と短所

長所:

• 通常の HTML ではどのモードでも完全な recall。4/4 のリンクと 3/3 の深度チェーンを、追加設定なしで拾える。
• -jc は browserless でもちゃんと機能する。リンク先 JS ファイル内の文字列リテラルから 2/2 のエンドポイントを回収でき、ブラウザコストも不要。
• -headless は、実行時に組み立てられるエンドポイントを拾えた唯一の方法。これは設計上、ソース解析では見えないクラス。
• scope のデフォルトは保守的。out-of-scope のホストは、デフォルトでも -fs fqdn でも -cs でも取得されなかった。
• 単一の Go バイナリ、MIT ライセンス、事前ビルド済み配布物と Docker イメージ、パイプライン向きの入出力。
• 失敗に強い。500 や dead link でクロールが止まらない。

短所:

• 1 回の実行で JS ファイル系と runtime-DOM 系の両方をカバーすることはできない。完全な coverage には 2 回の実行とマージが必要。
• -jc は -headless の下では何も追加しなかった。headless 実行では Class B が毎回 0/2。
• headless は wall time が 5.1 倍かかる（p50 で 66.82s 対 13.08s、範囲も重ならない）。
• -resume は seed 内の完了済みページを再クロールする。endpoint セットは戻せても、経過時間は戻らない。
• known files は robots.txt と sitemap.xml を要求したが、IP 対象では sitemap の <loc> エンドポイント 2/2 を回収できなかった。
• headless には Chromium が別途必要。"1 バイナリ" という話はブラウザで終わる。
• あくまで discovery ツール。構造化抽出も、コンテンツ変換も、フィールド schema もない。

未検証であり、したがって今回の数値がカバーしていないもの: -jsluice、-d 1 / -d 2 の専用深度打ち切りテスト、multi-seed の resume、自動フォーム入力、そして実際の JavaScript が重い・保護された production サイト。今回の数値は 1 台のマシン（macOS arm64）とローカル fixture の組み合わせだけです。

どんな人向けか、誰が避けるべきか

自分が触ってよいインフラのエンドポイント一覧を作る仕事なら、katana にはちょうどよいパイプラインの形があります。STDIN/STDOUT のつなぎやすさ、配布しやすいバイナリ、browserless と browser-backed の両モードがそろっているからです。この fixture の植え込みクラスには 2 回の実行とマージが必要でした。あなたの対象でも両方必要かどうかは、代表ページで確かめるべきことです。

データそのものが欲しいなら、katana は向いていません。製品の表を返すことはなく、製品がありそうな URL を返すだけで、抽出は別のツールの仕事です。1 回で完全に終わるコマンドが必要な場合も避けたほうがいいでしょう。2 回実行してマージするのはパイプラインなら問題ありませんが、対話的なプロンプトでは面倒です。さらに、IP を対象に sitemap の <loc> エンドポイント頼みで列挙するなら、出力を信じる前に実際に何が取れているのか確認してください。この fixture では、その経路は何も返しませんでした。

代替ツールと、抽出との境界

Katana は無料で、MIT ライセンスで、セルフホストできます。探索、モード選択、ブラウザの配置、結果のマージまで、自分の側で完結します。

オープンソースの中では、比較は言語よりも役割で見るのが実用的です。Colly はもう 1 つの Go 系の選択肢ですが、自分でコールバックを書いて組み込むライブラリであり、JavaScript は一切レンダリングしません。Crawl4AI は本物のブラウザを動かし、LLM パイプライン向けに Markdown を出力します。これは別の出力です。これらをまとめて比較したいなら、open-source scraper roundup にカテゴリを並べて整理しています。

開示事項: Thunderbit は掲載元の製品であり、この Katana の fixture ではテストしていません。Thunderbit は管理された抽出カテゴリの下流にあり、ページをテキストや構造化レコードに変換します。許可された対象のエンドポイント面を列挙するのではありません。ワークフローとして両方を組み合わせることはありますが、このレビューが証明しているのは Katana の discovery 挙動だけです。

Thunderbit で Web データ抽出を試す

結論

katana を使うべきなのは、成果物が「クロールしてよい対象のエンドポイント一覧」であり、かつその対象でモードごとの coverage を検証できる場合です。この fixture では、standard の -jc が仕込んだ JavaScript ファイル内リテラルを回収し、headless は runtime-DOM のエンドポイントを回収しました。Katana の今回試した browserless モードは、その runtime パスを拾えませんでした。デフォルト scope は第 2 ホストを取得せず、browserless 実行は 500 と dead link を越えて進みました。

運用上の注意もあります。混在するエンドポイントクラスでは 2 回実行してマージが必要になること、headless はローカル wall time の約 5 倍かかったこと、単一 seed の resume は完了済みパスを再取得したこと、known-files の recall は IP 対象で 0/2 だったことです。これらは v1.6.1 の fixture 結果であって、すべてのサイトへの保証ではありません。ただし、本番評価で繰り返すべきチェック項目を定義するには十分です。

Thunderbit で Web データ抽出を試す Get Started Free

よくある質問

katana は resume ファイルをどこに保存しますか？ また、resume するとすでにクロール済みのページはスキップされますか？ checkpoint は、フラグのヘルプが示すような作業ディレクトリの resume.cfg ではなく、~/.config/katana/resume-<xid>.cfg に保存されました。そして、完了済みページはスキップされません。ファイルに入っているのは in-flight の seed URL だけなので、単一 seed の resume では、完了済みの 10 件を含むベースライン 11 パスがすべて再取得されました。最終的な endpoint セットは同じですが、時間は節約されません。

なぜ -kf all は sitemap.xml を要求したのに、その中の URL をクロールしなかったのですか？ IP 対象に対しては、これはフラグのミスというより scope validation の境界に一致します。v1.6.1 のコードでは、Katana の sitemap パーサは <loc> ごとの request を作る際に root hostname を引き継がず、IP-literal ホスト向けの DNS-scope チェックがその URL を拒否することがあります。私はそのメカニズムを実行中に計測して確認してはいません。どのフラグ、深度、seed の組み合わせでも recall は 0 のままでした。カスタムの -fs ホスト正規表現は別の validation 分岐に入るので、ソースから予測される修正策ではありますが、私の環境では -kf と組み合わせて確認できませんでした。現時点で信頼するなら、<loc> URL を自分で抜き出して katana の seed にする方法です。

Katana の coverage テストを報告する際、何を残すべきですか？ Katana の正確なバージョンとコマンドを記録してください。-fs の式は 1 文字単位でそのまま残します。実行前にエンドポイントクラスを定義し、stdout に加えてサーバー側の hit log も保存し、観察事実とソースベースの仮説を分けてください。headless 実行ではブラウザのビルド番号も記録してください。この検証ではそれを残していないため、再現性に制限があります。

-jc、-headless、それとも両方を使うべきですか？ 必要なエンドポイントクラスで決めてください。この fixture では、standard の -jc は JavaScript ファイルに入ったリテラルを見つけ、headless は runtime DOM に挿入されたエンドポイントを見つけました。どちらのモードも単独では両方をカバーできなかったため、2 回実行して重複排除するやり方が、混在対象には妥当な選択でした。

1 つでも失敗した URL があるとクロールは止まりますか？ この管理下の実行では止まりませんでした。Katana は 500 応答と dead link の両方の後でも進み、到達可能な他のパスを返しました。ただし、それは本番のエラー管理の代わりにはなりません。失敗したリクエストのログを残し、許容失敗率を定義して、部分成功のクロールを完全な coverage と誤認しないようにしてください。