# 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.Feedser.Source.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.Feedser.Source.CertCc.Tests` – runs the connector snapshot suite against canned VINCE responses.
2. `UPDATE_CERTCC_FIXTURES=1 dotnet test src/StellaOps.Feedser.Source.CertCc.Tests` – regenerates fixtures under `src/StellaOps.Feedser.Source.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).***
