obscura

Obscura

Obscura を、軽量でステルス機能を備えた Rust 製ヘッドレスブラウザーとして自動化に活用できます。V8 を組み込み、DOM とレンダリングパイプラインを管理し、Chromium を起動せずに Chrome DevTools Protocol のワークフローを利用できます。レンダリングとステルス機能は、互いを補完する主要な機能として扱ってください。

ビルドのバリエーション

公式リリースアーカイブと Docker イメージには、レンダリング機能が含まれています。ソースをチェックアウトした場合は、render フィーチャーを指定してリリースモードでビルドします。

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render

wreq/BoringSSL トランスポート、ブラウザー識別情報の保護、トラッカーのブロックを利用するには、レンダリングとステルス機能を一緒にビルドします。

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render,stealth

DOM、抽出、CDP の自動化のみが必要な場合は、レンダリングなしでビルドします。

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features
CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features --features stealth

ソースから作業する場合は、以下のコマンドで ./target/release/obscura を使用してください。

ステルス機能を使う

ステルス機能を有効にしたビルドでは、レンダリング、スクリーンショット、スクリーンキャスト、PDF、CDP、MCP の機能をすべて利用できます。さらに、TLS、HTTP ヘッダー、ユーザーエージェント、navigator、WebGL の各サーフェスで一貫したブラウザーフィンガープリントを適用し、navigator.webdriver とパッチ適用済みのネイティブ関数を隠し、組み込みのトラッカードメインリストに含まれるドメインをブロックします。

グローバルな --stealth フラグを指定すると、実行時にステルス機能を有効にできます。サブコマンドの前後どちらに指定しても、fetch、serve、scrape、mcp に適用されます。

obscura --stealth fetch https://example.com --screenshot page.png
obscura serve --stealth --port 9222

実行時フラグを使うには、wreq/BoringSSL トランスポート向けの render,stealth ビルドが必要です。

フェッチ、評価、キャプチャ

obscura fetch https://example.com --dump text
obscura fetch https://example.com --eval "document.title"
obscura fetch https://example.com --screenshot page.png
obscura fetch https://example.com \
  --eval "window.scrollTo(0, document.documentElement.scrollHeight)" \
  --screenshot bottom.png

CLI のスクリーンショット機能は PNG を出力し、URL を 1 つ受け取ります。--wait を省略すると、最大 5 秒の適応的な安定待ちが使われます。--wait N を明示的に指定すると、N 秒間の固定待ちになります。--timeout も秒単位で指定し、ナビゲーションの時間を別途制限します。

バイナリまたは生の HTTP レスポンスを DOM と JavaScript による処理を迂回して取得する場合は、--dump original を使います。URL ごとにスクリーンショットを 1 枚ずつ出力する必要がない複数 URL の処理には、scrape を使います。

ローカルの http://127.0.0.1:N にアクセスするには、グローバルな --allow-private-network が必要です。このオプションを指定すると、ループバック、RFC1918、リンクローカルへのアクセスが許可されます。指定しない場合、フェッチは Access to private/internal IP address 127.0.0.1 is not allowed というエラーで失敗します。

CDP を操作する

サーバーを起動します。

obscura serve --port 9222

puppeteer-core を使う Puppeteer、または chromium.connectOverCDP を使う Playwright で接続します。標準の page.screenshot() はビューポートとページ全体のキャプチャに対応し、page.pdf() はラスター画像ベースの印刷出力を生成します。ページの下部をキャプチャしたい場合は、ビューポートをキャプチャする前にページの JavaScript でスクロールします。

Page.captureScreenshot、Page.startScreencast、Page.printToPDF には生の CDP を使います。スクリーンキャストのクライアントは、各 Page.screencastFrame を Page.screencastFrameAck で確認する必要があります。フレームはページのアクティビティに応じて生成されるもので、固定フレームレートのデスクトップキャプチャではありません。

PDF 出力では、用紙サイズ、余白、横向き、倍率、背景、ページ範囲を指定できます。選択可能なテキスト、タグ付き PDF、アウトライン、ヘッダー／フッター、CSS ページメディアの完全な動作には、現時点では対応していません。

MCP を操作する

stdio の場合は obscura mcp、HTTP の場合は obscura mcp --http --port 3000 を実行します。最初にページへ移動してから、現在のページを調べたり操作したりします。要素の参照が変わっている場合があるため、ページ遷移、クリック、スクロール、フレームワークによる再レンダリングの後は、スナップショットまたは操作可能な要素の一覧を更新してください。

レンダリング対応の MCP ビルドでは、browser_screenshot が MCP PNG 画像として、browser_pdf が埋め込み PDF リソースとして公開されます。MCP ではスクリーンキャストのフレームはストリーミングされません。そのワークフローには CDP を使ってください。

視覚的な動作を検証する

まず、対象の動作だけを切り分ける決定論的なフィクスチャから始めます。次に、幅広い実際のサイトを、初期位置とスクロール後の位置の両方でテストします。エンジンを比較する場合は、ビューポート、デバイススケール、ユーザーエージェント、ネットワーク入力、安定化ポリシー、スクロール位置、アニメーション時間、キャプチャ範囲を同一に保ちます。

差分を解釈する前に、両方のエンジンで正常にページ遷移し、空白ではない画像が生成されたことを確認します。ピクセル指標は回帰を検知するための警告として扱い、最終的な判定には使いません。リソースの読み込み完了、ボックスのジオメトリ、行の折り返し、構造上のエッジ、クリッピング、固定表示やスティッキー表示の動作を調べたうえで、実際の不具合をフィクスチャに落とし込みます。ホスト名固有のレンダリングロジックは導入しないでください。

期待値を正確に設定する

Obscura は一般的なレイアウトや描画の処理を幅広くサポートしていますが、Chrome を同梱したビルドではありません。対応範囲の狭い CSS、サービスワーカー、一部の Web API、ネイティブメディア、GPU やコンポジターの効果、PDF の構造、プラットフォームのフォントラスタライズは、Chromium と異なる場合があります。ドキュメントを編集する際は、プロジェクトで既に示されている位置付けや公開済みのベンチマークに関する主張を維持してください。パフォーマンスや忠実度の測定を追加または更新する場合は、ベンチマークスイートと条件を揃えた入力を使用してください。