Skip to content

Security remediation

When a finding has a fixed version, the Canopy Security Bot can open a pull request (a merge request on GitLab) that moves the dependency to it. Canopy then builds a preview from that branch, scans it again and records what it checked on the exact commit. A person reads the evidence and merges. Nothing is merged for you, and the bot cannot merge.

It sits behind the host.security.findings platform feature and needs the repository scanning of Security findings. Remediation needs the security-remediation runner and repository access. If remediation is requested before the installation has configured the runner, the operation is blocked and reports that the runner is unavailable.

  1. Allow Canopy Security to use a GitLab project (a whole group can be allowed for the read-only token only, with --no-remediation). In the app this is Repository access on the Security fixes page; on the command line: canopy security access allow --team <team_id> --scope <group[/project]>. Canopy creates the access tokens itself through the GitLab account you connected in Settings, so no token is copied: a read-only one (Reporter role, read_api and read_repository) so it can scan your code, and one for the Security Bot (Developer role, api and write_repository) so it can push canopy-security/ branches and open merge requests. You need the Maintainer or Owner role on the path. Both tokens last 364 days, are stored encrypted, and are revoked at GitLab when you withdraw the access (canopy security access withdraw <access_id> --team <team_id>); if GitLab cannot be told, Canopy says so and you revoke the token there. --no-remediation creates only the read token, which is the only kind a group can have: the token that writes is created for one project, never a group. If you prefer to create the tokens yourself, register them with canopy clone-identities register, using --purpose remediation for the bot’s. For GitHub the same App installation is registered with --purpose remediation; its tokens are minted per run and expire within the hour. Bitbucket cannot be used for remediation.
  2. Turn the bot on: canopy security bot enable --team <team_id> (an admin). It has no API key; it only acts inside Canopy’s jobs.
  3. Turn fixes on for the project: canopy security fixes enable --project <project_id> --team <team_id>. This enables dependency updates for every repository of the project; the number of pull requests open at once is 3 by default. canopy security fixes status shows the setting and disable turns it off again.

Turning the bot off, canopy security bot disable, refuses its next credential at once. A run already going finishes with the token it holds, which lasts less than an hour. Removing the clone identity or uninstalling the App stops it too.

Terminal window
canopy security remediate <finding_id>... --team <team_id> [--allow-major]

Canopy groups the fixable findings so a repository never gets a flood of pull requests: critical findings of one lockfile share a pull request, high findings share one per lockfile in groups of five, medium and low findings share one a week, and an update that crosses a major version is its own pull request and only with --allow-major. The pull requests stay within the repository’s open limit; findings that did not fit are reported as open_pr_cap_reached. Asking again for the same findings answers with the pull request already in progress.

A finding is skipped, with its reason, when it has no known fix (no_fix_available), its lockfile manager is not supported (unsupported_manager), the repository is not enabled (repository_not_enabled), it is not open (not_open), or it is dismissed or accepted.

The updates are made by Renovate, unmodified, in a short-lived virtual machine with network access only to the git provider and the package registries. Canopy writes Renovate’s configuration; a repository’s own Renovate configuration cannot turn on scripts, commands, plugins or automerge. The pull request is on a branch named canopy-security/... and its description lists each package, the versions and the advisory.

For the pull request’s current commit Canopy records:

Check Passes when
head_sha The pull request is open and still at the verified commit.
source_scan A complete scan of the commit’s lockfiles no longer finds any targeted vulnerability. A partial scan is not proof.
no_new_critical_high The update brings in no critical or high vulnerability the project did not already have.
preview_build The preview built an image whose source commit is this commit.
preview_health The preview is running this commit.
image_scan A complete scan of the preview image finds no targeted vulnerability.
customer_ci Only when CI is connected: every CI run for the commit passed. No run counts as missing, never as a pass.

Any failed check makes the verification failed. Missing evidence keeps it waiting and, after two hours, makes it inconclusive. A new commit on the pull request starts a new verification; evidence older than seven days is stale, which returns its findings to remediation_proposed and sets the provider status to an error (“the evidence is out of date”). The result is posted on the pull request as a commit status named Canopy security verification and one comment that is updated in place. It describes what was checked; it does not promise the application is free of vulnerabilities.

A preview of a pull request receives only the environment variables marked preview_safe, so a malicious change cannot read production secrets. Verification keeps the lockfile scan of the pull request out of the findings: it is evidence for this pull request, not a statement about the default branch.

Terminal window
canopy security merge-check <remediation_id> --team <team_id> [--method merge|squash|rebase]
canopy security merge <remediation_id> --team <team_id> --expected-head <sha> [--method merge|squash|rebase]

To review a fix before merging it from the command line:

Terminal window
canopy security remediation-changes <remediation_id> --team <team_id>
canopy security remediation-comments <remediation_id> --team <team_id>
canopy security comment <remediation_id> --team <team_id> --body <text>
canopy security approve <remediation_id> --team <team_id> --expected-head <sha>
canopy security remediation-correction <remediation_id> --team <team_id>

remediation-changes prints the diff of the pull request, remediation-comments its conversation, and remediation-correction what happened to each finding the fix addresses after the merge. comment and approve act as you on the provider, like merge: they need a signed-in person, and an API key is refused with 403 human_session_required. approve names the commit you looked at and stops with 409 head_changed if the pull request moved. canopy security remediations also takes --system <system_id>.

merge-check shows the gate of the pull request, the same gate every pull request in Canopy Source has (see Source pull requests). The worker reads every condition from the git provider with your own connected git account when it evaluates the gate, and a condition it cannot read counts as failed. A gate that judged an older commit is shown as not eligible and a fresh evaluation is requested: the pull request open, not a draft and from Canopy’s branch; the bot still on; the commit verified and unchanged; every required check passed; approvals as the provider requires; no conflicts; the merge method allowed; and your account able to write to the repository.

merge names the commit you looked at. It answers 202 with an action_id: the worker evaluates the gate again and merges only if every condition passes; the command waits for the outcome. If the pull request moved, the answer is 409 head_changed and nothing is merged; nothing is retried. A repository Canopy does not track yet answers 409 source_repository_pending. It must be a signed-in person: an API key or an agent is refused with 403 human_session_required. Every attempt is recorded. A pull request that targets a branch other than the one the environment tracks is refused. A merge made on GitLab or GitHub is recorded with its commit. After the merge, the finding is resolved by the next scan of the tracked branch, and its exposure changes when the fixed image is running.

Verification runs the update in a preview. When previews are not turned on for the environment (or the platform has no preview zone), Canopy says so at once instead of waiting two hours: once the lockfiles are checked the result is “Needs previews”, the findings stay at “Fix proposed”, and the pull request gets a commit status of error (“Needs previews to verify this update”) from the repository’s status identity, which needs no preview build. Turn previews on for the environment and use Check again.

A fix opens in Canopy at Security → Fixes, in the same frame as Canopy Source: the bot’s description and the diff of every changed file with a Viewed tick on each, the conversation, and the merge on the right. The page shows the base and the branch head, and the commit that is deployed. Approve, comment and merge act as you on GitLab or GitHub, and the merge is pinned to the commit you read. If you have not connected your git account, the page says so and links to the provider.

All routes are PREVIEW (unstable). Reading needs security:read; asking, verifying and merging need security:remediate (developer); turning the bot on or off needs security:manage (admin).

Route Purpose
GET, POST, DELETE /teams/{team_id}/security/bot Read, turn on, turn off the Security Bot.
GET, PUT /teams/{team_id}/security/projects/{project_id}/remediation Read, and turn on or off ({ enabled }, needs security:manage), the Security Bot’s fixes for every repository of a project. 404 for a project of another team; 422 unless enabled is a boolean.
GET, POST /teams/{team_id}/security/access, DELETE /teams/{team_id}/security/access/{id} List, allow and withdraw the GitLab paths Canopy Security may use. POST takes { provider: gitlab, scope, remediation }; 422 when GitLab is not connected, the path is unknown or you are not a Maintainer; 409 when the access already exists.
POST /teams/{team_id}/security/remediations { finding_ids, allow_major }. 202 with remediation_ids, existing_ids and skipped; 422 with the main reason when nothing could be queued.
GET /teams/{team_id}/security/remediations List; filters project_id, system, finding_id, status.
GET /teams/{team_id}/security/remediations/{id} The remediation, its verifications with evidence, tool runs and merge attempts. While a run is on a Grove, its tool run carries progress (phase, detail, since): waiting for a node, pulling the image, starting, running.
POST /teams/{team_id}/security/remediations/{id}/verify Check the current commit again. 409 when the pull request is not open.
GET /teams/{team_id}/security/remediations/{id}/merge-eligibility Every condition of the merge, from the stored gate (stale when it judged another commit).
POST /teams/{team_id}/security/remediations/{id}/merge { expected_head_sha, method }. 202 with action_id; 409 head_changed; 409 source_repository_pending.
GET /teams/{team_id}/security/remediations/{id}/merge-actions/{action_id} The merge action: status, and result.outcome (merged, ineligible with the gate, head_changed, not_mergeable, forbidden, unconfirmed).
GET /teams/{team_id}/security/remediations/{id}/changes The files the pull request changes with their diffs, in the shape Canopy Source uses for a commit. Read with your own connected git account: 409 no_git_access without one, 502 when the provider does not answer.
GET, POST /teams/{team_id}/security/remediations/{id}/comments The conversation of the pull request, oldest first, without the provider’s system notes; POST { body } comments under your own account (201; 422 for an empty text or more than 10000 characters).
POST /teams/{team_id}/security/remediations/{id}/approve { expected_head_sha }. Approves under your own account at exactly that commit. 409 head_changed, 403 when the provider refuses.

Commenting, approving and merging need a signed-in person, never an API key or an agent.

The SDK has the same operations as sdk.security (remediationChanges, remediationComments, commentOnRemediation, approveRemediation, mergeRemediation, mergeRemediationAction).

Nothing is merged automatically, and the bot never holds a merge credential. GitLab merge requests and GitHub pull requests are supported; Bitbucket is not. Renovate is limited to what it can update in a lockfile: a vulnerable package that is only a transitive dependency of something Renovate cannot move is reported as renovate_no_change.