> 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/pt-br/hacking-tools/web/php-security-scanner.md).

# Verificador de Segurança PHP

Localizador de funções do PHP Security Scanner para funções PHP perigosas, padrões arriscados, impacto da exploração, notas de triagem e orientação de remediação.

O PHP Security Scanner é uma ferramenta de revisão estática exclusiva para assinantes, usada para encontrar funções PHP perigosas, configuração fraca, caminhos arriscados de origem para destino e indicadores de escalonamento de privilégios em aplicativos PHP.

Use o localizador de funções como a principal visão de triagem: pesquise por nome da função, categoria, impacto ou severidade.

## Localizador de Funções

<table data-view="cards" data-full-width="true" data-search="true"><thead><tr><th>Função / Padrão</th><th>Categoria</th><th>Severidade</th><th>Impacto</th><th>Verificação do Scanner</th><th>Correção</th></tr></thead><tbody><tr><td><code>system()</code></td><td>Execução de comandos</td><td>Crítica</td><td>RCE como usuário web</td><td>Marque strings de comandos contaminadas, interpolação, concatenação e argumentos controlados pelo usuário.</td><td>Use APIs nativas do PHP ou comandos e argumentos estritamente permitidos em lista.</td></tr><tr><td><code>exec()</code></td><td>Execução de comandos</td><td>Crítica</td><td>RCE, captura de saída do comando</td><td>Verifique se a entrada de request, cookie, banco de dados, arquivo ou CLI alcança o comando.</td><td>Remova o uso de shell ou isole comandos fixos atrás de listas permitidas.</td></tr><tr><td><code>shell_exec()</code></td><td>Execução de comandos</td><td>Crítica</td><td>RCE com saída retornada</td><td>Detecte construção dinâmica de comandos e saída renderizada em respostas.</td><td>Substitua por chamadas seguras de biblioteca.</td></tr><tr><td><code>passthru()</code></td><td>Execução de comandos</td><td>Crítica</td><td>RCE com saída bruta</td><td>Escale quando acessível a partir de rotas web ou processamento de arquivos.</td><td>Evite chamadas de shell; valide conjuntos fixos de entrada.</td></tr><tr><td><code>proc_open()</code></td><td>Controle de processo</td><td>Crítica</td><td>RCE, interação com processo</td><td>Revise comando, especificação de descritores, ambiente e diretório de trabalho.</td><td>Use workers restritos e modelos de comando fixos.</td></tr><tr><td><code>popen()</code></td><td>Controle de processo</td><td>Crítica</td><td>RCE por meio de stream de processo</td><td>Marque strings de comando contaminadas e leituras de stream.</td><td>Substitua por APIs de stream/arquivo do PHP, quando possível.</td></tr><tr><td><code>pcntl_exec()</code></td><td>Controle de processo</td><td>Crítica</td><td>Substituição de processo, risco de escalonamento de privilégios</td><td>Escale em contextos de CLI, cron, SUID, sudo e worker.</td><td>Remova caminhos de execução do interpretador privilegiado.</td></tr><tr><td><code>`backticks`</code></td><td>Execução de comandos</td><td>Crítica</td><td>Execução oculta de shell</td><td>Detecte interpolação de variáveis dentro de expressões com crases.</td><td>Substitua por APIs seguras explícitas.</td></tr><tr><td><code>eval()</code></td><td>Execução de código</td><td>Crítica</td><td>Execução arbitrária de PHP</td><td>Marque todo uso; escale quando a string avaliada for dinâmica.</td><td>Use closures, parsers, mapas de despacho fixos ou modelos seguros.</td></tr><tr><td><code>assert()</code></td><td>Execução de código</td><td>Alta</td><td>Risco de execução de código legado</td><td>Marque asserções de string em bases de código PHP antigas.</td><td>Use apenas asserções booleanas; remova strings dinâmicas.</td></tr><tr><td><code>create_function()</code></td><td>Execução de código</td><td>Alta</td><td>Código legado avaliado</td><td>Detecte plugins antigos e código de compatibilidade com PHP 5/7.</td><td>Substitua por funções anônimas.</td></tr><tr><td><code>preg_replace()</code> por <code>/e</code></td><td>Execução de código</td><td>Alta</td><td>Substituição avaliada legada</td><td>Marque avaliação de substituição regex legada.</td><td>Use <code>preg_replace_callback()</code>.</td></tr><tr><td><code>mb_ereg_replace()</code> por <code>e</code></td><td>Execução de código</td><td>Alta</td><td>Risco de substituição avaliada</td><td>Revise padrões dinâmicos e valores de substituição.</td><td>Use lógica segura com callback sem avaliação.</td></tr><tr><td><code>include</code></td><td>Inclusão de arquivos</td><td>Crítica</td><td>LFI/RFI para execução de código</td><td>Marque caminhos controlados pelo usuário, wrappers e truques de extensão.</td><td>Associe escolhas do usuário a arquivos fixos.</td></tr><tr><td><code>include_once</code></td><td>Inclusão de arquivos</td><td>Crítica</td><td>LFI/RFI para execução de código</td><td>Verifique caminhos de include dinâmicos e efeitos colaterais de autoload.</td><td>Use mapas de include fixos e caminhos canônicos.</td></tr><tr><td><code>require</code></td><td>Inclusão de arquivos</td><td>Crítica</td><td>Execução de código do aplicativo</td><td>Escale quando o caminho contiver dados da requisição.</td><td>Rejeite entrada dinâmica do sistema de arquivos.</td></tr><tr><td><code>require_once</code></td><td>Inclusão de arquivos</td><td>Crítica</td><td>Execução de código do aplicativo</td><td>Revise carregadores de framework, carregadores de plugins e caminhos de template.</td><td>Use apenas módulos em lista permitida.</td></tr><tr><td><code>file_get_contents()</code></td><td>Leitura de arquivo / rede</td><td>Alta</td><td>LFI, SSRF, divulgação de segredos</td><td>Marque caminhos contaminados, URLs e <code>php://input</code> análise.</td><td>Canonicalize caminhos e bloqueie esquemas arriscados.</td></tr><tr><td><code>readfile()</code></td><td>Leitura de arquivo</td><td>Alta</td><td>Divulgação direta de arquivo</td><td>Detecte traversal de caminho e manipuladores públicos de download.</td><td>Sirva arquivos por ID a partir de diretórios aprovados.</td></tr><tr><td><code>fopen()</code></td><td>Acesso a arquivo / rede</td><td>Alta</td><td>LFI, SSRF, gravação arbitrária</td><td>Acompanhe modo, origem do caminho e wrappers de URL.</td><td>Valide esquema, modo e caminho canônico.</td></tr><tr><td><code>file()</code></td><td>Leitura de arquivo</td><td>Alta</td><td>Divulgação de arquivo baseada em linhas</td><td>Marque nomes de arquivo controlados pelo usuário.</td><td>Use caminhos de armazenamento fixos e verificações de limite.</td></tr><tr><td><code>SplFileObject</code></td><td>Acesso a arquivo</td><td>Alta</td><td>LFI, traversal de caminho</td><td>Detecte argumentos dinâmicos do construtor.</td><td>Aplique <code>realpath()</code> aplicação de limites.</td></tr><tr><td><code>file_put_contents()</code></td><td>Gravação de arquivo</td><td>Crítica</td><td>Web shell, sobrescrita, envenenamento de configuração</td><td>Escale quando o nome do arquivo e o conteúdo estiverem contaminados ou o caminho for público.</td><td>Gere nomes de arquivo e grave fora da raiz web.</td></tr><tr><td><code>fwrite()</code></td><td>Gravação de arquivo</td><td>Alta</td><td>Modificação arbitrária de arquivo</td><td>Rastreie a origem do manipulador a partir de <code>fopen()</code>.</td><td>Restrinja diretórios graváveis e tipos de arquivo.</td></tr><tr><td><code>copy()</code></td><td>Gravação / movimentação de arquivo</td><td>Alta</td><td>Plantio ou sobrescrita de arquivo</td><td>Verifique a contaminação da origem e do destino.</td><td>Use destinos fixos e nomes seguros contra colisão.</td></tr><tr><td><code>rename()</code></td><td>Movimentação de arquivo</td><td>Alta</td><td>Burlar upload, sobrescrita</td><td>Marque caminhos de destino controlados pelo usuário.</td><td>Use nomes de armazenamento gerados.</td></tr><tr><td><code>unlink()</code></td><td>Exclusão de arquivo</td><td>Alta</td><td>Exclusão arbitrária de arquivo</td><td>Detecte caminhos contaminados e traversal.</td><td>Exclua por ID de objeto, não por caminho bruto.</td></tr><tr><td><code>chmod()</code></td><td>Permissões</td><td>Alta</td><td>Enfraquecimento de privilégios</td><td>Marque modos amplos como <code>0777</code> e caminhos contaminados.</td><td>Use modos de menor privilégio e caminhos fixos.</td></tr><tr><td><code>chown()</code> / <code>chgrp()</code></td><td>Propriedade</td><td>Alta</td><td>Manipulação de privilégios</td><td>Revise scripts de implantação e administrativos.</td><td>Não exponha alterações de propriedade à entrada do aplicativo.</td></tr><tr><td><code>mkdir()</code></td><td>Sistema de arquivos</td><td>Média</td><td>Traversal de caminho, permissões fracas</td><td>Marque caminhos dinâmicos e modos permissivos.</td><td>Normalize caminhos e defina permissões rígidas.</td></tr><tr><td><code>touch()</code></td><td>Sistema de arquivos</td><td>Média</td><td>Criação de arquivo, abuso de timestamp</td><td>Escale em cron ou diretórios privilegiados.</td><td>Use caminhos fixos e verificações de propriedade.</td></tr><tr><td><code>unserialize()</code></td><td>Desserialização</td><td>Crítica</td><td>Injeção de objeto PHP</td><td>Marque todo uso com dados de request, cookie, upload, banco de dados, cache ou fila.</td><td>Use JSON ou restrinja <code>allowed_classes</code>.</td></tr><tr><td><code>Phar</code> / <code>phar://</code></td><td>Desserialização</td><td>Alta</td><td>Injeção de objeto disparada por metadados</td><td>Marque caminhos aceitos <code>phar://</code> e funções de arquivo que tocam uploads.</td><td>Bloqueie wrappers e evite caminhos de metadados que contenham objetos.</td></tr><tr><td><code>__wakeup()</code></td><td>Método mágico</td><td>Alta</td><td>Gadget de injeção de objeto</td><td>Revise ações de arquivo, SQL, comando e rede.</td><td>Mantenha métodos mágicos sem efeitos colaterais.</td></tr><tr><td><code>__destruct()</code></td><td>Método mágico</td><td>Alta</td><td>Gadget de injeção de objeto</td><td>Escale se ele excluir, gravar, incluir ou executar.</td><td>Evite efeitos colaterais perigosos em destructors.</td></tr><tr><td><code>__toString()</code></td><td>Método mágico</td><td>Média</td><td>Execução implícita de gadget</td><td>Verifique renderização de template e caminhos de log.</td><td>Mantenha os métodos de conversão puros.</td></tr><tr><td><code>curl_exec()</code></td><td>Rede / SSRF</td><td>Alta</td><td>SSRF, acesso a serviço interno</td><td>Acompanhe URL, redirects, cabeçalhos, proxy e opções de protocolo.</td><td>Permita apenas hosts da lista e bloqueie faixas privadas.</td></tr><tr><td><code>fsockopen()</code></td><td>Rede</td><td>Alta</td><td>Acesso bruto à rede interna</td><td>Marque valores dinâmicos de host e porta.</td><td>Restrinja destinos e saída de tráfego.</td></tr><tr><td><code>pfsockopen()</code></td><td>Rede</td><td>Alta</td><td>Acesso persistente à rede interna</td><td>Revise conexões de serviço de longa duração.</td><td>Use endpoints fixos.</td></tr><tr><td><code>stream_socket_client()</code></td><td>Rede</td><td>Alta</td><td>SSRF e abuso de protocolo</td><td>Marque esquemas, hosts e portas dinâmicos.</td><td>Use destinos de rede em lista permitida.</td></tr><tr><td><code>SoapClient</code></td><td>Rede</td><td>Média</td><td>Requisições no estilo SSRF</td><td>Revise valores dinâmicos de WSDL e endpoint.</td><td>Use WSDLs fixos e bloqueie redirecionamentos.</td></tr><tr><td><code>mysqli_query()</code></td><td>SQL</td><td>Alta</td><td>Injeção de SQL</td><td>Marque SQL concatenado ou interpolado.</td><td>Use instruções preparadas.</td></tr><tr><td><code>mysqli_multi_query()</code></td><td>SQL</td><td>Alta</td><td>Injeção de SQL em pilha</td><td>Escale consultas dinâmicas com múltiplas instruções.</td><td>Evite APIs de multi-query para dados influenciados pelo usuário.</td></tr><tr><td><code>PDO::query()</code></td><td>SQL</td><td>Alta</td><td>Injeção de SQL</td><td>Marque strings de consulta brutas contendo variáveis.</td><td>Use <code>prepare()</code> e parâmetros vinculados.</td></tr><tr><td><code>PDO::exec()</code></td><td>SQL</td><td>Alta</td><td>Injeção de SQL ou SQL destrutivo</td><td>Revise ações administrativas e migrações.</td><td>Use instruções parametrizadas.</td></tr><tr><td><code>call_user_func()</code></td><td>Despacho dinâmico</td><td>Alta</td><td>Abuso de callback</td><td>Marque nomes de callback contaminados.</td><td>Use mapas de despacho fixos.</td></tr><tr><td><code>call_user_func_array()</code></td><td>Despacho dinâmico</td><td>Alta</td><td>Abuso de callback com argumentos dinâmicos</td><td>Rastreie as origens do callback e dos argumentos.</td><td>Use manipuladores explícitos e entradas tipadas.</td></tr><tr><td><code>$fn()</code></td><td>Função variável</td><td>Alta</td><td>Despacho arbitrário de função</td><td>Marque nomes de função vindos de request ou dados do banco.</td><td>Associe nomes a funções fixas.</td></tr><tr><td><code>$object->$method()</code></td><td>Método dinâmico</td><td>Alta</td><td>Abuso de despacho de método</td><td>Marque nomes de método vindos da entrada.</td><td>Use mapas de métodos permitidos.</td></tr><tr><td><code>ReflectionFunction</code></td><td>Reflexão</td><td>Média</td><td>Invocação dinâmica</td><td>Revise nomes refletidos e a invocação.</td><td>Restrinja reflexão a ferramentas internas.</td></tr><tr><td><code>register_shutdown_function()</code></td><td>Callback adiado</td><td>Média</td><td>Caminho de execução oculto</td><td>Marque callbacks e argumentos dinâmicos.</td><td>Use callbacks fixos e explícitos.</td></tr><tr><td><code>move_uploaded_file()</code></td><td>Envie</td><td>Alta</td><td>Web shell, sobrescrita, traversal de caminho</td><td>Verifique o caminho de destino, lógica de extensão, armazenamento público e uso do nome original do arquivo.</td><td>Renomeie arquivos, permita extensões em lista e armazene fora da raiz web.</td></tr><tr><td><code>getimagesize()</code></td><td>Validação de upload</td><td>Média</td><td>Validação fraca de conteúdo</td><td>Marque quando usado como a única validação de upload.</td><td>Combine controles de extensão, MIME, conteúdo e armazenamento.</td></tr><tr><td><code>ZipArchive::extractTo()</code></td><td>Extração de arquivo compactado</td><td>Alta</td><td>Zip slip, gravação arbitrária</td><td>Verifique os nomes das entradas do arquivo compactado e o diretório de extração.</td><td>Canonicalize cada caminho extraído.</td></tr><tr><td><code>phpinfo()</code></td><td>Divulgação de informações</td><td>Média</td><td>Vazamento de configuração, caminho, módulo e ambiente</td><td>Marque se for acessível fora do desenvolvimento local.</td><td>Remova da produção.</td></tr><tr><td><code>var_dump()</code> / <code>print_r()</code></td><td>Saída de depuração</td><td>Baixa</td><td>Vazamento de dados e segredos</td><td>Escale quando usado em respostas ou caminhos de exceção.</td><td>Use logs estruturados com redação.</td></tr><tr><td><code>debug_backtrace()</code></td><td>Saída de depuração</td><td>Média</td><td>Divulgação de caminho e argumentos</td><td>Revise manipuladores de erro e rotas de depuração.</td><td>Desative a saída verbosa de depuração em produção.</td></tr></tbody></table>

## Localizador de Configuração

<table data-view="cards" data-full-width="true" data-search="true"><thead><tr><th>Diretiva</th><th>Severidade</th><th>Risco</th><th>Verificação do Scanner</th></tr></thead><tbody><tr><td><code>disable_functions</code></td><td>Alta</td><td>Funções perigosas de execução continuam disponíveis.</td><td>Reporte hardening ausente ou incompleto, especialmente quando existirem sinks de comando.</td></tr><tr><td><code>open_basedir</code></td><td>Média</td><td>O PHP pode acessar caminhos mais amplos do sistema de arquivos.</td><td>Marque valores ausentes, vazios ou excessivamente amplos.</td></tr><tr><td><code>allow_url_fopen</code></td><td>Média</td><td>As APIs de arquivo podem buscar URLs.</td><td>Escale leituras de arquivo baseadas em URL e funções propensas a SSRF.</td></tr><tr><td><code>allow_url_include</code></td><td>Crítica</td><td>Includes dinâmicos podem carregar recursos remotos.</td><td>Crítico quando ativado com caminhos de include dinâmicos.</td></tr><tr><td><code>display_errors</code></td><td>Média</td><td>Tracebacks, caminhos e segredos podem vazar.</td><td>Marque configurações de produção ativadas.</td></tr><tr><td><code>expose_php</code></td><td>Baixa</td><td>Divulgação da versão do PHP.</td><td>Recomende desativar em produção.</td></tr><tr><td><code>file_uploads</code></td><td>Informação</td><td>Existe superfície de ataque para upload.</td><td>Combine com verificações de caminho de upload, tamanho, extensão e conteúdo.</td></tr><tr><td><code>upload_max_filesize</code></td><td>Média</td><td>Uploads excessivamente grandes e abuso de armazenamento.</td><td>Marque valores maiores do que o aplicativo precisa.</td></tr><tr><td><code>session.cookie_httponly</code></td><td>Média</td><td>O roubo de cookie de sessão por script do lado do cliente fica mais fácil.</td><td>Recomenda-se ativar.</td></tr><tr><td><code>session.cookie_secure</code></td><td>Média</td><td>Cookies podem ser enviados por HTTP.</td><td>Recomenda-se ativar em sites HTTPS.</td></tr><tr><td><code>session.cookie_samesite</code></td><td>Baixa</td><td>A exposição a CSRF pode aumentar.</td><td>Recomenda-se explícito <code>Flexível</code> ou <code>Estrito</code>.</td></tr></tbody></table>

## Entradas de origem para destino

| Origem                           | Exemplos                                                                 |
| -------------------------------- | ------------------------------------------------------------------------ |
| Requisição                       | `$_GET`, `$_POST`, `$_REQUEST`                                           |
| Cookies / sessões                | `$_COOKIE`, valores de sessão                                            |
| Uploads                          | `$_FILES`, nomes de arquivos originais, caminhos temporários             |
| Cabeçalhos                       | `$_SERVER['HTTP_*']`, `getallheaders()`                                  |
| Corpo bruto                      | `php://input`, JSON/XML decodificados                                    |
| CLI / processos em segundo plano | `$argv`, `STDIN`, variáveis de ambiente                                  |
| Dados armazenados                | Linhas de banco de dados, entradas de cache, filas, colunas serializadas |
| Arquivos locais                  | Arquivos de configuração, importações CSV, arquivos temporários          |

## IDs de regra

| ID da regra        | Severidade | Significado                                                                                   |
| ------------------ | ---------- | --------------------------------------------------------------------------------------------- |
| `PHP-CMD-001`      | Crítica    | A entrada contaminada alcança a execução de comandos.                                         |
| `PHP-EVAL-001`     | Crítica    | A entrada contaminada alcança a avaliação de código PHP.                                      |
| `PHP-INCL-001`     | Crítica    | A entrada contaminada controla os caminhos de include/require.                                |
| `PHP-DESER-001`    | Crítica    | A entrada contaminada alcança `unserialize()`.                                                |
| `PHP-WRITE-001`    | Crítica    | A gravação de arquivo controlada pelo usuário alcança um caminho executável ou público.       |
| `PHP-UPLOAD-001`   | Alta       | A validação ou o armazenamento de upload podem permitir arquivos executáveis.                 |
| `PHP-SSRF-001`     | Alta       | A URL contaminada alcança destinos HTTP, de stream, socket ou cURL.                           |
| `PHP-SQL-001`      | Alta       | A entrada contaminada alcança SQL bruto.                                                      |
| `PHP-PATH-001`     | Alta       | O caminho contaminado alcança a lógica de leitura/gravação/exclusão/movimentação de arquivos. |
| `PHP-CALLBACK-001` | Alta       | O nome de função ou método contaminado alcança o despacho dinâmico.                           |
| `PHP-CONFIG-001`   | Alta       | Uma configuração perigosa do PHP aumenta a explorabilidade.                                   |
| `PHP-PRIV-001`     | Crítica    | A execução do PHP ocorre com SUID, sudo, cron ou em contexto privilegiado.                    |

## Triagem rápida

| Pergunta                                                               | Aumento de severidade               |
| ---------------------------------------------------------------------- | ----------------------------------- |
| Os dados da requisição podem alcançar a função?                        | Eleve para Alta ou Crítica.         |
| A função executa comandos, código PHP, includes ou desserialização?    | Crítica.                            |
| Ele acessa arquivos sob a raiz da web?                                 | Alta ou Crítica.                    |
| Ele aceita URLs, wrappers, hosts ou portas?                            | Alta.                               |
| Ele é executado por cron, sudo, SUID, workers ou hooks de implantação? | Crítica.                            |
| A validação se baseia apenas em listas de bloqueio, extensões ou MIME? | Eleve um nível.                     |
| O valor é selecionado de uma allowlist estrita?                        | Reduza a confiança ou a severidade. |

## Sinais de escalada de privilégio

| Sinal                                                        | Risco                                                                         |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| Binário PHP SUID                                             | O PHP pode ser executado com privilégios elevados do proprietário do arquivo. |
| Regra de sudo permite PHP                                    | O usuário pode executar PHP como outro usuário.                               |
| Cron de propriedade do root executa PHP gravável             | Um script gravável pode se tornar uma execução privilegiada.                  |
| Raiz da web gravável                                         | Um bug de gravação de arquivo ou upload pode virar execução de código.        |
| Segredos legíveis por todos                                  | Credenciais do aplicativo podem permitir movimento lateral.                   |
| Scripts do Composer são executados como usuário privilegiado | A execução de dependências ou scripts pode afetar a implantação.              |

## Modelo de relatório

```json
{
  "id": "PHP-CMD-001",
  "severity": "crítico",
  "function": "shell_exec",
  "file": "app/Controllers/ReportController.php",
  "line": 84,
  "source": "$_POST['format']",
  "impact": "Execução remota de comandos como o usuário do servidor web",
  "fix": "Substitua a execução de shell por uma biblioteca PHP nativa ou por argumentos estritamente em uma lista de permissões."
}
```

## Lista de verificação do scanner

* Analisar `.php`, `.inc`, `.phtml`, `.module`, `.theme`, rotas do framework, controladores, jobs e scripts de CLI.
* Rastreie entradas de requisição, cookies, uploads, cabeçalhos, corpo bruto, CLI, variáveis de ambiente, banco de dados, cache, fila e entradas baseadas em arquivo.
* Detecte destinos de execução de comandos, execução de código, include, arquivos, rede, SQL, desserialização, upload, callback, depuração e configuração.
* Pontue os achados com base em alcançabilidade, sanitização, versão do PHP, configuração, raiz da web, permissões e contexto de execução.
* Exporte nome da função, categoria, severidade, origem, destino, arquivo, linha, impacto, confiança e correção.


---

# 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/pt-br/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.