Observations

Reference for package observations, the traffic-derived inventory of which package versions are in use.

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.

Endpoint

GET /v1/<namespace-id>/observations

Parameter	Description
`firewall`	Limit to one firewall
`period`	`today` (default), `7d`, `30d`, or `90d`, by last-seen time
`pageSize`	Page size
`pageToken`	Cursor from the previous response's `nextPageToken`

Reading observations requires only namespace access.

CLI

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

--ecosystem is applied by the CLI to the page the server returned, not by the endpoint, so a filtered page can come back empty while later pages still hold matching rows. 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 shape

{
  "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 }
    }
  ],
  "nextPageToken": ""
}

Fields

Field	Type	Description
`firewall`	string	Firewall that served the package
`ecosystem`	string	Package ecosystem
`packageName`	string	Package name
`version`	string	Exact version observed
`internal`	boolean	Whether it was served from an internal upstream
`firstSeen`	string	First request for this version
`lastSeen`	string	Most recent request
`count`	number	Requests for this version in the period
`vulnerabilities`	object	Severity summary from current advisory data, see below

Vulnerability summary

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

Bucket	Score
`critical`	9.0 and above
`high`	7.0 to 8.9
`moderate`	4.0 to 6.9
`low`	0.1 to 3.9
`noRisk`	below 0.1

How the effective score is chosen per vulnerability, including the vendor priority and the fallback from severity labels to scores, is described under CVSS score on the advisory sources page.

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 sorting observations by this summary.

Concept: Observability
How-to: Block vulnerable packages
Reference: CLI, Advisory sources, Metrics, API

Observations

Endpoint

CLI

Response shape

Fields

Vulnerability summary

Related

On this page