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.
What a finding says
Section titled “What a finding says”| 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.
Was it corrected?
Section titled “Was it corrected?”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.
What to look at first
Section titled “What to look at first”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.
Coverage
Section titled “Coverage”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. |
How scans happen
Section titled “How scans happen”- 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.
In the app
Section titled “In the app”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.
Who is told
Section titled “Who is told”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.
Systems, images, releases and the graph
Section titled “Systems, images, releases and the graph”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.
Asking Cortex about a finding
Section titled “Asking Cortex about a finding”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.
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.
What this does not do yet
Section titled “What this does not do yet”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.
Bill of materials
Section titled “Bill of materials”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.