Shodan CVEDB Product Vulnerability Enrichment

arazzo: 1.0.1
info:
  title: Shodan CVEDB Product Vulnerability Enrichment
  summary: Resolve a product to a CPE, search its CVEs, then pull full CVE details.
  description: >-
    A vulnerability research pattern over the free CVEDB. The workflow looks up
    the CPE 2.3 dictionary entries for a product, searches the CVE catalog for
    vulnerabilities affecting that product ordered by exploitation likelihood,
    and then retrieves the full record for the top CVE. CVEDB is unauthenticated
    so no API key is required. Every step spells out its request inline so the
    flow can be read and executed without opening the underlying OpenAPI
    description.
  version: 1.0.0
  x-realizes-capability-ids:
  - BC-620.40
  x-capability-derivation:
    method: 'deterministic join: sourceDescriptions -> per-tag OpenAPI -> tag/capability edge. No classification at this step.'
    min_confidence: 0.7
    sources:
    - capability_id: BC-620.40
      capability_name: Vulnerability Management
      spec: shodan-cve-api-openapi.yml
      confidence: 0.85
    model: Turbo EA Capabilities by Vincent Verdet — Turbo EA, https://github.com/vincentmakes/turbo-ea-capabilities, CC BY 4.0
sourceDescriptions:
- name: cpeApi
  url: ../openapi/shodan-cpe-api-openapi.yml
  type: openapi
- name: cveApi
  url: ../openapi/shodan-cve-api-openapi.yml
  type: openapi
workflows:
- workflowId: cve-enrichment
  summary: Enumerate CPEs and CVEs for a product and detail the top CVE.
  description: >-
    Searches the CPE dictionary for a product, searches the CVE catalog for that
    product ordered by EPSS, and retrieves the full details for the top CVE.
  inputs:
    type: object
    required:
    - product
    properties:
      product:
        type: string
        description: The product name to research (e.g. "nginx").
      isKev:
        type: boolean
        description: Restrict CVE results to CISA Known Exploited Vulnerabilities.
        default: false
      cveId:
        type: string
        description: >-
          The CVE identifier to detail. CVEDB search returns a list keyed by
          position, so the chosen CVE id is carried forward through this input
          for the detail lookup.
  steps:
  - stepId: searchCpes
    description: >-
      Retrieve the CPE 2.3 dictionary entries matching the product.
    operationId: searchCpes
    parameters:
    - name: product
      in: query
      value: $inputs.product
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      cpes: $response.body#/cpes
  - stepId: searchCves
    description: >-
      Search the CVE catalog for vulnerabilities affecting the product, ordered
      by EPSS so the most likely to be exploited surface first.
    operationId: searchCves
    parameters:
    - name: product
      in: query
      value: $inputs.product
    - name: is_kev
      in: query
      value: $inputs.isKev
    - name: sort_by_epss
      in: query
      value: true
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      cves: $response.body#/cves
      topCveId: $response.body#/cves/0/cve_id
  - stepId: cveDetails
    description: >-
      Retrieve the full record for the chosen CVE, including CVSS, EPSS, KEV
      status, references, and impacted CPEs.
    operationId: getCve
    parameters:
    - name: cveId
      in: path
      value: $inputs.cveId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      summary: $response.body#/summary
      cvss: $response.body#/cvss
      epss: $response.body#/epss
      kev: $response.body#/kev
  outputs:
    cpes: $steps.searchCpes.outputs.cpes
    topCveId: $steps.searchCves.outputs.topCveId
    cvss: $steps.cveDetails.outputs.cvss
    kev: $steps.cveDetails.outputs.kev