Sistema Analizador de Dependencias Multi-Lenguaje (DepAnalyzer)

Diccionario de Datos

Versión 1.0

ÍNDICE GENERAL

1. Introducción
2. Convenciones del Modelo
3. Entidades del Dominio
4. Detalle de Estructuras
5. Catálogos y Enumeraciones
6. Relaciones entre Entidades
7. Reglas de Calidad de Datos
8. Seguridad, Privacidad y Persistencia
9. Trazabilidad Técnica
10. Glosario

1. Introducción

1.1 Propósito

Este documento define los datos que utiliza DepAnalyzer para detectar proyectos, interpretar dependencias, consultar versiones y vulnerabilidades, construir grafos, generar reportes y proponer actualizaciones. Su propósito es proporcionar un vocabulario común entre requerimientos, arquitectura, implementación, pruebas y documentación.

1.2 Alcance

El diccionario cubre los modelos en memoria, valores de configuración, estructuras de reporte y datos temporales generados durante el análisis. DepAnalyzer no utiliza una base de datos relacional permanente; por ello, las entidades descritas corresponden principalmente a objetos Kotlin, documentos JSON, archivos de construcción y respuestas de APIs.

1.3 Fuentes de Datos

2. Convenciones del Modelo

• Los nombres de tipos Kotlin se expresan en PascalCase.
• Los atributos se expresan en camelCase.
• Los identificadores de catálogo se representan en UPPER_SNAKE_CASE.
• Los campos no disponibles se mantienen como nulos o valores explícitos como unknown, según el contrato del modelo.
• Las rutas deben interpretarse respecto del proyecto analizado, salvo que se indique que son absolutas.
• Las fechas y horas intercambiadas como texto deben emplear ISO 8601.
• Los puntajes CVSS se representan como números decimales entre 0.0 y 10.0.
• Las coordenadas de paquetes deben conservar el ecosistema para evitar colisiones entre Maven, npm y PyPI.

3. Entidades del Dominio

4. Detalle de Estructuras

4.1 Proyecto Detectado

4.2 Dependencia

La identidad lógica se obtiene combinando ecosistema y coordenada. En Maven se utiliza group:artifact:version; en npm y PyPI se utiliza name:version, conservando siempre el ecosistema.

4.3 Vulnerabilidad

4.4 Reporte de Dependencias

4.5 Grafo y Cadena Vulnerable

4.6 Sugerencia y Resultado de Actualización

4.7 Evento de Telemetría

No se deben incluir rutas personales, nombres de proyectos, contenido de archivos, tokens ni coordenadas privadas.

5. Catálogos y Enumeraciones

6. Relaciones entre Entidades

erDiagram
    PROJECT ||--o{ DEPENDENCY : contains
    DEPENDENCY ||--o{ DEPENDENCY : requires
    DEPENDENCY ||--o{ VULNERABILITY : affected_by
    PROJECT ||--|| REPORT : produces
    REPORT ||--o{ DEPENDENCY : classifies
    REPORT ||--o{ VULNERABILITY_CHAIN : includes
    VULNERABILITY_CHAIN }o--|| DEPENDENCY : targets
    DEPENDENCY ||--o{ UPDATE_SUGGESTION : generates
    UPDATE_SUGGESTION ||--o| UPDATE_RESULT : produces
    UPDATE_RESULT ||--o| BACKUP : references

La relación recursiva entre dependencias representa el grafo transitivo. Un reporte puede contener el mismo componente en diferentes vistas, pero debe evitar duplicar hallazgos equivalentes dentro de una misma clasificación.

7. Reglas de Calidad de Datos

1. Toda dependencia debe conservar su ecosistema y una coordenada identificable.
2. Una versión no resuelta debe registrarse como ausencia conocida y no provocar la pérdida del resto del reporte.
3. Los valores de severidad deben normalizarse antes de ordenar o filtrar hallazgos.
4. Las listas JSON deben serializarse como arreglos vacíos cuando no existan resultados, no como texto descriptivo.
5. Los errores de una fuente externa deben conservarse como advertencias sin inventar vulnerabilidades.
6. Las URLs de repositorios deben validarse antes de utilizar credenciales.
7. Una cadena vulnerable debe comenzar en una dependencia directa y terminar en el componente afectado.
8. Las sugerencias de actualización deben incluir versión actual, versión objetivo y razón.
9. Un resultado aplicado debe referenciar el respaldo creado o explicar por qué no fue necesario.
10. Los nombres de campos públicos del JSON deben permanecer estables o versionarse cuando exista un cambio incompatible.

8. Seguridad, Privacidad y Persistencia

DepAnalyzer procesa la mayoría de datos en memoria. Los archivos persistentes se limitan a reportes solicitados, respaldos de actualización, artefactos de pruebas y documentación. Los tokens se leen durante la ejecución y no forman parte del modelo de reporte.

• Las credenciales solo se envían por HTTPS a hosts incluidos en DEPANALYZER_TRUSTED_CREDENTIAL_HOSTS.
• Los reportes no deben contener tokens, contraseñas ni cabeceras de autenticación.
• La telemetría es anónima, puede desactivarse y no debe incluir contenido del proyecto.
• Los backups deben ubicarse junto al archivo modificado o en la ruta definida por el actualizador.
• Los datos obtenidos desde APIs externas se consideran no confiables y deben validarse antes de mostrarse o serializarse.

9. Trazabilidad Técnica

10. Glosario