stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
daa6a4ae8ce372f398c450eeaaafcd079ca5ea46
git.stella-ops.org/src/StellaOps.Concelier.Connector.CertCc
History

README.md

CERT/CC Vulnerability Notes – Source Research

Canonical publication endpoints

  • Public portal – https://www.kb.cert.org/vuls/ lists recently published Vulnerability Notes and exposes a “Subscribe to our feed” link for automation entry points.citeturn0search0
  • Atom feed – https://www.kb.cert.org/vulfeed returns an Atom 1.0 feed of the same notes (<title>, <updated>, <summary> HTML payload). Feed metadata advertises rel="self" at https://kb.cert.org/vuls/atomfeed/. Use conditional GET headers (If-Modified-Since, If-None-Match) to avoid refetching unchanged entries.citeturn0search2

VINCE Vulnerability Note API

The VINCE documentation describes an unauthenticated REST-style API for structured retrieval:citeturn1view0

Endpoint Payload Notes
GET /vuls/api/{id}/ Canonical note metadata (title, overview, markdown segments, timestamps, aliases). Use numeric ID (e.g., 257161).
GET /vuls/api/{id}/vuls/ Per-CVE vulnerability records tied to the note. Includes CVE, description, timestamps.
GET /vuls/api/{id}/vendors/ Vendor statements per advisory. Provides status text and optional references.
GET /vuls/api/{id}/vendors/vuls/ Vendor × vulnerability status matrix. “known_affected” vs “known_not_affected” semantics.
GET /vuls/api/vuls/cve/{cve}/ Reverse lookup by CVE. Returns combined note + vendor context.
GET /vuls/api/{year}/summary/ Annual summary listing (count, notes[]). Year-month variants exist (/{year}/{month}/summary/).
GET /vuls/api/{id}/csaf/ CSAF 2.0 export generated by VINCE. Useful for downstream CSAF tooling.

Operational considerations:

  • API responses are JSON (UTF-8) and publicly accessible; no authentication tokens or cookies are required.citeturn1view0
  • Monthly and annual summary endpoints enable incremental crawling without diffing the Atom feed.
  • Expect high-volume notes to expose dozens of vendor records—prepare batching and pagination at the connector layer even though the API returns full arrays today.
  • Apply polite backoff: the documentation does not publish explicit rate limits, but the kb.cert.org infrastructure throttles bursts; mirror existing backoff strategy (exponential with jitter) used by other connectors.
  • Detail fetch tolerates missing optional endpoints (vendors, vendors-vuls, vuls) by logging a warning and continuing with partial data; repeated 4xx responses will not wedge the cursor.

Telemetry & monitoring

The connector exposes an OpenTelemetry meter named StellaOps.Concelier.Connector.CertCc. Key instruments include:

  • Planning: certcc.plan.windows, certcc.plan.requests, and certcc.plan.window_days.
  • Summary fetch: certcc.summary.fetch.attempts, .success, .not_modified, .failures.
  • Detail fetch: certcc.detail.fetch.attempts, .success, .unchanged, .missing, .failures with an endpoint dimension (note/vendors/vuls/vendors-vuls).
  • Parsing: certcc.parse.success, .failures, plus histograms for vendor/status/vulnerability counts.
  • Mapping: certcc.map.success, .failures, and histograms certcc.map.affected.count / certcc.map.normalized_versions.count.

Structured logs surface correlation IDs across fetch, parse, and map stages. Failures emit warnings for tolerated missing endpoints and errors for retry-worthy conditions so operators can hook them into existing alert policies.

Historical data sets

CERT/CC publishes a Vulnerability Data Archive (JSON exports plus tooling) for deep history or backfills. The archive is hosted on the SEI site with mirrored GitHub repositories containing normalized JSON conversions.citeturn0search3turn0search4

Snapshot regression workflow

The connector ships deterministic fixtures so QA and Merge teams can replay fetch→parse→map without live calls. Use the following flow when validating changes or refreshing snapshots:

  1. dotnet test src/StellaOps.Concelier.Connector.CertCc.Tests – runs the connector snapshot suite against canned VINCE responses.
  2. UPDATE_CERTCC_FIXTURES=1 dotnet test src/StellaOps.Concelier.Connector.CertCc.Tests – regenerates fixtures under src/StellaOps.Concelier.Connector.CertCc.Tests/Fixtures/*.snapshot.json and mirrors them in the test output directory (bin/Debug/net10.0/Source/CertCc/Fixtures).
    • The harness now records every HTTP request; certcc-requests.snapshot.json must list summaries/months in canonical order.
    • Expect certcc-advisories.snapshot.json to include normalized versions (scheme=certcc.vendor) and provenance decision reasons.
  3. Review diffs and attach certcc-*.snapshot.json plus test logs when handing off to Merge.

Fixtures are sorted and timestamps normalized to UTC ISO‑8601 to preserve determinism across machines.

Next steps for the connector

  1. Implement Atom polling for quick detection, with VINCE API lookups for structured details. CertCcSummaryPlanner already computes the VINCE year/month summary URIs to fetch per window; wire this into the fetch job and persist the resulting TimeWindowCursorState.
  2. Persist updated timestamps and VINCE revision counters to drive resume logic.
  3. Capture vendor statements/CSAF exports to populate range primitives once model hooks exist.
  4. Evaluate using the data archive for seed fixtures covering legacy notes (pre-2010).***