Skip to main content

Network reputation (TCA-0407)

The Network Reputation service provides information regarding the reputation of a requested URL, domain, or IP address. When a URL is submitted, the service provides its ReversingLabs classification, along with an overview of detections from our partners. It also includes the category of the URL (for example phishing, gambling, adult content) and indicates whether we have encountered any malware samples associated with the submitted URL.

When a domain or IP address is submitted, the response does not include the ReversingLabs classification. The remaining information in the response remains the same as for URLs.

The service supports both single and bulk queries. Bulk queries allow for a combination of URLs, domains, and IP addresses to be processed in the same request.

General Info about Requests/Responses​

  • All requests require the post_format parameter which supports two options: xml or json.
  • Default response format is xml
  • The number of URLs, domains or IP addresses in the request must not be greater than 100.

Network Reputation Query​

This query returns reputation information about queried URLs, domains and IP addresses.

Request​

POST /api/networking/reputation/v1/query/{post_format}

Path parameters:

  • post_format
    • Required parameter that defines the POST payload format. Supported options are xml and json.

Request body:

{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "string"
        },
        {
          "network_location": "string",
          "type": "string"
        }
      ],
      "response_format": "string"
    }
  }
}
  • network_locations
    • A list of one or more network locations to be queried.
    • For every network_location, users can optionally set the type of the requested URI: URL, IP or DOMAIN. If the type isn't provided, the service will detect the URI type.
    • Expected domain format: fully qualified domain name using dots as separators, without any prefixes or suffixes.
    • Expected URL format: Submissions prefixed with a protocol name (http:// and https://).
    • Expected IP format: IP address without any prefixes or suffixes (1.2.3.4).
    • Submissions that do not follow the expected formatting will be interpreted as follows:
      • A domain or IP with a slash (domain.suffix/ or 1.2.3.4/) will be treated as a URL.
      • Entries with multiple slashes at the end or prefixed by protocols (e.g., https://1.2.3.4, 1.2.3.4// ) are also URLs.
    • Required
  • response_format
    • Defines the response format. Supported options are xml and json. The default is xml.
    • Optional

Response​

The response contains reputation information for all valid requested network locations, along with the list of invalid network locations.

{
  "rl": {
    "entries": []
  }
}

rl.entries[]

{
  "type": "string",
  "requested_network_location": "string",
  "associated_malware": 0,
  "last_seen": "string",
  "first_seen": "string",
  "third_party_reputations": {},
  "threat_level": 0
}

  • requested_network_location

    • The requested URL, domain or IP address

  • type

    • The type of requested network location

  • classification

    • ReversingLabs classification, available only for URLs. Possible values are malicious, suspicious, known, or unknown.

  • categories

    • List of categories that the URI in question belongs to. List items are strings. The strings are arbitrary values obtained from third-party sources or from user overrides (using TCA-0408).

  • first_seen

    • Indicates the initial detection of the requested URL/domain/IP by a third-party source, the first instance of obtaining metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the first time the requested URL has been crawled or analyzed by the Spectra Sandbox.

  • last_seen

    • The last time when the requested URL/domain/IP received an indicator that updated its report. This can be the last time when we checked the URL/domain/IP reputation against third-party sources, the last time we obtained metadata for the requested URL/domain/IP from ReversingLabs static/dynamic file processing services (related files), or the last time the requested URL/domain/IP has been crawled or analyzed by the Spectra Sandbox.

  • third_party_reputations

    • Third party URL/domain/IP reputation counters showing the number of third party sources that detected the item as malicious/clean/undetected.

  • associated_malware

    • A boolean indicator showing if ReversingLabs downloaded malware from the submitted URL/domain/IP directly. The value does not rely on third-party results.

  • reason

    • Reason why the URL was given a classification. This parameter is only shown if the classification is not unknown. Possible values are
      • whitelist, blacklist - The URL was found on a ReversingLabs curated whitelist/blacklist.
      • file_reputation - Classification based on the downloaded content.
      • sandbox - Classification based on dynamic analysis (ReversingLabs Cloud Sandbox).
      • third_party_reputation, domain_third_party_reputation - Classification based on third-party reputation sources.
      • user_override - Classification overridden by you, or a user belonging to your organization.
      • analyst_override - Classification overridden by a ReversingLabs analyst.

  • threat_level

    • Malware severity indicator expressed as an integer between 0 and 5. Values from 1 to 5 indicate threats from lowest to highest severity, 0 is reserved for known URIs. For unknown URIs, this value is omitted.
    • In real-world situations, threat level values are typically interpreted in the following way:
      • Threat Level 4, 5 - immediate response required (e.g., different types of Trojans, URI found on a blocklist or matches a known malware regex)
      • Threat Level 2, 3 - should be examined within 24 hours (e.g., first stage exploits, URLs with homoglyph variations)
      • Threat Level 1 - not urgent, but should be periodically reviewed (e.g. Adware / PUA, misleading subdomains).

Examples​

Example 1​

A JSON URL query request and response.

Request:

/api/networking/reputation/v1/query/json

{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "http://icayus.com/wTpWgvg"
        }
      ],
      "response_format": "json"
    }
  }
}

Response:

{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "http://icayus.com/wTpWgvg",
        "associated_malware": false,
        "last_seen": "2024-04-16T07:12:50",
        "first_seen": "2024-03-11T19:15:10",
        "classification": "malicious",
        "reason": "third_party_reputation",
        "categories": [
          "phishing",
          "spam",
          "suspicious",
          "scam_illegal_unethical",
          "uncategorized"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 17,
          "malicious": 2,
	  "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}

Example 2​

A JSON query including all supported types: URL, domain and IP address. Some are provided without the optional type field.

Request:

/api/networking/reputation/v1/query/json

{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "https://psychology-degree-programs-us.today/"
        },
        {
          "network_location": "https://international-partnerships.ec.europa.eu/index_en",
          "type": "url"
        },
        {
          "network_location": "www.stemalservice.it",
          "type": "domain"
        },
        {
          "network_location": "216.239.34.36",
          "type": "ip"
        }
      ],
      "response_format": "json"
    }
  }
}

Response:

{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "https://psychology-degree-programs-us.today/",
        "associated_malware": false,
        "last_seen": "2024-04-16T07:19:54",
        "first_seen": "2024-01-24T19:17:44",
        "classification": "known",
        "reason": "file_reputation",
        "categories": [
          "business_and_economy",
          "uncategorized"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	  "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "url",
        "requested_network_location": "https://international-partnerships.ec.europa.eu/index_en",
        "associated_malware": false,
        "last_seen": "2024-04-16T06:07:36",
        "first_seen": "2024-04-15T08:45:36",
        "classification": "known",
        "reason": "file_reputation",
        "categories": [
          "government_legal",
          "government"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	  "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "domain",
        "requested_network_location": "www.stemalservice.it",
        "associated_malware": false,
        "last_seen": "2024-04-10T05:29:50",
        "first_seen": "2024-04-10T05:29:50",
        "third_party_reputations": {
          "total": 12,
          "undetected": 12,
          "malicious": 0,
	  "suspicious": 0,
          "clean": 0
        }
      },
      {
        "type": "ip",
        "requested_network_location": "216.239.34.36",
        "associated_malware": false,
        "last_seen": "2024-04-15T10:42:56",
        "first_seen": "2024-02-16T22:41:05",
        "third_party_reputations": {
          "total": 11,
          "undetected": 11,
          "malicious": 0,
	  "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}

Example 3​

A JSON URL query, the result has a user classification override.

Request:

/api/networking/reputation/v1/query/json

{
  "rl": {
    "query": {
      "network_locations": [
        {
          "network_location": "https://override-my-example.com"
        }
      ],
      "response_format": "json"
    }
  }
}

Response:

{
  "rl": {
    "entries": [
      {
        "type": "url",
        "requested_network_location": "https://override-my-example.com",
        "associated_malware": false,
        "last_seen": "2024-04-16T08:08:04",
        "first_seen": "2024-04-16T08:08:04",
        "classification": "malicious",
        "reason": "user_override",
        "categories": [
          "Proxy Avoidance and Anonymizers"
        ],
        "third_party_reputations": {
          "total": 19,
          "undetected": 19,
          "malicious": 0,
	  "suspicious": 0,
          "clean": 0
        }
      }
    ]
  }
}

Custom Response Status Codes​

This API implements custom response status codes:

CODEDESCRIPTION
413The request contained more than the maximum allowed amount of network locations (100).