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 have | Where it is | How to fix it |
|---|---|---|
| A dependency finding: a malicious package, or a package reported on a pull request | Findings, like any finding | Remediate on the finding, or POST /findings/{id}/remediate |
| A pentest's advisories against a package | The pentest's Dependency advisories tab | Fix 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"
| Field | Meaning |
|---|---|
package | The package name, as the pentest lists it. Required. |
manifest | Optional. 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
action | When | The change |
|---|---|---|
upgrade | A vulnerable version of a package your project declares | The version range in the manifest moves to the first version without the flaw, keeping its operator (^, ~). |
override | A vulnerable or malicious version pulled in by another package | The package is forced to a safe version through the package manager's own mechanism: overrides for npm and pnpm, resolutions for Yarn. |
pin | A malicious version of a package | The 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. |
remove | A malicious package with no release known to be clean | The package is taken out. Code that imports it will need a replacement. |
skipped | No automatic change is possible | Nothing 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
| Project | Automatic 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*.txt | Yes: 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, Cargo | No. 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.
| Check | Console label | What passes |
|---|---|---|
lockfile | Lockfile regenerated in the sandbox | Your package manager regenerated the lockfile from the edited manifest. See below. |
scope | Stays on the code the finding is about | The 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. |
resolved | Affected version is gone | The new manifest and lockfile are read, and the affected version is no longer in them. The plan is not trusted: the result is. |
applies | Applies to a fresh checkout | The change applies cleanly to a new checkout. |
tests | Project tests | The 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 has | What happens |
|---|---|
| A test command, and it passes with the new versions | The fix is verified. |
| A test command, and it fails with the new versions | The fix is not proposed. |
| A test command, but the new dependencies could not be installed in the sandbox to run it | The fix is not proposed. Tests that exist and could not be run are not treated as passed. |
| No test command | The 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.
| Part | Content |
|---|---|
| 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 wrong | Each advisory or finding, with a link to the finding or to the pentest |
| What this changes | A table: package, from, to, the kind of change, and the advisory ids it clears. Skipped packages are listed with the reason. |
| Checks | The lockfile and resolved checks with their details |
| Tests, Not verified, How to revert | As 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
outcome | detail says | What to do |
|---|---|---|
no_fix_needed | The affected version is no longer what this version of the code resolves. | Nothing. It was already changed. |
failed | No 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. |
failed | The 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. |
failed | The affected version is still resolved after the change. | Another package requires that exact version. Upgrade that package first. |
failed | The 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.
#Related
Nullgap documentation