24. Documentación de seguridad: permisos, amenazas, controles y datos sensibles
24.1 Introducción
La seguridad del software no depende solo de mecanismos técnicos. También requiere documentación clara sobre permisos, amenazas, controles, datos sensibles, responsabilidades y procedimientos. Si la información de seguridad no está documentada, el equipo puede aplicar controles de forma inconsistente o desconocer riesgos importantes.
La documentación de seguridad ayuda a construir, operar y mantener el sistema con conciencia de riesgos. Permite saber quién puede hacer qué, qué datos deben protegerse, qué amenazas se consideran, qué controles existen y cómo responder ante eventos de seguridad.
En este tema veremos cómo documentar autenticación, autorización, roles, datos sensibles, controles, amenazas, auditoría, configuración segura y respuesta ante incidentes.
24.2 Qué es documentación de seguridad
La documentación de seguridad describe decisiones, reglas, controles y procedimientos relacionados con la protección del sistema y sus datos. Puede estar dirigida a desarrollo, operación, seguridad, soporte, auditoría o responsables del producto.
Debe ser precisa y cuidadosa. Una documentación de seguridad incompleta puede dejar huecos. Una documentación demasiado expuesta puede revelar información sensible. Por eso, también es importante definir quién puede acceder a cada documento.
24.3 Elementos de seguridad documentados
La imagen muestra los elementos principales de la documentación de seguridad: autenticación, autorización, roles, permisos, amenazas, controles, datos sensibles, auditoría, configuración segura y respuesta ante incidentes.
24.4 Autenticación
La autenticación permite comprobar la identidad de un usuario, sistema o servicio. La documentación debe indicar qué mecanismos se usan: usuario y contraseña, tokens, sesiones, certificados, autenticación multifactor, proveedor externo o integración corporativa.
También conviene documentar reglas como duración de sesión, renovación de token, bloqueo por intentos fallidos, recuperación de cuenta y políticas de contraseña si aplican.
24.5 Autorización
La autorización define qué puede hacer una identidad autenticada. La documentación debe explicar roles, permisos, alcances, restricciones por recurso y reglas especiales.
Por ejemplo, un paciente puede consultar sus propios turnos, pero no los de otros pacientes. Un administrador puede modificar agendas. Un profesional puede ver su agenda, pero no cambiar permisos de usuarios.
Documentar autorización evita inconsistencias entre interfaz, API, servicios y base de datos.
24.6 Roles y permisos
Los roles agrupan permisos. Documentarlos permite entender qué acciones están permitidas para cada perfil. Una matriz de permisos es útil cuando existen varios roles y muchas operaciones.
La matriz debe mantenerse actualizada. Si se agrega una funcionalidad y no se define quién puede usarla, pueden aparecer accesos indebidos o bloqueos injustificados.
24.7 Matriz de permisos
| Acción | Paciente | Profesional | Administrador |
|---|---|---|---|
| Consultar turnos propios | Sí | Sí | Sí |
| Reservar turno | Sí | No | Sí |
| Modificar agenda | No | Limitado | Sí |
| Administrar usuarios | No | No | Sí |
24.8 Datos sensibles
Los datos sensibles requieren protección especial. Pueden incluir información personal, datos médicos, credenciales, tokens, documentos, direcciones, teléfonos, datos financieros o cualquier información que pueda causar daño si se expone.
La documentación debe identificar qué datos son sensibles, dónde se almacenan, quién puede acceder, cómo se protegen, cuánto tiempo se conservan y cómo se eliminan o anonimizan.
No se deben incluir datos reales sensibles en ejemplos, capturas o documentos accesibles sin control.
24.9 Amenazas
Documentar amenazas ayuda a comprender riesgos. Una amenaza puede ser acceso no autorizado, fuga de datos, manipulación de información, denegación de servicio, robo de credenciales, uso indebido de APIs o configuración insegura.
No siempre se necesita un análisis formal complejo, pero sí conviene registrar amenazas relevantes para funcionalidades críticas. Esto ayuda a justificar controles y pruebas de seguridad.
24.10 Controles de seguridad
Los controles son medidas que reducen riesgos. Pueden ser autenticación, autorización, cifrado, validación de entradas, registros de auditoría, límites de uso, revisión de dependencias, configuración segura, respaldos, monitoreo o segregación de ambientes.
La documentación debe indicar qué control existe, qué riesgo reduce, dónde se aplica y cómo se verifica. Un control no documentado puede ser omitido o duplicado de forma inconsistente.
24.11 Validación de entradas
La validación de entradas evita que el sistema procese datos inválidos, maliciosos o inesperados. La documentación debe indicar reglas de validación importantes, límites, formatos, campos obligatorios y manejo de errores.
Esto se relaciona con seguridad porque muchas vulnerabilidades comienzan con entradas no controladas. También se relaciona con calidad funcional, porque los usuarios deben recibir mensajes claros.
24.12 Auditoría
La auditoría registra eventos relevantes: inicios de sesión, cambios de permisos, modificaciones de datos sensibles, acciones administrativas, fallos de autenticación o accesos a información crítica.
La documentación debe indicar qué eventos se registran, dónde se consultan, quién puede acceder, cuánto tiempo se conservan y cómo se protegen contra alteración.
24.13 Configuración segura
Muchas fallas de seguridad provienen de configuración incorrecta. La documentación debe indicar configuraciones seguras por ambiente: manejo de secretos, certificados, cabeceras, permisos, acceso a bases de datos, claves y servicios externos.
También debe indicar configuraciones prohibidas en producción, como modo de depuración habilitado, credenciales por defecto o exposición de herramientas internas.
24.14 Respuesta ante incidentes de seguridad
La documentación debe indicar qué hacer ante un incidente de seguridad: preservar evidencia, contener el problema, escalar, comunicar, revisar accesos, rotar credenciales, analizar impacto y registrar acciones.
Estos procedimientos deben estar disponibles para quienes los necesiten, pero con control de acceso adecuado. No toda información de seguridad debe estar publicada abiertamente.
24.15 Relación con pruebas
La documentación de seguridad debe relacionarse con pruebas: pruebas de permisos, intentos de acceso no autorizado, validación de entradas, manejo de sesiones, exposición de datos y configuración segura.
Si una regla de seguridad está documentada, debería existir alguna forma de verificarla. Esto puede incluir pruebas automatizadas, revisiones, análisis estático o checklist de despliegue.
24.16 Errores frecuentes
Al documentar seguridad suelen aparecer estos errores:
- No distinguir autenticación de autorización.
- Omitir matriz de permisos o mantenerla desactualizada.
- Incluir secretos reales en documentación o ejemplos.
- No identificar datos sensibles.
- Documentar controles sin relacionarlos con amenazas.
- No indicar procedimientos ante incidentes de seguridad.
- Publicar demasiados detalles sensibles sin control de acceso.
24.17 Qué debes recordar de este tema
- La documentación de seguridad describe permisos, riesgos, controles y datos sensibles.
- Autenticación identifica; autorización define acciones permitidas.
- Una matriz de permisos ayuda a mantener coherencia entre roles y funcionalidades.
- Los datos sensibles deben identificarse y protegerse.
- Las amenazas justifican controles de seguridad.
- La auditoría permite investigar acciones relevantes.
- La documentación de seguridad debe proteger información sensible y tener acceso controlado cuando corresponda.
24.18 Conclusión
La documentación de seguridad permite aplicar controles de forma consistente y entender los riesgos del sistema. Al registrar permisos, amenazas, datos sensibles y procedimientos, el equipo puede construir y operar software con mayor responsabilidad.
En el próximo tema estudiaremos la documentación de pruebas: estrategia, casos, datos, evidencias y resultados.