a2host/docs/04-security/security-model.md

275 lines
14 KiB
Markdown

# Modelo de Seguridad y Mitigación de Amenazas
## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`)
**Estándar:** OWASP Application Security Verification Standard (ASVS) / STRIDE Threat Modeling
**Proyecto:** a2host — Lightweight Subdomain Orchestrator
**Versión:** 1.0.0
**Fecha de Emisión:** 19 de Noviembre de 2026
**Clasificación:** Documento de Seguridad Crítica
**Autor:** Especialista en Ciberseguridad y Redacción Técnica (@docs)
---
### Registro de Revisiones
| Versión | Fecha | Autor | Justificación y Cambios |
| :---: | :---: | :---: | :--- |
| `1.0.0` | 2026-11-19 | Arquitecto de Seguridad (@docs) | Modelo integral de seguridad: Prevención de inyección Shell mediante `execFile`, matriz STRIDE, arquitectura SGID 2775, aislamiento de sudoers y criptografía scrypt/HMAC. |
---
## 1. Introducción y Filosofía de Defensa en Profundidad
El sistema `a2host` ejecuta operaciones con privilegios elevados en el sistema operativo anfitrión (Ubuntu Server) para configurar servidores web, recargar servicios del sistema y asignar permisos de archivos. En un servidor con recursos limitados (1 GB de RAM) y compartición de servicios críticos (Gitea, bases de datos), una brecha de seguridad podría resultar en compromiso total del host (*Remote Code Execution* o *Privilege Escalation*).
Para mitigar estos riesgos de forma absoluta, `a2host` implementa una estrategia de **Defensa en Profundidad (*Defense in Depth*)** estructurada en cinco anillos concéntricos:
```mermaid
flowchart TD
subgraph Anillo1["Anillo 1: Perímetro de Red y Autenticación"]
Auth["HMAC Cookie HttpOnly + Rate Limiting + scrypt Hash"]
end
subgraph Anillo2["Anillo 2: Validación e Inmunización de Entrada"]
Regex["Regex Estricto: ^[a-z0-9-]+$ (Max 63 chars)"]
PortCheck["Bloqueo de Puertos Reservados (22, 80, 443, 3000...)"]
end
subgraph Anillo3["Anillo 3: Ejecución Aislada de Procesos"]
ExecFile["execFile / spawn (Sin subshell /bin/sh)"]
ArgVector["Vector de Argumentos Estáticos: ['a2ensite', file]"]
end
subgraph Anillo4["Anillo 4: Aislamiento del Sistema de Archivos"]
SGID["SGID 2775 en /var/www/ + ggc:www-data"]
PathSan["Path.resolve + Basename (Anti-Traversal)"]
ProtectedSites["Protección Inmutable: git.conf, 000-default.conf"]
end
subgraph Anillo5["Anillo 5: Principio de Mínimo Privilegio en SO"]
Sudoers["/etc/sudoers.d/ggc restringido a comandos exactos"]
PM2Cap["PM2 memory cap: 120MB"]
end
Anillo1 --> Anillo2
Anillo2 --> Anillo3
Anillo3 --> Anillo4
Anillo4 --> Anillo5
```
---
## 2. Análisis de Amenazas (Matriz STRIDE)
| Categoría STRIDE | Amenaza Identificada | Vector de Ataque | Mitigación Implementada en `a2host` | Severidad Residual |
| :--- | :--- | :--- | :--- | :---: |
| **Spoofing** (Suplantación) | Un atacante se hace pasar por el administrador para manipular subdominios. | Robo de cookie de sesión o intercepción de credenciales. | Cookies `HttpOnly`, `SameSite=Strict`, firma HMAC-SHA256, hashing robusto con `scrypt` y TLS forzado en proxy. | **Baja** |
| **Tampering** (Manipulación) | Modificación indebida de `git.conf` o inyección de directivas maliciosas de Apache. | Petición manipulada al endpoint de guardado o inyección en archivo `.conf`. | Lista negra de protección inmutable (`PROTECTED_SITES`), validación estricta de sintaxis en `configtest` y plantillas parametrizadas sin interpolación libre. | **Baja** |
| **Repudiation** (Repudio) | Un operador niega haber eliminado un subdominio o purgado archivos. | Falta de trazabilidad en las acciones de administración. | Registro estructurado de auditoría en `stdout` / logs de PM2 con marca temporal, IP origen, usuario y acción. | **Baja** |
| **Information Disclosure** (Fuga de Info) | Fuga de rutas internas del servidor o dumps de memoria en respuestas de error. | Provocación de excepciones no capturadas. | Formato RFC 7807 sanitizado, supresión de stack traces en producción (`NODE_ENV=production`) y exclusión de hashes en respuestas JSON. | **Baja** |
| **Denial of Service** (DoS) | Saturación de memoria en VPS de 1GB o bucles de reinicio de Apache. | Inyección de configuración rota o saturación de peticiones concurrentes. | Rollback atómico instantáneo ante fallos de `configtest`, límite de memoria PM2 a 120MB y rate limiting en capa Express. | **Baja** |
| **Elevation of Privilege** (Escalada) | Ejecución arbitraria de comandos en el shell mediante el usuario `sudo`. | Inyección de comandos en nombres de subdominios (`sub; bash -i`). | **Erradicación de `/bin/sh`:** Uso exclusivo de `execFile` con argumentos vectorizados y convalidación estricta con regex. | **Nula** |
---
## 3. Prevención Absoluta de Inyección de Comandos en Shell
### 3.1 Anatomía del Riesgo: `exec()` vs `execFile()`
En entornos Node.js convencionales, el error más común al invocar utilidades del sistema es el uso de `child_process.exec()` concatenando cadenas:
```javascript
// ⚠️ VULNERABILIDAD CRÍTICA (PROHIBIDO EN a2host):
const { exec } = require('child_process');
// Si subdomain = "test; rm -rf / #"
exec(`sudo a2ensite ${subdomain}.conf`);
// El shell (/bin/sh) ejecuta dos comandos independientes con permisos sudo.
```
### 3.2 Solución Implementada: Vectorización Directa de Syscalls
`a2host` prohíbe el uso de `child_process.exec()`. Todas las operaciones se realizan mediante `child_process.execFile` o `child_process.spawn`:
```javascript
// ✅ IMPLEMENTACIÓN SEGURA Y MANDATORIA EN a2host:
const { execFile } = require('child_process');
function runSafeCommand(binary, args) {
return new Promise((resolve, reject) => {
// Invoca directamente la syscall execve() sin intermediación de /bin/sh
execFile(binary, args, { timeout: 10000 }, (error, stdout, stderr) => {
if (error) {
return reject({ error, stdout, stderr });
}
resolve({ stdout, stderr });
});
});
}
// Ejemplo de llamada segura:
// Invocación: ['a2ensite', 'test; rm -rf / #.conf']
// El kernel busca literalmente un archivo con ese nombre, neutralizando la inyección.
await runSafeCommand('sudo', ['a2ensite', `${safeSubdomain}.conf`]);
```
### 3.3 Regla de Validación de Expresión Regular
Como primera línea de defensa antes de invocar cualquier controlador del sistema operativo, el nombre del subdominio debe superar la validación léxica:
$$\text{Regex} = \wedge [a-z0-9-]+ \$ \quad (\text{longitud entre } 1 \text{ y } 63 \text{ caracteres})$$
```javascript
const SUBDOMAIN_REGEX = /^[a-z0-9-]+$/;
function validateSubdomainName(name) {
if (!name || typeof name !== 'string') {
throw new Error('El nombre de subdominio es obligatorio y debe ser texto');
}
if (name.length < 1 || name.length > 63) {
throw new Error('La longitud del subdominio debe estar entre 1 y 63 caracteres');
}
if (!SUBDOMAIN_REGEX.test(name)) {
throw new Error('El subdominio solo puede contener letras minúsculas, números y guiones');
}
if (name.startsWith('-') || name.endsWith('-')) {
throw new Error('El subdominio no puede comenzar ni terminar con un guión');
}
}
```
---
## 4. Arquitectura de Permisos UNIX y Bit SGID
### 4.1 Problema Operativo en Servidores Web Compartidos
Cuando un desarrollador despliega código mediante Git, SSH o SFTP bajo el usuario operativo `ggc`, los nuevos ficheros se crean por defecto con permisos del usuario creador (`ggc:ggc` y `umask 022`). Esto genera conflictos de lectura/escritura cuando el proceso de Apache (`www-data:www-data`) intenta leer archivos estáticos o ejecutar scripts dinámicos, obligando a los operadores a ejecutar `sudo chown` constantemente.
### 4.2 Solución Estándar: Permiso SGID (Set Group ID) `2775`
Para erradicar este problema y garantizar que el usuario `ggc` pueda gestionar archivos libremente sin requerir privilegios de superusuario, `a2host` aprovisiona los directorios web aplicando el bit especial **SGID**:
```mermaid
flowchart TD
Dir["Directorio Padre: /var/www/<subdominio><br/>Permisos: 2775 (drwxrwsr-x)<br/>Propietario: ggc:www-data"]
GitUser["Usuario 'ggc' despliega vía Git / SFTP"] -->|"Crea archivo 'app.js'"| NewFile["Archivo Creado: app.js"]
Dir -->|"Hereda automáticamente el grupo padre"| NewFile
NewFile -->|"Resultado en Disco:"| FinalPerms["Permisos: -rw-rw-r--<br/>Propietario: ggc:www-data"]
FinalPerms -->|"Lectura y Ejecución Directa"| ApacheDaemon["Apache2 (Usuario: www-data)"]
```
#### Desglose Octal de Permisos `2775`:
- `2` (SGID): Obliga a todo archivo o subcarpeta creada dentro del directorio a heredar automáticamente el grupo `www-data`.
- `7` (Propietario `ggc`): Lectura, escritura y ejecución (`rwx`).
- `7` (Grupo `www-data`): Lectura, escritura y ejecución (`rwx`).
- `5` (Otros): Lectura y ejecución (`r-x`).
#### Comando Ejecutado en el Aprovisionamiento:
```bash
sudo chown -R ggc:www-data /var/www/<subdominio>
sudo chmod -R 2775 /var/www/<subdominio>
```
---
## 5. Principio de Mínimo Privilegio en `sudoers`
El usuario `ggc` ejecuta el backend `a2host`. Para cumplir con el principio de mínimo privilegio, el archivo `/etc/sudoers.d/ggc` debe limitar la ejecución sin contraseña (`NOPASSWD`) estrictamente a los binarios requeridos por el orquestador:
```sudoers
# Archivo: /etc/sudoers.d/ggc
# Configuración estricta de permisos NOPASSWD para a2host
ggc ALL=(ALL) NOPASSWD: /usr/sbin/a2ensite
ggc ALL=(ALL) NOPASSWD: /usr/sbin/a2dissite
ggc ALL=(ALL) NOPASSWD: /usr/sbin/apache2ctl configtest
ggc ALL=(ALL) NOPASSWD: /bin/systemctl reload apache2
ggc ALL=(ALL) NOPASSWD: /bin/chown -R ggc\:www-data /var/www/*
ggc ALL=(ALL) NOPASSWD: /bin/chmod -R 2775 /var/www/*
```
> **Aislamiento:** El usuario `ggc` no requiere acceso de superusuario global sin contraseña; únicamente a las primitivas necesarias para la gestión de Apache.
---
## 6. Inmutabilidad de Sitios Críticos del Sistema
Para evitar la interrupción de servicios vitales que ya residen en el servidor (como el servidor Git institucional en `git.conf` o el host predeterminado de Apache en `000-default.conf`), el sistema implementa una lista de exclusión inmutable.
```javascript
const PROTECTED_SITES = new Set(
(process.env.PROTECTED_SITES || '000-default.conf,default-ssl.conf,git.conf')
.split(',')
.map(s => s.trim().toLowerCase())
);
function assertNotProtected(confFileName) {
const normalized = confFileName.endsWith('.conf') ? confFileName : `${confFileName}.conf`;
if (PROTECTED_SITES.has(normalized.toLowerCase())) {
const error = new Error(`El sitio '${confFileName}' es crítico para el sistema y no puede modificarse ni eliminarse.`);
error.status = 403;
error.code = 'SITE_PROTECTED';
throw error;
}
}
```
Toda petición de `toggle`, `update` o `delete` sobre estos sitios es interceptada de forma inmediata y rechazada con código `403 Forbidden`.
---
## 7. Criptografía, Gestión de Sesiones y Almacenamiento Seguro
### 7.1 Algoritmo de Hashing: `scrypt`
A diferencia de `md5` o `sha256` (vulnerables a ataques de fuerza bruta mediante GPU), `a2host` utiliza la función estándar `crypto.scrypt` de Node.js:
- **Factor de Costo ($N$):** 16384 (Memoria intensiva).
- **Tamaño de Bloque ($r$):** 8.
- **Paralelismo ($p$):** 1.
- **Sal Aleatoria:** 16 bytes generados mediante `crypto.randomBytes(16)`.
- **Longitud de Clave:** 64 bytes.
```javascript
const crypto = require('crypto');
const { promisify } = require('util');
const scrypt = promisify(crypto.scrypt);
async function hashPassword(password) {
const salt = crypto.randomBytes(16).toString('hex');
const derivedKey = await scrypt(password, salt, 64, { N: 16384, r: 8, p: 1 });
return `scrypt$16384$8$1$${salt}$${derivedKey.toString('hex')}`;
}
```
### 7.2 Comparación en Tiempo Constante (`timingSafeEqual`)
Para prevenir ataques de análisis de tiempo de respuesta (*timing side-channel attacks*), la verificación de hashes y firmas HMAC se realiza byte a byte sin interrupción anticipada:
```javascript
async function verifyPassword(password, storedHash) {
const [algo, N, r, p, salt, hashHex] = storedHash.split('$');
const keyBuffer = Buffer.from(hashHex, 'hex');
const derivedKey = await scrypt(password, salt, 64, {
N: parseInt(N, 10),
r: parseInt(r, 10),
p: parseInt(p, 10)
});
// timingSafeEqual garantiza tiempo constante independiente del match
return crypto.timingSafeEqual(keyBuffer, derivedKey);
}
```
### 7.3 Sesiones Criptográficas Firmadas por HMAC-SHA256
Las cookies de sesión se firman utilizando `HMAC-SHA256` con la clave secreta `SESSION_SECRET`:
- Si la cookie es alterada en el cliente, la firma no coincidirá y la petición será rechazada con `401 Unauthorized`.
- Flags mandatorios de cabecera:
```http
Set-Cookie: a2host_session=s%3A...; Path=/; HttpOnly; SameSite=Strict; Priority=High
```
- `HttpOnly`: Previene que scripts maliciosos (XSS) lean la cookie.
- `SameSite=Strict`: Previene falsificación de peticiones en sitios cruzados (CSRF).
- `Secure`: Requerido en entornos HTTPS de producción.
---
## 8. Protección contra Denegación de Servicio (DoS) y Recursos
1. **Límite de Tamaño de Payload:** Express se configura con límite estricto `express.json({ limit: '64kb' })` para evitar agotamiento de memoria ante subidas masivas de datos en el cuerpo HTTP.
2. **Rate Limiting:** Se aplica limitación de peticiones por ventana de tiempo (`express-rate-limit`):
- `/api/auth/login`: Máximo 5 intentos por cada 15 minutos por dirección IP.
- `/api/*`: Máximo 100 peticiones por minuto por cliente autenticado.
3. **Reserva Estricta de Puertos:** Bloqueo incondicional de los puertos del sistema: `22 (SSH)`, `80 (HTTP)`, `443 (HTTPS)`, `3000 (Gitea)`, `3005 (Panel a2host)`, `3306 (MySQL)`, `5101 (Servicio interno)`, `5432 (Postgres)`.