Concelier JVN Connector - Operations Runbook

Last updated: 2026-01-16

This runbook is for operators who run the JVN (Japan Vulnerability Notes) connector in a Stella Ops Concelier instance. It covers configuration, the jvn -> jpcert source-ID migration, offline mirroring, and how to diagnose the non-XML payload failure mode.

1. Overview

The JVN connector ingests Japan Vulnerability Notes (JVN) advisories and maps them to canonical IDs. The runtime/catalog source ID is jpcert.

2. Authentication

• No authentication required for public feeds.

3. Configuration (concelier.yaml)

concelier:
  sources:
    jpcert:
      baseUri: "<jvn-feed-base>"
      maxDocumentsPerFetch: 20
      fetchTimeout: "00:00:45"
      requestDelay: "00:00:00"

Legacy concelier:sources:jvn binding is still accepted for compatibility, but operators should use concelier:sources:jpcert for new installs and UI-driven setup.

4. Offline and air-gapped deployments

• Mirror JVN feeds into the Offline Kit and repoint baseUri to the mirror. See the mirror operations guide for staging and verification steps.

5. Common failure modes

• Feed format changes or upstream outages.
• System.Xml.XmlException: Data at the root level is invalid. Line 1, position 1.— the response was not XML. A structured shape probe emits a JVN overview returned non-XML payload warning containing the request URI, HTTP status, Content-Type, content length, and the first 200 bytes of the body (control chars escaped). Most common causes:
  • BaseEndpoint points to a path that does not serve the MyJVN RSS document (e.g. omits the /myjvn path segment and falls through to a load-balancer health probe).
  • Upstream returned an HTML error page (502/503) with HTTP 200 from an upstream cache.
  • The endpoint added a UTF-8 BOM or switched to JSON. Compare the body excerpt in the warning against the expected <?xml version="1.0" encoding="UTF-8"?> prefix.
• The required attribute 'errCd' is missing during source:jpcert:parse in fixture mode - first inspect the stored document URI and root element. A detail URI with method=getVulnDetailInfo must resolve to a VULDEF-Document, not the overview rdf:RDF. The local fixture dispatches the shared /cert/jpcert/myjvn path by method plus the frozen vulnId; unsupported combinations intentionally return 404. Do not relax JvnDetailParser XSD validation to accept an overview document as detail data. Run devops/compose/fixtures/integration-fixtures/advisory/verify-jpcert-contract.ps1 against an isolated disposable nginx container before reloading the shared fixture.