> For the complete documentation index, see [llms.txt](https://hacking-notes.jord4n.pro/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hacking-notes.jord4n.pro/ja/hacking-tools/web/php-security-scanner.md).

# PHP セキュリティスキャナー

危険な PHP 関数、リスクの高いパターン、悪用時の影響、トリアージメモ、修復ガイダンスのための PHP セキュリティスキャナー関数検索ツール。

PHP Security Scanner は、PHP アプリケーション内の危険な PHP 関数、弱い設定、リスクのある source-to-sink パス、権限昇格の指標を見つけるための、購読者限定の静的レビュー ツールです。

関数ファインダーを主要なトリアージ表示として使用してください。関数名、カテゴリ、影響、または重要度で検索できます。

## 関数ファインダー

<table data-view="cards" data-full-width="true" data-search="true"><thead><tr><th>関数 / パターン</th><th>カテゴリ</th><th>重要度</th><th>影響</th><th>スキャナー チェック</th><th>修正</th></tr></thead><tbody><tr><td><code>system()</code></td><td>コマンド実行</td><td>重大</td><td>Web ユーザーとしての RCE</td><td>汚染されたコマンド文字列、補間、連結、およびユーザー制御の引数をフラグ付けします。</td><td>ネイティブ PHP API または、厳格な許可リストに基づくコマンドと引数を使用してください。</td></tr><tr><td><code>exec()</code></td><td>コマンド実行</td><td>重大</td><td>RCE、コマンド出力の取得</td><td>リクエスト、Cookie、DB、ファイル、または CLI 入力がコマンドに到達するか確認します。</td><td>シェルの使用を削除するか、固定コマンドを許可リストの後ろに隔離します。</td></tr><tr><td><code>shell_exec()</code></td><td>コマンド実行</td><td>重大</td><td>返された出力を伴う RCE</td><td>動的なコマンド構築と、レスポンスにレンダリングされる出力を検出します。</td><td>安全なライブラリ呼び出しに置き換えます。</td></tr><tr><td><code>passthru()</code></td><td>コマンド実行</td><td>重大</td><td>生の出力を伴う RCE</td><td>Web ルートまたはファイル処理から到達可能な場合は、重要度を引き上げます。</td><td>シェル呼び出しを避け、固定された入力セットを検証します。</td></tr><tr><td><code>proc_open()</code></td><td>プロセス制御</td><td>重大</td><td>RCE、プロセス操作</td><td>コマンド、descriptor spec、環境、および作業ディレクトリを確認します。</td><td>制限されたワーカーと固定のコマンド テンプレートを使用します。</td></tr><tr><td><code>popen()</code></td><td>プロセス制御</td><td>重大</td><td>プロセス ストリーム経由の RCE</td><td>汚染されたコマンド文字列とストリーム読み取りをフラグ付けします。</td><td>可能な場合は PHP のストリーム/ファイル API に置き換えます。</td></tr><tr><td><code>pcntl_exec()</code></td><td>プロセス制御</td><td>重大</td><td>プロセス置換、権限昇格リスク</td><td>CLI、cron、SUID、sudo、worker のコンテキストでは重要度を引き上げます。</td><td>特権付きインタプリタ実行パスを削除します。</td></tr><tr><td><code>`backticks`</code></td><td>コマンド実行</td><td>重大</td><td>隠れたシェル実行</td><td>バッククォート式内の変数補間を検出します。</td><td>明示的で安全な API に置き換えます。</td></tr><tr><td><code>eval()</code></td><td>コード実行</td><td>重大</td><td>任意の PHP 実行</td><td>すべての使用をフラグ付けし、評価される文字列が動的であれば重要度を引き上げます。</td><td>クロージャ、パーサー、固定のディスパッチ マップ、または安全なテンプレートを使用します。</td></tr><tr><td><code>assert()</code></td><td>コード実行</td><td>高</td><td>レガシーなコード実行リスク</td><td>古い PHP コードベースの文字列アサーションをフラグ付けします。</td><td>真偽値のアサーションのみを使用し、動的文字列を削除します。</td></tr><tr><td><code>create_function()</code></td><td>コード実行</td><td>高</td><td>レガシーな評価済みコード</td><td>古いプラグインや PHP 5/7 互換コードを検出します。</td><td>無名関数に置き換えます。</td></tr><tr><td><code>preg_replace()</code> を <code>/e</code></td><td>コード実行</td><td>高</td><td>レガシーな評価済み置換</td><td>レガシーな正規表現置換の評価をフラグ付けします。</td><td>使用する <code>preg_replace_callback()</code>.</td></tr><tr><td><code>mb_ereg_replace()</code> を <code>e</code></td><td>コード実行</td><td>高</td><td>評価済み置換のリスク</td><td>動的なパターンと置換値を確認します。</td><td>評価を伴わない callback-safe なロジックを使用します。</td></tr><tr><td><code>include</code></td><td>ファイル取り込み</td><td>重大</td><td>LFI/RFI によるコード実行</td><td>ユーザー制御のパス、ラッパー、および拡張子のトリックをフラグ付けします。</td><td>ユーザーの選択を固定ファイルにマップします。</td></tr><tr><td><code>include_once</code></td><td>ファイル取り込み</td><td>重大</td><td>LFI/RFI によるコード実行</td><td>動的な include パスと autoload の副作用を確認します。</td><td>固定の include マップと正規化されたパスを使用します。</td></tr><tr><td><code>require</code></td><td>ファイル取り込み</td><td>重大</td><td>アプリケーション コード実行</td><td>パスにリクエスト データが含まれる場合は重要度を引き上げます。</td><td>動的なファイルシステム入力を拒否します。</td></tr><tr><td><code>require_once</code></td><td>ファイル取り込み</td><td>重大</td><td>アプリケーション コード実行</td><td>フレームワーク ローダー、プラグイン ローダー、テンプレート パスを確認します。</td><td>許可リストにあるモジュールのみを使用します。</td></tr><tr><td><code>file_get_contents()</code></td><td>ファイル / ネットワーク読み取り</td><td>高</td><td>LFI、SSRF、機密情報漏えい</td><td>汚染されたパス、URL、および <code>php://input</code> 解析をフラグ付けします。</td><td>パスを正規化し、危険なスキームをブロックします。</td></tr><tr><td><code>readfile()</code></td><td>ファイル読み取り</td><td>高</td><td>直接的なファイル漏えい</td><td>パス トラバーサルと公開ダウンロード ハンドラーを検出します。</td><td>承認済みディレクトリから ID でファイルを配信します。</td></tr><tr><td><code>fopen()</code></td><td>ファイル / ネットワーク アクセス</td><td>高</td><td>LFI、SSRF、任意書き込み</td><td>mode、path source、URL ラッパーを追跡します。</td><td>スキーム、mode、正規化パスを検証します。</td></tr><tr><td><code>file()</code></td><td>ファイル読み取り</td><td>高</td><td>行ベースのファイル漏えい</td><td>ユーザー制御のファイル名をフラグ付けします。</td><td>固定の保存パスと境界チェックを使用します。</td></tr><tr><td><code>SplFileObject</code></td><td>ファイル アクセス</td><td>高</td><td>LFI、パス トラバーサル</td><td>動的なコンストラクタ引数を検出します。</td><td>適用 <code>realpath()</code> 境界の強制。</td></tr><tr><td><code>file_put_contents()</code></td><td>ファイル書き込み</td><td>重大</td><td>Web シェル、上書き、設定汚染</td><td>ファイル名と内容が汚染されているか、パスが公開されている場合は重要度を引き上げます。</td><td>ファイル名を生成し、Web ルートの外に書き込みます。</td></tr><tr><td><code>fwrite()</code></td><td>ファイル書き込み</td><td>高</td><td>任意のファイル変更</td><td>ハンドルの起点を追跡します <code>fopen()</code>.</td><td>書き込み可能なディレクトリとファイル種別を制限します。</td></tr><tr><td><code>copy()</code></td><td>ファイル書き込み / 移動</td><td>高</td><td>ファイルの配置または上書き</td><td>ソースと宛先の汚染を確認します。</td><td>固定の宛先と衝突に安全な名前を使用します。</td></tr><tr><td><code>rename()</code></td><td>ファイル移動</td><td>高</td><td>アップロード バイパス、上書き</td><td>ユーザー制御の宛先パスをフラグ付けします。</td><td>生成された保存名を使用します。</td></tr><tr><td><code>unlink()</code></td><td>ファイル削除</td><td>高</td><td>任意のファイル削除</td><td>汚染されたパスとトラバーサルを検出します。</td><td>生のパスではなく、オブジェクト ID で削除します。</td></tr><tr><td><code>chmod()</code></td><td>権限</td><td>高</td><td>権限の弱体化</td><td>次のような広いモードと <code>0777</code> 汚染されたパスをフラグ付けします。</td><td>最小権限のモードと固定パスを使用します。</td></tr><tr><td><code>chown()</code> / <code>chgrp()</code></td><td>所有権</td><td>高</td><td>権限操作</td><td>デプロイおよび管理スクリプトを確認します。</td><td>所有権の変更をアプリ入力に公開しないでください。</td></tr><tr><td><code>mkdir()</code></td><td>ファイルシステム</td><td>中</td><td>パス トラバーサル、弱い権限</td><td>動的なパスと寛容すぎるモードをフラグ付けします。</td><td>パスを正規化し、厳格な権限を設定します。</td></tr><tr><td><code>touch()</code></td><td>ファイルシステム</td><td>中</td><td>ファイル作成、タイムスタンプ悪用</td><td>cron または特権ディレクトリでは重要度を引き上げます。</td><td>固定パスと所有権チェックを使用します。</td></tr><tr><td><code>unserialize()</code></td><td>デシリアライズ</td><td>重大</td><td>PHP オブジェクト インジェクション</td><td>リクエスト、Cookie、アップロード、DB、キャッシュ、またはキュー データを用いたすべての使用をフラグ付けします。</td><td>JSON を使用するか、制限します <code>allowed_classes</code>.</td></tr><tr><td><code>Phar</code> / <code>phar://</code></td><td>デシリアライズ</td><td>高</td><td>メタデータ起因のオブジェクト インジェクション</td><td>受け入れられた <code>phar://</code> パスと、アップロードに触れるファイル関数を</td><td>ラッパーをブロックし、オブジェクトを含むメタデータ パスを避けます。</td></tr><tr><td><code>__wakeup()</code></td><td>マジック メソッド</td><td>高</td><td>オブジェクト インジェクション ガジェット</td><td>ファイル、SQL、コマンド、およびネットワーク操作を確認します。</td><td>マジック メソッドは副作用がないようにします。</td></tr><tr><td><code>__destruct()</code></td><td>マジック メソッド</td><td>高</td><td>オブジェクト インジェクション ガジェット</td><td>削除、書き込み、取り込み、または実行を行う場合は重要度を引き上げます。</td><td>危険なデストラクタの副作用を避けます。</td></tr><tr><td><code>__toString()</code></td><td>マジック メソッド</td><td>中</td><td>暗黙のガジェット実行</td><td>テンプレートのレンダリングとログ出力のパスを確認します。</td><td>変換メソッドは純粋に保ちます。</td></tr><tr><td><code>curl_exec()</code></td><td>ネットワーク / SSRF</td><td>高</td><td>SSRF、内部サービス アクセス</td><td>URL、リダイレクト、ヘッダー、プロキシ、およびプロトコル オプションを追跡します。</td><td>ホストを許可リスト化し、プライベート範囲をブロックします。</td></tr><tr><td><code>fsockopen()</code></td><td>ネットワーク</td><td>高</td><td>生の内部ネットワーク アクセス</td><td>動的なホストとポートの値をフラグ付けします。</td><td>宛先と外向き通信を制限します。</td></tr><tr><td><code>pfsockopen()</code></td><td>ネットワーク</td><td>高</td><td>永続的な内部ネットワーク アクセス</td><td>長寿命のサービス接続を確認します。</td><td>固定エンドポイントを使用します。</td></tr><tr><td><code>stream_socket_client()</code></td><td>ネットワーク</td><td>高</td><td>SSRF とプロトコル悪用</td><td>動的なスキーム、ホスト、およびポートをフラグ付けします。</td><td>許可リスト化されたネットワーク先を使用します。</td></tr><tr><td><code>SoapClient</code></td><td>ネットワーク</td><td>中</td><td>SSRF 風のリクエスト</td><td>動的な WSDL とエンドポイント値を確認します。</td><td>固定 WSDL を使用し、リダイレクトをブロックします。</td></tr><tr><td><code>mysqli_query()</code></td><td>SQL</td><td>高</td><td>SQL インジェクション</td><td>連結された、または補間された SQL をフラグ付けします。</td><td>プリペアド ステートメントを使用します。</td></tr><tr><td><code>mysqli_multi_query()</code></td><td>SQL</td><td>高</td><td>スタック型 SQL インジェクション</td><td>動的な複数ステートメント クエリは重要度を引き上げます。</td><td>ユーザーの影響を受けるデータに対して multi-query API の使用を避けます。</td></tr><tr><td><code>PDO::query()</code></td><td>SQL</td><td>高</td><td>SQL インジェクション</td><td>変数を含む生のクエリ文字列をフラグ付けします。</td><td>使用する <code>prepare()</code> およびバインドされたパラメータ。</td></tr><tr><td><code>PDO::exec()</code></td><td>SQL</td><td>高</td><td>SQL インジェクションまたは破壊的 SQL</td><td>管理アクションと移行を確認します。</td><td>パラメータ化ステートメントを使用します。</td></tr><tr><td><code>call_user_func()</code></td><td>動的ディスパッチ</td><td>高</td><td>コールバック悪用</td><td>汚染されたコールバック名をフラグ付けします。</td><td>固定のディスパッチ マップを使用します。</td></tr><tr><td><code>call_user_func_array()</code></td><td>動的ディスパッチ</td><td>高</td><td>動的引数を伴うコールバック悪用</td><td>コールバックと引数の起点を追跡します。</td><td>明示的なハンドラーと型付き入力を使用します。</td></tr><tr><td><code>$fn()</code></td><td>変数関数</td><td>高</td><td>任意の関数ディスパッチ</td><td>リクエストまたは DB データ由来の関数名をフラグ付けします。</td><td>名前を固定関数にマップします。</td></tr><tr><td><code>$object->$method()</code></td><td>動的メソッド</td><td>高</td><td>メソッド ディスパッチ悪用</td><td>入力由来のメソッド名をフラグ付けします。</td><td>許可リスト化されたメソッド マップを使用します。</td></tr><tr><td><code>ReflectionFunction</code></td><td>リフレクション</td><td>中</td><td>動的呼び出し</td><td>反映された名前と呼び出しを確認します。</td><td>リフレクションは内部ツールに限定します。</td></tr><tr><td><code>register_shutdown_function()</code></td><td>遅延コールバック</td><td>中</td><td>隠れた実行パス</td><td>動的なコールバックと引数をフラグ付けします。</td><td>明示的で固定のコールバックを使用します。</td></tr><tr><td><code>move_uploaded_file()</code></td><td>アップロード</td><td>高</td><td>Web シェル、上書き、パス トラバーサル</td><td>宛先パス、拡張子ロジック、公開ストレージ、および元のファイル名の使用を確認します。</td><td>ファイル名を変更し、拡張子を許可リスト化し、Web ルートの外に保存します。</td></tr><tr><td><code>getimagesize()</code></td><td>アップロード検証</td><td>中</td><td>弱い内容検証</td><td>これが唯一のアップロード検証として使われている場合はフラグ付けします。</td><td>拡張子、MIME、内容、および保存の制御を組み合わせます。</td></tr><tr><td><code>ZipArchive::extractTo()</code></td><td>アーカイブ展開</td><td>高</td><td>Zip Slip、任意書き込み</td><td>アーカイブのエントリ名と展開先ディレクトリを確認します。</td><td>展開された各パスを正規化します。</td></tr><tr><td><code>phpinfo()</code></td><td>情報漏えい</td><td>中</td><td>設定、パス、モジュール、および環境の漏えい</td><td>ローカル開発以外から到達可能ならフラグ付けします。</td><td>本番環境から削除します。</td></tr><tr><td><code>var_dump()</code> / <code>print_r()</code></td><td>デバッグ出力</td><td>低</td><td>データと機密情報の漏えい</td><td>レスポンスや例外パスで使用される場合は重要度を引き上げます。</td><td>マスキング付きの構造化ログを使用します。</td></tr><tr><td><code>debug_backtrace()</code></td><td>デバッグ出力</td><td>中</td><td>パスと引数の漏えい</td><td>エラー ハンドラーとデバッグ ルートを確認します。</td><td>本番環境では詳細なデバッグ出力を無効にします。</td></tr></tbody></table>

## 設定ファインダー

<table data-view="cards" data-full-width="true" data-search="true"><thead><tr><th>ディレクティブ</th><th>重要度</th><th>リスク</th><th>スキャナー チェック</th></tr></thead><tbody><tr><td><code>disable_functions</code></td><td>高</td><td>危険な実行関数がまだ利用可能です。</td><td>特にコマンドのシンクが存在する場合は、ハードニングの欠落や不完全さを報告します。</td></tr><tr><td><code>open_basedir</code></td><td>中</td><td>PHP がより広いファイルシステム パスにアクセスできます。</td><td>欠如、空、または広すぎる値をフラグ付けします。</td></tr><tr><td><code>allow_url_fopen</code></td><td>中</td><td>ファイル API で URL を取得できます。</td><td>URL ベースのファイル読み取りと SSRF に弱い関数を重要度引き上げします。</td></tr><tr><td><code>allow_url_include</code></td><td>重大</td><td>動的な include はリモート リソースを読み込む可能性があります。</td><td>動的な include パスと組み合わさると重大です。</td></tr><tr><td><code>display_errors</code></td><td>中</td><td>スタック トレース、パス、および機密情報が漏えいする可能性があります。</td><td>有効化された本番設定をフラグ付けします。</td></tr><tr><td><code>expose_php</code></td><td>低</td><td>PHP バージョンの開示。</td><td>本番環境では無効化することを推奨します。</td></tr><tr><td><code>file_uploads</code></td><td>情報</td><td>アップロードの攻撃対象領域が存在します。</td><td>アップロード パス、サイズ、拡張子、内容の検証チェックと組み合わせます。</td></tr><tr><td><code>upload_max_filesize</code></td><td>中</td><td>大きすぎるアップロードとストレージの悪用。</td><td>アプリケーションに必要な値より大きい値をフラグ付けします。</td></tr><tr><td><code>session.cookie_httponly</code></td><td>中</td><td>クライアント側スクリプトによるセッション Cookie の窃取が容易になります。</td><td>有効化を推奨します。</td></tr><tr><td><code>session.cookie_secure</code></td><td>中</td><td>Cookie が HTTP で送信される可能性があります。</td><td>HTTPS サイトでは有効化を推奨します。</td></tr><tr><td><code>session.cookie_samesite</code></td><td>低</td><td>CSRF への露出が増える可能性があります。</td><td>明示的に推奨 <code>緩い</code> または <code>厳格</code>.</td></tr></tbody></table>

## ソースからシンクへの入力

| ソース            | 例                                       |
| -------------- | --------------------------------------- |
| リクエスト          | `$_GET`, `$_POST`, `$_REQUEST`          |
| Cookie / セッション | `$_COOKIE`、セッション値                       |
| アップロード         | `$_FILES`、元のファイル名、一時パス                  |
| ヘッダー           | `$_SERVER['HTTP_*']`, `getallheaders()` |
| 生のボディ          | `php://input`、デコード済み JSON/XML           |
| CLI / ワーカー     | `$argv`, `STDIN`、環境変数                   |
| 保存済みデータ        | データベース行、キャッシュエントリ、キュー、シリアライズ済みカラム       |
| ローカルファイル       | 設定ファイル、CSVインポート、一時ファイル                  |

## ルールID

| ルールID              | 重要度 | 意味                                           |
| ------------------ | --- | -------------------------------------------- |
| `PHP-CMD-001`      | 重大  | 汚染された入力がコマンド実行に到達する。                         |
| `PHP-EVAL-001`     | 重大  | 汚染された入力がPHPコード評価に到達する。                       |
| `PHP-INCL-001`     | 重大  | 汚染された入力がinclude/requireのパスを制御する。             |
| `PHP-DESER-001`    | 重大  | 汚染された入力が到達する `unserialize()`.                |
| `PHP-WRITE-001`    | 重大  | ユーザー制御のファイル書き込みが実行可能なパスまたは公開パスに到達する。         |
| `PHP-UPLOAD-001`   | 高   | アップロードの検証または保存により、実行可能ファイルが許可される可能性がある。      |
| `PHP-SSRF-001`     | 高   | 汚染されたURLがHTTP、ストリーム、ソケット、または cURL のシンクに到達する。 |
| `PHP-SQL-001`      | 高   | 汚染された入力が生のSQLに到達する。                          |
| `PHP-PATH-001`     | 高   | 汚染されたパスがファイルの読み取り/書き込み/削除/移動ロジックに到達する。       |
| `PHP-CALLBACK-001` | 高   | 汚染された関数名またはメソッド名が動的ディスパッチに到達する。              |
| `PHP-CONFIG-001`   | 高   | 危険なPHP設定により悪用可能性が高まる。                        |
| `PHP-PRIV-001`     | 重大  | PHPの実行がSUID、sudo、cron、または特権コンテキストで行われる。      |

## 簡易トリアージ

| 質問                                          | 深刻度の引き上げ       |
| ------------------------------------------- | -------------- |
| リクエストデータは関数に到達できますか？                        | 高または重大に引き上げる。  |
| その関数はコマンド、PHPコード、include、またはデシリアライズを実行しますか？ | 重大。            |
| Webルート配下のファイルに触れますか？                        | 高または重大。        |
| URL、ラッパー、ホスト、またはポートを受け付けますか？                | 高。             |
| cron、sudo、SUID、ワーカー、またはデプロイフックから実行されますか？    | 重大。            |
| 検証はブロックリスト、拡張子のみ、またはMIMEのみですか？              | 1段階引き上げる。      |
| 値は厳格な許可リストから選択されていますか？                      | 信頼度または深刻度を下げる。 |

## 権限昇格の兆候

| 兆候                           | リスク                                     |
| ---------------------------- | --------------------------------------- |
| SUID付きPHPバイナリ                | PHPを昇格したファイル所有者権限で実行できます。               |
| sudoルールがPHPを許可               | ユーザーは別のユーザーとしてPHPを実行できます。               |
| root所有のcronが書き込み可能なPHPを実行    | 書き込み可能なスクリプトが特権実行になる可能性があります。           |
| 書き込み可能なWebルート                | ファイル書き込みまたはアップロードのバグがコード実行に変わる可能性があります。 |
| 全ユーザー読み取り可能なシークレット           | アプリの認証情報が横展開を可能にすることがあります。              |
| Composerスクリプトが特権ユーザーとして実行される | 依存関係やスクリプトの実行がデプロイに影響する可能性があります。        |

## レポートテンプレート

```json
{
  "id": "PHP-CMD-001",
  "severity": "重大",
  "function": "shell_exec",
  "file": "app/Controllers/ReportController.php",
  "line": 84,
  "source": "$_POST['format']",
  "impact": "Webサーバーユーザーとしてのリモートコマンド実行",
  "fix": "シェル実行をネイティブPHPライブラリ、または厳格な許可リスト付き引数に置き換えてください。"
}
```

## スキャナーチェックリスト

* 解析 `.php`, `.inc`, `.phtml`, `.module`, `.theme`、フレームワークのルート、コントローラ、ジョブ、およびCLIスクリプト。
* リクエスト、Cookie、アップロード、ヘッダー、生のボディ、CLI、環境変数、データベース、キャッシュ、キュー、ファイルベースの入力を追跡する。
* コマンド実行、コード実行、include、ファイル、ネットワーク、SQL、デシリアライズ、アップロード、コールバック、デバッグ、設定のシンクを検出する。
* 到達可能性、サニタイズ、PHPバージョン、設定、Webルート、権限、実行コンテキストを使って検出結果をスコア付けする。
* 関数名、カテゴリ、深刻度、ソース、シンク、ファイル、行、影響、信頼度、修正を出力する。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hacking-notes.jord4n.pro/ja/hacking-tools/web/php-security-scanner.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.