NPQ-Dokumentation

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

Kerndokumentation

optional-features.md

Konfiguration und Verwendung optionaler Sicherheitsfunktionen, einschließlich der jüngsten Verbesserungen und Fehlerbehebungen.

age.marshall.md

Detaillierte Dokumentation der Sicherheitskomponente Age Marshall, 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)

Vorhandene 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 reine 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 - Implementierungszusammenfassung für die optionale Reduzierung von pacote-Abhängigkeiten

Dokumentationsstandards

Struktur

• Jede Funktion erhält ihre eigene Markdown-Datei im Verzeichnis feature/
• Kernfunktionen werden auf der obersten Dokumentationsebene beschrieben
• Technische Implementierungsdetails werden mit Codebeispielen ergänzt
• Benutzerseitige Konfiguration wird mit Verwendungsbeispielen dokumentiert

Inhaltsrichtlinien

• Übersicht: Kurzbeschreibung 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. Jeder Marshall konzentriert sich auf einen spezifischen Sicherheitsaspekt:

• Age Marshall (age.marshall.md) - Validierung von Paketalter und -reife
• Signature Marshall - Signaturprüfung der NPM-Registry (siehe signature-verification-fix.md)
• Provenance Marshall - Überprüfung der Build-Attestationen von Paketen
• Snyk Marshall - Integration der Schwachstellendatenbank
• Typosquatting Marshall - Erkennung ähnlicher 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: Zugehörige Dokumentationsdateien aktualisieren
4. Beispiele: Praktische Verwendungsbeispiele aufnehmen
5. Tests: Testabdeckung und Validierung dokumentieren

Schnellreferenz

Projektkontext

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

Designspezifikationen

• Custom-Registry-Unterstützung - genehmigtes Design für npm-kompatible Artifactory- und Private-Registry-Unterstützung.
• Coding-Agent-JSON-Erkennung - genehmigtes Design zur automatischen Auswahl des JSON-Audit-Modus in Coding-Agent-Umgebungen.
• JSON-Audit-Ausgabe - genehmigtes Design für versionierte, nicht-interaktive maschinenlesbare Audit-Ergebnisse.
• Warnungen zu Maintainer-Identitäten mit abgelaufenen Domains - genehmigtes Design für zuordenbare Warnungen zu abgelaufenen Domains.
• Aufgelöste Version bei abgelaufener Domain - Design zur Auflösung der exakten Abhängigkeitsversion für Prüfungen abgelaufener Domains.

Implementierungspläne

• Custom-Registry-Unterstützung - schrittweiser Implementierungsplan für Issue #429.
• Coding-Agent-JSON-Erkennung - Test-first-Implementierungsplan für Issue #426 für npq und npq-hero.
• JSON-Audit-Ausgabe - schrittweiser Plan für versionierte, reine JSON-Audit-CLI-Ausgabe.
• Aufgelöste Version bei abgelaufener Domain - Implementierungsplan für die exakte Auflösung der Abhängigkeitsversion bei Prüfungen abgelaufener Domains.
• Warnungen zu Maintainer-Identitäten mit abgelaufenen Domains - Test-first-Implementierungsplan für zuordenbare Warnungen zu abgelaufenen Domains.