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 i miglioramenti recenti e le 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 esaustivi della copertura dei test che hanno portato la copertura complessiva dall'84.4% al 93.39%
• signature-verification-fix.md - Correzione critica di bug per la verifica delle firme con intervalli di versioni (ad 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 con versione, leggibile da macchina e limitato all'audit, per CI e automazione
• malicious-package.md - Documentazione per il rilevamento di pacchetti notoriamente dannosi tramite i 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 in feature/
• Funzionalità principali documentate a livello di root dei docs
• Dettagli tecnici di implementazione inclusi con esempi di codice
• Configurazione rivolta all'utente documentata con esempi di utilizzo

Linee Guida per i Contenuti

• Panoramica: Breve descrizione della funzionalità/componente
• Progettazione Tecnica: Dettagli di architettura e 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 un aspetto specifico della sicurezza:

• Age Marshall (age.marshall.md) - Validazione di età e maturità dei pacchetti
• Signature Marshall - Verifica delle firme del registry 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 dei 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. Aggiornamento dell'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

• Supporto registry personalizzati - design approvato per il supporto di Artifactory compatibile con npm e registry privati.
• Rilevamento JSON per coding-agent - design approvato per la selezione automatica della modalità di audit JSON in ambienti coding-agent.
• Output di audit JSON - design approvato per risultati di audit con versione, non interattivi e leggibili da macchina.
• Avvisi di identità dei maintainer con dominio scaduto - design approvato per avvisi di dominio scaduto attribuibili.
• Versione risolta per dominio scaduto - design per la risoluzione della versione esatta della dipendenza per i controlli sui domini scaduti.

Piani di Implementazione

• Supporto registry personalizzati - piano di implementazione attività per attività per l'issue #429.
• Rilevamento JSON per coding-agent - piano di implementazione test-first per l'issue #426 in npq e npq-hero.
• Output di audit JSON - piano attività per attività per l'output CLI JSON con versione e solo audit.
• Versione risolta per dominio scaduto - piano di implementazione per la risoluzione esatta della versione della dipendenza nei controlli sui domini scaduti.
• Avvisi di identità dei maintainer con dominio scaduto - piano di implementazione test-first per avvisi di dominio scaduto attribuibili.