From f133c739f8c6903e48d7849e2df3fa497da0e41e Mon Sep 17 00:00:00 2001 From: Chris Taylor Date: Thu, 29 Oct 2026 15:27:54 +0000 Subject: [PATCH] docs(wordpress): visitor IP matching is an off-by-default setting Co-Authored-By: Claude Opus 5.5 --- .../docs/de/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- .../docs/en/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- .../docs/es/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- .../docs/fr/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- .../docs/it/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- .../docs/pt-br/wordpress-plugin/hooks.mdx | 22 ++++++++++++++----- 6 files changed, 96 insertions(+), 36 deletions(-) diff --git a/src/content/docs/de/wordpress-plugin/hooks.mdx b/src/content/docs/de/wordpress-plugin/hooks.mdx index 1e754821c5943..caea07a74f114 100644 --- a/src/content/docs/de/wordpress-plugin/hooks.mdx +++ b/src/content/docs/de/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. IP-Adresse des Besuchers +## 4. Abgleich der Besucher-IP -Ab Version 1.23.0 sendet das Plugin die IP-Adresse des Besuchers mit jeder Verifizierungsanfrage, was die Bot-Erkennung verbessert. Standardmäßig wird `REMOTE_ADDR` verwendet. Wenn Ihre Website hinter einem Proxy oder CDN wie Cloudflare liegt, enthält `REMOTE_ADDR` die Adresse des Proxys. Übergeben Sie die echte IP des Besuchers dann mit dem **prosopo/procaptcha/visitor_ip**-Filter: +Ist der IP-Abgleich aktiv, sendet das Plugin die IP-Adresse des Besuchers mit jeder Verifizierungsanfrage, und Procaptcha lehnt ein Token ab, das von einer anderen IP gelöst wurde. Er ist **standardmäßig aus**: Die meisten Websites laufen hinter Cloudflare oder einem anderen Proxy, und würde die Adresse des Proxys statt der des Besuchers gesendet, würden echte Besucher abgelehnt. + +Zum Einschalten öffnen Sie **Einstellungen > Prosopo Procaptcha > General** und wählen unter **Abgleich der Besucher-IP**, woher die IP des Besuchers stammt: + +- **An – Website läuft hinter Cloudflare**: der Header `CF-Connecting-IP`. +- **An – Website läuft hinter einem anderen Proxy**: die erste Adresse im Header `X-Forwarded-For`. +- **An – Besucher verbinden sich direkt**: `REMOTE_ADDR`. + +Wählen Sie nur einen Header, den Ihr Proxy setzt, da Besucher diese Header selbst senden können. Fehlt der Header oder ist er keine gültige IP-Adresse, wird nichts gesendet und das Token ohne IP-Abgleich verifiziert. + +Für andere Konfigurationen erhält der Filter **prosopo/procaptcha/visitor_ip** die IP aus der Einstellung (leer, wenn sie aus ist) und `REMOTE_ADDR`. Geben Sie die zu sendende IP zurück oder einen leeren String, um keine zu senden: ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Vertrauen Sie nur einem weitergeleiteten Header, den Ihr Proxy setzt. Werte, die keine gültige IP-Adresse sind, werden nicht gesendet. +Version 1.23.0 hat standardmäßig `REMOTE_ADDR` gesendet. Aktualisieren Sie auf 1.24.0 oder neuer, wenn Ihre Website hinter einem Proxy läuft. ## 5. Verifizierungsergebnis diff --git a/src/content/docs/en/wordpress-plugin/hooks.mdx b/src/content/docs/en/wordpress-plugin/hooks.mdx index 41f28d7dd5535..ce34d80409080 100644 --- a/src/content/docs/en/wordpress-plugin/hooks.mdx +++ b/src/content/docs/en/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. Visitor IP address +## 4. Visitor IP matching -From version 1.23.0, the plugin sends the visitor's IP address with each verification request, which improves bot detection. By default it uses `REMOTE_ADDR`. If your site is behind a proxy or CDN such as Cloudflare, `REMOTE_ADDR` is the proxy's address, so pass the real visitor IP with the **prosopo/procaptcha/visitor_ip** filter: +When IP matching is on, the plugin sends the visitor's IP address with each verification request, and Procaptcha rejects a token solved from a different IP. It's **off by default**: most sites are behind Cloudflare or another proxy, and sending the proxy's address instead of the visitor's would reject real visitors. + +To turn it on, go to **Settings > Prosopo Procaptcha > General** and pick where the visitor's IP comes from under **Visitor IP matching**: + +- **On - site is behind Cloudflare**: the `CF-Connecting-IP` header. +- **On - site is behind another proxy**: the first address in the `X-Forwarded-For` header. +- **On - visitors connect directly**: `REMOTE_ADDR`. + +Only pick a header that your proxy sets, as visitors can send these headers themselves. If the header is missing or isn't a valid IP address, nothing is sent and the token is verified without IP matching. + +For other setups, the **prosopo/procaptcha/visitor_ip** filter receives the IP from the setting (empty when it's off) and `REMOTE_ADDR`. Return the IP to send, or an empty string to send none: ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Only trust a forwarded header that your proxy sets. Values that aren't a valid IP address aren't sent. +Version 1.23.0 sent `REMOTE_ADDR` by default. Update to 1.24.0 or later if your site is behind a proxy. ## 5. Verification result diff --git a/src/content/docs/es/wordpress-plugin/hooks.mdx b/src/content/docs/es/wordpress-plugin/hooks.mdx index df74a317b60d9..d295315cab55e 100644 --- a/src/content/docs/es/wordpress-plugin/hooks.mdx +++ b/src/content/docs/es/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. Dirección IP del visitante +## 4. Coincidencia de IP del visitante -A partir de la versión 1.23.0, el plugin envía la dirección IP del visitante con cada solicitud de verificación, lo que mejora la detección de bots. Por defecto utiliza `REMOTE_ADDR`. Si su sitio está detrás de un proxy o CDN como Cloudflare, `REMOTE_ADDR` es la dirección del proxy, así que pase la IP real del visitante con el filtro **prosopo/procaptcha/visitor_ip**: +Con la coincidencia de IP activada, el plugin envía la dirección IP del visitante en cada solicitud de verificación, y Procaptcha rechaza un token resuelto desde otra IP. Está **desactivada por defecto**: la mayoría de los sitios están detrás de Cloudflare u otro proxy, y enviar la dirección del proxy en lugar de la del visitante rechazaría a visitantes reales. + +Para activarla, vaya a **Ajustes > Prosopo Procaptcha > General** y elija de dónde procede la IP del visitante en **Coincidencia de IP del visitante**: + +- **Activado: el sitio está detrás de Cloudflare**: la cabecera `CF-Connecting-IP`. +- **Activado: el sitio está detrás de otro proxy**: la primera dirección de la cabecera `X-Forwarded-For`. +- **Activado: los visitantes se conectan directamente**: `REMOTE_ADDR`. + +Elija solo una cabecera que establezca su proxy, ya que los visitantes pueden enviar estas cabeceras ellos mismos. Si falta la cabecera o no es una dirección IP válida, no se envía nada y el token se verifica sin coincidencia de IP. + +Para otras configuraciones, el filtro **prosopo/procaptcha/visitor_ip** recibe la IP del ajuste (vacía si está desactivado) y `REMOTE_ADDR`. Devuelva la IP que desea enviar, o una cadena vacía para no enviar ninguna: ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Confíe solo en una cabecera reenviada que establezca su proxy. Los valores que no sean una dirección IP válida no se envían. +La versión 1.23.0 enviaba `REMOTE_ADDR` por defecto. Actualice a la 1.24.0 o posterior si su sitio está detrás de un proxy. ## 5. Resultado de la verificación diff --git a/src/content/docs/fr/wordpress-plugin/hooks.mdx b/src/content/docs/fr/wordpress-plugin/hooks.mdx index e212ac4188776..57ddc63edbe36 100644 --- a/src/content/docs/fr/wordpress-plugin/hooks.mdx +++ b/src/content/docs/fr/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. Adresse IP du visiteur +## 4. Correspondance de l'IP du visiteur -Depuis la version 1.23.0, le plugin envoie l'adresse IP du visiteur avec chaque requête de vérification, ce qui améliore la détection des bots. Par défaut, il utilise `REMOTE_ADDR`. Si votre site est derrière un proxy ou un CDN comme Cloudflare, `REMOTE_ADDR` contient l'adresse du proxy : transmettez alors l'IP réelle du visiteur avec le filtre **prosopo/procaptcha/visitor_ip** : +Lorsque la correspondance d'IP est activée, le plugin envoie l'adresse IP du visiteur avec chaque requête de vérification, et Procaptcha rejette un jeton résolu depuis une autre IP. Elle est **désactivée par défaut** : la plupart des sites sont derrière Cloudflare ou un autre proxy, et envoyer l'adresse du proxy au lieu de celle du visiteur rejetterait de vrais visiteurs. + +Pour l'activer, allez dans **Réglages > Prosopo Procaptcha > General** et choisissez d'où vient l'IP du visiteur sous **Correspondance de l'IP du visiteur** : + +- **Activé – le site est derrière Cloudflare** : l'en-tête `CF-Connecting-IP`. +- **Activé – le site est derrière un autre proxy** : la première adresse de l'en-tête `X-Forwarded-For`. +- **Activé – les visiteurs se connectent directement** : `REMOTE_ADDR`. + +Ne choisissez qu'un en-tête défini par votre proxy, car les visiteurs peuvent envoyer ces en-têtes eux-mêmes. Si l'en-tête est absent ou n'est pas une adresse IP valide, rien n'est envoyé et le jeton est vérifié sans correspondance d'IP. + +Pour d'autres configurations, le filtre **prosopo/procaptcha/visitor_ip** reçoit l'IP issue du réglage (vide s'il est désactivé) et `REMOTE_ADDR`. Renvoyez l'IP à envoyer, ou une chaîne vide pour n'en envoyer aucune : ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Ne faites confiance qu'à un en-tête transféré défini par votre proxy. Les valeurs qui ne sont pas une adresse IP valide ne sont pas envoyées. +La version 1.23.0 envoyait `REMOTE_ADDR` par défaut. Passez à la 1.24.0 ou plus récente si votre site est derrière un proxy. ## 5. Résultat de la vérification diff --git a/src/content/docs/it/wordpress-plugin/hooks.mdx b/src/content/docs/it/wordpress-plugin/hooks.mdx index d780da48bbfb1..acdfa1ee275b2 100644 --- a/src/content/docs/it/wordpress-plugin/hooks.mdx +++ b/src/content/docs/it/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. Indirizzo IP del visitatore +## 4. Corrispondenza IP del visitatore -Dalla versione 1.23.0, il plugin invia l'indirizzo IP del visitatore con ogni richiesta di verifica, migliorando il rilevamento dei bot. Per impostazione predefinita utilizza `REMOTE_ADDR`. Se il tuo sito è dietro un proxy o una CDN come Cloudflare, `REMOTE_ADDR` è l'indirizzo del proxy, quindi passa l'IP reale del visitatore con il filtro **prosopo/procaptcha/visitor_ip**: +Con la corrispondenza IP attiva, il plugin invia l'indirizzo IP del visitatore con ogni richiesta di verifica, e Procaptcha rifiuta un token risolto da un altro IP. È **disattivata per impostazione predefinita**: la maggior parte dei siti è dietro Cloudflare o un altro proxy, e inviare l'indirizzo del proxy invece di quello del visitatore rifiuterebbe visitatori reali. + +Per attivarla, vai su **Impostazioni > Prosopo Procaptcha > General** e scegli da dove proviene l'IP del visitatore in **Corrispondenza IP del visitatore**: + +- **Attivato – il sito è dietro Cloudflare**: l'header `CF-Connecting-IP`. +- **Attivato – il sito è dietro un altro proxy**: il primo indirizzo nell'header `X-Forwarded-For`. +- **Attivato – i visitatori si connettono direttamente**: `REMOTE_ADDR`. + +Scegli solo un header impostato dal tuo proxy, perché i visitatori possono inviare questi header da soli. Se l'header manca o non è un indirizzo IP valido, non viene inviato nulla e il token viene verificato senza corrispondenza IP. + +Per altre configurazioni, il filtro **prosopo/procaptcha/visitor_ip** riceve l'IP dall'impostazione (vuoto quando è disattivata) e `REMOTE_ADDR`. Restituisci l'IP da inviare, o una stringa vuota per non inviarne nessuno: ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Fidati solo di un header inoltrato impostato dal tuo proxy. I valori che non sono un indirizzo IP valido non vengono inviati. +La versione 1.23.0 inviava `REMOTE_ADDR` per impostazione predefinita. Aggiorna alla 1.24.0 o successiva se il tuo sito è dietro un proxy. ## 5. Risultato della verifica diff --git a/src/content/docs/pt-br/wordpress-plugin/hooks.mdx b/src/content/docs/pt-br/wordpress-plugin/hooks.mdx index b22d64261542e..a5523ff115368 100644 --- a/src/content/docs/pt-br/wordpress-plugin/hooks.mdx +++ b/src/content/docs/pt-br/wordpress-plugin/hooks.mdx @@ -37,17 +37,27 @@ add_filter('prosopo/procaptcha/captcha_attributes', function (array $attributes) }); ``` -## 4. Endereço IP do visitante +## 4. Correspondência do IP do visitante -A partir da versão 1.23.0, o plugin envia o endereço IP do visitante em cada solicitação de verificação, o que melhora a detecção de bots. Por padrão, ele usa `REMOTE_ADDR`. Se o seu site estiver atrás de um proxy ou CDN como o Cloudflare, `REMOTE_ADDR` é o endereço do proxy, então informe o IP real do visitante com o filtro **prosopo/procaptcha/visitor_ip**: +Com a correspondência de IP ativada, o plugin envia o endereço IP do visitante em cada solicitação de verificação, e o Procaptcha rejeita um token resolvido a partir de outro IP. Ela fica **desativada por padrão**: a maioria dos sites está atrás do Cloudflare ou de outro proxy, e enviar o endereço do proxy em vez do visitante rejeitaria visitantes reais. + +Para ativá-la, vá em **Configurações > Prosopo Procaptcha > General** e escolha de onde vem o IP do visitante em **Correspondência do IP do visitante**: + +- **Ativado – o site está atrás do Cloudflare**: o cabeçalho `CF-Connecting-IP`. +- **Ativado – o site está atrás de outro proxy**: o primeiro endereço do cabeçalho `X-Forwarded-For`. +- **Ativado – os visitantes se conectam diretamente**: `REMOTE_ADDR`. + +Escolha apenas um cabeçalho definido pelo seu proxy, pois os visitantes podem enviar esses cabeçalhos por conta própria. Se o cabeçalho estiver ausente ou não for um endereço IP válido, nada é enviado e o token é verificado sem correspondência de IP. + +Para outras configurações, o filtro **prosopo/procaptcha/visitor_ip** recebe o IP da configuração (vazio quando desativada) e `REMOTE_ADDR`. Retorne o IP a enviar, ou uma string vazia para não enviar nenhum: ```php -add_filter('prosopo/procaptcha/visitor_ip', function (string $ip): string { - return $_SERVER['HTTP_CF_CONNECTING_IP'] ?? $ip; -}); +add_filter('prosopo/procaptcha/visitor_ip', function (string $ip, string $remote_addr): string { + return $_SERVER['HTTP_TRUE_CLIENT_IP'] ?? $ip; +}, 10, 2); ``` -Confie apenas em um cabeçalho encaminhado definido pelo seu proxy. Valores que não sejam um endereço IP válido não são enviados. +A versão 1.23.0 enviava `REMOTE_ADDR` por padrão. Atualize para a 1.24.0 ou posterior se o seu site estiver atrás de um proxy. ## 5. Resultado da verificação