74 lines
2.2 KiB
Markdown
74 lines
2.2 KiB
Markdown
# Concelier Evidence Batch API (draft v1)
|
|
|
|
Path: `POST /v1/evidence/batch`
|
|
Auth: same as other advisory read endpoints; requires tenant header `X-Stella-Tenant`.
|
|
Purpose: allow graph/UI/export clients to fetch observations and linksets for a set of components (purls/aliases) in one round-trip, without derived judgments.
|
|
|
|
## Request
|
|
```json
|
|
{
|
|
"items": [
|
|
{
|
|
"componentId": "component-a",
|
|
"purls": ["pkg:maven/org.example/app@1.0.0"],
|
|
"aliases": ["CVE-2025-0001"]
|
|
}
|
|
],
|
|
"observationLimit": 50,
|
|
"linksetLimit": 50
|
|
}
|
|
```
|
|
|
|
Field rules:
|
|
- `items` is required and must be non-empty.
|
|
- Each item must supply at least one identifier (`purls` or `aliases`).
|
|
- `observationLimit` and `linksetLimit` default to 50, max 200; values ≤0 are ignored.
|
|
|
|
## Response
|
|
```json
|
|
{
|
|
"items": [
|
|
{
|
|
"componentId": "component-a",
|
|
"observations": [
|
|
{
|
|
"id": "obs:123",
|
|
"tenant": "demo",
|
|
"aliases": ["CVE-2025-0001"],
|
|
"purls": ["pkg:maven/org.example/app@1.0.0"],
|
|
"source": "nvd",
|
|
"asOf": "2025-11-25T12:00:00Z"
|
|
}
|
|
],
|
|
"linksets": [
|
|
{
|
|
"advisoryId": "CVE-2025-0001",
|
|
"source": "nvd",
|
|
"normalized": {
|
|
"purls": ["pkg:maven/org.example/app@1.0.0"]
|
|
},
|
|
"createdAt": "2025-11-25T12:00:00Z"
|
|
}
|
|
],
|
|
"hasMore": false,
|
|
"retrievedAt": "2025-11-25T12:00:01Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Determinism:
|
|
- Results ordered by provider ordering returned from storage; clients must not assume stable sort keys beyond the documented arrays.
|
|
- `retrievedAt` is server UTC ISO-8601.
|
|
- `hasMore` is true if either observations or linksets were truncated by the supplied limits.
|
|
|
|
Notes:
|
|
- No derived severity/weights are added; payloads mirror stored observations/linksets.
|
|
- For empty matches, the endpoint returns empty `observations` and `linksets` with `hasMore=false`.
|
|
|
|
Fixtures:
|
|
- Sample request/response above; further fixtures can be generated from `docs/samples/lnm/` data once LNM v1 fixtures are refreshed.
|
|
|
|
Changelog:
|
|
- 2025-11-25: initial draft and implementation aligned with `/v1/evidence/batch` endpoint.
|