Documentación de NPQ

Este directorio contiene documentación exhaustiva de la herramienta de auditoría de seguridad NPQ (Node Package Quality).

Documentación principal

optional-features.md

Configuración y uso de las funcionalidades de seguridad opcionales, incluidas las mejoras recientes y las correcciones de errores.

age.marshall.md

Documentación detallada del componente de seguridad Age Marshall que valida la antigüedad y la madurez de los paquetes.

Documentación de funcionalidades

El directorio feature/ contiene documentación detallada para funcionalidades e implementaciones específicas:

Desarrollos recientes

• test-coverage-improvements.md - Mejoras integrales de cobertura de pruebas que aumentaron la cobertura general del 84.4% al 93.39%
• signature-verification-fix.md - Corrección crítica de errores para la verificación de firmas con rangos de versiones (p. ej., @angular/common@^20.2.4)

Funcionalidades existentes

• auto-continue.md - Documentación de la funcionalidad de continuación automática que agiliza los flujos de trabajo de instalación de paquetes
• exit-codes.md - Referencia del comportamiento de salida de los procesos npq y npq-hero
• json-output.md - Salida únicamente de auditoría, versionada y legible por máquina para CI y automatización
• malicious-package.md - Documentación de la detección de paquetes maliciosos conocidos mediante datos de Snyk/OSV
• pacote-dependency-reduction.md - Resumen de implementación de la reducción opcional de dependencias de pacote

Estándares de documentación

Estructura

• Cada funcionalidad tiene su propio archivo markdown en feature/
• Funcionalidad principal documentada en el nivel raíz de la documentación
• Detalles técnicos de implementación incluidos con ejemplos de código
• Configuración orientada al usuario documentada con ejemplos de uso

Pautas de contenido

• Resumen: Breve descripción de la funcionalidad o componente
• Diseño técnico: Detalles de arquitectura e implementación
• Ejemplos de uso: Ejemplos prácticos con fragmentos de código
• Pruebas: Información de cobertura y validación
• Consideraciones futuras: Notas de mantenimiento y evolución

Documentación de Marshall

Los componentes Marshall son los módulos principales de validación de seguridad en NPQ. Cada marshall se centra en un aspecto de seguridad específico:

• Age Marshall (age.marshall.md) - Validación de la antigüedad y madurez de los paquetes
• Signature Marshall - Verificación de firmas del registro NPM (consulte signature-verification-fix.md)
• Provenance Marshall - Verificación de la atestación de compilación de paquetes
• Snyk Marshall - Integración con la base de datos de vulnerabilidades
• Typosquatting Marshall - Detección de similitud de nombres de paquetes

Contribución a la documentación

Al añadir nuevas funcionalidades o realizar cambios significativos:

1. Documentación de la funcionalidad: Cree un nuevo archivo en el directorio feature/
2. Actualizar el índice: Añada una entrada a este README
3. Referencias cruzadas: Actualice los archivos de documentación relacionados
4. Ejemplos: Incluya ejemplos prácticos de uso
5. Pruebas: Documente la cobertura y la validación de las pruebas

Referencia rápida

Contexto del proyecto

• Desarrollo - configuración local, flujos de trabajo y comandos útiles.
• Pruebas - comandos de prueba, organización de pruebas y expectativas de verificación.
• Arquitectura - estructura del repositorio, límites de los paquetes y flujos importantes.
• Convenciones - convenciones de codificación, documentación y mantenimiento.

Especificaciones de diseño

• Soporte para registros personalizados - diseño aprobado para el soporte de Artifactory compatible con npm y registros privados.
• Detección JSON de agentes de codificación - diseño aprobado para seleccionar automáticamente el modo de auditoría JSON en entornos de agentes de codificación.
• Salida de auditoría JSON - diseño aprobado para resultados de auditoría versionados, no interactivos y legibles por máquina.
• Advertencias de identidad de mantenedores con dominios caducados - diseño aprobado para advertencias atribuibles de dominios caducados.
• Versión resuelta de dominios caducados - diseño para resolver la versión exacta de la dependencia en las comprobaciones de dominios caducados.

Planes de implementación

• Soporte para registros personalizados - plan de implementación tarea por tarea para el issue #429.
• Detección JSON de agentes de codificación - plan de implementación basado en pruebas primero para el issue #426 en npq y npq-hero.
• Salida de auditoría JSON - plan tarea por tarea para la salida JSON de CLI versionada y únicamente de auditoría.
• Versión resuelta de dominios caducados - plan de implementación para la resolución exacta de la versión de dependencia en las comprobaciones de dominios caducados.
• Advertencias de identidad de mantenedores con dominios caducados - plan de implementación basado en pruebas primero para advertencias atribuibles de dominios caducados.