Skip to main content

IP threat intelligence (TCA-0406)

This service returns threat intelligence data for the submitted IP address. The reports contain IP address reputation from various reputation sources, the maliciousness of files found on the submitted IP address, and other metadata like related URLs and IP address resolutions.

Information about the hosted files, related URLs, and IP address resolutions comes from our internal databases and URLs submitted for analysis using the TCA-0404 Analyze URL service.

Users can send requests to the following endpoints:

IP report endpoint

This endpoint returns:

  • Third-party IP address reputation and categorization.
  • Counters of samples downloaded from the IP address, mapped to their classification status (malicious, suspicious, known, unknown)
  • The most common threats (malware type, family) hosted on the submitted IP address

Downloaded files endpoint

Provides a list of hashes and classifications for files found on the submitted IP address.

The results can be filtered to return samples with specific classifications. If requested, the endpoint can return extended metadata for each file.

Extended records contain:

  • Additional sample properties: SHA1 hash, MD5 hash, SHA256 hash, sample size, sample type, download availability of the sample, first and last seen dates, first and last download times, last download URL.
  • Sample reputation information: classification, threat level, trust factor, malware family name, malware type, threat name, targeted platform and subplatform.

Related URLs endpoint

Returns a list of URLs hosted on the submitted IP address.

Resolutions endpoint

Provides a list of IP-to-domain mappings.

This API is rate limited to 5 requests per second.

IP report endpoint​

This service returns threat intelligence data for the submitted IP. The report contains IP reputation from various reputation sources, classification statistics for files downloaded from the IP, and the top threats hosted on the submitted IP.

Request​

POST /api/networking/ip/report/v1/query/{format}

Path parameters:

  • format
    • Defines the POST body format. The following values are supported: xml and json
    • Required

Request body:

{
  "rl": {
    "query": {
      "ip": "string",
      "response_format": "string"
    }
  }
}
  • ip
    • The IP for which to retrieve the report.
    • Required
  • response_format
    • Defines the response format. The following values are supported: xml (default) and json.
    • Optional

Response​

The returned report contains third party reputation and statistics, counters of downloaded samples mapped to their classification status (malicious, suspicious, known, unknown), the top threats hosted on the submitted IP address, and last change time of any of the listed elements.

Third party reputation data will always be present in the response, while other report sections might not.

{
  "rl": {
    "requested_ip": "string",
    "third_party_reputations": {},
    "downloaded_files_statistics": {},
    "top_threats": [],
    "last_seen": "string",
    "modified_time": "string"
  }
}

rl.third_party_reputations.statistics

{
  "total": 0,
  "malicious": 0,
  "suspicious": 0,
  "clean": 0,
  "undetected": 0
}
  • total
    • The total number of consulted IP reputation sources
  • malicious
    • The number of sources that consider the IP malicious
  • suspicious
    • The number of sources that consider the IP suspicious
  • clean
    • The number of sources that consider the IP clean
  • undetected
    • The number of sources that do not have information about the IP

rl.third_party_reputations.sources[]

{
  "source": "string",
  "update_time": "string",
  "detect_time": "string",
  "detection": "string",
  "category": "string"
}
  • source
    • Name of the third party source
  • detection
    • Detection for the submitted IP. The possible values are malicious/suspicious/clean/undetected. If the source does not have any information about the IP, the value will be undetected.
  • categories
    • IP categorization according to the source, e.g. phishing. Not all sources provide categorization information.
  • update_time
    • Time when the information from the source was last updated
  • detect_time
    • Time when the IP was last detected or given a category by the source.

rl.downloaded_files_statistics

{
  "known": 0,
  "unknown": 0,
  "suspicious": 0,
  "total": 0,
  "malicious": 0
}
  • total
    • The total number of files downloaded from the IP
  • known
    • The number of files classified as KNOWN
  • suspicious
    • The number of files classified as SUSPICIOUS
  • malicious
    • The number of files classified as MALICIOUS
  • unknown
    • The number of files without classification

rl.top_threats

List of top 5 threats found at a given IP. Threats are ranked first by files_count and then by threat_level.

{
  "threat_name": "string",
  "threat_level": 0,
  "files_count": 0
}
  • threat_name
    • Name of the specific threat that was found
  • threat_level
    • Threat level based on threat_name
  • files_count
    • The number of files classified as that threat

Examples - report retrieval​

Retrieve a report (JSON)​

Retrieving an IP report in JSON format, using a JSON POST body

/api/networking/ip/report/v1/query/json
{
  "rl": {
    "query": {
      "ip": "216.239.34.36",
      "response_format": "json"
    }
  }
}

Retrieve a report (JSON) for IP with no files​

Retrieving an IP report in JSON format, using a JSON POST body. The submitted IP has no files associated with it, but third party detections exist.

/api/networking/ip/report/v1/query/json
{
  "rl": {
    "query": {
      "ip": "149.28.54.212",
      "response_format": "json"
    }
  }
}

IP downloaded files endpoint​

Request​

POST /api/networking/ip/downloaded_files/v1/query/{format}

Path parameters:

  • format
    • Defines the POST body format. The following values are supported: xml and json.
    • Required

Request body:

{
  "rl": {
    "query": {
      "ip": "string",
      "response_format": "string",
      "limit": "string",
      "extended": "string",
      "classification": "string"
    }
  }
}
  • ip
    • The IP for which to retrieve a list of files.
    • Required
  • response_format
    • Defines the response format. The following values are supported: xml (default) and json
    • Optional
  • limit
    • The number of files to return in the response. Default value: 1000
    • Optional
  • extended
    • Allows choosing between true - extended, and false - non-extended data set (default)
    • Optional
  • classification
    • If this parameter is provided in the request, the response will contain only samples that match the requested classification. Supported values are: KNOWN, SUSPICIOUS, MALICIOUS, UNKNOWN
    • Optional

Response​

The response will contain metadata for files downloaded from the submitted IP. Empty fields are not included in the response.

{
  "rl": {
    "requested_ip": "string",
    "next_page": "string",
    "downloaded_files": []
  }
}
  • requested_ip
    • The submitted IP
  • downloaded_files
    • A list of files and their metadata
  • next_page
    • This value can be used with the page parameter in the next request to retrieve the next page of records

rl.downloaded_files[]

{
  "first_download": "string",
  "threat_level": 0,
  "classification": "string",
  "last_seen": "string",
  "last_download_url": "string",
  "sample_size": 0,
  "sample_available": 0,
  "sha1": "string",
  "last_download": "string",
  "first_seen": "string",
  "sha256": "string",
  "trust_factor": 0,
  "md5": "string"
}
  • sha1
    • The SHA1 hash of the file
  • last_download_url
    • URL from which the file was last downloaded
  • classification
    • File classification. Can be one of the following: KNOWN, MALICIOUS, SUSPICIOUS, UNKNOWN
  • md5
    • MD5 of the file
  • sha256
    • SHA256 of the file
  • first_download
    • Time when the file was first downloaded from the requested IP (UTC)
  • last_download
    • Time when the file was last downloaded from the requested IP (UTC)
  • sample_available
    • Indicates whether the sample is present in the ReversingLabs storage and available for download (true) or not (false).
  • trust_factor
    • Trustworthiness indicator for known samples, expressed as an integer between 0 and 5, where 0 indicates the most trusted samples (highest confidence). Applies to known samples only
  • threat_name
    • Complete malware threat name. Conforms to the ReversingLabs Malware naming standard: platform-subplatform.type.familyname. Applies to malicious and suspicious samples only
  • threat_level
    • Malware severity indicator for suspicious and malicious samples, expressed as an integer between 0 and 5, where 5 indicates the most dangerous threats (highest severity). Applies to malicious and suspicious samples only
  • malware_type
    • The type part of the full threat name detected for the sample (for example, Trojan, Adware, Rootkit...). Conforms to the ReversingLabs Malware naming standard. Applies to malicious and suspicious samples only
  • malware_family
    • The familyname part of the full threat name detected for the sample (for example, Marsdaemon, Orcus, Androrat...). Applies to malicious and suspicious samples only
  • platform
    • The platform targeted by the malware
  • subplatform
    • The subplatform targeted by the malware
  • sample_type
    • File type, as detected by Spectra Core
  • sample_size
    • File size (in bytes)
  • first_seen
    • Time when the sample was first seen in the ReversingLabs system (UTC)
  • last_seen
    • Time when the sample was last seen in the ReversingLabs system (UTC)

Examples - file metadata​

Retrieve files using pagination​

Get basic metadata about files downloaded from 37.34.248.24, starting from page 54d1ec4a661e374661f04c2db29e1736dac62ff8, using a json request. Limit the response to 2 items.

Request:

/api/networking/ip/downloaded_files/v1/query/json

Response:

{
  "rl": {
    "requested_ip": "37.34.248.24",
    "next_page": "5bbf9eb85c388624b367e46205dc62244544f33b",
    "downloaded_files": [
      {
        "last_download_url": "http://rgyui.top/dl/build.exe",
        "sha1": "54d1ec4a661e374661f04c2db29e1736dac62ff8",
        "classification": "MALICIOUS"
      },
      {
        "last_download_url": "http://acacaca.org/test3/get.php?first=true&pid=54CDD75ABCEFFD43CB02140E4B4CC293",
        "sha1": "596da184fb7a232c38144ebfd158af1e83224478",
        "classification": "KNOWN"
      }
    ]
  }
}

Retrieve files downloaded from an IP address with extended metadata​

Get extended metadata about MALICIOUS files downloaded from 37.34.248.24 using a JSON request. Request the response in JSON, and limit it to 1 item.

Request:

/api/networking/ip/downloaded_files/v1/query/json
{
  "rl": {
    "query": {
      "ip": "37.34.248.24",
      "limit": 1,
      "extended": true,
      "classification": "MALICIOUS",
      "response_format": "json"
    }
  }
}

Response:

{
  "rl": {
    "requested_ip": "37.34.248.24",
    "next_page": "54d1ec4a661e374661f04c2db29e1736dac62ff8",
    "downloaded_files": [
      {
        "first_download": "2022-03-23T23:14:01",
        "threat_level": 5,
        "classification": "MALICIOUS",
        "threat_name": "Win32.Ransomware.StopCrypt",
        "last_seen": "2022-09-24T20:10:31",
        "sample_type": "PE/Exe",
        "last_download_url": "http://zerit.top/dl/build2.exe",
        "sample_size": 659968,
        "sample_available": true,
        "sha1": "1d61784e581389bfbb73fb6c3fdc9eb7af9af9b9",
        "platform": "Win32",
        "last_download": "2022-03-23T23:14:01",
        "malware_type": "Ransomware",
        "first_seen": "2022-03-21T19:42:44",
        "sha256": "082bf5ea5ae40e0328401f3e74b516e362ddc57c60ab194e1d2afd297ddf6e5e",
        "trust_factor": 5,
        "malware_family": "StopCrypt",
        "md5": "467f161440e8fac46258178e1b0784ca"
      }
    ]
  }
}

IP URLs endpoint​

This service provides a list of URLs associated with the requested IP.

Request​

POST /api/networking/ip/urls/v1/query/{format}

Path parameters:

  • format
    • Defines the POST body format. The following values are supported: xml and json
    • Required

Request body:

{
  "rl": {
    "query": {
      "ip": "string",
      "response_format": "string",
      "limit": "string"
    }
  }
}
  • ip
    • The IP for which to retrieve the URLs.
    • Required
  • response_format
    • Defines the response format. The following values are supported: xml (default) and json.
    • Optional
  • limit
    • The number of files to return in the response. Default value: 1000
    • Optional

Response​

The endpoint will return a list of maximum limit records. If the limit value is not provided in the request, the maximum of 1000 records will be returned by default.

{
  "rl": {
    "requested_ip": "string",
    "next_page": "string",
    "urls": []
  }
}
  • requested_ip
    • submitted IP
  • next_page
    • This value can be used with the page parameter in the next request to retrieve the next page of analyzed URLs
  • urls
    • List of associated URLs

Examples - IP URLs​

Retrieve URLs for specified IP with paging​

Retrieving three records in JSON format, and providing the next page parameter 0030a7528573ce306ea2d0d9d66128b915bc95b1.

Request:

/api/networking/ip/urls/v1/query/json
{
  "rl": {
    "query": {
      "ip": "104.19.138.57",
      "limit": 3,
      "response_format": "json",
      "page": "0030a7528573ce306ea2d0d9d66128b915bc95b1"
    }
  }
}

Response:

{
  "rl": {
    "next_page": "006ecec7f550cadfcbc0176ca2ace08ad1833d02",
    "requested_ip": "104.19.138.57",
    "urls": [
      {
        "url": "https://google.com/url?cad=rja&esrc=s&rct=j&sa=t&source=web&uact=8&url=https://procrackerz.org/hitmanpro-crack-full-download/&usg=AOvVaw2qNutd2-aIy96HjHtql3Ww&ved=2ahUKEwiP4v79xZrxAhWotIsKHUMODTcQFjAAegQIBhAD"
      },
      {
        "url": "https://google.com/maps/place/Vernier+Software+&+Technology/"
      },
      {
        "url": "https://google.com/cse/cse.js?cx=014672437645974190520:sx5qa5dqcmm"
      }
    ]
  }
}

IP Domain Resolutions endpoint​

This service provides a list of IP-to-domain mappings for the specified IP.

Request​

POST /api/networking/ip/resolutions/v1/query/{format}

Path parameters:

  • format
    • Defines the POST body format. The following values are supported: xml and json
    • Required

Request body:

{
  "rl": {
    "query": {
      "ip": "string",
      "response_format": "string",
      "limit": "string"
    }
  }
}
  • ip
    • The IP for which to retrieve domain resolutions.
    • Required
  • response_format
    • Defines the response format. The following values are supported: xml (default) and json.
    • Optional
  • limit
    • The number of files to return in the response. Default value: 1000
    • Optional

Response​

The endpoint will return a list of maximum limit records. If the limit value is not provided in the request, the maximum of 1000 records will be returned by default.

{
  "rl": {
    "requested_ip": "string",
    "next_page": "string",
    "resolutions": []
  }
}
  • requested_ip
    • submitted IP
  • next_page
    • This value can be used with the page parameter in the next request to retrieve the next page of analyzed URLs
  • resolutions
    • List of associated resolutions

rl.resolutions

{
  "last_resolution_time": "string",
  "host_name": "string",
  "provider": "string"
}
  • host_name
    • The domain resolves to requested IP
  • last_resolution_time
    • Most recent time IP has resolved to this domain
  • provider
    • Provider of this resolution

Examples - IP Domain Resolutions​

Retrieve domain resolutions for an IP with paging​

Retrieving five records in JSON format, and providing the next page parameter 07c9693a82ee38525a7d75727abfae1bf03d9e31.

Request:

/api/networking/ip/resolutions/v1/query/json
{
  "rl": {
    "query": {
      "ip": "37.34.248.24",
      "response_format": "json",
      "limit": 3,
      "page": "587196222d542cf07fbb337dc6c723810738214e"
    }
  }
}

Response:

{
  "rl": {
    "requested_ip": "37.34.248.24",
    "resolutions": [
      {
        "provider": "ReversingLabs",
        "host_name": "zerit.top",
        "last_resolution_time": "2022-03-23T23:14:01"
      },
      {
        "provider": "ReversingLabs",
        "host_name": "winnlinne.com",
        "last_resolution_time": "2022-10-07T00:29:41"
      },
      {
        "provider": "ReversingLabs",
        "host_name": "abababa.org",
        "last_resolution_time": "2022-06-17T10:49:43"
      }
    ],
    "next_page": "6f4226f6457c9e24364d56dd3c047acbc1b25fc8"
  }
}