Nullgap.dev Docs

Fixes

Dependency fixes

Fix a vulnerable or malicious dependency with the smallest manifest and lockfile change, regenerated in the sandbox and checked before a pull request is opened.

A dependency fix is the smallest change to your manifest and lockfile that clears a problem with a package: an upgrade for a vulnerable version, a pin or a removal for a malicious one. Nothing is written by AI. The change is computed, the lockfile is regenerated by your package manager inside the sandbox, and the result is checked by reading it.

#Two starting points

There are two kinds of dependency problem, and each has its own way in. See Advisories and findings for why they are kept apart.

You haveWhere it isHow to fix it
A dependency finding: a malicious package, or a package reported on a pull requestFindings, like any findingRemediate on the finding, or POST /findings/{id}/remediate
A pentest's advisories against a packageThe pentest's Dependency advisories tabFix on the row, or POST /pentests/{id}/advisories/fix

Any member can start either. By API, a key with the write or admin scope.

#From a finding

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_5e9c2a7b4d10/remediate"

A fix started from a dependency finding takes the other open dependency findings on the same package in the same manifest with it, up to 20: one change clears them together. You do not need scope for this. GET /findings/{id}/fix-scope shows them, with kind set to dependency.

#From a pentest's advisories

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package":"lodash","manifest":"package-lock.json"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/pen_4c1d9e7a2b60/advisories/fix"
FieldMeaning
packageThe package name, as the pentest lists it. Required.
manifestOptional. Limit the fix to the advisories listed against this one manifest or lockfile. Without it, every advisory the pentest lists against the package is taken, up to 20.

The answer is a fix run with kind set to dependency, pentestId set, and an empty findingId: advisories are not findings, so the run carries them itself and its pull request links back to the pentest. If a run for that package from that pentest is already queued or running, that run is returned.

The request is refused with 404 not_found when the pentest lists no advisory for that package.

In the console, the Fix button is shown on advisories that name a fixed version.

#What the fix changes

actionWhenThe change
upgradeA vulnerable version of a package your project declaresThe version range in the manifest moves to the first version without the flaw, keeping its operator (^, ~).
overrideA vulnerable or malicious version pulled in by another packageThe package is forced to a safe version through the package manager's own mechanism: overrides for npm and pnpm, resolutions for Yarn.
pinA malicious version of a packageThe package is pinned to one exact version: the newest earlier release with no known advisory, or the clean release the advisory names. An exact version, not a range, because a range could resolve to the bad release again.
removeA malicious package with no release known to be cleanThe package is taken out. Code that imports it will need a replacement.
skippedNo automatic change is possibleNothing is changed for that package. note says why.

Rules the planner follows:

  • Never a downgrade. A target must be newer than every installed version. For a malicious release, the pin is to an earlier clean one.
  • A malicious package is not upgraded in place. Upgrading is the wrong reflex when a release was compromised.
  • A jump to a new major version is made when that is where the fix is, and the change carries a note to review breaking changes.

#What is supported

ProjectAutomatic fix
npm, pnpm and Yarn (package.json with package-lock.json, npm-shrinkwrap.json, pnpm-lock.yaml or yarn.lock)Yes: manifest edited, lockfile regenerated
Python requirements*.txtYes: the pin is edited. Pins with --hash values are skipped for a vulnerable package, because the hashes belong to the old release.
Poetry, uv, Pipenv, CargoNo. The run ends as failed and names the command to run with your own package manager.

#How it is verified

The checks are recorded by name, like those of a code fix. In place of the three probe runs, a dependency fix has lockfile and resolved.

CheckConsole labelWhat passes
lockfileLockfile regenerated in the sandboxYour package manager regenerated the lockfile from the edited manifest. See below.
scopeStays on the code the finding is aboutThe change touches dependency manifests and lockfiles only. If regenerating the lockfile changed any other file, or the change would touch a protected path, it is refused.
resolvedAffected version is goneThe new manifest and lockfile are read, and the affected version is no longer in them. The plan is not trusted: the result is.
appliesApplies to a fresh checkoutThe change applies cleanly to a new checkout.
testsProject testsThe new dependencies are installed from the new lockfile in the sandbox, and your test command passes against them.

#The lockfile

The lockfile is not edited by hand. Your package manager regenerates it from the edited manifest, inside the sandbox, with these conditions:

  • Install scripts are off. No package's install script runs.
  • The command resolves versions and writes the lockfile. It does not build your project.
  • This one command is given network access, to reach the package registry. Nothing else in a fix run is.
  • It never runs outside the sandbox.

If the lockfile cannot be regenerated, the lockfile check fails and no pull request is opened. A manifest and a lockfile that disagree would break every install from the lockfile, so no change is better than half of one.

For a requirements file there is no separate lockfile. The lockfile check is then not_run, and its detail says so.

#The resolved check

A fix can be planned correctly and still not work: another package may require exactly the affected version. So after the lockfile is regenerated, Nullgap reads it. If the affected version is still there, resolved fails, the run ends as failed, and the detail names what is still resolved.

#Tests

Your repository hasWhat happens
A test command, and it passes with the new versionsThe fix is verified.
A test command, and it fails with the new versionsThe fix is not proposed.
A test command, but the new dependencies could not be installed in the sandbox to run itThe fix is not proposed. Tests that exist and could not be run are not treated as passed.
No test commandThe fix is proposed. The pull request states under Not verified that nothing was run against the new versions.

The test command comes from testCommand in the repository's .nullgap/config.json.

#The pull request

A dependency fix is always a pull request. A fix for a pentest's advisories targets the repository's default branch.

PartContent
Title"Upgrade" the package "to" the version; "Pin" it to a version, saying which release is malicious; or "Remove malicious package" and its name
What was wrongEach advisory or finding, with a link to the finding or to the pentest
What this changesA table: package, from, to, the kind of change, and the advisory ids it clears. Skipped packages are listed with the reason.
ChecksThe lockfile and resolved checks with their details
Tests, Not verified, How to revertAs for any fix. Reverting restores the affected version, so only do that together with another fix.

#When the package was malicious

Merging the pull request removes the package. It does not undo anything the package already did: its install scripts may have run on every machine and pipeline that installed it.

The pull request therefore adds a section, If this package was ever installed, listing what to check (when the release entered the lockfile, which pipelines and machines installed it, what was built in that window, which caches still hold it) and what to rotate (pipeline secrets, registry and source-control tokens, cloud credentials, signing and SSH keys, database passwords and API keys the build could read).

Treat that list as the start of an incident, not as a formality.

#What a dependency fix spends

A dependency fix uses no automation credits. It is computed and checked without AI, so it can be started with an empty credit balance.

It is otherwise an ordinary fix run: it appears on the Automations page and under GET /automation-runs, sends the remediation.completed webhook event, and can be started by an automation for a new dependency finding.

#When it cannot be fixed automatically

outcomedetail saysWhat to do
no_fix_neededThe affected version is no longer what this version of the code resolves.Nothing. It was already changed.
failedNo automatic change is possible, with the reason per package: no fixed version is published, the package manager is not supported, a hashed pin, or a malicious package that arrives through another package with no clean release.Make the change with your own package manager. For the last case, remove or replace the package that depends on it.
failedThe lockfile could not be regenerated.Read the package manager's output in the detail. A private registry the sandbox cannot reach is a common cause.
failedThe affected version is still resolved after the change.Another package requires that exact version. Upgrade that package first.
failedThe tests fail, or could not be run, with the new versions.Apply the upgrade on a branch of your own and fix what breaks.

For code that was added by address or upload, the request is refused with 409 read_only_repository: no pull request can be opened on it.

Nullgap documentation