{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/recorded-future/main/json-schema/recorded-future-vulnerability-lookup-response-schema.json",
  "title": "VulnerabilityLookupResponse",
  "description": "Vulnerability (CVE) enrichment response. The response includes only the fields specified in the `fields` query parameter. All properties under `data` are optional because they appear only when requested.",
  "x-generated": "2026-10-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/recorded-future-connect-api-openapi.yml#/components/schemas/VulnerabilityLookupResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Vulnerability entity data with requested enrichment fields.",
      "properties": {
        "entity": {
          "$ref": "#/$defs/Entity"
        },
        "risk": {
          "$ref": "#/$defs/RiskData"
        },
        "aiInsights": {
          "$ref": "#/$defs/AiInsights"
        },
        "links": {
          "$ref": "#/$defs/LinksData"
        },
        "intelCard": {
          "type": "string",
          "format": "uri",
          "description": "URL to the Recorded Future Intelligence Card for this vulnerability."
        },
        "cvss": {
          "type": "object",
          "description": "CVSS (Common Vulnerability Scoring System) data. Included when the fields parameter contains 'cvss'.",
          "properties": {
            "accessVector": {
              "type": "string",
              "description": "CVSS access vector (e.g., NETWORK, LOCAL)."
            },
            "accessComplexity": {
              "type": "string",
              "description": "CVSS access complexity (e.g., LOW, MEDIUM, HIGH)."
            },
            "authentication": {
              "type": "string",
              "description": "CVSS authentication requirement."
            },
            "confidentiality": {
              "type": "string",
              "description": "Confidentiality impact (e.g., PARTIAL, COMPLETE)."
            },
            "integrity": {
              "type": "string",
              "description": "Integrity impact."
            },
            "availability": {
              "type": "string",
              "description": "Availability impact."
            },
            "score": {
              "type": "number",
              "description": "CVSS numeric score (0.0-10.0)."
            },
            "version": {
              "type": "string",
              "description": "CVSS version (e.g., '2.0')."
            },
            "published": {
              "type": "string",
              "format": "date-time",
              "description": "CVE publication date."
            },
            "lastModified": {
              "type": "string",
              "format": "date-time",
              "description": "CVE last modified date."
            }
          }
        },
        "commonNames": {
          "type": "array",
          "description": "Known aliases for this vulnerability (e.g., ['Log4Shell']).",
          "items": {
            "type": "string"
          }
        },
        "lifecycleStage": {
          "type": "string",
          "description": "Current exploitation lifecycle stage.",
          "enum": [
            "Exploited",
            "Weaponized",
            "Proof of Concept",
            "Disclosed"
          ]
        },
        "linkedMalware": {
          "type": "object",
          "description": "Malware families known to exploit this vulnerability.",
          "properties": {
            "entities": {
              "type": "array",
              "description": "Malware entity references.",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "Malware entity ID."
                  },
                  "name": {
                    "type": "string",
                    "description": "Malware family name."
                  },
                  "type": {
                    "type": "string",
                    "description": "Entity type (Malware)."
                  }
                }
              }
            },
            "total_count": {
              "type": "integer",
              "description": "Total number of linked malware families."
            }
          }
        },
        "nvdDescription": {
          "type": "string",
          "description": "NVD (National Vulnerability Database) description text."
        },
        "timestamps": {
          "$ref": "#/$defs/Timestamps"
        },
        "analystNotes": {
          "type": "array",
          "description": "Insikt Group analyst notes providing expert analysis and context.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Unique identifier for this analyst note."
              },
              "attributes": {
                "type": "object",
                "description": "Content and metadata of the analyst note.",
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Title of the analyst note."
                  },
                  "text": {
                    "type": "string",
                    "description": "Full text content of the analyst note."
                  },
                  "validated_on": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Date when the note was last validated."
                  },
                  "published": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Date when the note was published."
                  },
                  "topic": {
                    "type": "object",
                    "description": "The topic category of this note.",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "type": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      }
                    }
                  },
                  "context_entities": {
                    "type": "array",
                    "description": "Entities referenced as context in the note.",
                    "items": {
                      "$ref": "#/$defs/Entity"
                    }
                  },
                  "note_entities": {
                    "type": "array",
                    "description": "Primary subject entities of the note.",
                    "items": {
                      "$ref": "#/$defs/Entity"
                    }
                  },
                  "validation_urls": {
                    "type": "array",
                    "description": "URLs used to validate the note.",
                    "items": {
                      "$ref": "#/$defs/Entity"
                    }
                  }
                }
              },
              "source": {
                "type": "object",
                "description": "Source of the analyst note.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "relatedEntities": {
          "type": "array",
          "description": "Co-occurrence relationships grouped by entity type (not editorially validated).",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Relationship type category (e.g., RelatedIpAddress, RelatedHash, RelatedMalware, RelatedThreatActor)."
              },
              "entities": {
                "type": "array",
                "description": "Related entities ordered by co-occurrence count.",
                "items": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of co-occurrences."
                    },
                    "entity": {
                      "$ref": "#/$defs/Entity"
                    }
                  }
                }
              }
            }
          }
        },
        "counts": {
          "type": "array",
          "description": "Daily reference count time-series.",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "format": "date",
                "description": "The date for this reference count."
              },
              "count": {
                "type": "integer",
                "description": "Number of references on this date."
              }
            }
          }
        },
        "metrics": {
          "type": "array",
          "description": "Flat metric counters for aggregate statistics.",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Metric type identifier (e.g., linkedToCyberExploit, linkedToRAT)."
              },
              "value": {
                "type": "integer",
                "description": "The metric count value."
              }
            }
          }
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Request metadata. Included when the metadata query parameter is set to true."
    }
  },
  "required": [
    "data"
  ],
  "$defs": {
    "AiInsights": {
      "type": "object",
      "description": "AI-generated threat analysis. Included when the fields parameter contains 'aiInsights'. Text is null when fewer than 3 risk rules are triggered.",
      "properties": {
        "text": {
          "type": [
            "string",
            "null"
          ],
          "description": "AI-generated threat analysis paragraph. Null when fewer than 3 risk rules are triggered."
        },
        "numberOfReferences": {
          "type": "integer",
          "description": "Number of intelligence references used to generate the insight."
        },
        "comment": {
          "type": [
            "string",
            "null"
          ],
          "description": "Explanatory comment (e.g., why insights are not available)."
        }
      }
    },
    "Entity": {
      "type": "object",
      "description": "Recorded Future entity identification.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Recorded Future entity ID. Format varies by type: ip:1.2.3.4, idn:example.com, hash:<value>, url:https://..., or opaque alphanumeric IDs for vulnerabilities, malware, and companies."
        },
        "name": {
          "type": "string",
          "description": "Human-readable entity name."
        },
        "type": {
          "type": "string",
          "description": "Entity type classification.",
          "enum": [
            "IpAddress",
            "InternetDomainName",
            "Hash",
            "URL",
            "CyberVulnerability",
            "Malware",
            "Company"
          ]
        },
        "description": {
          "type": "string",
          "description": "Entity description (present for vulnerabilities and some other types)."
        }
      },
      "required": [
        "id",
        "name",
        "type"
      ]
    },
    "EvidenceDetail": {
      "type": "object",
      "description": "Evidence for a triggered risk rule, including the rule name, severity, and supporting evidence string.",
      "properties": {
        "rule": {
          "type": "string",
          "description": "Risk rule name that was triggered."
        },
        "criticality": {
          "type": "integer",
          "description": "Numeric criticality level of the rule (1=Informational, 2=Unusual, 3=Suspicious, 4=Malicious)."
        },
        "criticalityLabel": {
          "type": "string",
          "description": "Human-readable criticality label. IOC entities use: Unusual, Suspicious, Malicious, Very Malicious. Company entities use: Informational, Moderate, High, Very High.",
          "enum": [
            "Informational",
            "Unusual",
            "Suspicious",
            "Moderate",
            "Malicious",
            "High",
            "Very Malicious",
            "Very High"
          ]
        },
        "evidenceString": {
          "type": "string",
          "description": "Human-readable evidence summary with source references and sighting details."
        },
        "mitigationString": {
          "type": "string",
          "description": "Recommended mitigation or remediation guidance for this risk rule."
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of when the evidence was observed."
        }
      }
    },
    "LinksData": {
      "type": "object",
      "description": "Validated intelligence relationships to threat actors, malware, MITRE ATT&CK techniques, and other entities. Included when the fields parameter contains 'links'. Unlike relatedEntities, these are editorially validated relationships.",
      "properties": {
        "hits": {
          "type": "array",
          "description": "Intelligence hits containing sectioned relationship data.",
          "items": {
            "type": "object",
            "properties": {
              "start_date": {
                "type": "string",
                "description": "Start date of the intelligence hit time window."
              },
              "stop_date": {
                "type": "string",
                "description": "End date of the intelligence hit time window."
              },
              "total_count": {
                "type": "integer",
                "description": "Total number of entity relationships in this hit."
              },
              "sample_reference_ids": {
                "type": "array",
                "description": "Sample reference IDs supporting this hit.",
                "items": {
                  "type": "string"
                }
              },
              "counts": {
                "type": "array",
                "description": "Breakdown counts by entity type.",
                "items": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of entities."
                    },
                    "type": {
                      "type": "object",
                      "description": "Entity type metadata.",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "type": {
                          "type": "string"
                        }
                      }
                    }
                  }
                }
              },
              "event_count": {
                "type": "integer",
                "description": "Number of events in this hit."
              },
              "sections": {
                "type": "array",
                "description": "Relationship sections grouped by category.",
                "items": {
                  "type": "object",
                  "properties": {
                    "section_id": {
                      "type": "object",
                      "description": "Section identifier.",
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "Section ID."
                        },
                        "name": {
                          "type": "string",
                          "description": "Section category name (e.g., 'Actors, Tools & TTPs', 'Victims & Exploit Targets', 'Indicators & Detection Rules')."
                        },
                        "type": {
                          "type": "string",
                          "description": "Section type (e.g., 'Category')."
                        }
                      }
                    },
                    "total_count": {
                      "type": "integer",
                      "description": "Total entities in this section."
                    },
                    "lists": {
                      "type": "array",
                      "description": "Entity lists within this section, grouped by entity type.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "entities": {
                            "type": "array",
                            "items": {
                              "$ref": "#/$defs/LinksEntity"
                            }
                          },
                          "total_count": {
                            "type": "integer",
                            "description": "Total entities in this list."
                          },
                          "type": {
                            "type": "object",
                            "description": "Entity type metadata for this list.",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "type": {
                                "type": "string"
                              },
                              "description": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "method_aggregates": {
          "type": "array",
          "description": "Aggregated counts of linked entities by analysis method.",
          "items": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of links found by this method."
              },
              "type": {
                "type": "string",
                "description": "Analysis method type."
              }
            }
          }
        },
        "counts": {
          "type": "array",
          "description": "Summary counts of linked entities by type.",
          "items": {
            "type": "object",
            "properties": {
              "count": {
                "type": "integer",
                "description": "Number of linked entities of this type."
              },
              "type": {
                "type": "object",
                "description": "Entity type metadata.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "type": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    },
    "LinksEntity": {
      "type": "object",
      "description": "An entity referenced in a validated intelligence link.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Recorded Future entity ID."
        },
        "name": {
          "type": "string",
          "description": "Entity display name."
        },
        "type": {
          "type": "string",
          "description": "Entity type (e.g., MitreAttackIdentifier, Malware, ThreatActor, Company, IpAddress)."
        }
      }
    },
    "RiskData": {
      "type": "object",
      "description": "Risk assessment data with score, triggered rules, and supporting evidence. Included when the fields parameter contains 'risk'. Not available for Malware entities.",
      "properties": {
        "score": {
          "type": "integer",
          "description": "Numeric risk score from 0 (no risk) to 99 (critical risk).",
          "minimum": 0,
          "maximum": 99
        },
        "criticality": {
          "type": "integer",
          "description": "Numeric criticality level (0=None, 1=Informational, 2=Unusual, 3=Suspicious, 4=Malicious)."
        },
        "criticalityLabel": {
          "type": "string",
          "description": "Risk criticality label. IOC entities use: Unusual, Suspicious, Malicious, Very Malicious. Company entities use: Informational, Moderate, High, Very High.",
          "enum": [
            "None",
            "Informational",
            "Unusual",
            "Suspicious",
            "Moderate",
            "Malicious",
            "High",
            "Very Malicious",
            "Very High"
          ]
        },
        "riskString": {
          "type": "string",
          "description": "Triggered vs total risk rules (e.g., '16/81')."
        },
        "rules": {
          "type": "integer",
          "description": "Number of currently triggered risk rules."
        },
        "riskSummary": {
          "type": "string",
          "description": "Human-readable risk summary (e.g., '16 of 81 Risk Rules currently observed.')."
        },
        "evidenceDetails": {
          "type": "array",
          "description": "Evidence for each triggered risk rule.",
          "items": {
            "$ref": "#/$defs/EvidenceDetail"
          }
        }
      }
    },
    "Timestamps": {
      "type": "object",
      "description": "First and last seen timestamps for the entity in Recorded Future data.",
      "properties": {
        "firstSeen": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of first observation."
        },
        "lastSeen": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of most recent observation."
        }
      }
    }
  }
}