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/modules/platform/samples/console-vex-30-001.json already includes VEX sample keyed by advisory; add Concelier response sample to docs/modules/platform/samples/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).