nokk

---

インストール

pip install nokk                    # Python: the prebuilt binary is in the wheel
npm install @koloss777/nokk         # Node: run it with `npx nokk`
docker run --rm -p 9222:9222 ghcr.io/koloss777/nokk:latest

ブラウザーをダウンロードする必要はありません。Linux（x86_64、ARM64）、Apple Silicon 搭載の macOS、Windows x64 向けのビルド済みバイナリを用意しています。それ以外の場合はソースからビルドしてください。

クイックスタート

# Load a page behind Cloudflare, clear the challenge, print what is behind it
nokk --load https://www.scrapingcourse.com/cloudflare-challenge --solve-challenge 30 \
     --eval "document.querySelector('h2').textContent.trim()"

# Or run the CDP server and drive it from any client
nokk --port 9222 --auto-solve   # ws://127.0.0.1:9222/devtools/browser/nokk

import nokk
from playwright.sync_api import sync_playwright

with nokk.launch(auto_solve=True) as server, sync_playwright() as pw:
    page = pw.chromium.connect_over_cdp(server.ws_endpoint).new_page()
    page.goto("https://www.scrapingcourse.com/cloudflare-challenge")
    print(page.title())

AI エージェントの場合は、uvx nokk-mcp を実行するとMCP サーバーとして起動します。 Puppeteer、Node、セッション、Cloudflare のオプションについては以下をご覧ください。

nokk を選ぶ理由

Puppeteer と Playwright は本物の Chromium を操作しますが、ボット対策システムは navigator.webdriver、CDP の痕跡、ヘッドレス時の TLS ハンドシェイクを通じてそれを検出します。nokk は TLS ハンドシェイクから JavaScript 環境まで Chrome に見えるように作られており、 レンダリングエンジンを一切搭載していません。

	nokk 0.1.35	Chrome 151（Puppeteer／Playwright）
起動から CDP 応答まで	約 0.05 秒	約 0.2 秒
アイドル時のメモリ（PSS）	約 60 MB、1 プロセス	約 330 MB、12～14 プロセス
Cloudflare の突破、実時間の中央値	12.4 秒	12.4 秒
最長の突破時間	15.6 秒	27.8 秒
1 回の突破にかかる CPU 時間	6.4 秒	9.5 秒
1 回の突破時の最大メモリ	約 570 MB	約 720 MB
突破成功数	24/24	24/24
TLS フィンガープリント（JA3／JA4）	Chrome 151 と一致	Chrome
スクリーンショット、PDF、レイアウト	なし	あり
CDP の対応範囲	一般的な操作	全機能

_{nokk 0.1.35 を使用し、2026 年 10 月に 8 コアの Linux マシンで測定。Cloudflare の行は、本番サイト 8 件で 1 つのプロキシを通して各 3 回実行した結果です。nokk は --until-clearance を指定し、Chrome はチェックボックスをクリックするハーネスで操作しました。Cookie を取得してサイトを開けた場合のみ、突破成功として数えています。}

次の用途には向いていません。 スクリーンショット、PDF、レイアウトや描画、または Playwright／CDP の全機能が必要な場合です。nokk は設計上レンダリングエンジンを搭載しておらず、CDP の対応範囲は、Puppeteer と Playwright がナビゲーションとスクリプト実行に使う操作に限られます。

公開ページでの測定結果

8 コアの Linux マシンで、プロキシなしで --solve-challenge 30 を指定し、CLI から各ページを 3 回実行しました（2026 年 10 月）。所要時間は、プロセスの起動から結果の表示まで、コマンド全体を計測したものです。tools/cf-check.sh でご自身でも実行できます。

ページ	チャレンジ	解決数	中央値	最長
chess.com/login	稼働中のサイトにある非表示の Turnstile ウィジェット	3/3	7 秒	9 秒
scrapingcourse.com/cloudflare-challenge	管理型インタースティシャル	3/3	5 秒	7 秒
peet.ws/turnstile-test/managed.html	管理型ウィジェット	3/3	7 秒	8 秒
peet.ws/turnstile-test/non-interactive.html	非対話型ウィジェット	3/3	3 秒	4 秒
nopecha.com/demo/cloudflare	チェックボックス付きの対話型インタースティシャル	3/3	10 秒	11 秒

Cloudflare の背後にある本番サイトでの結果は、上記の比較のとおりです。 8 サイト中、24 件すべてを解決しました。サイト名はここでは公開していません。

使用方法

コマンドライン

nokk --fetch https://tls.browserleaks.com/json                   # Chrome TLS + HTTP/2 fingerprint
nokk --load https://example.com --eval 'document.title'          # run the page, query the DOM
nokk --load https://quotes.toscrape.com --dump-requests          # every request the page makes
nokk --load https://target --proxy socks5://host:1080            # through a proxy
nokk --port 9222 --rotate-fingerprint --geoip-timezone           # CDP server, a machine per context

広告、分析、トラッカーのリクエストはデフォルトで破棄されます。--allow-trackers を指定すると読み込みます。 アンチボットベンダーは、トークンを発行するために実行する必要があるため、ブロックされることはありません。

Puppeteer

import puppeteer from 'puppeteer';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/nokk',   // nokk --port 9222
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());

Node と Python

どちらのパッケージにもビルド済みバイナリが含まれており、CDP サーバーが自動的に起動します。

const server = await require("@koloss777/nokk").launch({ autoSolve: true });
// server.wsEndpoint -> puppeteer.connect / chromium.connectOverCDP

with nokk.launch(auto_solve=True) as server:   # or: await nokk.launch_async()
    ...  # server.ws_endpoint -> connect_over_cdp

crawl4ai、Scrapy、Playwright MCP、その他の CDP ツール

CDP 経由で Chrome を操作できるものなら、nokk も操作できます。独自の Chromium では Cloudflare にブロックされる crawl4ai も、nokk を通せばその先のページにアクセスできます： BrowserConfig(browser_mode="custom", cdp_url=server.ws_endpoint)。Scrapy （scrapy-playwright の PLAYWRIGHT_CDP_URL）と Playwright MCP（--cdp-endpoint）も同様に動作します。docs/integrations.md をご覧ください。

AI エージェント向け（MCP）

nokk は Model Context Protocol サーバーとして動作するため、Claude Desktop や Claude Code などのエージェントは、フィンガープリントを偽装したエンジンを通じてブラウジングできます。uv を使えば、事前のインストールは不要です：

{ "mcpServers": { "nokk": { "command": "uvx", "args": ["nokk-mcp", "--rotate-fingerprint"] } } }

uv を使わない場合：pip install "nokk[mcp]" を実行し、次のように指定します："command": "python", "args": ["-m", "nokk.mcp"]。 ツール：open、read_text、read_html、click、fill、evaluate、links、solve_challenge、 challenge_state、reset。

Cloudflare チャレンジ

nokk は、非表示のウィジェット、管理型インタースティシャル、対話型の Verify you are human チェックボックスを自動で通過します。サイトごとの設定は不要です。ウィジェットでクリックが必要な場合、エンジンが人間と同じようにクリックします。

• --solve-challenge N は制限時間を設定し、ゲートが残っている場合に --fail-on-challenge を指定すると 3 で終了します。
• --until-clearance は新しい cf_clearance が取得された時点で停止し、ゲートの先にある重いページの読み込みを省略します。
• --auto-solve は CDP 経由のすべての page.goto() で同じ処理を行います。Nokk.solveChallenge を使えば、必要に応じて実行できます。
• 実際のブラウザーから取得した cf_clearance もインポートできます。nokk の JA4 は Chrome 151 と一致するためです。

詳細、CDP メソッド、イベントについては、docs/cloudflare.md をご覧ください。

永続セッション

--session-store ./sessions を指定すると、cf_clearance を含む各名前付きセッションの Cookie jar がディスクに保存され、新しいプロセスで再読み込みされます。セッションを一度ウォームアップして再利用すれば、実行のたびにチャレンジを解決する必要はありません。docs/sessions.md をご覧ください。

フィンガープリントのローテーション

--rotate-fingerprint を指定すると、各ブラウザーコンテキストに一貫性のあるマシン情報が割り当てられます。TLS エミュレーション、User-Agent、クライアントヒント、プラットフォーム、画面、WebGL の設定がすべて一致します。--geoip-timezone を指定すると、タイムゾーンと言語がプロキシの出口 IP に合わせられます。docs/fingerprints.md をご覧ください。

ビルド

ビルド	追加される機能	入手先
light（デフォルト）	上記のすべて。canvas と WebGL のピクセルは合成されます	pip、npm、ghcr.io/koloss777/nokk:latest、nokk-*.tar.gz
render	実際の canvas 2D および WebGL のラスタライズ。ピーク時のサイズが約 100 MB 増加します	:render イメージ、nokk-render-*.tar.gz、--features render,webgl

Linux x86_64 と ARM64、Apple Silicon 搭載の macOS、Windows x64 向けにビルド済みのものを提供しています。render ビルドは Linux x86_64 向けです。Docker のバリアント、アーカイブ、ソースからのビルド方法については、docs/install.md をご覧ください。

動作の仕組み

小規模なクレートで構成された Cargo ワークスペースです。V8 アイソレートプール、BoringSSL を使用した Chrome フィンガープリント付き HTTP クライアント、html5ever DOM、ステルスレイヤー、CDP サーバーで構成されています。スレッドごとに 1 つのアイソレートを割り当て、その中で複数のコンテキストを実行します。すべての I/O はアイソレートのスレッド外で tokio により実行され、JS フィンガープリントと TLS フィンガープリントは常に一致します。詳しくは docs/architecture.md をご覧ください。

プロジェクトの状況

アルファ版です。 エンジンは実装済みで、エンドツーエンドで動作します。V8 が解析済みの DOM に対してページの JS を実行し、フィンガープリント付きの通信処理が Cloudflare の TLS/HTTP チェックを通過します。また、実際のサイトで不可視、マネージド、インタラクティブな Turnstile を解決し、Puppeteer と Playwright が CDP 経由で接続してページを開き、移動し、評価します。

まだ完了していないことと、注意が必要な点は次のとおりです。

• JS フィンガープリントの強化は継続中です。 強化策の多くは実装済みです。ネイティブ toString のマスキング、Object.getOwnPropertyNames からの内部要素の隠蔽、実際のプロトタイプインスタンスとしての navigator／screen、IP と整合するタイムゾーン、コンテキストごとの整合性を保ったフィンガープリントのローテーション、Web Workers、Chrome のピクセルとサンプルを使った canvas／WebGL／WebGPU／audio、Trusted Types、CSP に対応しています。nokk は現在 Cloudflare のチャレンジを解決できます。Chrome との項目ごとの比較を通じて、残る判別要素を特定していますが、CreepJS のような専用フィンガープリントテストスイートとまだ同等ではありません。ロードマップをご覧ください。
• CDP の対応範囲は一般的な操作に限られ、プロトコル全体を網羅しているわけではありません。 Puppeteer と Playwright は CDP 経由で接続します。ナビゲーション、evaluate、$／$eval／$$eval、title()、url()、新しいページ、CDP セッションはテスト済みですが、あまり使用されないドメインはまだ実装されていません。
• コンテキストごとの Cookie 分離とセッションごとの永続化には対応しています（各ブラウザーコンテキストが独自の Cookie jar を持ち、名前付きセッションは実行間で永続化されます）。ホストごと／プロキシごと／全体の接続数制限はまだ適用されていません（フェーズ 7）。
• レンダリングには対応していません。スクリーンショット、PDF、レイアウト／ペイントは意図的に対象外です。

段階的な計画と具体的な強化バックログについては、ROADMAP.md をご覧ください。

コントリビューション

Issue と PR を歓迎します。ロードマップの強化バックログは、取り組みを始めるのに適しています。変更を送る前に、次のことを行ってください。

cargo fmt
cargo clippy --all-targets
cargo test

ライセンス

お好みに応じて、MIT または Apache-2.0 のいずれかのライセンスの下で利用できます。

別途明示しない限り、Apache-2.0 ライセンスに定める本プロジェクトへの収録を目的として提出されたコントリビューションは、追加の条件や制約なしに、上記のとおりデュアルライセンスで提供されるものとします。

---