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.
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.
Related
- Concept: Observability
- How-to: Block vulnerable packages
- Reference: Advisory sources, Metrics, API