Saltar al contenido principal

Capítulo II: Arquitectura, Diagramas y Diseño de Software

Este documento describe detalladamente el diseño del sistema, los flujos de datos y las decisiones tecnológicas que impulsan el funcionamiento del ecosistema TVAPyMM.

🏛️ Arquitectura del Sistema​

TVAPyMM opera bajo un diseño cliente-servidor completamente desacoplado. El frontend es una Single Page Application (SPA) enfocada en la visualización interactiva del panel de control, mientras que el backend consiste en una API REST sin estado (stateless) encargada de las orquestaciones, los análisis de seguridad y la persistencia de datos.

🔐 Flujo de Autenticación y Auto-aprovisionamiento​

TVAPyMM emplea un esquema de seguridad basado en tokens de autenticación sin estado (stateless JWT). Toda la seguridad e interceptación de recursos es gestionada por Spring Security, actuando bajo el rol de Servidor de Recursos OAuth2.

El Ciclo de Auto-aprovisionamiento Dinámico​

Para eliminar fricciones en el registro de usuarios, la plataforma implementa un ciclo automático de creación de perfiles:

  1. El usuario inicia sesión en la interfaz web de React a través del portal de inicio de sesión único de Auth0.
  2. Auth0 emite y firma un token JWT que contiene los datos del usuario (como el ID único sub, el email y el name).
  3. El frontend almacena el JWT y lo adjunta en la cabecera Authorization: Bearer <token> en cada solicitud HTTP hacia el backend.
  4. Al cargarse por primera vez, el frontend realiza una petición a GET /users/me.
  5. El backend:
    • Descarga las claves públicas del emisor y valida que la firma sea legítima, que pertenezca a la audiencia configurada (AUTH0_AUDIENCE) y que el emisor coincida (AUTH0_ISSUER_URI).
    • Extrae los campos sub (ID de usuario de Auth0), name y email del payload.
    • Consulta en PostgreSQL si existe un registro de la tabla User con ese identificador.
    • Si el usuario no existe en la base de datos local, se crea automáticamente un nuevo registro y se le asigna un UUID interno.
  6. A partir de ese momento, todas las entidades creadas (proyectos, reportes, vulnerabilidades) se asocian al UUID interno generado, garantizando un aislamiento de datos absoluto.
Seguridad y Control de Acceso Estricto

Todos los endpoints de la API (a excepción de los expuestos bajo /public/**) están protegidos. El backend realiza verificaciones estrictas de pertenencia: ningún usuario puede leer, modificar, escanear o eliminar proyectos o datos que no pertenezcan a su UUID local de usuario.

🗄️ Modelo de Datos y Entidades​

La capa de persistencia utiliza Spring Data JPA sobre una base de datos relacional PostgreSQL. A continuación se detalla el diagrama entidad-relación principal:

🪣 Diseño de Almacenamiento: Oracle Cloud vs. Servidor Local​

Cada análisis genera un reporte en formato Markdown que consolida el estado de seguridad de los proyectos web analizados. TVAPyMM cuenta con dos opciones para gestionar estos archivos, configurables dinámicamente con variables de entorno en application.properties:

1. Modo Producción: Oracle Cloud Infrastructure (OCI) Object Storage​

  • Antecedentes: En las etapas iniciales de la tesis, el portal utilizaba AWS S3. Sin embargo, para capitalizar los beneficios de infraestructura y la capa gratuita permanente (Always Free tier) de Oracle, la plataforma se migró por completo a servidores e infraestructura de Oracle Cloud. El backend aprovecha la API compatible con S3 provista por Oracle Cloud Object Storage, lo que permite reutilizar librerías cliente estándares.
  • Proceso: Al finalizar el escaneo, MarkdownReportGenerator escribe el archivo y el servicio de almacenamiento (compatible con API S3) lo sube directamente al bucket privado de Oracle Cloud empleando una ruta estructurada: reports/{projectId}/{reportId}.md.
  • Guardado: La base de datos guarda únicamente la clave o ruta del archivo (reportUrl), evitando almacenar URLs completas.
  • Descarga: Dado que los archivos en el bucket de Oracle Cloud son privados, cuando el usuario solicita descargar un reporte mediante GET /reports/{id}, el backend calcula una URL temporal prefirmada con validez de 7 días. El frontend simplemente redirige al navegador a ese enlace de descarga directo y seguro.

2. Modo Fallback (Desarrollo Local)​

  • Proceso: Al activar el parámetro de entorno APP_REPORTS_LOCAL_STORAGE=true, se ignora toda la configuración de la nube.
  • Guardado: Los archivos Markdown se graban de manera directa en el almacenamiento del sistema operativo del servidor bajo la ruta definida en app.reports.local-path (por defecto ./reports).
  • Utilidad: Esta modalidad es sumamente conveniente para trabajar sin conexión a Internet o realizar pruebas unitarias rápidas locales.