theus-cli 0.2.83 → 0.2.84

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

@@ -1,474 +0,0 @@
----
-name: seguridad-quarkus
-description: Buenas prácticas de seguridad en Quarkus para autenticación, autorización, JWT/OIDC, RBAC, validación de entrada, CSRF, gestión de secretos y seguridad de dependencias.
----
-
-# Revisión de seguridad en Quarkus
-
-Buenas prácticas para asegurar aplicaciones Quarkus con autenticación, autorización y validación de entrada.
-
-## Cuándo usarla
-
-- Al añadir autenticación (JWT, OIDC, Basic Auth)
-- Al implementar autorización con `@RolesAllowed` o `SecurityIdentity`
-- Al validar entrada de usuario (Bean Validation, validadores personalizados)
-- Al configurar CORS o cabeceras de seguridad
-- Al gestionar secretos (Vault, variables de entorno, config sources)
-- Al añadir rate limiting o protección contra fuerza bruta
-- Al escanear dependencias en busca de CVEs
-- Al trabajar con MicroProfile JWT o SmallRye JWT
-
-## Autenticación
-
-### Autenticación con JWT
-
-```java
-// Recurso protegido con JWT
-@Path("/api/protected")
-@Authenticated
-public class ProtectedResource {
-
-  @Inject
-  JsonWebToken jwt;
-
-  @Inject
-  SecurityIdentity securityIdentity;
-
-  @GET
-  public Response getData() {
-    String username = jwt.getName();
-    Set<String> roles = jwt.getGroups();
-    return Response.ok(Map.of(
-        "username", username,
-        "roles", roles,
-        "principal", securityIdentity.getPrincipal().getName()
-    )).build();
-  }
-}
-```
-
-Configuración (application.properties):
-```properties
-mp.jwt.verify.publickey.location=publicKey.pem
-mp.jwt.verify.issuer=https://auth.example.com
-
-# OIDC
-quarkus.oidc.auth-server-url=https://auth.example.com/realms/myrealm
-quarkus.oidc.client-id=backend-service
-quarkus.oidc.credentials.secret=${OIDC_SECRET}
-```
-
-### Filtro de autenticación personalizado
-
-```java
-@Provider
-@Priority(Priorities.AUTHENTICATION)
-public class CustomAuthFilter implements ContainerRequestFilter {
-
-  @Inject
-  SecurityIdentity identity;
-
-  @Override
-  public void filter(ContainerRequestContext requestContext) {
-    String authHeader = requestContext.getHeaderString(HttpHeaders.AUTHORIZATION);
-
-    // Rechaza de inmediato si la cabecera está ausente o mal formada
-    if (authHeader == null || !authHeader.startsWith("Bearer ")) {
-      requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
-      return;
-    }
-
-    String token = authHeader.substring(7);
-    if (!validateToken(token)) {
-      requestContext.abortWith(Response.status(Response.Status.UNAUTHORIZED).build());
-    }
-  }
-
-  private boolean validateToken(String token) {
-    // Lógica de validación del token
-    return true;
-  }
-}
-```
-
-## Autorización
-
-### Control de acceso basado en roles (RBAC)
-
-```java
-@Path("/api/admin")
-@RolesAllowed("ADMIN")
-public class AdminResource {
-
-  @GET
-  @Path("/users")
-  public List<UserDto> listUsers() {
-    return userService.findAll();
-  }
-
-  @DELETE
-  @Path("/users/{id}")
-  @RolesAllowed({"ADMIN", "SUPER_ADMIN"})
-  public Response deleteUser(@PathParam("id") Long id) {
-    userService.delete(id);
-    return Response.noContent().build();
-  }
-}
-
-@Path("/api/users")
-public class UserResource {
-
-  @Inject
-  SecurityIdentity securityIdentity;
-
-  @GET
-  @Path("/{id}")
-  @RolesAllowed("USER")
-  public Response getUser(@PathParam("id") Long id) {
-    // Verifica la propiedad del recurso
-    if (!securityIdentity.hasRole("ADMIN") &&
-        !isOwner(id, securityIdentity.getPrincipal().getName())) {
-      return Response.status(Response.Status.FORBIDDEN).build();
-    }
-    return Response.ok(userService.findById(id)).build();
-  }
-
-  private boolean isOwner(Long userId, String username) {
-    return userService.isOwner(userId, username);
-  }
-}
-```
-
-### Seguridad programática
-
-```java
-@ApplicationScoped
-public class SecurityService {
-
-  @Inject
-  SecurityIdentity securityIdentity;
-
-  public boolean canAccessResource(Long resourceId) {
-    if (securityIdentity.isAnonymous()) {
-      return false;
-    }
-
-    if (securityIdentity.hasRole("ADMIN")) {
-      return true;
-    }
-
-    String userId = securityIdentity.getPrincipal().getName();
-    return resourceRepository.isOwner(resourceId, userId);
-  }
-}
-```
-
-## Validación de entrada
-
-### Bean Validation
-
-```java
-// MAL: sin validación
-@POST
-public Response createUser(UserDto dto) {
-  return Response.ok(userService.create(dto)).build();
-}
-
-// BIEN: DTO validado
-public record CreateUserDto(
-    @NotBlank @Size(max = 100) String name,
-    @NotBlank @Email String email,
-    @NotNull @Min(18) @Max(150) Integer age,
-    @Pattern(regexp = "^\\+?[1-9]\\d{1,14}$") String phone
-) {}
-
-@POST
-@Path("/users")
-public Response createUser(@Valid CreateUserDto dto) {
-  User user = userService.create(dto);
-  return Response.status(Response.Status.CREATED).entity(user).build();
-}
-```
-
-### Validadores personalizados
-
-```java
-@Target({ElementType.FIELD, ElementType.PARAMETER})
-@Retention(RetentionPolicy.RUNTIME)
-@Constraint(validatedBy = UsernameValidator.class)
-public @interface ValidUsername {
-  String message() default "Formato de nombre de usuario inválido";
-  Class<?>[] groups() default {};
-  Class<? extends Payload>[] payload() default {};
-}
-
-public class UsernameValidator implements ConstraintValidator<ValidUsername, String> {
-  @Override
-  public boolean isValid(String value, ConstraintValidatorContext context) {
-    if (value == null) return false;
-    return value.matches("^[a-zA-Z0-9_-]{3,20}$");
-  }
-}
-
-// Uso
-public record CreateUserDto(
-    @ValidUsername String username,
-    @NotBlank @Email String email
-) {}
-```
-
-## Prevención de inyección SQL
-
-### Panache Active Record (seguro por defecto)
-
-```java
-// BIEN: consultas parametrizadas con Panache
-List<User> users = User.list("email = ?1 and active = ?2", email, true);
-
-Optional<User> user = User.find("username", username).firstResultOptional();
-
-// BIEN: parámetros con nombre
-List<User> users = User.list("email = :email and age > :minAge",
-    Parameters.with("email", email).and("minAge", 18));
-```
-
-### Consultas nativas (usa parámetros)
-
-```java
-// MAL: concatenación de strings
-@Query(value = "SELECT * FROM users WHERE name = '" + name + "'", nativeQuery = true)
-
-// BIEN: consulta nativa parametrizada
-@Entity
-public class User extends PanacheEntity {
-  public static List<User> findByEmailNative(String email) {
-    return getEntityManager()
-        .createNativeQuery("SELECT * FROM users WHERE email = :email", User.class)
-        .setParameter("email", email)
-        .getResultList();
-  }
-}
-```
-
-## Hashing de contraseñas
-
-```java
-@ApplicationScoped
-public class PasswordService {
-
-  public String hash(String plainPassword) {
-    return BcryptUtil.bcryptHash(plainPassword);
-  }
-
-  public boolean verify(String plainPassword, String hashedPassword) {
-    return BcryptUtil.matches(plainPassword, hashedPassword);
-  }
-}
-
-// En el servicio
-@ApplicationScoped
-public class UserService {
-  @Inject
-  PasswordService passwordService;
-
-  @Transactional
-  public User register(CreateUserDto dto) {
-    String hashedPassword = passwordService.hash(dto.password());
-    User user = new User();
-    user.email = dto.email();
-    user.password = hashedPassword;
-    user.persist();
-    return user;
-  }
-
-  public boolean authenticate(String email, String password) {
-    return User.find("email", email)
-        .firstResultOptional()
-        .map(u -> passwordService.verify(password, u.password))
-        .orElse(false);
-  }
-}
-```
-
-## Configuración de CORS
-
-```properties
-# application.properties
-quarkus.http.cors=true
-quarkus.http.cors.origins=https://app.example.com,https://admin.example.com
-quarkus.http.cors.methods=GET,POST,PUT,DELETE
-quarkus.http.cors.headers=accept,authorization,content-type,x-requested-with
-quarkus.http.cors.exposed-headers=Content-Disposition
-quarkus.http.cors.access-control-max-age=24H
-quarkus.http.cors.access-control-allow-credentials=true
-```
-
-## Gestión de secretos
-
-```properties
-# application.properties - AQUÍ NO VAN SECRETOS
-
-# Usa variables de entorno
-quarkus.datasource.username=${DB_USER}
-quarkus.datasource.password=${DB_PASSWORD}
-quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
-
-# O usa Vault
-quarkus.vault.url=https://vault.example.com
-quarkus.vault.authentication.kubernetes.role=my-role
-```
-
-### Integración con HashiCorp Vault
-
-```java
-@ApplicationScoped
-public class SecretService {
-
-  @ConfigProperty(name = "api-key")
-  String apiKey; // Obtenida desde Vault
-
-  public String getSecret(String key) {
-    return ConfigProvider.getConfig().getValue(key, String.class);
-  }
-}
-```
-
-## Rate limiting
-
-**Nota de seguridad**: nunca uses `X-Forwarded-For` directamente — los clientes pueden falsificarla.
-Usa la dirección remota real de la petición del servlet, o una identidad autenticada
-(API key, subject del JWT) cuando esté disponible.
-
-```java
-@ApplicationScoped
-public class RateLimitFilter implements ContainerRequestFilter {
-  private final Map<String, RateLimiter> limiters = new ConcurrentHashMap<>();
-
-  @Inject
-  HttpServletRequest servletRequest;
-
-  @Override
-  public void filter(ContainerRequestContext requestContext) {
-    String clientId = getClientIdentifier();
-    RateLimiter limiter = limiters.computeIfAbsent(clientId,
-        k -> RateLimiter.create(100.0)); // 100 peticiones por segundo
-
-    if (!limiter.tryAcquire()) {
-      requestContext.abortWith(
-          Response.status(429)
-              .entity(Map.of("error", "Demasiadas peticiones"))
-              .build()
-      );
-    }
-  }
-
-  private String getClientIdentifier() {
-    // Usa la dirección remota que proporciona el contenedor (no X-Forwarded-For).
-    // Si estás detrás de un proxy de confianza, configura
-    // quarkus.http.proxy.proxy-address-forwarding=true para que
-    // getRemoteAddr() devuelva la IP real del cliente.
-    return servletRequest.getRemoteAddr();
-  }
-}
-```
-
-## Cabeceras de seguridad
-
-```java
-@Provider
-public class SecurityHeadersFilter implements ContainerResponseFilter {
-
-  @Override
-  public void filter(ContainerRequestContext request, ContainerResponseContext response) {
-    MultivaluedMap<String, Object> headers = response.getHeaders();
-
-    // Previene clickjacking
-    headers.putSingle("X-Frame-Options", "DENY");
-
-    // Protección XSS
-    headers.putSingle("X-Content-Type-Options", "nosniff");
-    headers.putSingle("X-XSS-Protection", "1; mode=block");
-
-    // HSTS
-    headers.putSingle("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
-
-    // CSP — evita 'unsafe-inline' en script-src porque anula la protección XSS;
-    // usa nonces o hashes. 'unsafe-inline' en style-src es aceptable cuando
-    // frameworks CSS lo requieren, pero prefiere nonces siempre que sea posible.
-    headers.putSingle("Content-Security-Policy",
-        "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'");
-  }
-}
-```
-
-## Registro de auditoría
-
-```java
-@ApplicationScoped
-public class AuditService {
-  private static final Logger LOG = Logger.getLogger(AuditService.class);
-
-  @Inject
-  SecurityIdentity securityIdentity;
-
-  public void logAccess(String resource, String action) {
-    String user = securityIdentity.isAnonymous()
-        ? "anonymous"
-        : securityIdentity.getPrincipal().getName();
-
-    LOG.infof("AUDIT: user=%s action=%s resource=%s timestamp=%s",
-        user, action, resource, Instant.now());
-  }
-}
-
-// Uso en un recurso
-@Path("/api/sensitive")
-public class SensitiveResource {
-  @Inject
-  AuditService auditService;
-
-  @GET
-  @RolesAllowed("ADMIN")
-  public Response getData() {
-    auditService.logAccess("sensitive-data", "READ");
-    return Response.ok(data).build();
-  }
-}
-```
-
-## Escaneo de seguridad de dependencias
-
-```bash
-# Maven
-mvn org.owasp:dependency-check-maven:check
-
-# Gradle
-./gradlew dependencyCheckAnalyze
-
-# Revisar extensiones de Quarkus
-quarkus extension list --installable
-```
-
-## Buenas prácticas
-
-- Usa siempre HTTPS en producción
-- Habilita JWT u OIDC para autenticación sin estado
-- Usa `@RolesAllowed` para autorización declarativa
-- Valida toda la entrada con Bean Validation
-- Hashea contraseñas con BCrypt (nunca en texto plano)
-- Guarda los secretos en Vault o variables de entorno
-- Usa consultas parametrizadas para prevenir inyección SQL
-- Añade cabeceras de seguridad a todas las respuestas
-- Implementa rate limiting en endpoints públicos
-- Audita las operaciones sensibles
-- Mantén las dependencias actualizadas y escanea CVEs
-- Usa `SecurityIdentity` para comprobaciones programáticas
-- Configura políticas CORS apropiadas
-- Prueba las rutas de autenticación y autorización
-
-## Skills relacionadas
-
-- `patrones-quarkus`
-- `tdd-quarkus`
-- `verificacion-quarkus`
-- `revision-seguridad`