IpLookupResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/recorded-future/main/json-schema/recorded-future-ip-lookup-response-schema.json",
  "title": "IpLookupResponse",
  "description": "IP address 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/IpLookupResponse",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "description": "IP address 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 IP."
        },
        "location": {
          "type": "object",
          "description": "Geolocation and network ownership data for the IP address. Included when the fields parameter contains 'location'.",
          "properties": {
            "organization": {
              "type": "string",
              "description": "Hosting organization or ISP name."
            },
            "cidr": {
              "type": "object",
              "description": "CIDR block containing this IP.",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "CIDR entity ID."
                },
                "name": {
                  "type": "string",
                  "description": "CIDR notation (e.g., '64.227.176.0/20')."
                },
                "type": {
                  "type": "string",
                  "description": "Entity type."
                }
              }
            },
            "location": {
              "type": "object",
              "description": "Geographic location.",
              "properties": {
                "continent": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                }
              }
            },
            "asn": {
              "description": "Autonomous System Number. May be a simple string (e.g., 'AS14061') or an entity object with id/name/type.",
              "oneOf": [
                {
                  "type": "string",
                  "description": "ASN string (e.g., 'AS14061')."
                },
                {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "ASN entity ID (e.g., 'asn:AS14061')."
                    },
                    "name": {
                      "type": "string",
                      "description": "ASN display name (e.g., 'AS14061')."
                    },
                    "type": {
                      "type": "string",
                      "description": "Entity type."
                    }
                  }
                }
              ]
            }
          }
        },
        "dnsPortCert": {
          "type": "object",
          "description": "DNS records, open ports, and TLS certificates associated with the IP. Included when the fields parameter contains 'dnsPortCert'.",
          "properties": {
            "certificates": {
              "type": "array",
              "description": "TLS/SSL certificates observed on this IP.",
              "items": {
                "type": "object"
              }
            },
            "dns": {
              "type": "object",
              "description": "DNS resolution data.",
              "properties": {
                "forwardDns": {
                  "type": "array",
                  "description": "Domains resolving to this IP.",
                  "items": {
                    "type": "object"
                  }
                },
                "reverseDns": {
                  "type": "array",
                  "description": "Reverse DNS (PTR) records for this IP.",
                  "items": {
                    "type": "object"
                  }
                }
              }
            },
            "ports": {
              "type": "array",
              "description": "Open ports observed on this IP.",
              "items": {
                "type": "object",
                "properties": {
                  "port": {
                    "type": "integer",
                    "description": "Port number."
                  },
                  "protocol": {
                    "type": "string",
                    "description": "Protocol (e.g., 'tcp', 'udp')."
                  },
                  "name": {
                    "type": "string",
                    "description": "Service name (e.g., 'ssh', 'http')."
                  },
                  "product": {
                    "type": "string",
                    "description": "Software product name."
                  },
                  "version": {
                    "type": "string",
                    "description": "Software version."
                  },
                  "extraInfo": {
                    "type": "string",
                    "description": "Additional service information."
                  }
                }
              }
            }
          }
        },
        "scanner": {
          "type": "object",
          "description": "Scanning behavior analysis for the IP. Included when the fields parameter contains 'scanner'.",
          "properties": {
            "verdict": {
              "type": "string",
              "description": "Scanning verdict (e.g., 'scanner', 'not_scanner')."
            },
            "lastSeen": {
              "type": "string",
              "format": "date-time",
              "description": "Last observed scanning activity."
            },
            "scannerCountry": {
              "type": "string",
              "description": "Country of origin for scanning activity."
            },
            "scannedIpCountries": {
              "type": "array",
              "description": "Countries of IPs targeted by this scanner.",
              "items": {
                "type": "string"
              }
            },
            "globalScanner": {
              "type": "boolean",
              "description": "Whether this IP is classified as a global scanner."
            },
            "tags": {
              "type": "object",
              "description": "Scanner classification tags.",
              "properties": {
                "entity": {
                  "type": "array",
                  "description": "Entity-level tags.",
                  "items": {
                    "type": "object"
                  }
                }
              }
            },
            "rdns": {
              "type": "array",
              "description": "Reverse DNS hostnames for this IP.",
              "items": {
                "type": "string"
              }
            },
            "webRequests": {
              "type": "array",
              "description": "Observed web requests made by this scanner.",
              "items": {
                "type": "object"
              }
            },
            "userAgents": {
              "type": "array",
              "description": "User agent strings observed from this scanner.",
              "items": {
                "type": "string"
              }
            },
            "ports": {
              "type": "object",
              "description": "Ports scanned by this IP, grouped by protocol.",
              "properties": {
                "tcp": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "description": "TCP ports scanned."
                },
                "udp": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  },
                  "description": "UDP ports scanned."
                }
              }
            }
          }
        },
        "riskyCIDRIPs": {
          "type": "array",
          "description": "Other risky IPs in the same CIDR block. Included when the fields parameter contains 'riskyCIDRIPs'.",
          "items": {
            "type": "object",
            "properties": {
              "score": {
                "type": "integer",
                "description": "Risk score of the related IP."
              },
              "ip": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "IP entity ID."
                  },
                  "name": {
                    "type": "string",
                    "description": "IP address string."
                  },
                  "type": {
                    "type": "string",
                    "description": "Entity type (e.g., 'IpAddress')."
                  }
                }
              }
            }
          }
        },
        "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"
          }
        },
        "threatLists": {
          "type": "array",
          "description": "Curated threat list memberships.",
          "items": {
            "$ref": "#/$defs/ThreatList"
          }
        },
        "riskMapping": {
          "type": "array",
          "description": "Risk rule to MITRE ATT&CK mapping.",
          "items": {
            "$ref": "#/$defs/RiskMapping"
          }
        },
        "analystNotes": {
          "type": "array",
          "description": "Insikt Group analyst notes. Can be very large (67KB+).",
          "items": {
            "type": "object"
          }
        },
        "relatedEntities": {
          "type": "array",
          "description": "Co-occurrence relationships (not editorially validated). Can be 19-29KB.",
          "items": {
            "type": "object"
          }
        },
        "counts": {
          "type": "array",
          "description": "Daily reference count time-series.",
          "items": {
            "type": "object"
          }
        },
        "metrics": {
          "type": "array",
          "description": "Flat metric counters.",
          "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"
      ]
    },
    "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"
          }
        }
      }
    },
    "RiskMapping": {
      "type": "object",
      "description": "Mapping of triggered risk rules to MITRE ATT&CK techniques and other frameworks.",
      "properties": {
        "rule": {
          "type": "string",
          "description": "Risk rule name."
        },
        "categories": {
          "type": "array",
          "description": "Framework categories this rule maps to.",
          "items": {
            "type": "object",
            "properties": {
              "framework": {
                "type": "string",
                "description": "Framework name (e.g., 'MITRE ATT&CK')."
              },
              "name": {
                "type": "string",
                "description": "Category or technique name."
              }
            }
          }
        }
      }
    },
    "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"
          ]
        }
      }
    },
    "ThreatList": {
      "type": "object",
      "description": "A curated threat intelligence list membership.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Threat list entity ID."
        },
        "name": {
          "type": "string",
          "description": "Threat list name."
        },
        "type": {
          "type": "string",
          "description": "Entity type (e.g., 'EntityList')."
        },
        "description": {
          "type": "string",
          "description": "Description of the threat list and its purpose."
        }
      }
    },
    "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."
        }
      }
    }
  }
}