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 |
ecosystem | Limit to one ecosystem, such as npm or oci |
search | Limit to package names containing this text |
period | today (default), 7d, 30d, or 90d, by last-seen time |
pageSize | Rows per page. Default 50, maximum 500 |
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 jsonPage 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, "unknown": 0 }
}
],
"nextPageToken": "",
"total": 1,
"ecosystems": ["npm"]
}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 |
manifestDigest | string | Container images only. The digest of the exact image that was served, since a tag can move and a multi-platform tag names several images |
platform | string | Container images only. The platform served from a multi-platform image, such as linux/amd64 |
imageScan | string | Container images only. scanned, or not_scanned when nobody has scanned the image yet, in which case an empty summary does not mean no vulnerabilities |
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 summary
Observations are enriched with the current known vulnerabilities for each package version, bucketed by 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 |
unknown | no score at all |
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 sorting observations by this summary.
Related
- Concept: Observability
- How-to: Block vulnerable packages
- Reference: CLI, Advisory sources, Metrics, API