From 3bb568928a1916dfb66efa5bc1b884330cad8c71 Mon Sep 17 00:00:00 2001 From: lacatoire Date: Thu, 27 Aug 2026 17:48:07 +0200 Subject: [PATCH] [Sync-En] taint: sync the Taint extension documentation with EN --- reference/taint/book.xml | 63 ++-- reference/taint/configure.xml | 51 ++- reference/taint/detail.xml | 378 ++++++++++------------- reference/taint/functions/is-tainted.xml | 56 +++- reference/taint/functions/taint.xml | 90 +++++- reference/taint/functions/untaint.xml | 83 ++++- reference/taint/ini.xml | 50 ++- reference/taint/reference.xml | 4 +- reference/taint/setup.xml | 33 +- 9 files changed, 495 insertions(+), 313 deletions(-) diff --git a/reference/taint/book.xml b/reference/taint/book.xml index 94de8b830..661dd1fde 100644 --- a/reference/taint/book.xml +++ b/reference/taint/book.xml @@ -1,6 +1,5 @@ - - + @@ -9,50 +8,58 @@ &reftitle.intro; - - Taint es una extensión que sirve para detectar código XSS (strings - corrompidos, «tainted»). - También se puede utilizar para localizar vulnerabilidades a inyecciones SQL, inyecciones - «shell», etc. - - - Si taint está habilitada, advertirá de si se ha proporcionado una cadena corrompida - (que venga de $_GET, $_POST - o $_COOKIE) a alguna función. - + + Taint es una extensión para detectar código XSS (cadenas corrompidas). + También se puede utilizar para localizar inyecciones SQL, inyecciones de + comandos, inyecciones de rutas de ficheros y vulnerabilidades similares. + + + Cuando taint está habilitada, las cadenas recibidas de la entrada del + usuario —$_GET, $_POST y + $_COOKIE— se marcan como corrompidas al inicio de la + petición, y la marca se sigue a través de las operaciones sobre cadenas. + Cuando una cadena corrompida alcanza un sumidero peligroso (salida, + consulta SQL, comando del intérprete de órdenes, ruta de fichero, ...), + taint emite una advertencia que señala ese punto. Véase + Propagación y sumideros comprobados + para consultar las listas completas. + + + Taint es una herramienta de desarrollo y de auditoría, no una defensa en + tiempo de ejecución: únicamente informa de posibles problemas y nunca + bloquea ni altera los datos. Es deliberadamente conservadora y puede + informar de más de la cuenta, por lo que una ejecución limpia significa + solamente «nada que taint pudiera ver», nunca «demostrablemente seguro». + No se debe habilitar en entornos de producción. + - Ejemplo de <function>taint</function> + Ejemplo de taint ]]> &example.outputs.similar; diff --git a/reference/taint/configure.xml b/reference/taint/configure.xml index 4c57695bb..c4ceb5ef0 100644 --- a/reference/taint/configure.xml +++ b/reference/taint/configure.xml @@ -1,19 +1,58 @@ - - - +
&reftitle.install; - + &pecl.info; - &url.pecl.package;taint + &url.pecl.package;taint. + + + + Se instala con PECL: + + + + + + + El código fuente está alojado en + GitHub. Para compilar + la extensión a partir del código fuente: + + + + -
+ + A continuación, se habilita la extensión añadiendo + extension=taint.so (o extension=php_taint.dll + en Windows) a &php.ini;, y estableciendo + taint.enable a + 1. + + + + Taint es una herramienta de desarrollo y de auditoría. No se debe + habilitar en entornos de producción: la instrumentación ralentiza todas + las peticiones y deshabilita el JIT de OPcache, y las advertencias pueden + filtrar datos de la petición a los registros. + + + - + - Más detalles + Propagación y sumideros comprobados
- Funciones y sentencias que propagarán la marca de corrupción de una - cadena corrupta + Cómo se propaga la marca de corrupción + + La marca de corrupción es un único bit almacenado en la propia cadena, no + en la variable que la contiene. Asignar, pasar o compartir de cualquier + otro modo una cadena corrompida conserva la marca. La concatenación y la + interpolación de cadenas también la propagan: + - - - - - - - Función/Sentencia - Desde - - + Operadores que propagan la marca de corrupción + - = (asignación) - 0.1.0 - - - . (concatenación) - 0.1.0 - - - "{$var}" (sustitución de variables) - 0.1.0 - - - .= (concatenación de asignación) - 0.1.0 - - - strval - 0.3.0 - - - explode/split - 0.3.0 + = (asignación, incluidos list() y la desestructuración de arrays) - implode/join - 0.3.0 + . (concatenación) - sprintf - 0.3.0 + .= (concatenación con asignación) - vsprintf - 0.3.0 - - - trim - 0.4.0 + "{$var}" (interpolación de cadenas, incluida la vía rápida ROPE) + + +
+ + + Además, taint conoce un conjunto fijo de funciones de cadenas: cuando + alguno de los argumentos de cadena pertinentes está corrompido, la cadena + devuelta también se marca como corrompida. Se cubren tanto la llamada + normal como, a partir de PHP 8.4, la llamada de vía rápida sin marco. + + + + Funciones que propagan la marca de corrupción + + - rtrim - 0.4.0 + trim, rtrim, ltrim - ltrim - 0.4.0 + substr, strstr - strstr - 0.5.0 + str_replace, str_ireplace - str_pad - 0.5.0 + str_pad, strtolower, strtoupper, strval - str_replace - 0.5.0 + explode (cada elemento del array resultante) - substr - 0.5.0 + implode/join (un separador corrompido corrompe también el resultado) - strtolower - 0.5.0 + sprintf, vsprintf (solo el especificador %s transmite la marca; sprintf("%d", $t) devuelve una cadena limpia) - strtoupper - 0.5.0 + dirname, basename, pathinfo
+ + Cualquier función que taint no conozca explícitamente devuelve una cadena + nueva y sin marcar, incluidas las funciones auxiliares de escape como + htmlspecialchars, htmlentities o + mysqli_real_escape_string. Esto es deliberado: taint + prefiere informar de más de la cuenta antes que intentar decidir si un + valor es seguro para un contexto de salida concreto. Se debe + usar untaint para eliminar la marca de los valores que + se hayan validado explícitamente. +
-
- Funciones y sentencias que comprobarán cadenas corrompidas +
+ Dónde emite advertencias taint + + Cuando una cadena corrompida alcanza uno de los sumideros indicados a + continuación, taint emite una advertencia (por omisión un + E_USER_WARNING; el nivel se puede configurar mediante + taint.error_level). + Solo se inspeccionan los argumentos de cadena de primer nivel; volcar un + array que únicamente contenga valores corrompidos no genera advertencia. + - + Sumideros de salida - - - - Función/Sentencia - Desde - + SumideroQué se comprueba - Sentencias básicas - - - eval - 0.1.0 - - - include/include_once - 0.1.0 - - - require/require_once - 0.1.0 - - - - - Funciones de salida - - - echo - 0.1.0 - - - print - 0.1.0 - - - printf - 0.1.0 - - - file_put_contents - 0.1.0 - - - - Funciones del sistema de ficheros - - - fopen - 0.2.0 - - - opendir - 0.2.0 - - - basename - 0.2.0 - - - dirname - 0.2.0 - - - file - 0.2.0 - - - pathinfo - 0.2.0 + echo, print + la expresión mostrada o impresa - - Funciones relacionadas con bases de datos + printf, vprintf + la cadena de formato y los valores sustituidos - mysql_query - 0.2.0 + print_r, var_dump, var_export + el valor volcado, cuando es una cadena - mysqli_query/MySQLi::query - 0.2.0 + exit/die con un mensaje + el mensaje - sqlite_query/SqliteDataBase::query - 0.3.0 - - - sqlite_single_query/SqliteDataBase::singleQuery - 0.3.0 - - - oci_parse - 0.3.0 + file_put_contents, fwrite, fputs hacia php://output + los datos escritos + + +
+ + + + Sumideros del sistema de ficheros + + + SumideroQué se comprueba + + - PDO::query - 0.3.0 + fopen, opendir, unlink + la ruta - PDO::prepare - 0.3.0 + file, readfile, file_get_contents, highlight_file/show_source + la ruta - SQLite3::query - 2.0.1 + copy, rename, move_uploaded_file + tanto la ruta de origen como la de destino - SQLite3::prepare - 2.0.1 + mkdir, rmdir, touch + la ruta - - Funciones relacionadas con la línea de comandos + include, include_once, require, require_once + la ruta del fichero + + +
+ + + + Sumideros SQL + + + SumideroQué se comprueba + + - system - 0.1.0 + mysqli_query, mysqli_prepare, mysqli_real_query, mysqli_multi_query + la cadena de la consulta - exec - 0.1.0 + mysql_query, sqlite_query, sqlite_single_query, oci_parse, pg_query, pg_send_query + la cadena de la consulta - proc_open - 0.1.0 + mysqli::query, mysqli::prepare, mysqli::real_query, mysqli::multi_query + la cadena de la consulta - passthru - 0.1.0 + PDO::query, PDO::prepare, PDO::exec + la cadena de la consulta - shell_exec - 0.3.0 + SQLite3::query, SQLite3::prepare, SQLite3::exec, SQLiteDatabase::query, SQLiteDatabase::singleQuery + la cadena de la consulta - -
-
- -
- Funciones que sanean cadenas corruptas - + Sumideros de ejecución de comandos - - - - Función - Desde - + SumideroQué se comprueba - addslashes - 0.1.0 - - - addcslashes - 0.1.0 + exec, system, passthru, shell_exec (incluido el operador de comillas invertidas) + la cadena del comando - htmlspecialchars - 0.1.0 + proc_open, popen + la cadena del comando - htmlentities - 0.1.0 + eval + el código evaluado - escapeshellcmd - 0.1.0 + las llamadas dinámicas como $func(), $obj->$method(), call_user_func o los callables en forma de array + el nombre de la función, del método o de la clase que se resuelve - mysql_escape_string - 0.1.0 - - - mysql_real_escape_string - 0.1.0 + preg_match, preg_match_all, preg_replace, preg_split, preg_grep, preg_replace_callback + el patrón (y el nombre de la función de retrollamada en el caso de preg_replace_callback) + + +
+ + + + Sumideros de cabeceras y cookies + + + SumideroQué se comprueba + + - mysqli_escape_string/MySQLi::escape_string - 0.1.0 + header + la cadena de la cabecera - mysqli_real_escape_string/MySQLi::real_escape_string - 0.1.0 + setcookie, setrawcookie + el nombre y el valor de la cookie + + +
+ + + + Otros sumideros + + + SumideroQué se comprueba + + - sqlite_escape_string/SqliteDataBase::escapeString - 0.3.0 + unserialize + la cadena serializada - PDO::quote - 0.3.0 + mail + el destinatario, el asunto, los parámetros adicionales y las cabeceras adicionales (el cuerpo del mensaje es contenido y no se comprueba)
- + + Las advertencias siguen el formato + nombre_de_funcion() [sumidero]: mensaje, donde + sumidero identifica la operación comprobada (por ejemplo + echo, include o el nombre de la + función) y el mensaje describe lo que se ha detectado como posiblemente + corrompido. +
+ + - - + is_tainted - Comprobar si un string está corrompido + Comprueba si una cadena está corrompida @@ -15,10 +13,10 @@ boolis_tainted stringstring - - Comprueba si un string está corrompido - - + + Comprueba si el valor dado lleva la marca de corrupción. Solo las cadenas + pueden estar corrompidas; cualquier otro tipo devuelve &false;. + @@ -27,9 +25,9 @@ string - - - + + El valor a comprobar. + @@ -37,12 +35,44 @@ &reftitle.returnvalues; + + Devuelve &true; si el valor es una cadena corrompida y &false; en caso + contrario. Devuelve siempre &false; cuando + taint.enable está deshabilitada. + + + + + &reftitle.examples; + + Ejemplo de <function>is_tainted</function> + + +]]> + + &example.outputs.similar; + + + + + + + + &reftitle.seealso; - Devuelve TRUE si el string está corrompido, FALSE en caso contrario. + + taint + untaint + - - + taint - Corrompe un string + Marca cadenas como corrompidas @@ -13,11 +12,22 @@ booltaint stringstring - stringstrings + stringstrings - - Crea un string corrompido. Solamente se usa para realizar pruebas. - + + Marca manualmente como corrompidas las cadenas dadas, como si procedieran + de la entrada del usuario. Las variables se pasan por referencia, pero la + marca en sí se almacena en la cadena y no en la variable: todas las + variables que compartan la misma cadena quedan corrompidas a la vez. + + + Esto resulta útil sobre todo para las pruebas y para simular la entrada del + usuario en scripts CLI, donde las superglobales + $_GET, + $_POST y + $_COOKIE + no están rellenadas. + @@ -26,16 +36,17 @@ string - - - + + Una variable que contiene la cadena a marcar. + strings - - + + Variables adicionales a marcar. + @@ -43,13 +54,62 @@ &reftitle.returnvalues; + + Devuelve siempre &true;. Cuando + taint.enable está deshabilitada, la + función no hace nada y sigue devolviendo &true;. + + + + + &reftitle.examples; + + Ejemplo de <function>taint</function> + + +]]> + + &example.outputs.similar; + + + + + + + + &reftitle.notes; + + + Solo se marcan las cadenas no vacías; las variables que contienen otros + tipos, o cadenas vacías, se ignoran silenciosamente. + + + + + Las cadenas internadas, persistentes y permanentes (literales de cadena, + cadenas compartidas de opcache) nunca pueden llevar la marca y se omiten + silenciosamente. + + + + + + &reftitle.seealso; - Devuelve TRUE si la transformación se lleva a cabo. Siempre devuelve TRUE si la extensión - taint no esta activada. + + untaint + is_tainted + - - + untaint - Sanea un string + Elimina la marca de corrupción de las cadenas @@ -13,11 +12,18 @@ booluntaint stringstring - stringstrings + stringstrings - - Sanea un string - + + Elimina la marca de corrupción de las cadenas dadas. + + + La marca se almacena en la propia cadena, no en la variable, por lo que + esto la elimina a la vez para todas las variables que compartan la misma + cadena. Se usa para incluir en una lista blanca los valores que se hayan + validado explícitamente, por ejemplo tras una comprobación estricta con una + lista de valores permitidos. + @@ -26,17 +32,17 @@ string - - - + + Una variable que contiene la cadena a limpiar. + strings - - - + + Variables adicionales a limpiar. + @@ -44,11 +50,58 @@ &reftitle.returnvalues; - + + Devuelve siempre &true;. Cuando + taint.enable está deshabilitada, la + función no hace nada y sigue devolviendo &true;. + + - + + &reftitle.examples; + + Ejemplo de <function>untaint</function> + + +]]> + + &example.outputs.similar; + + + + + + + + &reftitle.notes; + + + Solo los valores de tipo cadena pueden llevar la marca; pasar un valor que + no sea una cadena no tiene ningún efecto. + + + + &reftitle.seealso; + + + taint + is_tainted + + + diff --git a/reference/taint/ini.xml b/reference/taint/ini.xml index e87f7cfb3..324a47eae 100644 --- a/reference/taint/ini.xml +++ b/reference/taint/ini.xml @@ -1,13 +1,12 @@ - - +
&reftitle.runtime; &extension.runtime; - &ConfigureOptions; de taint + &ConfigureOptions; de Taint @@ -26,7 +25,7 @@ taint.error_level - E_WARNING + 512 (E_USER_WARNING) INI_ALL @@ -42,12 +41,27 @@ taint.enable - int + bool - - Si habilitar taint. - + + Interruptor principal. Cuando está habilitado, taint intercepta el + ejecutor y marca como corrompidas las cadenas procedentes de + $_GET, $_POST y + $_COOKIE al inicio de la petición. + + + Esta directiva solo se puede establecer en &php.ini;: su activación + requiere reiniciar el proceso, por lo que no se puede alternar por + petición ni por directorio. + + + + No se debe habilitar esta directiva en entornos de producción: la + instrumentación ralentiza todas las peticiones y es incompatible con + el JIT de OPcache. + + @@ -56,13 +70,27 @@ int + + El nivel de error empleado cuando taint informa de una cadena + posiblemente corrompida. Por omisión es + E_USER_WARNING (512). + + + Dado que esta directiva es INI_ALL, se puede + cambiar en tiempo de ejecución. Por ejemplo, para silenciar las + advertencias de taint en el script actual: + - El tipo del error del que taint informará cuando encuentre una cadena - corrupta. + + +]]> + - diff --git a/reference/taint/reference.xml b/reference/taint/reference.xml index 1567ce5b5..3ece43971 100644 --- a/reference/taint/reference.xml +++ b/reference/taint/reference.xml @@ -1,7 +1,5 @@ - - - + &Functions; de taint diff --git a/reference/taint/setup.xml b/reference/taint/setup.xml index 7c683162c..9b59c5fdf 100644 --- a/reference/taint/setup.xml +++ b/reference/taint/setup.xml @@ -1,25 +1,34 @@ - - + &reftitle.setup; -
- &reftitle.install; - - &pecl.moved; - - - &pecl.info; - &url.pecl.package;taint. - +
+ &reftitle.required; + + Taint 3.x requiere PHP 8.0 o posterior. Para PHP 7.x se deben usar las + versiones 2.1.x de taint, y para PHP 5.x las versiones 1.x. +
+ + &reference.taint.configure; + + - &reference.taint.ini; + &reference.taint.ini; +
+ &reftitle.resources; + + Taint no define ningún tipo de recurso. La propia marca de corrupción se + almacena en la estructura interna zend_string, no en un + recurso visible para el usuario. + +
+