Vulnerability Management (Polycrate API)

The security area of the Polycrate API since 0.32.0: CVE catalog, vulnerability products on catalogue apps, OSV/NVD/CISA KEV enrichment, findings, incident linking and upstream release sync.

Vulnerability Management (Polycrate API)

Since Polycrate API 0.32.0, the platform manages a security area for app-related vulnerabilities: CVE catalog, vulnerability products on catalogue apps, findings and optional linking with incidents.

Overview

flowchart LR
  Block["Template Block<br/>block.poly vulnerability.products"] --> Sync["Product Sync"]
  Sync --> VP["VulnerabilityProduct"]
  VP --> OSV["OSV Enrichment"]
  OSV --> CVE["CVE + CVESourceRecord"]
  CVE --> Match["Finding Matcher"]
  Match --> Finding["VulnerabilityFinding"]
  Finding --> Incident["Incident optional"]
Object Scope Purpose
CVE global Canonical CVE entry including sources (MVP: OSV)
VulnerabilityProduct on CatalogueApp Product identity for enrichment/matching
VulnerabilityFinding org-/workspace-scoped Match on a deployed app / instance
ComplianceReport organization Monthly evidence pack (automatic)

UI: navigation Security or, on the catalogue app, the tabs Vulnerability Products and Upstream Releases.

Vulnerability Products on Template Blocks

The source of truth for recurring apps is the optional section in block.poly:

vulnerability:
  products:
    - vendor: goauthentik
      product: authentik
      ecosystem: Go
      purl: "pkg:golang/goauthentik.io/authentik"

Details and fields: Blocks: Vulnerability Products · Recommendations.

Sync Behavior

Trigger Behavior
Template block create / Hub import Signal → product sync for the catalogue app
Celery Beat (sync_vulnerability_products) Catch-up across catalogue apps with registry/template block
UI/API action sync-vulnerability-products ObjectTask on the catalogue app
  • Entries from the block receive source=block.
  • Manually created products (source=manual) are not orphan-deleted.
  • If vulnerability.products is missing and there are no manual rows: no OSV enrichment for this app.

CVE Catalog and Enrichment

Beat task enrich_cve_catalog (typically nightly):

Source Prerequisite Result
OSV ecosystem + package name (product) CVESourceRecord source=osv
NVD cpe set explicitly (no synthetic CPE from vendor/product) source=nvd; optional SystemConfig.config.NVD_API_KEY (without key: rate limit + cap per product)
CISA KEV after OSV/NVD known exploited CVEs → source=cisa_kev

Finding matching uses OSV and NVD records. Without ecosystem, OSV returns no usable matches; without cpe, NVD is skipped.

Findings and Incidents

  • Beat task match_vulnerability_findings links catalog CVEs with deployed apps (e.g. via CatalogueApp / installed version).
  • Findings are org-scoped; status transitions (accept / false positive) via the UI/API.
  • Findings can be attached to incidents (security workflow).

Upstream Releases (related)

Catalogue apps can synchronize GitHub releases as notes (kind: app-release):

  • Meta from the block (releases_url / git_repository_url / app_version → tracked_app_version)
  • Beat sync_catalogue_app_releases or action Sync releases
  • Platform credential in SystemConfig: GITHUB_RELEASE_SYNC_CREDENTIAL_ID (otherwise strict rate limits / no private repos)

Version normalization only removes a leading v if it is followed by a digit (v1.2.3 → 1.2.3). Tags like version/0.7.10 remain unchanged.

Prerequisites After Deploy

  1. Django migrations and Celery worker/beat with the current API version
  2. Populate template blocks with vulnerability.products (or create products manually)
  3. Optional: GitHub credential for upstream sync (GITHUB_RELEASE_SYNC_CREDENTIAL_ID)
  4. Optional: NVD_API_KEY in SystemConfig, otherwise strict NVD rate limit
  5. Optional one-time Sync Now / wait for beat for product and release catch-up

See Also