theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/seguridad-perl/SKILL.md

@@ -1,507 +0,0 @@
----
-name: seguridad-perl
-description: Seguridad integral en Perl — modo taint, validación de entrada, ejecución segura de procesos, consultas DBI parametrizadas, seguridad web (XSS/SQLi/CSRF) y políticas de seguridad de perlcritic.
----
-
-# Patrones de seguridad en Perl
-
-Directrices de seguridad integrales para aplicaciones Perl: validación de entrada, prevención de inyecciones y prácticas de código seguro.
-
-## Cuándo usarla
-
-- Al manejar entrada de usuario en aplicaciones Perl.
-- Al construir aplicaciones web en Perl (CGI, Mojolicious, Dancer2, Catalyst).
-- Al revisar código Perl en busca de vulnerabilidades de seguridad.
-- Al realizar operaciones con archivos usando rutas proporcionadas por el usuario.
-- Al ejecutar comandos del sistema desde Perl.
-- Al escribir consultas de base de datos con DBI.
-
-## Cómo funciona
-
-Empieza por fronteras de entrada conscientes del taint y avanza hacia afuera: valida y destainta las entradas, mantén restringidos el sistema de archivos y la ejecución de procesos, y usa consultas DBI parametrizadas en todas partes. Los ejemplos siguientes muestran los valores por defecto seguros que esta skill espera que apliques antes de publicar código Perl que toque entrada de usuario, la shell o la red.
-
-## Modo taint
-
-El modo taint de Perl (`-T`) rastrea los datos provenientes de fuentes externas e impide que se usen en operaciones inseguras sin validación explícita.
-
-### Habilitar el modo taint
-
-```perl
-#!/usr/bin/perl -T
-use v5.36;
-
-# Contaminado (tainted): todo lo que venga de fuera del programa
-my $input    = $ARGV[0];        # Contaminado
-my $env_path = $ENV{PATH};      # Contaminado
-my $form     = <STDIN>;         # Contaminado
-my $query    = $ENV{QUERY_STRING}; # Contaminado
-
-# Sanear PATH temprano (obligatorio en modo taint)
-$ENV{PATH} = '/usr/local/bin:/usr/bin:/bin';
-delete @ENV{qw(IFS CDPATH ENV BASH_ENV)};
-```
-
-### Patrón de destaintado
-
-```perl
-use v5.36;
-
-# Bien: validar y destaintar con una regex específica
-sub untaint_username($input) {
-    if ($input =~ /^([a-zA-Z0-9_]{3,30})$/) {
-        return $1;  # $1 queda destaintado
-    }
-    die "Nombre de usuario inválido: debe tener 3-30 caracteres alfanuméricos\n";
-}
-
-# Bien: validar y destaintar una ruta de archivo
-sub untaint_filename($input) {
-    if ($input =~ m{^([a-zA-Z0-9._-]+)$}) {
-        return $1;
-    }
-    die "Nombre de archivo inválido: contiene caracteres inseguros\n";
-}
-
-# Mal: destaintado demasiado permisivo (anula el propósito)
-sub bad_untaint($input) {
-    $input =~ /^(.*)$/s;
-    return $1;  # Acepta CUALQUIER cosa — inútil
-}
-```
-
-## Validación de entrada
-
-### Lista de permitidos antes que lista de bloqueados
-
-```perl
-use v5.36;
-
-# Bien: lista de permitidos — define exactamente lo que se acepta
-sub validate_sort_field($field) {
-    my %allowed = map { $_ => 1 } qw(name email created_at updated_at);
-    die "Campo de ordenación inválido: $field\n" unless $allowed{$field};
-    return $field;
-}
-
-# Bien: validar con patrones específicos
-sub validate_email($email) {
-    if ($email =~ /^([a-zA-Z0-9._%+-]+\@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$/) {
-        return $1;
-    }
-    die "Dirección de correo inválida\n";
-}
-
-sub validate_integer($input) {
-    if ($input =~ /^(-?\d{1,10})$/) {
-        return $1 + 0;  # Coaccionar a número
-    }
-    die "Entero inválido\n";
-}
-
-# Mal: lista de bloqueados — siempre incompleta
-sub bad_validate($input) {
-    die "Inválido" if $input =~ /[<>"';&|]/;  # Se le escapan ataques codificados
-    return $input;
-}
-```
-
-### Restricciones de longitud
-
-```perl
-use v5.36;
-
-sub validate_comment($text) {
-    die "El comentario es obligatorio\n"          unless length($text) > 0;
-    die "El comentario supera los 10000 caracteres\n" if length($text) > 10_000;
-    return $text;
-}
-```
-
-## Expresiones regulares seguras
-
-### Prevención de ReDoS
-
-El backtracking catastrófico ocurre con cuantificadores anidados sobre patrones que se solapan.
-
-```perl
-use v5.36;
-
-# Mal: vulnerable a ReDoS (backtracking exponencial)
-my $bad_re = qr/^(a+)+$/;           # Cuantificadores anidados
-my $bad_re2 = qr/^([a-zA-Z]+)*$/;   # Cuantificadores anidados sobre una clase
-my $bad_re3 = qr/^(.*?,){10,}$/;    # Combinación repetida greedy/lazy
-
-# Bien: reescribir sin anidamiento
-my $good_re = qr/^a+$/;             # Cuantificador único
-my $good_re2 = qr/^[a-zA-Z]+$/;     # Cuantificador único sobre una clase
-
-# Bien: usar cuantificadores posesivos o grupos atómicos para evitar backtracking
-my $safe_re = qr/^[a-zA-Z]++$/;             # Posesivo (5.10+)
-my $safe_re2 = qr/^(?>a+)$/;                # Grupo atómico
-
-# Bien: imponer un timeout sobre patrones no confiables
-use POSIX qw(alarm);
-sub safe_match($string, $pattern, $timeout = 2) {
-    my $matched;
-    eval {
-        local $SIG{ALRM} = sub { die "Timeout de la regex\n" };
-        alarm($timeout);
-        $matched = $string =~ $pattern;
-        alarm(0);
-    };
-    alarm(0);
-    die $@ if $@;
-    return $matched;
-}
-```
-
-## Operaciones seguras con archivos
-
-### Open de tres argumentos
-
-```perl
-use v5.36;
-
-# Bien: open de tres argumentos, filehandle léxico, comprobar el retorno
-sub read_file($path) {
-    open my $fh, '<:encoding(UTF-8)', $path
-        or die "No se puede abrir '$path': $!\n";
-    local $/;
-    my $content = <$fh>;
-    close $fh;
-    return $content;
-}
-
-# Mal: open de dos argumentos con datos de usuario (inyección de comandos)
-sub bad_read($path) {
-    open my $fh, $path;        # Si $path = "|rm -rf /", ¡ejecuta el comando!
-    open my $fh, "< $path";   # Inyección de metacaracteres de shell
-}
-```
-
-### Prevención de TOCTOU y path traversal
-
-```perl
-use v5.36;
-use Fcntl qw(:DEFAULT :flock);
-use File::Spec;
-use Cwd qw(realpath);
-
-# Creación atómica de archivos
-sub create_file_safe($path) {
-    sysopen(my $fh, $path, O_WRONLY | O_CREAT | O_EXCL, 0600)
-        or die "No se puede crear '$path': $!\n";
-    return $fh;
-}
-
-# Validar que la ruta permanezca dentro del directorio permitido
-sub safe_path($base_dir, $user_path) {
-    my $real = realpath(File::Spec->catfile($base_dir, $user_path))
-        // die "La ruta no existe\n";
-    my $base_real = realpath($base_dir)
-        // die "El directorio base no existe\n";
-    die "Path traversal bloqueado\n" unless $real =~ /^\Q$base_real\E(?:\/|\z)/;
-    return $real;
-}
-```
-
-Usa `File::Temp` para archivos temporales (`tempfile(UNLINK => 1)`) y `flock(LOCK_EX)` para prevenir condiciones de carrera.
-
-## Ejecución segura de procesos
-
-### system y exec en forma de lista
-
-```perl
-use v5.36;
-
-# Bien: forma de lista — sin interpolación de shell
-sub run_command(@cmd) {
-    system(@cmd) == 0
-        or die "El comando falló: @cmd\n";
-}
-
-run_command('grep', '-r', $user_pattern, '/var/log/app/');
-
-# Bien: capturar la salida de forma segura con IPC::Run3
-use IPC::Run3;
-sub capture_output(@cmd) {
-    my ($stdout, $stderr);
-    run3(\@cmd, \undef, \$stdout, \$stderr);
-    if ($?) {
-        die "El comando falló (exit $?): $stderr\n";
-    }
-    return $stdout;
-}
-
-# Mal: forma de string — ¡inyección de shell!
-sub bad_search($pattern) {
-    system("grep -r '$pattern' /var/log/app/");  # Si $pattern = "'; rm -rf / #"
-}
-
-# Mal: backticks con interpolación
-my $output = `ls $user_dir`;   # Riesgo de inyección de shell
-```
-
-Usa también `Capture::Tiny` para capturar de forma segura el stdout/stderr de comandos externos.
-
-## Prevención de inyección SQL
-
-### Placeholders de DBI
-
-```perl
-use v5.36;
-use DBI;
-
-my $dbh = DBI->connect($dsn, $user, $pass, {
-    RaiseError => 1,
-    PrintError => 0,
-    AutoCommit => 1,
-});
-
-# Bien: consultas parametrizadas — usa siempre placeholders
-sub find_user($dbh, $email) {
-    my $sth = $dbh->prepare('SELECT * FROM users WHERE email = ?');
-    $sth->execute($email);
-    return $sth->fetchrow_hashref;
-}
-
-sub search_users($dbh, $name, $status) {
-    my $sth = $dbh->prepare(
-        'SELECT * FROM users WHERE name LIKE ? AND status = ? ORDER BY name'
-    );
-    $sth->execute("%$name%", $status);
-    return $sth->fetchall_arrayref({});
-}
-
-# Mal: interpolación de strings en SQL (¡vulnerabilidad SQLi!)
-sub bad_find($dbh, $email) {
-    my $sth = $dbh->prepare("SELECT * FROM users WHERE email = '$email'");
-    # Si $email = "' OR 1=1 --", devuelve todos los usuarios
-    $sth->execute;
-    return $sth->fetchrow_hashref;
-}
-```
-
-### Listas de permitidos para columnas dinámicas
-
-```perl
-use v5.36;
-
-# Bien: validar los nombres de columna contra una lista de permitidos
-sub order_by($dbh, $column, $direction) {
-    my %allowed_cols = map { $_ => 1 } qw(name email created_at);
-    my %allowed_dirs = map { $_ => 1 } qw(ASC DESC);
-
-    die "Columna inválida: $column\n"      unless $allowed_cols{$column};
-    die "Dirección inválida: $direction\n" unless $allowed_dirs{uc $direction};
-
-    my $sth = $dbh->prepare("SELECT * FROM users ORDER BY $column $direction");
-    $sth->execute;
-    return $sth->fetchall_arrayref({});
-}
-
-# Mal: interpolar directamente la columna elegida por el usuario
-sub bad_order($dbh, $column) {
-    $dbh->prepare("SELECT * FROM users ORDER BY $column");  # ¡SQLi!
-}
-```
-
-### DBIx::Class (seguridad del ORM)
-
-```perl
-use v5.36;
-
-# DBIx::Class genera consultas parametrizadas seguras
-my @users = $schema->resultset('User')->search({
-    status => 'active',
-    email  => { -like => '%@example.com' },
-}, {
-    order_by => { -asc => 'name' },
-    rows     => 50,
-});
-```
-
-## Seguridad web
-
-### Prevención de XSS
-
-```perl
-use v5.36;
-use HTML::Entities qw(encode_entities);
-use URI::Escape qw(uri_escape_utf8);
-
-# Bien: codificar la salida para el contexto HTML
-sub safe_html($user_input) {
-    return encode_entities($user_input);
-}
-
-# Bien: codificar para el contexto de URL
-sub safe_url_param($value) {
-    return uri_escape_utf8($value);
-}
-
-# Bien: codificar para el contexto JSON
-use JSON::MaybeXS qw(encode_json);
-sub safe_json($data) {
-    return encode_json($data);  # Se encarga del escapado
-}
-
-# Auto-escapado en plantillas (Mojolicious)
-# <%= $user_input %>   — auto-escapado (seguro)
-# <%== $raw_html %>    — salida cruda (peligroso, solo para contenido confiable)
-
-# Auto-escapado en plantillas (Template Toolkit)
-# [% user_input | html %]  — codificación HTML explícita
-
-# Mal: salida cruda en HTML
-sub bad_html($input) {
-    print "<div>$input</div>";  # XSS si $input contiene <script>
-}
-```
-
-### Protección CSRF
-
-```perl
-use v5.36;
-use Crypt::URandom qw(urandom);
-use MIME::Base64 qw(encode_base64url);
-
-sub generate_csrf_token() {
-    return encode_base64url(urandom(32));
-}
-```
-
-Usa comparación en tiempo constante al verificar tokens. La mayoría de los frameworks web (Mojolicious, Dancer2, Catalyst) traen protección CSRF incorporada — prefiérela sobre soluciones artesanales.
-
-### Seguridad de sesiones y cabeceras
-
-```perl
-use v5.36;
-
-# Sesión + cabeceras en Mojolicious
-$app->secrets(['secreto-largo-aleatorio-rotado-regularmente']);
-$app->sessions->secure(1);          # Solo HTTPS
-$app->sessions->samesite('Lax');
-
-$app->hook(after_dispatch => sub ($c) {
-    $c->res->headers->header('X-Content-Type-Options' => 'nosniff');
-    $c->res->headers->header('X-Frame-Options'        => 'DENY');
-    $c->res->headers->header('Content-Security-Policy' => "default-src 'self'");
-    $c->res->headers->header('Strict-Transport-Security' => 'max-age=31536000; includeSubDomains');
-});
-```
-
-## Codificación de la salida
-
-Codifica siempre la salida según su contexto: `HTML::Entities::encode_entities()` para HTML, `URI::Escape::uri_escape_utf8()` para URLs, `JSON::MaybeXS::encode_json()` para JSON.
-
-## Seguridad de módulos CPAN
-
-- **Fija versiones** en el cpanfile: `requires 'DBI', '== 1.643';`
-- **Prefiere módulos mantenidos**: revisa en MetaCPAN que haya releases recientes.
-- **Minimiza dependencias**: cada dependencia es superficie de ataque.
-
-## Herramientas de seguridad
-
-### Políticas de seguridad de perlcritic
-
-```ini
-# .perlcriticrc — configuración enfocada en seguridad
-severity = 3
-theme = security + core
-
-# Exigir open de tres argumentos
-[InputOutput::RequireThreeArgOpen]
-severity = 5
-
-# Exigir llamadas al sistema comprobadas
-[InputOutput::RequireCheckedSyscalls]
-functions = :builtins
-severity = 4
-
-# Prohibir eval de string
-[BuiltinFunctions::ProhibitStringyEval]
-severity = 5
-
-# Prohibir operadores de backtick
-[InputOutput::ProhibitBacktickOperators]
-severity = 4
-
-# Exigir comprobación de taint en CGI
-[Modules::RequireTaintChecking]
-severity = 5
-
-# Prohibir open de dos argumentos
-[InputOutput::ProhibitTwoArgOpen]
-severity = 5
-
-# Prohibir filehandles de palabra desnuda
-[InputOutput::ProhibitBarewordFileHandles]
-severity = 5
-```
-
-### Ejecutar perlcritic
-
-```bash
-# Revisar un archivo
-perlcritic --severity 3 --theme security lib/MyApp/Handler.pm
-
-# Revisar el proyecto completo
-perlcritic --severity 3 --theme security lib/
-
-# Integración en CI
-perlcritic --severity 4 --theme security --quiet lib/ || exit 1
-```
-
-## Lista de verificación rápida de seguridad
-
-| Comprobación | Qué verificar |
-|---|---|
-| Modo taint | Flag `-T` en scripts CGI/web |
-| Validación de entrada | Patrones de lista de permitidos, límites de longitud |
-| Operaciones con archivos | Open de tres argumentos, comprobaciones de path traversal |
-| Ejecución de procesos | system en forma de lista, sin interpolación de shell |
-| Consultas SQL | Placeholders de DBI, nunca interpolar |
-| Salida HTML | `encode_entities()`, auto-escapado de plantillas |
-| Tokens CSRF | Generados y verificados en peticiones que cambian estado |
-| Configuración de sesión | Cookies Secure, HttpOnly, SameSite |
-| Cabeceras HTTP | CSP, X-Frame-Options, HSTS |
-| Dependencias | Versiones fijadas, módulos auditados |
-| Seguridad de regex | Sin cuantificadores anidados, patrones anclados |
-| Mensajes de error | Sin stack traces ni rutas filtradas a los usuarios |
-
-## Antipatrones
-
-```perl
-# 1. Open de dos argumentos con datos de usuario (inyección de comandos)
-open my $fh, $user_input;               # Vulnerabilidad CRÍTICA
-
-# 2. system en forma de string (inyección de shell)
-system("convert $user_file output.png"); # Vulnerabilidad CRÍTICA
-
-# 3. Interpolación de strings en SQL
-$dbh->do("DELETE FROM users WHERE id = $id");  # SQLi
-
-# 4. eval con entrada de usuario (inyección de código)
-eval $user_code;                         # Ejecución remota de código
-
-# 5. Confiar en $ENV sin sanear
-my $path = $ENV{UPLOAD_DIR};             # Podría estar manipulado
-system("ls $path");                      # Doble vulnerabilidad
-
-# 6. Desactivar el taint sin validar
-($input) = $input =~ /(.*)/s;           # Destaintado perezoso — anula el propósito
-
-# 7. Datos de usuario crudos en HTML
-print "<div>¡Bienvenido, $username!</div>";  # XSS
-
-# 8. Redirecciones sin validar
-print $cgi->redirect($user_url);         # Redirección abierta
-```
-
-**Recuerda**: la flexibilidad de Perl es poderosa pero exige disciplina. Usa el modo taint para el código expuesto a la web, valida toda entrada con listas de permitidos, usa placeholders de DBI en cada consulta y codifica toda salida según su contexto. Defensa en profundidad — nunca dependas de una sola capa.
-
-## Skills relacionadas
-
-- `patrones-perl`
-- `testing-perl`