Skip to main content

Endpoint Software Security

ServiceRadar separates endpoint software collection from vulnerability matching. Agents and add-ons collect package and SBOM evidence. Vulnerability intelligence add-ons or Wasm plugins own feed downloads, provider-specific validation, and advisory normalization. The control plane owns the generic advisory contract, source/snapshot metadata, matching, risk scoring, and finding display.

The runtime boundary is intentionally neutral. Native add-ons are not required just because a producer needs durable artifacts, credentials, or large feed snapshots. Wasm plugins and native add-ons both use logical ServiceRadar APIs brokered by agent-gateway. Neither runtime receives direct NATS JetStream Object Store credentials.

Data Path​

Endpoint software inventory follows this path:

  1. The endpoint inventory scanner add-on or compatibility collector runs on an eligible agent.
  2. The agent submits a bounded inventory payload through agent-gateway. Agents do not talk to web-ng or NATS JetStream directly.
  3. ServiceRadar.Inventory.EndpointInventoryIngestor validates the payload, normalizes packages, preserves scanner diagnostics, and records an OCSF Scan Activity event.
  4. If the payload includes a CycloneDX SBOM, EndpointInventoryArtifactStore uploads the raw SBOM through datasvc object storage.
  5. EndpointInventoryArtifactPersistence stores artifact metadata in platform.endpoint_inventory_artifacts and de-duplicates raw content in platform.endpoint_inventory_artifact_contents.
  6. Current package rows are stored in platform.endpoint_inventory_packages and normalized package coordinates are stored in platform.endpoint_packages.
  7. The central matcher compares current package and SBOM coordinates against producer-normalized advisories and writes device-scoped rows to platform.endpoint_vulnerability_matches.

The raw SBOM object key is a content-addressed path:

endpoint-inventory/by-hash/<sha256>.cdx.json

The object store is durable evidence storage. The CNPG rows are the query and UI surface.

Scanner Contracts​

Scanner add-ons should emit generic ServiceRadar contracts:

  • scan activity metadata
  • package rows and SBOM artifacts
  • scanner plugin/source diagnostics
  • OCSF-derived findings
  • display contracts for event and security views

The shared agent, gateway, ingest, database, and UI paths should not special-case scanner implementations. Scanner-specific details such as OSV ScaLibr plugin names, output translation, native config, and version metadata belong inside the scanner add-on package and the contracts it submits.

The existing package-manager collectors are compatibility fallback code during the migration to scanner add-ons. New extraction work should target scanner add-ons rather than adding more bespoke parser code to the agent.

Endpoint Inventory Profiles​

Use Settings > Agents > Endpoint Inventory to control where endpoint software inventory runs. Profiles target agents with SRQL, so the normal path is to define the desired device cohort once and let reconciliation create the add-on assignments.

Recommended workflow:

  1. Create or edit an endpoint inventory profile.
  2. Set the target SRQL query, for example in:devices for every eligible agent or a narrower query such as in:devices hostname:%pve%.
  3. Enable the profile.
  4. Reconcile the profile. Reconciliation evaluates the SRQL query, filters for eligible connected agents, and creates or updates the endpoint inventory add-on assignments.
  5. Open a device and use the Software tab to confirm the latest scan, package rows, source diagnostics, SBOM artifact hashes, and vulnerability matches.

Operators should not have to manually assign the endpoint inventory add-on to each agent after defining a profile. Manual assignment is useful for break-glass or one-off testing, but SRQL-backed profiles are the fleet workflow.

If the Software tab says a scan reported many packages but only a few current rows loaded, treat that as an ingest or retention problem. The scan summary, source diagnostics, package-set hash, artifact hash, and upload reason are shown so the operator can distinguish "scanner found nothing" from "scanner found packages but persistence did not keep them."

Vulnerability Intelligence Sources​

Vulnerability feeds are source-owned. A native add-on or Wasm plugin fetches, validates, and normalizes provider data, then submits a serviceradar.advisory_feed.contract.v1 batch. Core does not include built-in NVD, CISA, VulnCheck, OSV, or other provider parsers.

Each source definition tracks:

  • provider and feed key
  • enablement
  • contract type
  • retention period
  • last submit status and error
  • add-on/plugin provenance in metadata

Operators can disable matching for a registered source from the control plane. Changing provider URLs, credentials, schema rules, and download cadence is owned by the producer package rather than core.

Common first-party sources include CISA KEV, NVD/NIST feeds, VulnCheck KEV, and VulnCheck NVD mirrors. Third-party producers can add more sources without core code changes when they emit the same advisory batch contract.

Credential and artifact handling is always gateway-mediated:

  • Producers ask the host SDK for named credentials instead of reading platform secrets directly.
  • Producers stage raw or normalized snapshots through artifact APIs such as open, write, commit, abort, metadata, and digest validation.
  • The agent forwards those calls to agent-gateway, and agent-gateway writes to the internal object path.
  • Producers submit advisory batches with the committed object identity and validation metadata.

Do not build a producer that writes directly to NATS JetStream Object Store or calls web-ng from an agent. That bypasses ServiceRadar's edge trust boundary.

Scheduled Feed Producers​

Feed producers that need recurring downloads declare producer_schedules in their package manifest. The schedule contract is owned by the plugin or add-on package and includes the action id, cadence bounds, optional cron support, jitter, required settings, credential requirements, payload template, and target scope. Core persists that contract when the package is imported or approved.

Operators configure cadence, enablement, credentials, and target scope from Settings -> Security -> Vulnerability Feeds. The UI is generated from the package contract and stores operator choices separately from the package manifest, so upgrading a producer does not silently overwrite local schedule state.

Due runs are dispatched by the core AshOban scheduler through the existing agent commandbus. Wasm producers use plugin.run_action; native add-on producers use addon.run_command. Both receive a serviceradar.producer_schedule_run.v1 payload through agent-gateway and the selected agent. Credential selections are converted into scoped broker grants before the command reaches the agent; raw credential refs remain platform state. Producers never receive direct access to web-ng, core-elx, or NATS JetStream object storage.

Snapshot Validation​

Accepted raw or normalized feed snapshots are stored by the producer through gateway-mediated artifact storage under a producer-owned object key such as:

vulnerability-feeds/<provider>/<feed-key>/<sha256>.<format>

The control plane records producer-supplied snapshot metadata in platform.vulnerability_feed_snapshots, including source URL when provided, object key, content hash, validation result, size, and accepted timestamp.

Provider-specific validation happens in the producer. For example, a CISA KEV producer should validate the published JSON Schema, and a VulnCheck producer should verify backup pointer SHA-256 values before submitting a batch. Core records that validation result but does not implement those provider parsers.

Large pointer JSON feeds and zip archives can be processed by a Wasm plugin when the Wasm host exposes the needed gateway-backed APIs for credentials, bounded download, chunked artifact writes, digest validation, and scheduling. Use a native add-on only when the producer needs runtime capabilities outside the Wasm sandbox, not because it needs the object store.

Advisory Normalization​

Accepted producer records are stored in platform.vulnerability_advisories. An advisory preserves:

  • provider and feed key
  • source object identity
  • CVE or advisory id
  • severity and CVSS fields when available
  • publication and modified timestamps
  • KEV or exploit metadata
  • references
  • affected coordinates and match semantics

Affected coordinates keep their type. CPE, PURL, package, ecosystem, vendor, and version range data should not be collapsed into an opaque string because the matcher must be able to explain why a package matched.

Matching​

Matching runs in the control plane. Agents do not download vulnerability feeds and do not run feed matching jobs.

The matcher reads current endpoint package rows and advisory coordinates, then writes device-scoped vulnerability matches with:

  • device UID and agent id
  • endpoint package and scan references
  • advisory reference and CVE/advisory id
  • feed provider and coordinate type
  • installed version and fixed version evidence
  • match confidence
  • KEV and exploit flags
  • first seen, last seen, and resolved timestamps

The Software tab uses these match rows to show actionable package risk beside the inventory that produced it. Raw event pages remain audit context, not the primary remediation workflow.

Security Views​

Endpoint inventory, Trivy, Falco, Bumblebee, and PowerDNS all feed the Security experience through OCSF-derived contracts.

  • /security is the tactical work queue. It shows current scanner coverage, security finding severity, scan activity, DNS security activity, normalized Trivy vulnerability rows, and active finding drill-downs.
  • /dashboards/security-findings is a customizable dashboard package. It is for operators who want editable posture panels and saved SRQL-backed widgets.
  • Device Software tabs are the remediation view for host packages and endpoint vulnerability matches.
  • Raw event pages are audit and troubleshooting context. Integrations should ship display contracts so event details expose useful fields before the raw JSON.

Trivy report events are aggregate lifecycle records. The actionable rows are the child vulnerability findings: CVE, title, severity, affected package or image, installed version, fixed version, resource, namespace, references, and observed time. Falco detection details should expose rule, priority, process/container, Kubernetes node/pod, device correlation, and source evidence.

Diagnostics​

Use these checks when endpoint inventory or scanner data looks incomplete:

  • Confirm the agent is connected and advertises the endpoint inventory capability.
  • Reconcile the endpoint inventory profile and verify the add-on assignment state.
  • Open the device Software tab and compare reported package count with loaded current rows.
  • Review source diagnostics for failed package managers, truncated output, or disabled sources.
  • Check package-set hash and artifact hash changes to verify whether a new scan produced new evidence.
  • Check /security for scan activity and source coverage.
  • Use Observability drill-downs for raw OCSF events when a display contract or normalized child row is missing.
  • If normalized Trivy child rows are empty while aggregate Trivy events exist, verify the Trivy child-finding migration is applied and backfill or replay the report events.