Документация NPQ

Этот каталог содержит исчерпывающую документацию для инструмента аудита безопасности NPQ (Node Package Quality).

Основная документация

optional-features.md

Конфигурация и использование дополнительных функций безопасности, включая недавние улучшения и исправления ошибок.

age.marshall.md

Подробная документация компонента безопасности Age Marshall, который проверяет возраст и зрелость пакета.

Документация функций

Каталог feature/ содержит подробную документацию для конкретных функций и реализаций:

Последние разработки

• test-coverage-improvements.md — Комплексные улучшения тестового покрытия, которые повысили общее покрытие с 84,4% до 93,39%
• signature-verification-fix.md — Критическое исправление ошибки проверки подписи с диапазонами версий (например, @angular/common@^20.2.4)

Существующие функции

• auto-continue.md — Документация функции автоматического продолжения, которая оптимизирует рабочие процессы установки пакетов
• exit-codes.md — Справочник по поведению кодов выхода процессов npq и npq-hero
• json-output.md — Версионированный, машиночитаемый вывод только для аудита для CI и автоматизации
• malicious-package.md — Документация по обнаружению известных вредоносных пакетов через данные Snyk/OSV
• pacote-dependency-reduction.md — Сводка реализации необязательного сокращения зависимостей pacote

Стандарты документации

Структура

• Каждая функция получает собственный файл Markdown в feature/
• Основная функциональность документируется на корневом уровне документации
• Технические детали реализации включаются с примерами кода
• Конфигурация для пользователей документируется с примерами использования

Рекомендации по содержимому

• Обзор: Краткое описание функции/компонента
• Технический дизайн: Детали архитектуры и реализации
• Примеры использования: Практические примеры с фрагментами кода
• Тестирование: Информация о покрытии и валидации
• Будущие соображения: Заметки по сопровождению и развитию

Документация Marshall

Компоненты Marshall — это основные модули проверки безопасности в NPQ. Каждый Marshall фокусируется на конкретном аспекте безопасности:

• Age Marshall (age.marshall.md) — Проверка возраста и зрелости пакета
• Signature Marshall — Проверка подписи реестра NPM (см. signature-verification-fix.md)
• Provenance Marshall — Проверка подтверждения сборки пакета
• Snyk Marshall — Интеграция с базой данных уязвимостей
• Typosquatting Marshall — Обнаружение схожести имён пакетов

Вклад в документацию

При добавлении новых функций или внесении значительных изменений:

1. Документация функции: Создайте новый файл в каталоге feature/
2. Обновление индекса: Добавьте запись в этот README
3. Перекрёстные ссылки: Обновите связанные файлы документации
4. Примеры: Включите практические примеры использования
5. Тестирование: Документируйте тестовое покрытие и валидацию

Краткий справочник

Контекст проекта

• Разработка — локальная настройка, рабочие процессы и полезные команды.
• Тестирование — команды тестирования, организация тестов и ожидания по проверке.
• Архитектура — структура репозитория, границы пакетов и важные потоки.
• Соглашения — соглашения по кодированию, документации и сопровождению.

Спецификации дизайна

• Безопасность неинтерактивной установки — утверждённый дизайн для безопасных при сбое не-TTY установок с явным согласием для автоматизации и кодинг-агентов.

• Безопасность неинтерактивной установки — план, ориентированный на тестирование, для маршрутизации не-TTY установок с безопасным сбоем и передачи кодинг-агентам.

• Запуск менеджера пакетов без оболочки — утверждённый дизайн для передачи аргументов менеджера пакетов без реконструкции команд оболочки.

• Поддержка пользовательских реестров — утверждённый дизайн для поддержки совместимых с npm Artifactory и частных реестров.

• Обнаружение JSON кодинг-агентами — утверждённый дизайн для автоматического выбора режима JSON-аудита в средах кодинг-агентов.

• JSON-вывод аудита — утверждённый дизайн для версионированных, неинтерактивных машиночитаемых результатов аудита.

• Предупреждения об истёкших доменах для сопровождающих — утверждённый дизайн для атрибутируемых предупреждений об истёкших доменах.

• Разрешённая версия для истёкших доменов — дизайн для разрешения точной версии зависимости для проверок истёкших доменов.

Планы реализации

• Безопасность неинтерактивной установки — план, ориентированный на тестирование, для маршрутизации не-TTY установок с безопасным сбоем и передачи кодинг-агентам.
• Запуск менеджера пакетов без оболочки — план, ориентированный на тестирование, для запуска менеджеров пакетов без реконструкции команд оболочки.
• Поддержка пользовательских реестров — пошаговый план реализации для задачи #429.
• Обнаружение JSON кодинг-агентами — план реализации, ориентированный на тестирование, для задачи #426 в npq и npq-hero.
• JSON-вывод аудита — пошаговый план для версионированного, только аудиторского JSON-вывода CLI.
• Разрешённая версия для истёкших доменов — план реализации для точного разрешения версии зависимости в проверках истёкших доменов.
• Предупреждения об истёкших доменах для сопровождающих — план реализации, ориентированный на тестирование, для атрибутируемых предупреждений об истёкших доменах.