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 依赖缩减的实现摘要

文档标准

结构

• 每个功能在 feature/ 中拥有独立的 markdown 文件
• 核心功能在根文档层级进行记录
• 包含带代码示例的技术实现细节
• 面向用户的配置附带使用示例进行记录

内容指南

• 概述：功能/组件的简要描述
• 技术设计：架构和实现细节
• 使用示例：带代码片段的实际示例
• 测试：覆盖率和验证信息
• 未来考虑：维护和演进说明

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 安装路由和编码代理透传的测试优先计划。

• 无 Shell 包管理器启动 - 已批准的无需重建 shell 命令即可转发包管理器参数的设计。

• 自定义注册表支持 - 已批准的兼容 npm 的 Artifactory 和私有注册表支持设计。

• 编码代理 JSON 检测 - 已批准的自动在编码代理环境中选择 JSON 审计模式的设计。

• JSON 审计输出 - 已批准的带版本号、非交互式机器可读审计结果设计。

• 过期域名维护者身份警告 - 已批准的可归因过期域名警告设计。

• 过期域名解析版本 - 用于解析过期域名检查中确切依赖版本的设计。

实现计划

• 非交互式安装安全 - 针对默认拒绝非 TTY 安装路由和编码代理透传的测试优先计划。
• 无 Shell 包管理器启动 - 无需重建 shell 命令即可启动包管理器的测试优先计划。
• 自定义注册表支持 - 针对 issue #429 的逐任务实现计划。
• 编码代理 JSON 检测 - 针对 issue #426 跨 npq 和 npq-hero 的测试优先实现计划。
• JSON 审计输出 - 针对带版本号、仅审计 JSON CLI 输出的逐任务计划。
• 过期域名解析版本 - 在过期域名检查中实现精确依赖版本解析的实现计划。
• 过期域名维护者身份警告 - 针对可归因过期域名警告的测试优先实现计划。