NPQ-Dokumentation

Dieses Verzeichnis enthält umfassende Dokumentation für das Sicherheits-Audit-Tool NPQ (Node Package Quality).

Kerndokumentation

optional-features.md

Konfiguration und Verwendung optionaler Sicherheitsfunktionen, einschließlich aktueller Verbesserungen und Fehlerbehebungen.

age.marshall.md

Detaillierte Dokumentation der Age-Marshall-Sicherheitskomponente, die Paketalter und -reife validiert.

Funktionsdokumentation

Das Verzeichnis feature/ enthält detaillierte Dokumentation für spezifische Funktionen und Implementierungen:

Aktuelle Entwicklungen

• test-coverage-improvements.md - Umfassende Verbesserungen der Testabdeckung, die die Gesamtabdeckung von 84,4 % auf 93,39 % erhöht haben
• signature-verification-fix.md - Kritische Fehlerbehebung für die Signaturprüfung mit Versionsbereichen (z. B. @angular/common@^20.2.4)

Bestehende Funktionen

• auto-continue.md - Dokumentation für die Auto-Continue-Funktion, die Paketinstallations-Workflows optimiert
• exit-codes.md - Referenz für das Exit-Verhalten der Prozesse npq und npq-hero
• json-output.md - Versionierte, maschinenlesbare Audit-Ausgabe für CI und Automatisierung
• malicious-package.md - Dokumentation zur Erkennung bekannter bösartiger Pakete über Snyk/OSV-Daten
• pacote-dependency-reduction.md - Implementierungsübersicht für die optionale Reduzierung der pacote-Abhängigkeiten

Dokumentationsstandards

Struktur

• Jede Funktion erhält eine eigene Markdown-Datei im Verzeichnis feature/
• Kernfunktionalität wird auf der obersten Dokumentationsebene dokumentiert
• Technische Implementierungsdetails werden mit Codebeispielen bereitgestellt
• Benutzerorientierte Konfiguration wird mit Verwendungsbeispielen dokumentiert

Inhaltsrichtlinien

• Überblick: Kurze Beschreibung der Funktion/Komponente
• Technisches Design: Architektur- und Implementierungsdetails
• Verwendungsbeispiele: Praktische Beispiele mit Codeausschnitten
• Tests: Informationen zu Abdeckung und Validierung
• Zukünftige Überlegungen: Hinweise zu Wartung und Weiterentwicklung

Marshall-Dokumentation

Marshall-Komponenten sind die zentralen Sicherheitsvalidierungsmodule in NPQ. Jede Marshall-Komponente konzentriert sich auf einen spezifischen Sicherheitsaspekt:

• Age Marshall (age.marshall.md) - Validierung von Paketalter und -reife
• Signature Marshall - Überprüfung der NPM-Registry-Signaturen (siehe signature-verification-fix.md)
• Provenance Marshall - Verifizierung der Paket-Build-Herkunft
• Snyk Marshall - Integration der Schwachstellendatenbank
• Typosquatting Marshall - Erkennung von Ähnlichkeiten bei Paketnamen

Beiträge zur Dokumentation

Beim Hinzufügen neuer Funktionen oder bei wesentlichen Änderungen:

1. Funktionsdokumentation: Neue Datei im Verzeichnis feature/ erstellen
2. Index aktualisieren: Eintrag in dieser README hinzufügen
3. Querverweise: Verwandte Dokumentationsdateien aktualisieren
4. Beispiele: Praktische Verwendungsbeispiele einfügen
5. Tests: Testabdeckung und Validierung dokumentieren

Kurzreferenz

Projektkontext

• Entwicklung - lokale Einrichtung, Workflows und nützliche Befehle.
• Tests - Testbefehle, Testorganisation und Verifikationserwartungen.
• Architektur - Repository-Struktur, Paketgrenzen und wichtige Abläufe.
• Konventionen - Kodierungs-, Dokumentations- und Wartungskonventionen.

Designspezifikationen

• Sicherheit bei nicht-interaktiven Installationen - genehmigtes Design für Fail-Closed-Non-TTY-Installationen mit expliziten Opt-ins für Automatisierung und Coding-Agenten.

• Sicherheit bei nicht-interaktiven Installationen - Test-First-Plan für Fail-Closed-Non-TTY-Installationsrouting und Coding-Agent-Durchreichung.

• Shell-freies Starten von Paketmanagern - genehmigtes Design für die Weiterleitung von Paketmanager-Argumenten ohne Shell-Befehlsrekonstruktion.

• Unterstützung benutzerdefinierter Registries - genehmigtes Design für npm-kompatible Artifactory- und private Registry-Unterstützung.

• JSON-Erkennung für Coding-Agenten - genehmigtes Design für die automatische Auswahl des JSON-Audit-Modus in Coding-Agent-Umgebungen.

• JSON-Audit-Ausgabe - genehmigtes Design für versionierte, nicht-interaktive maschinenlesbare Audit-Ergebnisse.

• Warnungen zu abgelaufenen Domains von Maintainern - genehmigtes Design für zurechenbare Warnungen zu abgelaufenen Domains.

• Aufgelöste Version bei abgelaufenen Domains - Design zur Auflösung der exakten Abhängigkeitsversion für Prüfungen abgelaufener Domains.

Implementierungspläne

• Sicherheit bei nicht-interaktiven Installationen - Test-First-Plan für Fail-Closed-Non-TTY-Installationsrouting und Coding-Agent-Durchreichung.
• Shell-freies Starten von Paketmanagern - Test-First-Plan zum Starten von Paketmanagern ohne Shell-Befehlsrekonstruktion.
• Unterstützung benutzerdefinierter Registries - Schritt-für-Schritt-Implementierungsplan für Issue #429.
• JSON-Erkennung für Coding-Agenten - Test-First-Implementierungsplan für Issue #426 in npq und npq-hero.
• JSON-Audit-Ausgabe - Schritt-für-Schritt-Plan für versionierte, reine Audit-JSON-CLI-Ausgabe.
• Aufgelöste Version bei abgelaufenen Domains - Implementierungsplan für die exakte Auflösung der Abhängigkeitsversion bei Prüfungen abgelaufener Domains.
• Warnungen zu abgelaufenen Domains von Maintainern - Test-First-Implementierungsplan für zurechenbare Warnungen zu abgelaufenen Domains.