Add Information from an Uploaded File to the User-Defined Suspicious Objects List

This task encodes a file to Base64, uploads the file to the Apex Central server, extracts information from the file, and adds the information to the User-Defined Suspicious Objects (UDSO) list.

  1. Obtain an application ID and API key.
  2. Define the libraries and functions necessary to create JSON Web Tokens for authorization.
  3. Encode and upload the file, and then extract and add information to the UDSO list.

Obtain an Application ID and API Key

This task retrieves the application ID and API key for an external application that consumes Apex Central Automation APIs.

  1. Go to Administration > Settings > Automation API Access Settings.

    The Automation API Access Settings screen appears.

  2. Click Add.

    The Application Access Settings section appears and displays the following information:

    • Application ID: Used by Apex Central to identify the external application

    • API key: Used by the external application to sign requests sent to Apex Central

    • API type: Indicates the API functions that the external application can access

  3. Select Enable application integration using Apex Central Automation APIs.
  4. Configure the following settings.

    • Application name: Specify an easily identifiable name for the application.

    • Communication time-out: Select the maximum number of seconds allowed for a request to reach Apex Central after the application generates the request.

  5. Click Save.

    The Automation API Access Settings screen appears and displays the newly added application in the table.

  6. In Python, assign values to following parameters.

    Parameter

    Value

    use_application_id

    Your application ID

    use_api_key

    Your API key

    use_url_base

    Your server URL

    		 
    use_application_id = YOUR_APPLICATION_ID
use_api_key = YOUR_API_KEY
use_url_base = YOUR_SERVER_URL

Define the Libraries and Functions Required for JSON Web Token Creation

This task defines the necessary libraries and functions for creating the JSON web token (JWT).

  1. Define the necessary libraries. 
    import base64
import jwt
import hashlib
import time
import json
  2. Define the function that creates the checksum. 
    def create_checksum(http_method, raw_url, headers, request_body):
    string_to_hash = http_method.upper() + '|' + raw_url.lower() + '|' + headers + '|' + request_body
    base64_string = base64.b64encode(hashlib.sha256(str.encode(string_to_hash)).digest()).decode('utf-8')
    return base64_string
  3. Define the function that creates the JWT. 
    
def create_jwt_token(appication_id, api_key, http_method, raw_url, headers, request_body,
                     iat=time.time(), algorithm='HS256', version='V1'):
    checksum = create_checksum(http_method, raw_url, headers, request_body)
    payload = {'appid': appication_id,
               'iat': iat,
               'version': version,
               'checksum': checksum}
    token = jwt.encode(payload, api_key, algorithm=algorithm).decode('utf-8')
    return token

Upload the File and Add Information to the User-Defined Suspicious Objects List

This task extracts and adds information from the uploaded file to the User-Defined Suspicious Objects (UDSO) list.

  1. Assign a value to file_name. 
    file_name = <YOUR_FILE_PATH>

    In this use case, the assigned file name is VerySmallFile.txt.

  2. Encode the file to Base64. 
    file_name='VerySmallFile.txt'
# Encoding the YARA file to base 64.
print('Encoding the YARA file to base 64.')
with open(file_name, "rb") as f:
    file_string_base64 = base64.b64encode(f.read())
  3. Upload the file to the Apex Central server, extract information from the file, add the information to the User-defined Suspicious Objects list, and assign the response value to r.

    For more information about the "Add file object to UDSO list" API, see https://automation.trendmicro.com/apex-central/api#operation/SuspiciousObjectResource_GetProductServers.

    Important:

    You must assign a value to file_scan_action, which is the action to be performed on the extracted file objects.

    The possible values are Log, Block, and Quarantine. In this use case, the assigned value is Log.

    # Upload the file to the Apex Central server.
print('Upload the file to the Apex Central server.')
 
productAgentAPIPath = '/WebApp/API/SuspiciousObjectResource/FileUDSO'
canonicalRequestHeaders = ''
useQueryString = ''
 
payload = {
  "file_name":file_name,
  "file_content_base64_string":file_string_base64.decode(),
  "file_scan_action":"LOG",
  "note":"Small file for test"
}
 
useRequestBody = json.dumps(payload) 
  
 
jwt_token = create_jwt_token(use_application_id, use_api_key, 'PUT',
                              productAgentAPIPath + useQueryString,
                              canonicalRequestHeaders, useRequestBody, iat=time.time())
 
headers = {'Authorization': 'Bearer ' + jwt_token, 'Content-Type': "application/json"}
 
r = requests.put(use_url_base + productAgentAPIPath + useQueryString, headers=headers, data=useRequestBody, verify=False)
  4. Perform error handling and print the API response. 
    if r.status_code !=200 and r.status_code!=201:
  print('Not successful, please handle your error')
print(r.status_code)
print(json.dumps(r.json(), indent=4))
  5. Verify that the operation was successful.

    If your request was successful, the response will be similar to the following:

    200
{
    "result_code": 1,
    "result_description": "Operation successful",
    "result_content": null
}
  6. Retrieve a list of UDSO entries from the Apex Central server.

    For more information about the "List UDSO entries" API, see https://automation.trendmicro.com/apex-central/api#operation/SuspiciousObjects_QueryUserDefinedSO.

    Note:

    You must specify the type of UDSO entry that you want to retrieve. In this use case, the useQueryString value is "?type=file".

    # (Optional) Check the result in the UDSO entries list.
print('(Optional) Check the result in the UDSO entries list.')
 
productAgentAPIPath = '/WebApp/api/SuspiciousObjects/UserDefinedSO/'
canonicalRequestHeaders = ''
 
useRequestBody = ''
 
useQueryString="?type=file"
jwt_token = create_jwt_token(use_application_id, use_api_key, 'GET',
                              productAgentAPIPath + useQueryString,
                              canonicalRequestHeaders, useRequestBody, iat=time.time())
 
headers = {'Authorization': 'Bearer ' + jwt_token , 'Content-Type': 'application/json;charset=utf-8'}
r = requests.get(use_url_base + productAgentAPIPath + useQueryString, headers=headers, verify=False)
 
print(r.status_code)
print(json.dumps(r.json(), indent=4))
  7. Verify that the objects listed in the response are files.

    If your request was successful, the response will be similar to the following:

    200
{
    "Data": [
        {
            "type": "file",
            "content": "601F1889667EFAEBB33B8C12572835DA3F027F78",
            "notes": "Small file for test",
            "scan_action": "log",
            "expiration_utc_date": null
        },
        {
            "type": "file",
            "content": "AFDB5F8ABCB4568224758141062B80573A79F300",
            "notes": "yara from desktop",
            "scan_action": "log",
            "expiration_utc_date": null
        }
    ],
    "Meta": {
        "Result": 1,
        "ErrorCode": 0,
        "ErrorMsg": ""
    },
    "PermissionCtrl": {
        "permission": "255",
        "elements": null
    },
    "FeatureCtrl": {
        "mode": "0"
    },
    "SystemCtrl": {
        "TmcmSoDist_Role": "none"
    }
}