Documentation NPQ

Ce répertoire contient une documentation complète pour l'outil d'audit de sécurité NPQ (Node Package Quality).

Documentation principale

optional-features.md

Configuration et utilisation des fonctionnalités de sécurité optionnelles, y compris les améliorations récentes et les corrections de bugs.

age.marshall.md

Documentation détaillée du composant de sécurité Age Marshall qui valide l'âge et la maturité des packages.

Documentation des fonctionnalités

Le répertoire feature/ contient une documentation détaillée pour des fonctionnalités et implémentations spécifiques :

Développements récents

• test-coverage-improvements.md - Améliorations complètes de la couverture de tests qui ont fait passer la couverture globale de 84,4 % à 93,39 %
• signature-verification-fix.md - Correction critique de bug pour la vérification de signature avec les plages de versions (par ex., @angular/common@^20.2.4)

Fonctionnalités existantes

• auto-continue.md - Documentation de la fonctionnalité auto-continue qui rationalise les flux de travail d'installation de packages
• exit-codes.md - Référence pour le comportement de sortie des processus npq et npq-hero
• json-output.md - Sortie d'audit versionnée et lisible par machine pour les environnements CI et l'automatisation
• malicious-package.md - Documentation pour la détection de packages connus comme malveillants via les données Snyk/OSV
• pacote-dependency-reduction.md - Résumé de l'implémentation pour la réduction optionnelle des dépendances pacote

Normes de documentation

Structure

• Chaque fonctionnalité possède son propre fichier markdown dans feature/
• Les fonctionnalités principales sont documentées au niveau racine de la documentation
• Les détails d'implémentation technique sont inclus avec des exemples de code
• La configuration destinée aux utilisateurs est documentée avec des exemples d'utilisation

Directives de contenu

• Vue d'ensemble : Brève description de la fonctionnalité/du composant
• Conception technique : Architecture et détails d'implémentation
• Exemples d'utilisation : Exemples pratiques avec des extraits de code
• Tests : Informations sur la couverture et la validation
• Considérations futures : Notes sur la maintenance et l'évolution

Documentation Marshall

Les composants Marshall sont les modules principaux de validation de sécurité dans NPQ. Chaque marshall se concentre sur un aspect de sécurité spécifique :

• Age Marshall (age.marshall.md) - Validation de l'âge et de la maturité des packages
• Signature Marshall - Vérification de signature du registre NPM (voir signature-verification-fix.md)
• Provenance Marshall - Vérification de l'attestation de construction des packages
• Snyk Marshall - Intégration de la base de données de vulnérabilités
• Typosquatting Marshall - Détection de similarité des noms de packages

Contribution à la documentation

Lors de l'ajout de nouvelles fonctionnalités ou de modifications importantes :

1. Documentation de la fonctionnalité : Créer un nouveau fichier dans le répertoire feature/
2. Mise à jour de l'index : Ajouter une entrée dans ce README
3. Références croisées : Mettre à jour les fichiers de documentation associés
4. Exemples : Inclure des exemples d'utilisation pratiques
5. Tests : Documenter la couverture de tests et la validation

Référence rapide

Contexte du projet

• Développement - configuration locale, flux de travail et commandes utiles.
• Tests - commandes de test, organisation des tests et attentes de vérification.
• Architecture - structure du dépôt, limites des packages et flux importants.
• Conventions - conventions de codage, de documentation et de maintenance.

Spécifications de conception

• Sécurité d'installation non interactive - conception approuvée pour les installations non-TTY en échec sécurisé avec des options d'adhésion explicites pour l'automatisation et les agents de codage.

• Sécurité d'installation non interactive - plan test-first pour le routage d'installation non-TTY en échec sécurisé et le passage aux agents de codage.

• Lancement du gestionnaire de packages sans shell - conception approuvée pour transmettre les arguments du gestionnaire de packages sans reconstruction de commande shell.

• Prise en charge des registres personnalisés - conception approuvée pour la prise en charge d'Artifactory compatible npm et des registres privés.

• Détection JSON pour agents de codage - conception approuvée pour la sélection automatique du mode d'audit JSON dans les environnements d'agents de codage.

• Sortie d'audit JSON - conception approuvée pour des résultats d'audit versionnés, non interactifs et lisibles par machine.

• Avertissements d'identité des mainteneurs avec domaine expiré - conception approuvée pour des avertissements attribuables concernant les domaines expirés.

• Version résolue pour domaine expiré - conception pour résoudre la version exacte de la dépendance pour les contrôles de domaines expirés.

Plans d'implémentation

• Sécurité d'installation non interactive - plan test-first pour le routage d'installation non-TTY en échec sécurisé et le passage aux agents de codage.
• Lancement du gestionnaire de packages sans shell - plan test-first pour lancer les gestionnaires de packages sans reconstruction de commande shell.
• Prise en charge des registres personnalisés - plan d'implémentation tâche par tâche pour le problème #429.
• Détection JSON pour agents de codage - plan d'implémentation test-first pour le problème #426 dans npq et npq-hero.
• Sortie d'audit JSON - plan tâche par tâche pour la sortie CLI JSON versionnée et réservée à l'audit.
• Version résolue pour domaine expiré - plan d'implémentation pour la résolution exacte de la version de dépendance dans les contrôles de domaines expirés.
• Avertissements d'identité des mainteneurs avec domaine expiré - plan d'implémentation test-first pour des avertissements attribuables concernant les domaines expirés.