npq

The Age Marshall is a security validation component in NPQ that belongs to the PackageHealth category. It analyzes package age and maturity to identify potential supply chain risks by performing two primary checks:

1. New Package Detection: Flags packages that are too new (less than 22 days old) to prevent installation of potentially malicious or typosquatting packages that haven't undergone community review.
2. Abandoned Package Detection: Warns about packages that appear unmaintained (versions older than 365 days) to alert users to potentially unpatched security vulnerabilities.

It works by fetching metadata from the npm registry and analyzing the time.created (package creation) and time[version] (version release) fields using millisecond precision.

The Dormant maintainer check flags when a publishing user (matched by _npmUser.email) has a previous release on this package, followed by a long calendar gap before the current release.

How the gap is measured: npq looks for the latest version in the package metadata that was published by the same email strictly before the current version. The gap is the difference in whole days between those two timestamps.

Rules:

• Gap > 274 days (~9 months): Throws an Error ("more than 9 months dormant").
• Gap > 183 days (~6 months): Throws a Warning ("more than 6 months dormant").
• Note: If the email has no prior history on this package, this check is skipped.
• Note: Other maintainers publishing in the gap does not reset the timer for this specific email; only versions with the same email count toward the gap calculation.

You can use npq-hero as a transparent drop-in replacement for your package manager (e.g., npm, yarn, pnpm). When aliased, npq-hero intercepts install commands to run security checks (marshalls) before handing off to the real package manager. All other commands (like npm test or npm audit) are passed through untouched, ensuring your existing workflows remain unchanged.

There are two distinct binaries:

• npq: A standalone CLI for explicit, on-demand use with its own flags (--dry-run, --plain, etc.).
• npq-hero: A wrapper designed for aliasing. It has no CLI flags of its own to prevent conflicts with the underlying package manager's flags.

The auto-continue feature streamlines package installation by automatically proceeding after a countdown when security audits detect warnings but no errors.

Activation Criteria:

1. The security audit completes with at least one warning and zero errors.
2. The user has not explicitly disabled the feature.

If no issues are found, installation proceeds immediately. If errors are found, npq will prompt for manual confirmation instead of using a countdown.

Default Behavior:

• Duration: 15 seconds.
• Interaction: You can press y or Y during the countdown to skip the timer and install immediately. Pressing Ctrl+C will abort the installation with exit code 1.

While the Age Marshall mitigates certain risks, developers should be aware of its limitations:

Risk Mitigation

• Supply Chain Attacks: Flags new packages for manual review.
• Typosquatting: Catches recently created packages with suspicious names.
• Abandoned Packages: Identifies potentially unmaintained software.

Limitations

• False Positives: Legitimate new packages will be flagged.
• Bypass Potential: Attackers can bypass detection by waiting 22 days before publishing malicious updates.
• Maintenance Assumption: Package age is a proxy for security and does not guarantee active maintenance or safety.

NPQ follows standard npm configuration precedence. If multiple sources define a setting, the highest priority wins. Scoped registries (e.g., @company:registry) are selected independently of the unscoped default registry.

1. Command-line options (e.g., `--registry`)
2. `npm_config_*` environment variables
3. Project `.npmrc`
4. User `.npmrc`
5. Global npm configuration
6. The public npm registry default

The criteria for marking a package as 'malicious' depend on the active data source:

Snyk API

A package is malicious if any vulnerability in the response has: vulnerability.title === "Malicious Package"

OSV API

A package is malicious if any vulnerability matches either of these conditions:

1. database_specific["malicious-packages-origins"]: If this property exists and is an array (even an empty one).
2. summary prefix: If the summary string, when lowercased, starts with "malicious" (e.g., "Malicious code in...").

When npq detects an expired domain (where DNS resolution fails and RDAP shows no active registration), it provides a corroborated warning. The warning includes a summary sentence followed by an Affected maintainers: section.

This section lists affected domains in lexical order. For each domain, it lists the associated maintainer identities in their registry order using the format name <email>. If a maintainer does not have a usable name, only the <email> is rendered.

Note that invalid email records are excluded from this identity list but are still counted as incomplete records under existing policies.

Maintainer domain example.com does not resolve in public DNS, and RDAP found no active registration; account takeover may be possible.

Affected maintainers:
- example.com: Alice Smith <alice@example.com>, Bob Jones <bob@example.com>