Add Objects from a STIX File to the User-Defined Suspicious Objects List

This task uploads a STIX file and then adds objects from the file to the User-Defined Suspicious Objects (UDSO) list.

Obtain an application ID and API key.
Define the libraries and functions necessary to create JSON Web Tokens for authorization.
Prepare and upload the OpenIOC file.
Add objects from the OpenIOC file to the User-Defined Suspicious Objects list.
Verify that the objects were added to the User-Defined Suspicious Objects 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.

Go to Administration > Settings > Automation API Access Settings.

The Automation API Access Settings screen appears.
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
Select Enable application integration using Apex Central Automation APIs.
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.
Click Save.

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

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).

Define the necessary libraries.

import base64
import jwt
import hashlib
import time
import json

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

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

Prepare and Upload the STIX File

This task encodes the STIX file to Base64 and uploads the file to the Apex Central server.

Assign a value to file_name.
```
file_name = <YOUR_FILE_PATH>
```
In this use case, the assigned file name is STIX_Malware_Sample.xml.

Encode the file to Base64.

file_name='STIX_Malware_Sample.xml'
# Encoding the OpenIOC file to base64.
print('1.Encoding the OpenIOC file to base64.')
with open(file_name, "rb") as f:
    file_string_base64 = base64.b64encode(f.read())

Upload the file to the Apex Central server and assign the response value to r.

For more information about the "Upload STIX file" API, see https://automation.trendmicro.com/apex-central/api#operation/STIXResource_POSTFile.

# Upload the STIX file to the Apex Central server.
print('Upload the STIX file to the Apex Central server.')
productAgentAPIPath = '/WebApp/IOCBackend/STIXResource/File'
canonicalRequestHeaders = ''
useQueryString = ''
 
payload = {
  "param":
  [
    {
      "FileName": file_name,
      "FileContentBase64":file_string_base64.decode()
    }
  ]
}
useRequestBody = json.dumps(payload) 
  
jwt_token = create_jwt_token(use_application_id, use_api_key, 'POST',
                              productAgentAPIPath + useQueryString,
                              canonicalRequestHeaders, useRequestBody, iat=time.time())
 
headers = {'Authorization': 'Bearer ' + jwt_token , 'Content-Type': 'application/json;charset=utf-8'}
r = requests.post(use_url_base + productAgentAPIPath + useQueryString, headers=headers, data=useRequestBody, verify=False)

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))
file_hashID = r.json()["Data"]["UploadedResultInfoList"][0]["FileHashID"]
print('file hashID:',file_hashID)

Verify that the file was uploaded.

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

200
{
    "Data": {
        "UploadedResultInfoList": [
            {
                "FileName": "STIX_Malware_Sample.xml",
                "FileHashID": "6c9855686b26c72858f21cfe9716f157459bed85",
                "UploadedStatus": 1
            }
        ],
        "UploadedResultMessageList": [
            {
                "MessageType": 1,
                "Message": "Uploaded 1 STIX file(s) successfully."
            }
        ]
    },
    "Meta": {
        "Result": 1,
        "ErrorCode": 0,
        "ErrorMsg": ""
    },
    "PermissionCtrl": {
        "permission": "255",
        "elements": null
    },
    "FeatureCtrl": {
        "mode": "0"
    },
    "SystemCtrl": {
        "TmcmSoDist_Role": "none"
    }
}

Assign values to the following parameters:


Parameter	Description	Value
`file_hashID`	Hash value of the uploaded file	`FileHashID` value from the response to the previous API call
`ScanType`	Action to be performed on objects added to the UDSO list	One of the following: `1`: Log `2`: Block `3`: Quarantine Note: In this use case, the value assigned to all objects is `1`.


file_hashID = r.json()["Data"]["UploadedResultInfoList"][0]["FileHashID"]

Print the value of file_hashID.
```
print('file hashID:',file_hashID)
```

Add Objects to the User-Defined Suspicious Objects List (STIX)

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

Extract objects from the file, add the objects to the UDSO list, and assign the response value to r.

For more information about the "Extract STIX objects to list" API, see https://automation.trendmicro.com/apex-central/api#operation/UserDefinedSOResource_STIXExtraction.

# Add Objects to UDSO from STIX file.
print('Add Objects to UDSO from STIX file.')
 
productAgentAPIPath = '/WebApp/SuspiciousObjectsBackend/UserDefinedSOResource/STIXExtraction'
canonicalRequestHeaders = ''
useQueryString = ''
#The type belongs to ScanType : 1: Log, 2: Block, 3: Quarantine(only available for file objects)
payload = {
    "param":{
        "FileHashIDList":[file_hashID],
        "ScanType":{
            "File":1,
            "IP":1,
            "URL":1,
            "Domain":1
            }
        }
    }
 
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;charset=utf-8'}
r = requests.put(use_url_base + productAgentAPIPath + useQueryString, headers=headers, data=useRequestBody, verify=False)

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))

Verify that the objects were extracted from the file.

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

200
{
    "Data": [
        {
            "FileHashID": "6c9855686b26c72858f21cfe9716f157459bed85",
            "ExtractingStatus": 1,
            "ExtractionErrorMessage": ""
        }
    ],
    "Meta": {
        "Result": 1,
        "ErrorCode": 0,
        "ErrorMsg": ""
    },
    "PermissionCtrl": {
        "permission": "255",
        "elements": null
    },
    "FeatureCtrl": {
        "mode": "0"
    },
    "SystemCtrl": {
        "TmcmSoDist_Role": "none"
    }
}

Note:

If the ExtractingStatus value is 1, the objects were successfully extracted.

Retrieve the UDSO list, and assign the response value to r.

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

# (Optional) Check the result in the User-Defined Suspicious Objects list.
print('(Optional) Check the result in the User-Defined Suspicious Objects list.')
 
productAgentAPIPath = '/WebApp/api/SuspiciousObjects/UserDefinedSO/'
canonicalRequestHeaders = ''
 
useRequestBody = ''
 
useQueryString=""
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)

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))

Verify that the objects were added to the UDSO list.

200
{
    "Data": [
        {
            "type": "ip",
            "content": "168.95.1.1",
            "notes": "Suspicious IP address",
            "scan_action": "log",
            "expiration_utc_date": "2020-06-01T16:00:00"
        },
        {
            "type": "file",
            "content": "601F1889667EFAEBB33B8C12572835DA3F027F78",
            "notes": "Small file for test",
            "scan_action": "log",
            "expiration_utc_date": null
        },
        ...
        {
            "type": "ip",
            "content": "5.175.166.35",
            "notes": "",
            "scan_action": "block",
            "expiration_utc_date": null
        }
    ],
    "Meta": {
        "Result": 1,
        "ErrorCode": 0,
        "ErrorMsg": ""
    },
    "PermissionCtrl": {
        "permission": "255",
        "elements": null
    },
    "FeatureCtrl": {
        "mode": "0"
    },
    "SystemCtrl": {
        "TmcmSoDist_Role": "none"
    }
}

Automation Center

Trend Micro Apex Central™

Apex Central Automation API Guide

Add Objects from a STIX File to the User-Defined Suspicious Objects List

Obtain an Application ID and API Key

Define the Libraries and Functions Required for JSON Web Token Creation

Prepare and Upload the STIX File

Add Objects to the User-Defined Suspicious Objects List (STIX)