SecureChain

User guide

Findings in the portal

The portal keeps each scan that you send, matches it with the advisory data and the TuxCare catalogue, and shows what to fix first. This page tells you how to read the findings, triage them, track the fix deadlines and the CRA clocks, record releases, and get alerts.

Open your workspace #

Go to your workspace address, for example https://name.sc.tuxcare.cloud, and select the button of your sign-in provider. If an admin added a single sign-on provider, the page shows its button too. You can also sign in at sc.tuxcare.cloud and open the workspace from Your workspaces. A person who has not accepted the terms sees the terms page after the first sign-in. Read it, then select Accept and continue. The portal asks one time for each workspace, and again only when TuxCare publishes new terms. The acceptance covers the SecureChain CLI for this workspace. An admin sees the date of each person in the Terms accepted column of the Users page.

The workspace menu is the button at the right of the header. It shows your role. It holds the pages that manage the workspace, Help (this guide), and Sign out.

The header of the portal with the workspace menu open: the email address and the role, the Manage list, Help, and Sign out.
The workspace menu, open.
  1. The button of the menu. It shows your role, and on a wide screen your email address.
  2. Manage: the pages that manage the workspace. An admin sees all of them.
  3. Help opens this guide. Sign out ends the session.
  4. The theme control: System, Light, or Dark. On a narrow screen, it is in the workspace menu.

To end a session on another device, open Access tokens in the workspace menu and select Sign out on the row of the session in Browser sessions.

When you ask TuxCare for help, a TuxCare engineer can open a read-only view of your workspace. A banner shows TuxCare staff — read only during that view.

Roles #

Each user has one role for the whole workspace.

ActionAdminMemberViewer
Read repositories, scans, and findingsYesYesYes
Send scansYesYesNo
Triage findings, set the default branch, mark releases, record a CRA decisionYesYesNo
Make and revoke their own tokensYesYesYes
Make scoped tokens and tokens for other usersYesNoNo
Register, rename, and delete repositories; manage products and product releasesYesNoNo
Manage users, departments, notifications, fix deadlines, and settings; read the audit logYesNoNo

A member or a viewer with a seat in a department sees only the repositories of that department. A user with no seat sees every repository. Every number in the portal counts only the repositories that you can see.

Find your way #

The top bar has six pages. Each page answers one question:

PageThe question
OverviewHow is the workspace now, and does it get better or worse?
RepositoriesWhich repositories need work, and what is wrong in one repository?
VulnerabilitiesWhich advisories affect us, and where? Are we affected by a given CVE?
PackagesWhere do we use a package, and at which versions? What do the TuxCare builds cover?
RemediationDo the teams fix the findings before the fix deadline?
ComplianceWhich findings start a CRA clock, and which reports does an auditor need?

On a narrow screen, select Menu to see the six pages and the search field.

The search field in the header finds an advisory, a package, or a repository. Press / to go to it. Type the text, then select the page to search. Press Enter to open the first choice.

Most pages keep their filters in the page address. Copy the address to share a filtered view. Select the ? button next to a label to read what the label means.

Overview #

The Overview is the first page. It shows the security state of the workspace for a department and a period (the last 30, 90, or 180 days).

The Overview page, with five tiles, two charts of the open findings, and the Fix first table of five packages.
The Overview page.
  1. The department, the period, and Export.
  2. The five tiles. Select a tile to open the page that explains it.
  3. The two charts. Table shows the same numbers as a table.
  4. Fix first: the package upgrades that close the most risk.
Open findings
The open findings of every repository, the change in the period, and a bar of the severities.
Critical · known exploited
The open critical findings and the open known-exploited findings. The line under them counts the open CRA clocks.
Past fix deadline
The open findings that are older than their fix deadline, and the share of findings that closed in time.
Fixable now
The open findings that have a fix: an upstream version or a TuxCare build.
Scan coverage
The repositories that sent a scan in the last 7 days. It also counts the stale repositories (no scan for 14 days), the repositories with no scan, and the repositories with a release that is not evaluated.

Repositories #

The Repositories page lists each repository of the workspace. A repository appears when its first scan arrives. An admin can also add one before the first scan with Register repository.

The Repositories page, with the filters and a table of repositories, each with a grade, its open findings, a trend line, and its last scan.
The Repositories page.
  1. Register repository adds a repository before its first scan. Only an admin sees it.
  2. The search field, the lists, the quick filters, and the sort order.
  3. Each row is a repository. Select its name to open it.
  4. The rule of the grade.

Each row shows the grade, the open findings by severity (for example 1 C · 4 H · 7 M · 0 L), the fixable findings, a 6-week trend, the branch that the row counts, and the age of the last scan. A last scan older than 14 days shows in an amber chip: check the CI job of that repository.

The quick filters keep the rows of one kind: Has critical, Known exploited, Stale scan, or Never scanned. Sort sorts by Risk, Last scan, or Name.

The grade #

Each repository gets a grade from A (good) to F (bad), from the open findings of its tracked refs. The worst rule that applies sets the grade.

GradeRule
ANo open critical or high finding, and at most 10 open medium findings.
BOne or more open high findings, all within the fix deadline.
CAn open high finding is past the fix deadline, or more than 10 medium findings are open.
DOne or more open critical findings.
FAn open critical finding is past the fix deadline, or an open finding is known to be exploited.

A repository with no complete, matched scan has no grade. A repository with a release whose match failed never gets grade A. The rules use the fix deadlines of your workspace.

A repository #

Select a repository to open its page. The header shows the grade, the name, the departments, the count of components, the last scan, and the commit. It also names the token and the CLI version that sent the scan, for example sent by ci-main (tux_…ab12), CLI 0.1.18.

The page of the repository github.com/acme/web-shop, with the Findings tab open, the findings grouped by package, and one package selected for bulk triage.
The page of a repository, with the Findings tab open and one package selected.
  1. The branch selector, Compliance report, and More.
  2. The four tiles.
  3. The tabs. Each tab shows its count.
  4. The filters of the findings, and the choice By package or Flat list.
  5. The bar of the bulk triage. It shows when you select a finding.
  6. The header row of a package: the findings, the worst severity, and the upgrade that closes all of them.
Branch
Selects a branch or a tag. All refs (tracked branch) shows the tracked branch: the default branch, else main, else master, else the newest complete scan. The default branch shows · default.
Slot
A slot is one project path and one set of ecosystems. A monorepo branch can have one slot for each CI job that scans it. When a branch has two or more slots, the page shows a Slot list. See More than one project in a repository.
More
Opens the export and the download of the SBOM of the scan. A member or an admin can make the selected branch the default branch. An admin can rename the repository, set its departments, or delete it. A delete removes all scans, findings, and repository tokens of the repository, and cannot be undone.

Right after a scan, the page says that the scan is being matched and shows the last matched scan. The page updates by itself when the match is done.

The tiles show the open findings, the changes since the previous scan (see Changes), the findings that you can fix now, and the findings past their fix deadline.

The Findings tab #

The tab lists each known vulnerability in the scan, the worst first.

The Fix plan tab #

The fix plan has one row for each package to change: the current version, the version to move to, the source of the fix (a TuxCare build or upstream), the findings that the change closes, and the worst severity. A package with a known-exploited finding comes first. To apply the plan, see Fix vulnerabilities.

The Fix plan tab, with one row for each package: the current version, the version to move to, and the source of the fix.
The Fix plan tab: one row for each package to change.

The Dependencies tab lists each package of the scan with its version, its ecosystem, its scope (direct or transitive, with the packages that pull it in), its open findings, and its TuxCare status: TuxCare build, TuxCare build available, No TuxCare build, or Not assessed.

The Dependencies tab of a repository, with seven packages. The TuxCare column names the TuxCare build of each package.
The Dependencies tab. The TuxCare column names the build that each package can move to.

Changes since the last scan #

The tile Since scan #N compares the scan with the previous scan of the same branch: for example +3 new and −3 resolved findings. Select Show the changes to see the lists. When a new advisory comes out, the portal checks the stored scans again, so a new finding can show with no new scan.

The Scans tab #

The tab lists each scan of the repository, with its branch, commit, path, status, and dates. Select a scan number to see its findings, dependencies, and fix plan, read only. Select Back to the newest scan to leave that view. Select SBOM to download the scan as a CycloneDX file. A member or an admin can select Mark as release on a complete scan. See Releases.

Only a complete scan feeds the findings and the comparisons. A partial, empty, or failed scan is not a clean result, and the page shows a warning for it.

The base image of a container image #

The page of a container image shows the Base image panel above the tabs. The panel shows:

The Base image panel: the base node:20-bookworm, an outdated build, 2 of 3 open findings from the base, and three upgrade rows: Rebuild with the same tag, Next major version, and Smaller variant.
The Base image panel of an image with an outdated node:20-bookworm base.

TuxCare keeps a list of known base images: the official Docker images and the TuxCare images, with the layers and the packages of each build. The portal finds the base of your image in two ways:

  1. By the layers. The portal compares the layers of your image with the layers of each known base image. The base image whose layers start your image, with the most layers, is the base. A match needs two layers or more.
  2. By the declared base. When no layers match, the portal reads the base that the image declares: the annotations org.opencontainers.image.base.name and org.opencontainers.image.base.digest. A digest must be the digest of a known build. A name alone selects the build that the tag points at now.

A finding comes from the base when its package is in the base image. With a match by the layers, a finding also comes from the base when its package is in a layer of the base. The other findings with a known layer come from your layers.

Each row of the table is one kind of upgrade. A row shows only when it removes a finding, except Rebuild with the same tag. When two rows name the same image, the image shows once.

Rebuild with the same tag
The newest build of your tag. It shows when your image uses an older build. Often a rebuild of your image is enough.
Newest in the same line
The newest version with the same major version and variant, for example node:20.18.0-bookworm for node:20-bookworm.
Next major version
The newest build of the highest major version above yours, with the same variant, for example node:22.11.0-bookworm. A major version can change how your application runs: test it.
Smaller variant
A slim or alpine variant of the same major version. It has fewer packages, so it can have fewer findings.
TuxCare image
A TuxCare image of the same operating system family that removes the most findings.
Keep this base with TuxCare ELS
Shows when the operating system of the base is past its end of life and TuxCare Endless Lifecycle Support covers it. The count is the base findings that have an ELS fix. The row links to the ELS page.

Removes counts the open findings of the base that the upgrade does not have. Adds counts the findings of the upgrade that the base of your image does not have now. Critical and High count the removed findings of that severity. The counts compare the advisory and the package, not the version. An ignored finding does not count. Select Copy to copy the FROM line of the upgrade, for example FROM node:22.11.0-bookworm.

When the portal cannot give advice, the panel tells you why:

The panel saysWhyWhat to do
This scan has no layer data.The scan does not list the layers of the image.Scan the image again with a current scan-worker or CLI.
The base image is not in the list of known base images.No known base image matches the layers, and the declared base, if any, is not in the list.Nothing in the portal. The findings of the image still show, with the origin Unknown.
The scan does not say which layer holds each package.The portal found the base, but the scan does not give the layer of each package, and no package with a finding is in the base image. The portal cannot split the findings.Scan the image again with a current scan-worker or syft.
Base-image advice is not set up for this workspace.The portal does not read the list of known base images.On your own install, the operator sets sync.base_images_url.
The portal could not match this scan.The match of the scan failed.Scan the image again. If the error stays, get help.

When the list of known base images is more than 3 days old, the panel says that the advice may be out of date.

On the page of an image, the Findings tab has an Origin filter: All, Base image, Your layers, and Unknown. Unknown is a finding whose package is not in the base image and whose layer the scan does not give, or a finding of an image with no known base.

A finding #

A finding is one advisory in one package of one scan. Its page tells you how to fix it and where else it is.

The page of the finding CVE-2021-23337 in lodash, with How to fix, the description, the list Affected in this workspace, the triage card with Ignored and 90 days selected, and the timeline.
The page of a finding.
  1. How to fix: the recommended fix, the alternatives, and the command.
  2. Affected in this workspace: each repository that has this advisory.
  3. The triage card: the state, the reason, and for an ignore, the time.
  4. The timeline of the finding.

A viewer sees the same page with no triage controls.

Triage findings #

A member or an admin sets the triage state of a finding. The state stays with the finding in later scans of the same branch.

new
Nobody has looked at the finding yet.
acknowledged
Somebody looked at it and accepts it for now. It stays open: it still sends alerts and counts toward its fix deadline.
ignored
The finding is muted. It is not open, sends no alerts, and is never past its deadline. Give a reason. The ignore ends after 30 days, after 90 days, on a date, or never. Then the finding goes back to new.

To triage one finding, open its page. In the Triage card, select the state, type the Reason, and for Ignored select the time under Ignore for. Select Save.

Triage many findings #

  1. Open the Findings tab of a repository, and filter it.
  2. Select the check box of each finding. The box of a package header row selects all findings of the package. The box in the table header selects every finding that the filters show.
  3. In the bar above the table, select Acknowledge, Ignore…, or Mark new.
  4. For Ignore…, type the Reason, select the time, and select Ignore.

One change applies to at most 500 findings. If the portal refuses one finding, no finding changes, and the page shows the error.

The justification of an ignore #

An ignore can also have a Justification. It tells a reader why the finding does not affect you, and the VEX file uses it. The values come from CycloneDX: the code is not present; the code is not reachable; it needs a configuration, a dependency, or an environment that you do not have; or it is protected by the compiler, at run time, at the perimeter, or by another control.

Vulnerabilities #

The Vulnerabilities page lists each advisory one time, with every repository that it affects. Use it to answer are we affected by this CVE?

The Vulnerabilities page, with the four steps of the funnel, the filters, and the table of advisories. One advisory shows its three repositories.
The Vulnerabilities page.
  1. The four steps of the funnel. Select a step to set its filters.
  2. The search field and the filters.
  3. An advisory with its list of repositories open.

Search for an advisory id that no scan has, and the page says Not affected.

Packages #

The Packages page lists every package of the tracked refs. The Inventory tab shows where each package is used.

The Inventory tab of the Packages page, with the package lodash selected and its usage panel open: five repositories, each with its version.
The Inventory tab, with the package lodash selected.
  1. The two tabs.
  2. The search field and the filters.
  3. The versions in use of a package.
  4. The usage panel of the selected package.

TuxCare coverage #

The TuxCare coverage tab counts the packages by TuxCare verdict:

Covered
You already ship a TuxCare build.
Hardenable
A TuxCare build with the fixes exists, and your subscription includes it. Run securechain harden.
Unprotected
A TuxCare build with the fixes exists, and your subscription does not include it.
No coverage
No TuxCare release line covers the package. TuxCare counts it as a request for coverage.
Frozen, Sunset
A frozen line keeps its last build and gets no new fixes. A sunset line gets no more fixes.

Remediation #

The Remediation page shows how fast the teams fix findings, against the fix deadlines.

The Remediation page, with the share fixed in time, one card for each severity, the findings past the fix deadline, and the table by department.
The Remediation page.
  1. The period, the department, and Edit deadlines.
  2. Fixed in time for the whole period.
  3. One card for each severity.
  4. The open findings that are past their fix deadline.
  5. The fix state of each department.
Fixed in time
The findings that closed before their deadline, divided by the findings that closed in the period.
Mean time to fix
The mean time from open to close of the findings that closed in the period. A finding opens at its first sighting in its slot, and closes at the first complete, matched scan of the slot that does not have it.
Past the fix deadline
The open findings that are older than their deadline. Fix these first.

Fix deadlines #

A fix deadline is the number of days to fix an open finding, from its first sighting.

SeverityDefault deadline
Critical, and every known-exploited finding7 days
High30 days
Medium90 days
Low, and a finding with no rating180 days

An acknowledged finding can pass its deadline. An ignored finding cannot. An admin changes the deadlines in Settings › Fix deadlines: 1 to 3650 days, and a worse severity cannot have a longer deadline. The grades and the counts use the new values at once.

The Fix deadlines card of the Settings page, with one field for each severity and the Save button.
Settings › Fix deadlines.

Releases #

A release is a scan that you mark as a build that you ship. The portal keeps it and checks it against each new advisory. Record a release from CI with securechain sca --release NAME (see Record a release), or select Mark as release on the Scans tab.

StateAlertsIn the workspace viewsChecked against new advisories
SupportedYesYesYes
DeprecatedNoYesYes
ArchivedNoNoNo: the portal freezes the findings in a snapshot.
The Releases tab of the repository web-shop with two releases. v2.3.1 is deprecated, and its row has Report, VEX, a state control, and Delete. v2.4.0 is supported, from Acme 3.2, and its state control is off, with the text The state comes from Acme 3.2.
The Releases tab of a repository, as an admin sees it.
  1. The Releases tab. The number counts the releases that are not archived.
  2. Show archived adds the archived releases to the list.
  3. The state of each release, for example supported, from Acme 3.2.
  4. Report opens the release report. VEX saves the VEX file.
  5. The state control and Delete. Only an admin sees Delete.
  6. A product release decides the state of this release, so its state control is off.

A release that is not evaluated #

When the portal checks a release again and the check fails or has not finished, the release is not evaluated. The row of the repository shows Not evaluated, the release, and the cause: matching or match failed. Its findings are not in the counts, and it is not clean. matching is normal for some seconds after a CI job sends the release. After match failed, the repository cannot get grade A until a later check succeeds. If the mark stays, contact TuxCare.

Product releases #

A product release is the set of releases that you ship together, one release of each repository of a product. For example, Acme 3.2 holds v1.3 of the web repository and v2.0 of the api repository.

  1. Open Compliance and select Releases on the product.
  2. As an admin, type a name under Name of the new product release, and select New product release.
  3. Select Edit members, pick one release for each repository, and save.
The product Acme Shop on the Compliance page with its Releases panel open. The panel has Show archived, the field Name of the new product release with the button New product release, and the product release Acme 3.2: state supported, members web-shop v2.4.0 and billing-api v1.8.0, with Report, VEX, a state control, Edit members, and Delete.
The product releases of a product, as an admin sees them.
  1. Releases opens and closes the list of product releases.
  2. The name of a new product release, and New product release. Only an admin sees them.
  3. A product release: its name, its state, its date, and its members.
  4. Report opens the product release report. VEX saves the VEX file.
  5. The state control, Edit members, and Delete. Only an admin sees them.

Export VEX #

A VEX file tells your customers which known advisories affect a release. Select VEX on a release or a product release. The file is CycloneDX 1.6 JSON. Every role can export it. The state of each advisory comes from the triage:

What the portal knowsVEX state
Open and new, or an ignore that has endedin_triage
Acknowledgedexploitable
Ignored, and the ignore has not endednot_affected, with the justification and the reason
Fixed by a TuxCare buildresolved, with the response update

An advisory in two packages of the release has one entry, with the most open state. A known-exploited advisory has the property tuxcare:exploited. The file of an archived release is frozen at the time of the archive (tuxcare:frozen_at). A script gets the file at GET /api/v1/releases/{id}/vex or /api/v1/product-releases/{id}/vex.

The release report #

Select Report on a release or a product release to open its compliance report. The report of a supported or deprecated release shows the findings of today. The report of an archived release shows Frozen at and the findings at the time of the archive. A script gets the data at GET /api/v1/releases/{id}/report.

Compliance #

The Compliance page holds the EU Cyber Resilience Act (CRA) clocks, the products, and the reports for an auditor.

The Compliance page, with two CRA clocks and the list of two products.
The Compliance page.
  1. A CRA clock, with its three times.
  2. Record decision records what you did about the clock.
  3. The products of the workspace.

CRA clocks #

Article 14 of the CRA tells a manufacturer to report an actively exploited vulnerability in a product: an early warning in 24 hours, and a notification in 72 hours. The portal starts a clock for each open known-exploited finding.

The portal shows the candidates. You decide if a finding is in a product that you sell and if you must report it.

Products #

A product is a named set of repositories that you place on the market. The CRA applies to a product. An admin selects New product, types the name, selects the repositories, and selects Save. A product does not change who can see a repository: departments do that. A delete keeps the repositories, and removes the product releases of the product.

Compliance report #

The compliance report is a document about one repository for an auditor. Open the repository, select a branch if you want, select Compliance report, then Print or save as PDF. Every role can open it. It has these sections:

A script gets the same data at GET /api/v1/repos/{id}/report, with ?ref= for a branch.

Export findings and dependencies #

Download the findings or the dependencies as CSV or JSON. For one repository, select More on its page. For all repositories that you can see, select Export on the Overview. Select Findings or Dependencies, then CSV or JSON, then Download.

Each scan also has a CycloneDX SBOM: see The Scans tab.

Alerts #

An admin sets up alerts on the Notifications page of the workspace menu. The portal sends an alert when a scan adds a vulnerable package, or when a new advisory affects a package that you already ship. Alerts cover the default branch and the supported releases. For a feature branch, use the pull request gate.

The Notifications page, with the alert settings, the Email delivery section, and one outbound webhook.
The Notifications page.
  1. Minimum severity, Delivery, and the weekly digest.
  2. The email addresses that get the alerts.
  3. The Slack webhook.
  4. Send test sends a test alert with the saved settings.
  5. Email delivery: the addresses that email does not reach.
  6. Outbound webhooks: your own endpoints.
Minimum severity
Findings below this level send no alert. A known-exploited finding always sends one. An ignored finding never does.
Delivery
immediate, or a daily digest at 00:00 UTC. The Weekly digest is a 7-day summary, sent also when nothing changed.
Email to
At most 10 addresses, separated by commas. Empty means every active user. In a hosted workspace, each address must be an active user who signed in at least once with the TuxCare sign-in.
Slack incoming webhook
An https Slack webhook URL.

A new scan sends its alert at once. After a feed update, the portal waits until the rechecks end (at most about 30 minutes), then sends one message for each repository. Select Send test to check the setup: at most 5 tests an hour.

Outbound webhooks #

Add an https endpoint under Outbound webhooks. Copy the signing secret: the portal shows it one time. Each alert arrives as a JSON POST with id, kind, created_at, and payload, and two headers:

Compute the HMAC, compare it with the header, and refuse an old timestamp. The portal does not follow redirects. When the endpoint does not answer 2xx, the portal tries again after 1, 5, and 15 minutes. In a feed-update alert, each finding also has a refs list.

Email that does not arrive #

The portal stops email to an address at once after a hard bounce or a spam report, and after three failed deliveries in a row over at least three days. The other admins get an email. Email delivery lists each address and the reason, and the Users page marks the user Email stopped. Correct the address, then select Resume email. Resume an address that reported spam only when the person asks for the email.

Terms #

Severity
The highest CVSS score of the group of records that describe one vulnerability (a CVE and its aliases).
open
The advisory applies to the version that you ship, and the finding is not ignored.
new, reopened
new: the finding is on this branch for the first time. reopened: the previous scan did not have it, and this scan has it again.
fixed by TuxCare
You ship a TuxCare build (a version that ends in -tuxcare.N) that has the fix.
Known exploited
A named source, for example CISA KEV or ENISA EUVD, says that attackers use the vulnerability. It passes any alert severity filter, uses the critical fix deadline, and starts a CRA clock.
Not assessed
The portal could not check the package, for example because no advisory source covers its ecosystem. It is not clean.
Tracked refs
The default branch and the supported and deprecated releases of a repository. The workspace views count these only.
Slot
One project path and one set of ecosystems on a branch.

Next: Fix