Appearance
SBOM and Vulnerability Scanner
The Telovix Console uses Trivy to scan container images for software bill of materials (SBOM) data and known vulnerabilities. Images are discovered automatically from sensor heartbeats and queued for scanning. Scan results include per-severity CVE counts and a CycloneDX SBOM export.
Scanner lifecycle: Trivy is automatically managed by the Telovix Console update system. Manual binary uploads are not supported. In air-gapped deployments, the supported Trivy binary is bundled with the Console package.
How image discovery works
Sensors report the container images running on their host in every heartbeat payload via the container_images[] field:
- On Kubernetes nodes, images are collected from the Kubernetes API cache (pods, containers, image digests).
- On non-Kubernetes hosts, images are discovered from the Docker socket.
When the Console receives heartbeat data containing new image references, it deduplicates them (by image digest where available, or image reference otherwise) and queues them for scanning. The same image digest is not re-scanned within the rescan window (default: 24 hours, configured in Console Settings).
Scanner requirements
SBOM scanning depends on the Telovix-managed Trivy binary being present on the Console host. If the scanner is unavailable, scans will not run until the Console package or the Telovix update flow restores it.
To check scanner status, navigate to Settings > Infrastructure in the Console. The SBOM Scanner panel shows available (whether the binary exists and is executable), version, sha256, size_bytes, and is_enabled.
Scan lifecycle
The scan queue loop runs every 30 seconds. Each iteration:
- Resets scans that have been stuck in
runningstate for more than 15 minutes back topending. - Fetches all
pendingscans from the database. - Runs up to the configured maximum concurrent scans (default: 2) in parallel using a semaphore.
- Each scan has a timeout of the configured scan timeout (default: 600 seconds / 10 minutes).
Scan statuses
| Status | Meaning |
|---|---|
pending | Queued and waiting for the next scan cycle |
running | Actively being scanned |
completed | Scan finished; results are available |
failed | Scan failed; error_message contains the reason |
Listing scans
In the Console, navigate to SBOM > Scans to see all scans, most recent first. Use the Status, Cluster, and Image filters to narrow results.
Filter parameters: status, cluster, image (substring match), limit, offset.
Each scan record includes:
scan_id,image_ref,image_name,image_tag,image_digestcluster_name,node_namestatus,trivy_version,triggered_by,error_messagevuln_critical,vuln_high,vuln_medium,vuln_low,vuln_unknownqueued_at,started_at,completed_at,scan_duration_secs
Manually queueing a scan
Requires admin role.
In the Console, navigate to SBOM > Scans and click Queue Scan. Enter the image reference, cluster name, and node name, then confirm.
Discover and queue all images
Scans all known images that have not been scanned within the rescan window. Requires admin role.
In the Console, navigate to SBOM > Scans and click Discover and Queue All. The Console shows queued, skipped_recent, skipped_already_scanning, and total_discovered counts after the operation completes.
Retrying a failed scan
Requires operator role. Only works on scans with status=failed.
In the Console, navigate to SBOM > Scans, filter by status failed, open the scan row, and click Retry.
Exporting SBOM data
CycloneDX for a single image
In the Console, navigate to SBOM > Scans, open a completed scan row, and click Download CycloneDX. The document is generated on demand if not already cached and includes the full component inventory from the scan output.
CycloneDX export for all completed scans
In the Console, navigate to SBOM > Scans and click Export All (CycloneDX) to download a combined CycloneDX document covering all completed scans.
Registry credentials
For images in private registries, store credentials in the Console. They are used to construct a Docker config JSON file that the scanner reads when pulling images.
Stored credentials are never shown in plaintext after being saved (the password_set boolean indicates whether a password exists).
In the Console, navigate to Settings > Infrastructure > SBOM Scanner - Registry Credentials. Click Add registry, enter the registry URL, username, and password, and save. To verify the credentials work, click Test on the credential row.
Scanner updates
In the Console, navigate to Settings > Infrastructure.
- To check for updates, click Check for Updates. The Console contacts the Telovix update service and shows the available version.
- To install an update, click Install Update after the check completes.
- For air-gapped environments, install the refreshed Console package that includes the supported Trivy binary. Manual scanner uploads are not supported.
Proxy support
If the scanner needs to reach a registry through an HTTP/HTTPS proxy, configure the proxy in Settings > Updates. The http_proxy and https_proxy values set there are applied to all scan processes.
Scanner settings
The following values are configurable from Console Settings:
- Maximum concurrent scans: maximum parallel scans (default:
2) - Scan timeout: per-scan timeout in seconds (default:
600) - Rescan interval: hours before re-scanning the same image digest (default:
24)
Limitations
- SBOM scanning requires the Trivy binary to be present. There is no fallback scanner.
- Container image discovery on non-Kubernetes nodes depends on Docker being reachable on the node's Docker socket. Nodes without Docker will not report images.
- Images in private registries require registry credentials to be configured before Trivy can pull them for scanning.
- The scan queue runs on the Console process. In a Console restart, in-progress scans (status
running) are reset topendingafter 15 minutes on the next scan loop iteration. - CycloneDX export is generated on-demand from Trivy output. It is not available for scans that have not completed.