0000-audit-overrides.md

npm audit fix can apply overrides

Summary

Allow npm audit fix to, in addition to updating versions in the dependency tree, add overrides to a project's package.json to allow for non-semver compatible security fixes.

Motivation

Currently security updates are limited to patches provided by the original authors. This means automatic fixes are impossible if the package is no longer maintained or patches include other changes that are undesirable.

Rationale and Alternatives

Being able to apply hotfix patches allows for security updates to be deployed faster and sometimes, at all. Without this, advice when a package is unmaintained and has a security vulnerability is to switch to a fork, but that's time consuming and difficult, particularly when the package is a transitive dependency. This means that even conscientious teams may take an extended period of time to apply updates.

This sort of feature exists in some third party tools (eg Synk) but they have to subvert npm's own integrity protections to make that possible.

For the purposes of transparency, to be clear the original motivation for this RFC is to provide large enterprises (eg Microsoft) with a facility in the tool to allow them to provide their employees with internally patched or rebuilt versions of dependencies. (Current tooling, like Synk, subverts npm's expectations in ways that are potentially fragile.)

Scenario

"Hot fixes"

A critical security flaw is found in a dependency of one of your depenedencies. The author of the transitive dependency is unavailable to provide updates. The package is widely used in your organization, usually as a transitive dependency. The ecosystem will eventually switch to another module. In the meantime you need some remediation.

You instruct your private registry to provide audit results for the affected versions of the module that indicate that a custom patched version is available, something like:

{
    "example": [
        {
            "id": 99999,
            "severity": "high",
            "title": "Remote Code Execution",
            "url": "https://npmjs.com/advisories/99999",
            "vulnerable_versions": "<=3.0.1",
            "overrides": {
                "3.0.0": "npm:@company/example-patched@3.0.0"
            }
        }
    ]
}

This instructs npm audit fix to add an overrides section to your package.json like:

"overrides": {
    "example@3.0.0": "npm:@company/example-patched@3.0.0"
}

Implementation

This obviously can't be a thing until overrides lands in npm itself.

Updating the npm audit report library may be required.

Updating the npm audit fix subcommand will be necessary.

Out of scope: Updating the npm audit end point to start giving this advice. It may or may not be desirable for the team that provides security advice for that end point, but that's ultimately up to them.

Unresolved Questions and Bikeshedding

Immediate plans: I (@iarna) intends to implement a proof-of-concept as a stand alone tool using yarn and pnpm overrides.

1. Details of the changes to audit API endpoint result need to be nailed down. There are some requirements and nice-to-haves:

2. Older clients must not fail when receiving the new advice.

3. Older clients should if possible report the new advice when they can't apply it.

4. Long term compatibility may not be at issue as all three major npm clients use the same reporting library. At the same time, it's not clear how easy it will be for other package managers to support npm-audit-report version 2, given that the official documentation is "use arborist" which will be a non-starter for them.

5. Would it be desirable to apply ALL audit fix results as overrides? NO.