Documentazione NPQ

Questa directory contiene la documentazione completa per lo strumento di audit di sicurezza NPQ (Node Package Quality).

Documentazione Principale

optional-features.md

Configurazione e utilizzo delle funzionalità di sicurezza opzionali, inclusi miglioramenti recenti e correzioni di bug.

age.marshall.md

Documentazione dettagliata del componente di sicurezza Age Marshall che valida l'età e la maturità dei pacchetti.

Documentazione delle Funzionalità

La directory feature/ contiene la documentazione dettagliata per funzionalità e implementazioni specifiche:

Sviluppi Recenti

• test-coverage-improvements.md - Miglioramenti completi della copertura dei test che hanno portato la copertura complessiva dall'84,4% al 93,39%
• signature-verification-fix.md - Correzione critica di un bug nella verifica delle firme con intervalli di versioni (es., @angular/common@^20.2.4)

Funzionalità Esistenti

• auto-continue.md - Documentazione della funzionalità auto-continue che semplifica i flussi di lavoro di installazione dei pacchetti
• exit-codes.md - Riferimento per il comportamento di uscita dei processi npq e npq-hero
• json-output.md - Output di audit versionato e leggibile da macchina per CI e automazione
• malicious-package.md - Documentazione per il rilevamento di pacchetti notoriamente dannosi tramite dati Snyk/OSV
• pacote-dependency-reduction.md - Riepilogo dell'implementazione per la riduzione opzionale delle dipendenze pacote

Standard di Documentazione

Struttura

• Ogni funzionalità ha il proprio file markdown nella directory feature/
• La funzionalità principale è documentata a livello di root della documentazione
• I dettagli tecnici di implementazione sono inclusi con esempi di codice
• La configurazione rivolta all'utente è documentata con esempi di utilizzo

Linee Guida sui Contenuti

• Panoramica: Breve descrizione della funzionalità/componente
• Progettazione Tecnica: Architettura e dettagli di implementazione
• Esempi di Utilizzo: Esempi pratici con frammenti di codice
• Test: Informazioni su copertura e validazione
• Considerazioni Future: Note su manutenzione ed evoluzione

Documentazione Marshall

I componenti Marshall sono i moduli principali di validazione della sicurezza in NPQ. Ogni marshall si concentra su una specifica problematica di sicurezza:

• Age Marshall (age.marshall.md) - Validazione di età e maturità dei pacchetti
• Signature Marshall - Verifica delle firme del registro NPM (vedi signature-verification-fix.md)
• Provenance Marshall - Verifica dell'attestazione di build dei pacchetti
• Snyk Marshall - Integrazione con il database delle vulnerabilità
• Typosquatting Marshall - Rilevamento di somiglianza nei nomi dei pacchetti

Contribuire alla Documentazione

Quando si aggiungono nuove funzionalità o si apportano modifiche significative:

1. Documentazione della Funzionalità: Creare un nuovo file nella directory feature/
2. Aggiornare l'Indice: Aggiungere una voce a questo README
3. Riferimenti Incrociati: Aggiornare i file di documentazione correlati
4. Esempi: Includere esempi pratici di utilizzo
5. Test: Documentare la copertura dei test e la validazione

Riferimento Rapido

Contesto del Progetto

• Sviluppo - configurazione locale, flussi di lavoro e comandi utili.
• Test - comandi di test, organizzazione dei test e aspettative di verifica.
• Architettura - struttura del repository, confini dei pacchetti e flussi importanti.
• Convenzioni - convenzioni di codifica, documentazione e manutenzione.

Specifiche di Progettazione

• Sicurezza installazione non interattiva - progettazione approvata per installazioni non-TTY fail-closed con opt-in espliciti per automazione e agenti di codifica.

• Sicurezza installazione non interattiva - piano test-first per il routing di installazioni non-TTY fail-closed e pass-through per agenti di codifica.

• Avvio del gestore pacchetti senza shell - progettazione approvata per l'inoltro degli argomenti del gestore pacchetti senza ricostruzione dei comandi shell.

• Supporto registri personalizzati - progettazione approvata per il supporto di Artifactory compatibile con npm e registri privati.

• Rilevamento JSON per agenti di codifica - progettazione approvata per la selezione automatica della modalità di audit JSON in ambienti con agenti di codifica.

• Output audit JSON - progettazione approvata per risultati di audit versionati, non interattivi e leggibili da macchina.

• Avvisi identità manutentori con dominio scaduto - progettazione approvata per avvisi attribuibili su domini scaduti.

• Versione risolta con dominio scaduto - progettazione per la risoluzione della versione esatta della dipendenza per i controlli sui domini scaduti.

Piani di Implementazione

• Sicurezza installazione non interattiva - piano test-first per il routing di installazioni non-TTY fail-closed e pass-through per agenti di codifica.
• Avvio del gestore pacchetti senza shell - piano test-first per l'avvio dei gestori pacchetti senza ricostruzione dei comandi shell.
• Supporto registri personalizzati - piano di implementazione attività per attività per l'issue #429.
• Rilevamento JSON per agenti di codifica - piano di implementazione test-first per l'issue #426 su npq e npq-hero.
• Output audit JSON - piano attività per attività per l'output CLI JSON versionato e solo audit.
• Versione risolta con dominio scaduto - piano di implementazione per la risoluzione esatta della versione della dipendenza nei controlli sui domini scaduti.
• Avvisi identità manutentori con dominio scaduto - piano di implementazione test-first per avvisi attribuibili su domini scaduti.