Skip to content

Security findings

Canopy reads the lockfiles of the branch each environment deploys and scans the images it builds. A vulnerability it finds becomes a finding: one package and one advisory in one project, kept across scans, with where it was seen, whether a fix exists and whether the vulnerable software is running.

Scanning is on by default for every Organization, with nothing to set up: Canopy reads the lockfiles of each environment’s tracked branch and scans each image a build registers, using the build read access it already has. The routes below are still PREVIEW (unstable) and sit behind the host.security.findings platform feature, which an administrator of the platform can switch off (every route then answers 403 with error: feature_disabled).

An image that the registry no longer holds is not scanned again and is not a scanner failure: its run is recorded as skipped with the failure code image_gone, and GET /teams/{team_id}/security/summary counts those apart, as gone_subjects of each scanner. A failed scan is retried at most three times a day per image or repository, one job attempt each, and failed runs older than 30 days are deleted unless a finding still refers to them.

Field Meaning
vulnerability_key The advisory. A CVE id when there is one, so two scanners that name the same flaw differently share a finding.
source_state open, fix_available, reopened, resolved_in_source, dismissed, risk_accepted, and while a fix is under way remediation_proposed, verification_running, verification_failed and ready_for_review.
exposure_state Where the vulnerable software is: running_production, running_non_production, built_not_deployed, source_only, fix_merged_not_deployed, residual_rollback_risk, resolved_in_deployment, unknown.
exposure_grade How well the exposure is known: known when every ready pod of the running workloads reports the vulnerable image digest itself, inferred when it comes from the generation a workload converged on, unknown when a running image has not been scanned completely.
severity, fix_available, best_fixed_version From the advisory as it is now; a revised advisory changes it and leaves a history entry.

See Security remediation for the pull requests that fix findings and the merge that follows.

After a fix is merged, a finding is fix_merged_not_deployed while any environment still runs an affected image, and resolved_in_deployment once none does. While an affected image is still available and an older release of an environment that used it could be rolled back to, the state is residual_rollback_risk instead: it clears when the image is removed from the registry or no such release remains.

A finding moves to resolved_in_source only when a complete, successful scan no longer sees it. A failed, timed out or partial scan changes nothing. Partial means something could not be read, for example a bun.lockb (binary lockfiles are not supported; bun.lock is) or a requirements.txt whose entries are not pinned; the reasons are listed on the scan run.

Each occurrence of a finding in an image has a relevance: running (a workload runs it), latest_build (the newest build of its environment), rollback (an older release of an environment could return to it), preview (built for a pull request) or history. Only the first three keep a finding open. A finding that only an older image still has resolves in source, and an image built for a pull request never opens a finding; it is kept as evidence. Relevance is recomputed when a workload converges or a release is deployed, reverted or promoted, and once a night for everything.

source_only is claimed only when every running image of the project has a complete scan without the finding; while a running image is unscanned the exposure is unknown (“Not yet scanned” in the app). A running image of another Organization never counts, even with the same digest.

Exposure is judged from what Forest reports as running: the image digest of each workload’s converged generation, never from branch state. A pull request preview is listed but does not count as production. The basis is inferred: Forest reports the generation a workload has converged on, not the image of each running pod.

When an advisory is revised, the finding gets a history entry. When it is withdrawn, the finding is dismissed with the system reason advisory_withdrawn; revoking that dismissal reopens it.

canopy security correction <finding_id> and the finding page answer, per environment where the finding was ever seen: the merge that fixed it, the first corrected build (scanned completely, without the finding), the release that carries it, whether it runs now, the vulnerable image digests that still run (marked “seen in a pod” or “inferred”), and the older releases that could still roll back to the vulnerable image. A fix’s own page shows the same under “After the merge”.

A digest is “seen in a pod” when the Forest controller reports the image ID the kubelet recorded for a ready pod, read within the last 30 minutes; it is never derived from a tag. With an older controller the exposure stays inferred. A pod still running the vulnerable image counts as exposure even after its workload converged on the fixed one.

Two places say it before the damage is done. The rollback dialog lists the open vulnerabilities the release you chose carries that the live release does not (GET /projects/{project_id}/security/rollback-impact), and the notification of a deploy says which vulnerabilities the new release no longer carries.

sort=priority (the default in the app) orders open findings by a key whose every part is shown on the finding under “Why it ranks here”, in this order: how well the exposure is known and whether it runs in production, whether CISA lists it as known exploited, whether a fix exists, severity, the EPSS band, and age. There is no score. EPSS and KEV are public signals shown with the day they were read; a finding without an EPSS score says “no EPSS score”, never “low”.

EPSS is the Exploit Prediction Scoring System of FIRST and KEV is the CISA Known Exploited Vulnerabilities catalog. Canopy downloads each once a day, keeps the entries for the CVEs your findings concern, and refuses a file it cannot read completely: the stored values stay as they were and the failure is logged. An environment with a public domain is marked “publicly routed” on the finding; that is a fact about routing, not a statement that it is exploitable.

canopy security coverage and the Coverage page account for every active repository and every running image:

State Meaning
complete The latest scan read everything, within the last two days.
partial Something could not be read; the reasons are listed. A partial scan never closes a finding.
unsupported_manifest The only gaps are manifests Canopy does not scan yet: mix.lock, pubspec.lock, Package.resolved, or a package.json no lockfile covers.
no_access Canopy could not read the repository: no access was allowed, or the provider refused.
failing The scanner keeps failing.
never_scanned, pending No scan yet, or the first one is queued.
image_gone The image was removed from the registry; nothing to do.
stale The last complete scan is more than two days old.
  • A push to the branch an environment deploys, when the webhook signature verifies.
  • Connecting a repository to an environment.
  • A daily sweep of repositories without a recent scan and of the images that still matter to a finding.
  • A refresh of the advisory database every hour, which re-matches every stored dependency list against the new data without reading any repository again.
  • A failed scan is retried, at most three times a day per repository.
  • On request: canopy security scan, at most 30 an hour per team.

An image is scanned when it is registered. Trivy covers operating system packages as well as language packages; the repository scan covers npm, pnpm, Yarn, Bun, pip (pinned), Poetry, Pipenv, uv, Go modules, Cargo, Bundler (Gemfile.lock), Composer (composer.lock), NuGet (packages.lock.json), Gradle (gradle.lockfile) and Maven (pom.xml).

A pom.xml lists only the dependencies written in it, not the ones they pull in, so a repository that relies on one is reported as partial with the reason dependencies_not_resolved and a scan of it never closes a finding. Use a Gradle lockfile or a resolved build for a complete answer. For Bundler, Composer, NuGet, Gradle and Maven, Canopy reports the findings and the fixed version but does not open the fix pull request yet.

Security is a destination of its own in the navigation (shown when the feature is on for the Organization you are working in). It always works in the active Organization; a link that belongs to another Organization asks you to switch instead of failing.

Page What it is for
Overview What needs attention now: findings running in production with a fix, fixes awaiting review (with the verification sentence), coverage problems by cause, and what was recently resolved in deployment.
Findings The work queue. Severity, exposure, and evidence filters live in the address, so a filtered list can be shared.
Fixes The pull requests the Security Bot opened and the checks on each.
Coverage What was and was not scanned, and why.
Activity The scans Canopy ran, newest first.
Settings Repository access and the Security Bot.

The old /settings/organization/vulnerabilities addresses redirect here.

Three events notify people, each with a link to the finding or fix:

Event When
A new production exposure with a fix A finding that has a fixed version starts running in production. Said once per finding; if it stops running and later returns, it is said again.
A verification failed The checks on a fix finished and failed.
A fix reached production The environment that ran the vulnerable image now runs the corrected one.

They go to the owners and watchers of the Systems that hold the project’s environments, and to every member of the Organization when the project is in no System with owners or watchers, as build and deploy notifications do.

A System page has a Security strip: the findings of its projects that run in production with a fix, the repositories and images that could not be read completely, and the fixes waiting for review. Each number links to the Findings list filtered by that System (system=<system_id> in the address, and --system in the CLI).

An image’s Artifact Passport and a release page show the finding counts of the image or of every image of the release, and link to the findings. An image that was never scanned says so instead of showing zero.

The Graph answers “what is affected by CVE-X”: GET /teams/{team_id}/security/advisories/{key}/affected (or canopy security affected <advisory> --team <team_id>) returns the findings, the environments that run it and the graph nodes and edges involved, and the same environments the Security pages show for that advisory. Image nodes in a graph response carry a security annotation with the counts.

Attach security_finding:<finding_id> or security_remediation:<remediation_id> as a context ref to the assistant. Cortex is given the recorded facts with the times Canopy recorded them (the advisory, where it runs, the scans that saw it, the checks on a fix and their evidence), what follows from them, and what Canopy has no record of. It is told to start every sentence with Recorded:, Implied: or Unknown:, to use only ids, versions and states that appear in the records, and never to say a vulnerability is or is not exploitable, because Canopy records only the public signals. A ref the person cannot read, from another Organization, or in an Organization without Security findings is refused as not found. Cortex has no tools that change anything.

Terminal window
canopy security summary --team <team_id>
canopy security findings --team <team_id> [--project <id>] [--system <system_id>] [--fix-available] [--severity critical,high] [--state <list>] [--exposure <list>] [--grade <list>] [--sort priority] [--ecosystem npm] [--package <name>] [--query <text>] [--limit <n>] [--cursor <cursor>]
canopy security finding <finding_id> --team <team_id>
canopy security affected <advisory_id> --team <team_id>
canopy security overview --team <team_id>
canopy security correction <finding_id> --team <team_id>
canopy security coverage --team <team_id> [--system <system_id>] [--state failing,no_access] [--limit <n>]
canopy security project <project_id>
canopy security dependencies --project <project_id> [--repository <repository_id>] [--limit <n>] [--cursor <cursor>]
canopy security rollback-impact --project <project_id> --environment <environment_id> --release <release_id>
canopy security system <system_id> --team <team_id>
canopy security artifact <artifact_id> --team <team_id>
canopy security release <release_id> --team <team_id>
canopy security dismiss <finding_id> --team <team_id> --reason <text>
canopy security accept-risk <finding_id> --team <team_id> --reason <text> --until <iso8601>
canopy security reopen <suppression_id> --team <team_id>
canopy security scan --project <project_id> [--subjects repositories|artifacts|all]
canopy security runs --team <team_id> [--project <id>]

Accepting a risk needs an end date at most 365 days away; when it passes the finding returns to the state its evidence gives it. Every command takes --json.

All routes are PREVIEW (unstable). Reads need security:read (viewer), a scan needs security:remediate (developer), dismissing, accepting a risk and reopening need security:manage (admin). A member of another team gets 404.

Route Purpose
GET /teams/{team_id}/security/summary Open findings by severity, state and exposure; the projects with the most; scanner and database health; stale subjects.
GET /teams/{team_id}/security/overview The four sections of the Overview page in one round trip, each bounded.
GET /teams/{team_id}/security/findings/{finding_id}/correction The correction record of one finding, per environment.
GET /teams/{team_id}/security/remediations/{remediation_id}/correction The correction records of every finding a fix addresses.
GET /projects/{project_id}/security/rollback-impact environment_id, release_id: the open findings a rollback to that release would bring back.
GET /teams/{team_id}/security/coverage Totals by coverage state and the subjects that are not complete, worst first. Filters state, system, limit.
GET /teams/{team_id}/security/findings List, newest change first. Filters project_id, system, fix_available, severity, source_state, exposure_state, exposure_grade, sort (recent or priority), ecosystem, package, q; lists are comma separated.
GET /teams/{team_id}/security/findings/{finding_id} One finding: advisory, links, occurrences, where it runs, the scan runs that saw it, history.
GET /teams/{team_id}/security/systems/{system_id} The Security strip of a System. 404 for a System you cannot see.
GET /teams/{team_id}/security/artifacts/{artifact_id} The finding counts of one image.
GET /teams/{team_id}/security/releases/{release_id} The finding counts over every image of a release.
GET /teams/{team_id}/security/advisories/{advisory_key}/affected What an advisory affects: findings, environments, graph nodes and edges.
POST /teams/{team_id}/security/findings/{finding_id}/suppressions { kind: dismissed | risk_accepted, reason, expires_at }. 409 if one is active.
DELETE /teams/{team_id}/security/suppressions/{suppression_id} Revoke.
GET /teams/{team_id}/security/scan-runs Runs with scanner and database versions, outcome, completeness and failure.
GET /projects/{project_id}/security Repositories and their lockfiles, images scanned, open findings, latest runs.
GET /projects/{project_id}/security/dependencies The packages of the last scanned lockfiles.
POST /projects/{project_id}/security/scans { subjects }. 429 with Retry-After beyond 30 an hour.

Lists are cursor paginated: pass next_cursor back as cursor; limit is 1 to 200 (default 50).

The SDK has the same operations as sdk.security.

Fixing a finding is its own page. Findings from images whose operating system packages changed advisories are re-checked by the daily rescan, not by the hourly re-match, which covers language packages.

GET /teams/{team_id}/security/sbom?repository_id=… (or artifact_id=… for an image) returns the packages of the newest successful scan as a CycloneDX 1.5 JSON document, and canopy security sbom --repository <id> --team <team_id> prints it. Each package appears once with its package URL; the canopy:scan-completeness property says whether the scan was complete. 404 when the subject has no successful scan yet.