82 lines
2.8 KiB
Markdown
82 lines
2.8 KiB
Markdown
# CONCELIER-VULN-29-001 · Concelier ↔ Vuln Explorer bridge (contract v0.1)
|
|
|
|
Purpose: unblock PREP-CONCELIER-VULN-29-001 by defining the request/response contract Concelier must expose for Vuln Explorer and VEX Lens to consume advisory evidence without merge semantics.
|
|
|
|
## API shape (Concelier WebService)
|
|
- Endpoint: `POST /v1/advisories/search`
|
|
- Auth: tenant-scoped token (`concelier.read` scope) with `mergeAllowed=false`.
|
|
- Request body:
|
|
```json
|
|
{
|
|
"query": {
|
|
"advisory_keys": ["GHSA-xxxx-xxxx"],
|
|
"purls": ["pkg:maven/org.example/app@1.2.3"],
|
|
"component_hashes": ["sha256:..."],
|
|
"has_vex": true
|
|
},
|
|
"page": {
|
|
"size": 50,
|
|
"cursor": null
|
|
}
|
|
}
|
|
```
|
|
- Response body:
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"advisory_key": "GHSA-xxxx-xxxx",
|
|
"source": "ghsa",
|
|
"observations": [{
|
|
"id": "obs-123",
|
|
"purl": "pkg:maven/org.example/app@1.2.3",
|
|
"version_range": "[1.2.0,2.0.0)",
|
|
"status": "affected",
|
|
"published": "2025-11-01T00:00:00Z",
|
|
"fixed": null,
|
|
"provenance": {
|
|
"source": "ghsa",
|
|
"retrieved_at": "2025-11-18T12:00:00Z",
|
|
"hash": "sha256:..."
|
|
}
|
|
}],
|
|
"vex": [{
|
|
"statement_id": "st-001",
|
|
"status": "not_affected",
|
|
"justification": "component_not_present",
|
|
"impact_statement": "Library not shipped",
|
|
"provenance": {
|
|
"source": "vendor-vex",
|
|
"retrieved_at": "2025-11-18T12:00:00Z",
|
|
"hash": "sha256:..."
|
|
}
|
|
}]
|
|
}
|
|
],
|
|
"page": {"cursor": "next-token", "size": 50}
|
|
}
|
|
```
|
|
|
|
## Determinism requirements
|
|
- Sort observations by `purl`, then `published`, then `id`.
|
|
- Sort VEX statements by `statement_id`.
|
|
- Timestamps UTC ISO-8601 with `Z`.
|
|
- Omit merge-derived fields; only surface source-provided values.
|
|
|
|
## Fields Vuln Explorer expects
|
|
- `advisory_key`, `source`, `observations[*].purl`, `observations[*].status`, `observations[*].provenance.hash`.
|
|
- VEX fields: `status`, `justification`, `impact_statement`, `provenance.hash`.
|
|
- Optional: `fix_version` when present; keep absent otherwise (no empty strings).
|
|
|
|
## Test fixtures
|
|
- Location: `docs/samples/console/console-vex-30-001.json` already includes VEX sample keyed by advisory; add Concelier response sample to `docs/samples/console/concelier-vuln-29-001.json` (to be generated alongside implementation).
|
|
|
|
## Owners
|
|
- Concelier WebService Guild (producer)
|
|
- Vuln Explorer Guild / VEX Lens Guild (consumers)
|
|
|
|
## Next actions to unblock work
|
|
- Implement endpoint stub with deterministic ordering and fixture from above sample.
|
|
- Hook to Link-Not-Merge storage (fact-only) once available.
|
|
- Add contract reference to OAS (Sprint 0114 CONCELIER-OAS-61-001 depends on this).
|