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
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:
|
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:
|
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:
|
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:
|
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
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"
}
]
}
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.
Use this request body:
{
"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"
}
]
}
Request
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.
import requests
import json
session = requests.session()
# Request URL
sage_url = "https://sage.cybereason.com"
endpoint_url = "/rest/classification_v1/ip_batch"
api_url = sage_url + endpoint_url
# These are the variables that represent different fields in the request.
ip_address = "1.2.3.4"
ip_type = "Ipv4"
query = json.dumps({"requestData":[{"requestKey":{"ipAddress":ip_address,"addressType":ip_type}}]})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
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"
}
]
}