Architecture & data flow
How the StackRadar scanner works: what runs in your cluster, exactly what data leaves it, how SBOMs are matched against vulnerabilities, and where your data is stored.
The two halves
StackRadar is split deliberately into an open-source scanner agent that runs in your cluster and a managed backend that stores SBOMs and does vulnerability matching. You can audit everything that runs inside your infrastructure on GitHub; the heavy state — a 300K+ record vulnerability database and your scan history — lives outside your cluster so there's nothing to operate or keep fresh in it.
What runs in your cluster
A single Helm release in the stackradar namespace. The agent watches the Kubernetes API for pods starting anywhere in the cluster. When a pod starts with a container image the agent hasn't already reported, it:
- Inspects the image and generates a CycloneDX 1.6 SBOM — a structured inventory of every package inside it (see the CycloneDX format reference).
- Checks with the API whether that SBOM already exists (a content-hash lookup via
GET /v1/sboms/check) so unchanged images aren't re-uploaded. - Uploads new SBOMs via
POST /v1/sboms/upload/cyclonedx, authenticated with the cluster-scoped API key.
Alongside that, the agent sends a periodic heartbeat (POST /v1/heartbeat) carrying its version in an X-Scanner-Version header, which is what powers the cluster health and version display in the dashboard.
Because scanning is triggered by pod starts rather than a schedule, coverage tracks your deploys: a new image is scanned the moment it starts running, and there is no window where a scheduled scan hasn't caught up yet.
Exactly what data leaves the cluster
| Sent | Not sent |
|---|---|
| CycloneDX SBOMs: package names, versions, PURLs, licenses, hashes | Source code or image layer contents |
| Image references and workload/cluster metadata for attribution | Environment variables, ConfigMaps, Secrets |
| Heartbeats: scanner version, cluster ID | Application traffic or logs |
All traffic is HTTPS to a single endpoint, api.stackradar.io, and all data is stored in the EU — relevant if you're working toward CRA or NIS2 compliance and need to answer "where does our dependency inventory live?".
What happens server-side
On upload, the SBOM is validated against the CycloneDX 1.6 schema, parsed, and its components stored. Each component is then matched against StackRadar's local mirror of the OSV.dev vulnerability database — matching is by Package URL and affected version ranges, described in detail in how vulnerability matching works.
The OSV mirror is synced continuously: incremental updates poll OSV.dev's change feed, so a newly published advisory is matched against SBOMs you already uploaded — you don't need to redeploy or rescan anything to learn that yesterday's image is affected by today's CVE.
Authentication model
The agent authenticates with a cluster-scoped API key sent in the X-API-Key header. A key identifies exactly one cluster in one organization, which is what lets the dashboard attribute every SBOM to the cluster it came from — and lets you revoke one cluster's access without touching the others. Full details in API keys & cluster scoping.
Verifying this yourself
Everything above is observable. Watch what the agent does:
# See the scanner's workload and its (lack of) privileges
kubectl get pods --namespace stackradar
kubectl describe pod --namespace stackradar -l app.kubernetes.io/name=stackradar-scanner
# Read the source of what's running
# https://github.com/lockdep/stackradar-scanner