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

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

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