Support Center > Search Results > SecureKnowledge Details
Additional Threat Emulation API info on Appliance Technical Level
Solution

Table of Contents:

  1. Introduction
  2. Availability
  3. Version Information
  4. Error Results Information
  5. How to Control the Error Results Cache

(1) Introduction

We are pleased to announce that additional Threat Emulation information is available through the Threat Prevention API on SandBlast Appliances (also known as Threat Prevention API to Appliance). 

The additional information is:
  • Threat Emulation version
  • Threat Emulation error results

(2) Availability

The additional API information is supported on Appliances that run Threat Emulation Engine release 10.2 and above.


(3) Version Information

You can see the appliance's Threat Emulation engine version through the API when you call Upload API or Query API. 

To see the version information, do the following:

1. Set the enable_allow_api_return_engine_version TECLI attribute to enabled. To do this., run the following TECLI command on the appliance:

[Expert@HostName:0]# tecli advance attribute set enable_allow_api_return_engine_version 1

Note
: You need to do this just once. 

2. Within the Request body, within the "te" object, add a new JSON Boolean attribute named version_info along with the true value. 

As a result, the Threat Emulation engine version appears within the Response body, within the "te" object, as a new JSON attribute named te_engine_version, along with a value in the format of tecli advance engine version output.


Request Example:
{

    "request" : [

         {

              "features" : [ "te" ],

              "sha1" : "...",

              "te" : {

                  "version_info" : true,

                  "reports" : [ ... ]

              }

         }

    ]

}


Response Example:
{

    "response": [

         {

              "features": [ "te" ],
              "md5": "...",
              "sha1": "...",
              "sha256": "...",
              "status": {
                  "code": ...,
                  "label": "...",
                  "message": "..."
              },
              "te": {
                  ...
                  "status": {
                      "code": ...
                      "label": "...",
                      "message": "..."
                  },
                  "te_engine_version": "59.990000065"
              }
          }
    ]
}

(4) Error Results Information

When Threat Emulation determines an error result to a file uploaded by the API, you can receive that error through the API.

You can receive this information during the set of API calls for handling and getting Threat Emulation verdict results. The optional Query API call (for checking if the result already exists in Threat Emulation cache) is first. If there are no results, the Upload API call is next, after which there is set of consecutive Query API calls until you receive the Threat Emulation result.

To receive these error results (if they exist), do the following. Note: you need to do steps 1..3 just once, on the Policy Granularity Manager:

1. Set the "password protected archives" error type to error state. Run the following TECLI command on the appliance:
       
[Expert@HostName:0]# tecli advance error set archive_pass_protected error

2. Set the "password protected document" error type to error state. Run the following TECLI command on the appliance:
       
[Expert@HostName:0]# tecli advance error set doc_pass_protected error

3. Verify that all error types are set to error state. Run the following TECLI command on the appliance:

        [Expert@HostName:0]# tecli advance error show

If there are still error types not set to error state, then set each of them to error state by following the instructions in the Threat Emulation Policy Granularity Manager

4. In both the Upload and Query API calls, within the Request body, within the "te" object, add a new JSON Boolean attribute named "return_errors" along with the true value. 

When Threat Emulation handling the Request determines an error result, then that error result appears within the Response, within the "te" object, as follows:
  • "status" is FOUND  (meaning "code" : 1001  and  "label" : "FOUND")
  • "combined_verdict" : "Error"
  • A new JSON attribute named "error_message" appears.
Important Note:  No additional JSON data appears within the "te" object of an error result.

The "error_message"
JSON attribute can have the following values:
  • File exceeds size limit
  • Password protected archives cannot be emulated
  • Max number of files in archive reached
  • Archive extraction error
  • Max decompression rate limit reached in the archive.
  • Unsupported file type
  • Password protected document
  • General Error
Request Example:
{

    "request" : [

         {

              "features" : [ "te" ],

              "sha1" : "...",

              "te" : {

                  "return_errors" : true,

                  "reports" : [ ... ]

              }

         }

    ]

}


Response Example:
{

    "response": [

         {

              "features": [ "te" ],
              "md5": "...",
              "sha1": "...",
              "sha256": "...",
              "status": {
                  "code": ...,
                  "label": "...",
                  "message": "..."
              },
              "te": {
                  "combined_verdict": "Error",
                  "error_message": "Archive extraction error",
                  "status": {
                      "code": 1001,
                      "label": "FOUND",
                      "message": "We have found your request"
                }
              }
          }
    ]
}

(5) How to Control the Error Results Cache

The additional API Threat Emulation error results are kept in the appliance's local cache. You can view and control the cache with the following TECLI commands:
  • To view the current error results cache, run the following TECLI command on the appliance:

            [Expert@HostName:0]# tecli cache api_errors dump
  • To remove all current error results from the cache, run the following TECLI command on the appliance:

            [Expert@HostName:0]# tecli cache api_errors clean
  • To view the error results TTL, run the following TECLI command on the appliance:

            [Expert@HostName:0]# tecli cache api_errors ttl display
  • To change the error results TTL, run the following TECLI command on the appliance:

            [Expert@HostName:0]# tecli cache api_errors ttl set <value in minutes>
  • To revert the error results TTL to its default value, run the following TECLI command on the appliance:

            [Expert@HostName:0]# tecli cache api_errors ttl default



This solution has been verified for the specific scenario, described by the combination of Product, Version and Symptoms. It may not work in other scenarios.

Give us Feedback
Please rate this document
[1=Worst,5=Best]
Comment