MalwareLookupResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/recorded-future/main/json-schema/recorded-future-malware-lookup-response-schema.json",
  "title": "MalwareLookupResponse",
  "description": "Malware enrichment response. Note: Malware entities do NOT have risk scores — use the categories field for classification. The response includes only the fields specified in the `fields` query parameter.",
  "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/MalwareLookupResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "Malware entity data with requested enrichment fields. Unlike other entity types, malware entities do not have risk scores.",
      "properties": {
        "entity": {
          "$ref": "#/$defs/Entity"
        },
        "categories": {
          "type": "array",
          "description": "Malware classification labels. Each category is an entity with id, name, and type. This is the primary classification mechanism for malware — there is no risk score.",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Category entity ID."
              },
              "name": {
                "type": "string",
                "description": "Category name (e.g., 'Remote Access Trojan', 'Ransomware', 'Backdoor')."
              },
              "type": {
                "type": "string",
                "description": "Entity type."
              }
            }
          }
        },
        "aiInsights": {
          "$ref": "#/$defs/AiInsights"
        },
        "links": {
          "$ref": "#/$defs/LinksData"
        },
        "intelCard": {
          "type": "string",
          "format": "uri",
          "description": "URL to the Recorded Future Intelligence Card for this malware."
        },
        "timestamps": {
          "$ref": "#/$defs/Timestamps"
        },
        "sightings": {
          "type": "array",
          "description": "Intelligence sightings from various source types. Each item's `type` field indicates the category (recentDarkWeb, recentPaste, recentInfoSec, recentSocialMedia, mostRecent, first). Included when the fields parameter contains 'sightings'.",
          "items": {
            "$ref": "#/$defs/Sighting"
          }
        },
        "analystNotes": {
          "type": "array",
          "description": "Insikt Group analyst notes. Can be very large.",
          "items": {
            "type": "object"
          }
        },
        "relatedEntities": {
          "type": "array",
          "description": "Co-occurrence relationships (not editorially validated).",
          "items": {
            "type": "object"
          }
        },
        "counts": {
          "type": "array",
          "description": "Daily reference count time-series. Can contain 2,000+ entries.",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "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"
      ]
    },
    "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)."
        }
      }
    },
    "Sighting": {
      "type": "object",
      "description": "An intelligence sighting from a specific source.",
      "properties": {
        "source": {
          "type": "string",
          "description": "Source name (e.g., 'GitHub', 'PasteBin', 'Turk Hack Team Forum')."
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL to the original source."
        },
        "published": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp of when the sighting was published."
        },
        "fragment": {
          "type": "string",
          "description": "Text fragment from the source mentioning the entity."
        },
        "title": {
          "type": "string",
          "description": "Title of the source document."
        },
        "type": {
          "type": "string",
          "description": "Sighting category.",
          "enum": [
            "recentDarkWeb",
            "recentPaste",
            "recentInfoSec",
            "recentSocialMedia",
            "mostRecent",
            "first"
          ]
        }
      }
    },
    "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."
        }
      }
    }
  }
}