Cisco CVRF Processor — Design Document

Overview

The Cisco CVRF Processor ingests Cisco security advisories published in CSAF-CVRF XML format (the documents declare the OASIS csaf-cvrf/v1.2 namespace). Advisories are enumerated from the Cisco Security Center pagination API, fetched, parsed, and stored in the VDB database using the standard CVEMetadata pipeline.

Cisco is the primary authority for cisco-sa-* advisory identifiers and the only feed that carries the Cisco Bug ID ↔ CVE mapping, which is what makes a Cisco advisory reachable from a customer’s CSCxx… bug reference.

Source

Naming

Data Flow

Cisco listing page (HTML)
  → extract CVRF XML URLs
  → for each URL: HTTP GET → raw XML bytes
  → ParseCVRF (xml.Unmarshal)
  → MapToSourceData (cisco SA ID as cveId, CVEs as aliases)
  → processor.StoreCVESourceData (upsert CVEMetadata, descriptions, references, metrics, affected, aliases)
  → S3 upload (application/xml)
  → db.InsertArtifact + InsertLinkWithArtifact
  → db.UpdateCVEMetadataFileLinkID

Resume / Idempotency

Two-level resume strategy:

1. Listing-page tracker (ECS processor only): SHA256 of the listing page HTML is stored in BulkDataDumpTracker (source=cisco_listing). If unchanged, the processor exits early.

2. Per-advisory hash: SHA256 of the raw CVRF XML bytes is stored in CVEMetadata.sourceFileHash. If the hash matches, the advisory is skipped on re-run.

The backfill ignores the listing-page tracker and always processes all URLs, using the per-advisory hash for resume unless --force is set.

Data Mapping

CVEMetadata (one row per advisory document)

CVEDescription (per DocumentNote + per Remediation)

CVEMetadataReferences

CVEAlias (per Vulnerability)

CVEMetric (per CVSSScoreSet, deduplicated by vector string)

⚠ Broken today — no CVSS is actually stored. Cisco’s CSAF-CVRF v1.2 documents nest the score as <CVSSScoreSets><ScoreSetV3><BaseScoreV3>6.3</BaseScoreV3><VectorV3>CVSS:3.1/…</VectorV3></ScoreSetV3>, but internal/cisco/types.go:96 decodes CVSSScoreSets>ScoreSet with BaseScore/Vector child elements (internal/cisco/types.go:113-118). The element names never match, so vuln.CVSSScoreSets is always empty and internal/cisco/mapper.go:92-106 emits no metrics. Production evidence: 8,137 of 8,139 source='cisco' rows have vectorString IS NULL (the two exceptions predate the current mapper). Fix = add ScoreSetV3/ScoreSetV2 variants with BaseScoreV3/VectorV3 (and the V2 spellings) to the Vulnerability struct.

The shared pipeline still derives one containerType="vulnetix" CVSS v4.0 metric per record from the advisory description (internal/processor/pipeline.go:521-548), so severity is not entirely absent — it is simply Vulnetix-derived rather than Cisco-published.

CVEAffected (per ProductStatus)

Placeholder and rejected rows under source='cisco'

Not every source='cisco' row is an advisory. Two side effects mint rows that carry no title, no rawDataJSON and datePublished = 0:

Exclude the alias/rejected shells (title IS NULL) from any coverage denominator for this source.

S3 Artifact

• Key: cisco/advisories/{sha256hex}/{advisoryID}.xml — non-canonical; the S3 Persistence Contract (and the generated section below) specify cisco/files/{sha256}/{filename}. cmd/cisco-cvrf-backfill writes the canonical path (cmd/cisco-cvrf-backfill/main.go:277), so the same source archives to two different prefixes depending on which binary ran.
• ContentType: application/xml
• BomFormat: cisco
• Type: OTHER

Internal Package: internal/cisco/

Reused Utilities

Local Testing

# Fetch up to 5 advisories from the Cisco listing page (uses .env)
just go-cisco-cvrf-backfill LIMIT=5

# Force reprocess all advisories
just go-cisco-cvrf-backfill FORCE=true

# Verify results
psql "$DATABASE_URL" -c 'SELECT "cveId", "title", "state" FROM "CVEMetadata" WHERE source='"'"'cisco'"'"' LIMIT 10;'
psql "$DATABASE_URL" -c 'SELECT "primaryCveId", "aliasCveId" FROM "CVEAlias" WHERE "primarySource"='"'"'cisco'"'"' LIMIT 10;'
psql "$DATABASE_URL" -c 'SELECT "metricType", "baseScore", "vectorString" FROM "CVEMetric" WHERE source='"'"'cisco'"'"' LIMIT 10;'
psql "$DATABASE_URL" -c 'SELECT "vendor", "product" FROM "CVEAffected" WHERE source='"'"'cisco'"'"' LIMIT 10;'

ECS Deployment

The ECS processor runs daily at 11:00 UTC via EventBridge Scheduler. It uses the listing-page SHA256 tracker to exit early when nothing has changed, keeping costs low.

CPU: 256 units (0.25 vCPU) Memory: 512 MB Architecture: ARM64 (Graviton)

S3 Persistence

• Archive path: cisco/files/{sha256}/{filename} ✓
• Quarantine path: failed-feeds/cisco-cvrf-processor/{YYYY-MM-DD}/{reason}/{filename} ✓
• Failure reasons emitted: parse-error, schema-violation

Uses s3client.Uploader from internal/s3client/uploader.go. Skipped when S3_BUCKET_NAME is unset (local dev).

See the S3 Persistence Contract for the full reason taxonomy.