Get an IP Address Reputation

Endpoint URL: https://sage.cybereason.com/rest/classification_v1/ip_batch
Endpoint URI: classification_v1/ip_batch

Action: POST

Returns details on IP address reputations based on the Cybereason threat intelligence service.

Request Headers

You must add an Content-Type:application/json header with the request.

Note

If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.

Request Body

Input: JSON

Download JSON syntax file

Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.

                {
                  "requestData": [
                                    {
                                        "requestKey": {
                                                          "ipAddress": "<IP address>",
                                                          "addressType": "<type>"
                                                      }
                                    }
                                 ]
                }

Request Parameters

URL/URI parameters: none

Request Body Parameters: The request contains the following fields/parameters:

Parameter	Type	Description
requestData	Array	An object that holds the list of items about which to return file reputation data.
requestKey	Array	An object containing the IP address on which you want to view threat intelligence data. You must add an ipAddress and addressType field in this object.
ipAddress	String	The IP address for which to return reputation information.
addressType	Enum	The type of IP address. Possible values include: Ipv4 Ipv6

Response Status Code

This request can return the following status codes:

• 200: Success OK or an error message saying why

Response Success Schema

The response contains the following fields:

Field	Type	Description
classificationResponses	Array	An object containing details on the domain reputation.
requestKey	Array	An array containing domain names.
ipAddress	String	The IP address for which you want to return reputation information.
addressType	Enum	The format for the IP address. Possible values include: Ipv4 Ipv6
ttl	Integer	Timestamp representing time the data is live.
aggregatedClassification	Array	An object containing the classification details on the IP address requested.
maliciousClassification	Array	An object containing malicious classification details on the IP address requested.
type	Enum	The malicious classification type for the IP address. Possible values include: ransomware maltool unwanted malware whitelist indifferent unknown no_type_found blacklist
classificationScore	Integer	The internal numerical value used by the Cybereason threat intelligence service to evaluate the malicious nature of an indicator. A score of -1 indicates a suspicious or malicious classification.
typeScore	Integer	The internal numerical value used by the Cybereason threat intelligence service for the type assigned to the file.
source	String	The source of the threat intelligence classification.
link	String	The link to the source of the threat intelligence that provides the reputation for this IP address.
firstSeen	Integer	A timestamp (in epoch) when the IP address was first seen by the Cybereason platform.
allowFurtherClassification	Boolean	Indicates whether additional classification for the IP address is possible.
cpId	Integer	A unique numerical ID created for the classification.
cpType	Enum	The type of classification, based on the decision of classification. Possible values include: TOKEN SAGE_API SAGE_GLOBAL CUSTOMER_CLASSIFICATION AV_REPORTED
lastUploadTimestamp	Integer	A timestamp (in epoch) when the information was last updated on the Threat Intel Server.

Response Failure Schema

None

Important Response Fields

Important information is found in these fields:

• classificationResponses object: An object containing details on the IP addresses you entered in the request body.

• ipAddress: The IP address on which you want threat intelligence.

• addressType: The IP version for the IP address (either version 4 or version 6).

• type: The classification assigned to the IP address by the Cybereason platform.

• source: The source used for the classification.

• link: A link to learn more about the IP address classification.

Example: Get the reputation for an IP address

CURLREST API ClientPython

Request

curl --request POST \
    --url https://sage.cybereason.com/rest/classification_v1/ip_batch \
    --header 'Content-Type:application/json' \
    --data '{
              "requestData": [
                                {
                                    "requestKey": {
                                                      "ipAddress": "1.2.3.4",
                                                      "addressType": "Ipv4"
                                                  }
                                }
                             ]
            }'

Response

{
    "classificationResponses": [
        {
            "requestKey": {
                "ipAddress": "1.2.3.4",
                "addressType": "Ipv4"
            },
            "ttl": 1920533,
            "aggregatedResult": {
                "maliciousClassification": {
                    "type": "indifferent",
                    "classificationScore": -1,
                    "typeScore": -1,
                    "source": "Example"
                },
                "link": "http://www.cybereason.com",
                "firstSeen": 1476350974204
            },
            "allowFurtherClassification": true,
            "cpId": 1,
            "cpType": "TOKEN"
        }
    ]
}