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:

{
  "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:

{
  "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).

2.8 KiB Raw Blame History