Retrieve Reputation Information from Global Threat Intelligence

In this tutorial, we will explain, step-by-step, how to retrieve reputation information from the Cybereason Global Threat intelligence server.

When analyzing different IOCs found in your environment, you may want to check how Cybereason classifies these IOCs. You can use the Cybereason API to retrieve reputation information on IP addresses, domain names, and file hashes from Cybereason Global Threat Intelligence.

You can then use this information to enrich your understanding of the IOCs you find.

Retrieve file reputations

Note

The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).

  1. In your REST API client, open a new tab/file.

  2. In the relevant field, enter the URL for the request:

    https://sage.cybereason.com/rest/classification_v1/file_batch

    For example, in Postman, you enter the URL here:

    URL to use for an API authentication request in the Postman API client

  3. Ensure that the method for the request is set to POST. (This may be the default for your REST API client, but if not, ensure that you select it.)

    Example of setting a method for the request

  4. For the Headers, in the Key column, add a Content-Type header.

  5. In the Value column, add the value application/json.

    For example, in Postman, your header will look like this:

    Example of request headers to use in a REST API client

  6. Navigate to the section to add your request body. In Postman, for example, this is the Body tab.

  7. In the Body tab, ensure that you have set your client editor to enable you to add raw JSON content. In Postman, for example, ensure tha Raw is selected.

  8. In the request body edit area, enter an open and closed bracket {}. This is the standard syntax for JSON.

  9. Inside the brackets, add this template request body:

    {
     "requestData": [
                 {
                  "requestKey": {
                              "md5": "<file hash value>"
                             }
                }
               ]
    }
    

    You will fill in this request part by part in the steps below.

  10. To check the reputation of a file hash, you need to provide the MD5 or SHA-1 hash value for a file.

    In the request body for the md5 key, for the <file hash value> placeholder value, update the value to 92f44e405db16ac55d97e3bfe3b132fa (a fictitious hash value).

    If you only had the SHA-1 value, you would change the md5 key to sha1 instead.

    Note

    If you want to check the value of a real file, substitute the actual file hash value in place of this fictitious one.

    {
     "requestData": [
                 {
                  "requestKey": {
                              "md5": "**92f44e405db16ac55d97e3bfe3b132fa**"
                             }
                }
               ]
    }
    
  11. In your client machine, run your request.

    In the response, the Cybereason Global Threat Intelligence server returns the classification/reputation details:

    {
        "classificationResponses": [
            {
                "requestKey": {
                    "sha1": null,
                    "md5": "92f44e405db16ac55d97e3bfe3b132fa"
                },
                "ttl": 62957583,
                "aggregatedResult": {
                    "maliciousClassification": {
                        "type": "indifferent",
                        "classificationScore": -1,
                        "typeScore": -1
                    },
                    "productClassification": {
                        "productType": "SHELL",
                        "type": "SHELL",
                        "title": "Power Shell",
                        "manufacturer": "Microsoft Windows",
                        "signatureVerified": true,
                        "externalSignatureVerificationStatus": "SIGNATURE_VERIFICATION_STATUS_SUCCESS",
                        "signed": true
                    },
                    "link": "https://www.virustotal.com/file/6c05e11399b7e3c8ed31bae72014cf249c144a8f4a2c54a758eb2e6fad47aec7/analysis/1533661076/"
                }
            }
        ]
    }
    

    In the request, you want to look inside the aggregatedResult object, in the maliciousClassification object, for the type key to see the actual classification.

    The other keys in the response can also provide details about the file to help your understand as needed.

Retrieve domain reputations

Note

The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).

  1. In your REST API client, open another new tab/file.

  2. In the relevant field, enter the URL for the request:

    https://sage.cybereason.com/rest/classification_v1/domain_batch

  3. Ensure that the method for the request is set to POST.

  4. For the Headers, in the Key column, add a Content-Type header.

  5. In the Value column, add the value application/json.

  6. In the Body tab, ensure that you ahve set your client editor to enable you to add raw JSON content.

  7. In the request body edit area, enter an open and closed bracket {}.

  8. Inside the brackets, add this template request body:

    {
     "requestData": [
                 {
                  "requestKey": {
                              "domain": "<domain name>"
                             }
                 }
                ]
    }
    
  9. To check a domain reputation, you need to provide the domain name.

    In the requedst body, for the domain key, update the <domain name> placeholder value to *www.cybereason.com.

    {
     "requestData": [
                 {
                  "requestKey": {
                              "domain": "www.cybereason.com"
                             }
                 }
                ]
    }
    
  10. In your client machine, run the request.

    In the response, the Cybereason Global Threat Intelligence server returns the classification/reputation details:

    {
        "classificationResponses": [
            {
                "requestKey": {
                    "domain": "www.cybereason.com"
                },
                "ttl": 52388991,
                "aggregatedResult": {
                    "maliciousClassification": {
                        "type": "indifferent",
                        "classificationScore": -1,
                        "typeScore": -1,
                        "source": "VirusTotal"
                    },
                    "link": "https://www.virustotal.com/en/domain/www.cybereason.com/information",
                    "firstSeen": 1481719121821
                },
                "allowFurtherClassification": true,
                "cpId": 2,
                "cpType": "VIRUS_TOTAL"
            }
        ]
    }
    

    In the request, you want to look inside the aggregatedResult object, in the maliciousClassification object, for the type key to see the actual classification.

    The other keys in the response can also provide details about the domain to help your understanding as needed.

Retrieve IP address reputations

Note

The request body is the same regardless of how you run the request (such as a cURL command, in a REST API client, or Python script).

  1. In your REST API client, open another new tab/file.

  2. In the relevant field, enter the URL for the request:

    https://sage.cybereason.com/rest/classification_v1/ip_batch

  3. Ensure that the method for the request is set to POST.

  4. For the Headers, in the Key column, add a Content-Type header.

  5. In the Value column, add the value application/json.

  6. Navigate to the section to add your request body.

  7. In the Body tab, ensure that you ahe set your client editor to enable you to add JSON content.

  8. In the request body edit area, enter an open and closed bracket {}.

  9. Inside the brackets, add this template request body:

    {
       "requestData": [
                          {
                              "requestKey": {
                                  "ipAddress": "<address>",
                                  "addressType": "<type>"
                              }
                          }
                      ]
                  }
    
  10. To check the reputation of an IP address, you need to provide IP address string.

    In the request body, for the ipAddress key, update the <IP address> value to 12.34.56.78 (a ficticious IP address).

    {
       "requestData": [
                          {
                              "requestKey": {
                                  "ipAddress": "**12.34.56.78**",
                                  "addressType": "<type>"
                              }
                          }
                      ]
                  }
    
  11. In addition, you need to specify the type of IP address.

    Below the ipAddress key, in the addressType key, for the type placeholder value, update the value to Ipv4 to indicate it is an IPv4 address type.

    {
       "requestData": [
                          {
                              "requestKey": {
                                  "ipAddress": "12.34.56.78",
                                  "addressType": "**Ipv**"
                              }
                          }
                      ]
                  }
    
  12. In your client machine, run the request.

    In the response, the Cybereason Global Threat Intelligence server returns the classification/reputation details:

    {
        "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"
            }
        ]
    }
    

    In the request, you want to look inside the aggregatedResult object, in the maliciousClassification object, for the type key to see the actual classification.

    The other keys in the response can also provide details about the file to help your understanding as needed.