Observations

An observation is one package version the firewall has served, with when and how often. Together they are a usage inventory derived from real traffic: not what manifests declare, but what builds actually fetched. For how observations relate to logs and metrics, see Observability.

EndpointCopy Anchor Link

GET /v1/<namespace-id>/observations

Reading observations requires only namespace access.

CLICopy Anchor Link

The same inventory from the terminal, as a table or as JSON. Without --period it covers today only, so widen the window for a review.

bsfw observations --period 30d --firewall <firewall-id>
bsfw observations --ecosystem npm -o json

Page through with --page-size and --page-token; the CLI prints the token to pass next when more rows are available. Flag-level detail: CLI reference.

Response shapeCopy Anchor Link

{
  "observations": [
    {
      "firewall": "3e7f5cb806f26e3beae2",
      "ecosystem": "npm",
      "packageName": "lodash",
      "version": "4.17.21",
      "internal": false,
      "firstSeen": "2026-05-12T08:03:11Z",
      "lastSeen": "2026-07-03T07:41:56Z",
      "count": 412,
      "vulnerabilities": { "total": 0, "critical": 0, "high": 0, "moderate": 0, "low": 0, "noRisk": 0, "unknown": 0 },
      "monitored": true
    }
  ],
  "nextPageToken": "",
  "total": 1,
  "ecosystems": ["npm"]
}

FieldsCopy Anchor Link

The response also carries nextPageToken, total (rows matching the filters across all pages), and ecosystems (the ecosystems that have observations under the other filters).

Vulnerability summaryCopy Anchor Link

Observations are enriched with the current known vulnerabilities for each package version, bucketed by CVSS score:

How the score is chosen per vulnerability, including the fallback from severity labels to scores, is described under CVSS score on the advisory sources page. A vulnerability with neither is counted as unknown, not at either end of the scale.

For a container image, the summary counts the vulnerabilities in the OS packages installed in the image, the same counts the image's page in the dashboard shows.

The summary reflects advisory data at query time, not at observation time; a version observed in May shows the vulnerabilities known today. That is the useful direction: "what do we currently depend on that is now known-vulnerable" is answered by this summary. To be told when it changes, see risk monitoring.

Risk monitoringCopy Anchor Link

Once a day, the firewall looks up every package version served in the namespace in the last 30 days, across all firewalls, in the latest advisory and malware data. The lookup is by name and version; the package is not downloaded or unpacked again. The firewall records what changed since the previous day. Internal packages and container images are not monitored.

A version's first check is a baseline: it runs shortly after the version is first served and records what is already known without reporting it. A version that drops out of the 30-day window is no longer monitored, and gets a new baseline if it is served again.

Each later check reports a finding in newRisks when one of these changes happens. A change stays in newRisks for 7 days.

Each entry in newRisks:

The same findings are sent as a summary email and as observation.risk.detected webhook events. Setup: Get risk alerts after download.

RelatedCopy Anchor Link

• Concept: Observability
• How-to: Get risk alerts after download, Block vulnerable packages
• Reference: CLI, Advisory sources, Metrics, API