Change the Update Source of Security Agents

This task retrieves a list of Security Agents and then modifies the update settings of the Update Agent.

  1. Obtain an application ID and API key.
  2. Define the libraries and functions necessary to create JSON Web Tokens for authorization.
  3. Obtain the entity ID of the Apex One server that you want to use as the main update source.
  4. Obtain the IP addresses of the Security Agents that will receive updates from the Update Agent.
  5. Modify the update settings of the Update Agent.

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

Obtain the Entity ID of the Main Update Source

This task retrieves the entity ID of the Apex One server that you want to use as the main update source.

  1. Retrieve the list of product servers that are managed by Apex Central, and assign the response value to r.

    For more information about the "List managed servers" API, see https://automation.trendmicro.com/apex-central/api#operation/ServerResource_GetProductServers.

    productAgentAPIPath = '/WebApp/API/ServerResource/ProductServers'
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)
  2. 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))
  3. Locate the entity ID of the server in the result_content parameter of the response.

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

    200
{
    "result_code": 1,
    "result_description": "Operation successful",
    "result_content": [
        { 
           "entity_id":"026332F39EBC-41C19604-02DD-2C5F-EDE5",
           "product":"SLF_PRODUCT_OFFICESCAN_CE",         
           "ad_domain":"",
           "ip_address_list":"192.168.121.131,fe80::8846:d1ac:8ee1:85ce",
           "host_name":"OSCESERVER",
           "capabilities":[
             "cmd_deploy_update_sources"
           ]
        },
        ...
        {
            "entity_id": "11111111-1111-AAAA-AAAA-111100000002",
            "product": "SLF_PRODUCT_OFFICESCAN_CE",
            "ad_domain": "",
            "ip_address_list": "fe80::593b:3e05:5967:1afa,fe80::41c9:a0fa:2dc8:c14,fe80::58da:3bd1:9347:a581,10.1.173.66,192.168.245.1,192.168.31.1,fd96:7568:9882:6:245c:df6c:8ec9:e527",
            "host_name": "ApexOne02",
            "capabilities": []
        }
    ]
}
    Important:

    Not all servers can deploy updates to Update Agents. If the capabilities value is cmd_deploy_update_sources, the specified server can deploy updates to Update Agents.

  4. Assign a value to ServerGUID.

    In this use case, the assigned value is the entity_id from the first server in the result list (r).

    ServerGUID = r.json()["result_content"][0]["entity_id"]
print("ServerGUID:", ServerGUID)

Obtain the IP Addresses of the Security Agents Managed by the Server

This task retrieves the IP addresses of the Security Agents that will receive updates from the Update Agent.

  1. Retrieve the list of Security Agents that are managed by the selected server, and assign the response value to r.

    For more information about the "List Security Agents" API, see https://automation.trendmicro.com/apex-central/api#tag/Security-Agents.

    ### (Optional) Get the IP address of product agents
print('(Optional) Get the IP address of product agents')
productAgentAPIPath = '/WebApp/API/AgentResource/ProductAgents'
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)
  2. 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))
  3. Locate the specific IP addresses in the result_content parameter of the response.

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

    200
{
    "result_code": 1,
    "result_description": "Operation successful",
    "result_content": [
       {
            "entity_id": "492E8584-0114-694D-BF9D-44CC20141501",
            "product": "SLF_PRODUCT_OFFICESCAN_CE",
            "managing_server_id": "33111111-1111-AAAA-AAAA-111100000001",
            "ad_domain": "",
            "folder_path": "DOMAIN",
            "ip_address_list": "10.1.1.1",
            "mac_address_list": "00-60-59-A4-70-2D",
            "host_name": "client01",
            "isolation_status": "normal",
            "capabilities": [
                "cmd_restore_isolated_agent",
                "cmd_isolate_agent",
                "cmd_relocate_agent",
                "cmd_uninstall_agent"
            ]
        },
        ...
        {
            "entity_id": "80180123-1059-CCCC-CCCC-111100000010",
            "product": "SLF_PRODUCT_HEADLESS_DSM",
            "managing_server_id": "80180123-1059-694D-BF9D-44CC80320001",
            "ad_domain": "",
            "folder_path": "iptlab",
            "ip_address_list": "100.1.1.10",
            "mac_address_list": "00-50-56-A7-69-10",
            "host_name": "host8",
            "isolation_status": "not_supported",
            "capabilities": []
        }
    ]
}
  4. Assign values to following parameters.

    Parameter

    Required Value

    AgentIPv4_FromIP

    First address in the IP range

    AgentIPv4_ToIP

    Last address in the IP range

    OUS_URL

    URL of the Update Agent

    In this use case, the second and last Security Agents in the list define the IP address range while the first Security Agent is assigned as the Update Agent.

    AgentIPv4_FromIP=r.json()["result_content"][1]["ip_address_list"]
AgentIPv4_ToIP=r.json()["result_content"][-1]["ip_address_list"]
OUS_URL="http://"+r.json()["result_content"][0]["ip_address_list"]+":21112/activeupdate"
print("AgentIPv4_FromIP:",AgentIPv4_FromIP)
print("AgentIPv4_ToIP:",AgentIPv4_ToIP)
print("OUS_URL:",OUS_URL)

Modify the Update Settings of the Update Agent

This task modifies how the Update Agent sends updates to the Security Agents.

  1. Deploy the update settings.

    For more information about the "Deploy update settings to Update Agents" API, see https://automation.trendmicro.com/apex-central/api#operation/ServerResource_PostProductServers.

    In this use case, the following settings are enabled.

    Setting

    Parameter

    Use customized update sources for Security Agents instead of the Apex One server.

    AllowUpdateFromOtherAU = 1

    Deploy components to Security Agents if all customized update sources are unavailable or cannot be found.

    UpdateComponentFromServerIfOUSFailed = 1

    Deploy domain settings to Security Agents if all customized update sources are unavailable or cannot be found.

    UpdateSettingFromServerIfOUSFailed= 1

    Deploy Security Agent programs and hotfixes to Security Agents if all customized update sources are unavailable or cannot be found.

    UpdateProgramFromServerIfOUSFailed = 1

    		 
    productAgentAPIPath = '/WebApp/API/ServerResource/ProductServers'
canonicalRequestHeaders = ''
useQueryString = ''
 
# Prepare input json that type is string.
OUSSettingJSONString_1={
  "FromIP":AgentIPv4_FromIP,
  "ToIP":AgentIPv4_ToIP,
  "OUS":OUS_URL
}
OUSSettingJSONString_1 = json.dumps(OUSSettingJSONString_1)
   
setting_data_JSON_string = {
  "AllowUpdateFromOtherAU":1,
  "UpdateComponentFromServerIfOUSFailed":1,
  "UpdateSettingFromServerIfOUSFailed":1,
  "UpdateProgramFromServerIfOUSFailed":1,
  "OUSList":[
    {
      "OUSSettingType":"IPv4",
      "OUSSettingJSONString":OUSSettingJSONString_1
    }
  ]
}
 
setting_data_JSON_string = str(setting_data_JSON_string)
 
payload = {
  "entity_id": ServerGUID,
  "act":"cmd_deploy_update_sources",
  "setting_data_JSON_string":setting_data_JSON_string
  }
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)
  2. Perform error handling and print the API response. 
    if r.status_code !=200 or r.status_code!=201:
  print('Not successful, please handle your error')
print(r.status_code)
print(json.dumps(r.json(), indent=4))
  3. Verify that the update settings were deployed.

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

    200
{
 "result_code":1
 "result_description":"Operation successful"
 "result_content":[        
    { 
     "entity_id":"026332F39EBC-41C19604-02DD-2C5F-EDE5",
     "product":"SLF_PRODUCT_OFFICESCAN_CE",         
     "ad_domain":"",
     "ip_address_list":
        "192.168.121.131,fe80::8846:d1ac:8ee1:85ce",
     "host_name":"OSCESERVER"
     "capabilities":[
        "cmd_deploy_update_sources"
        ]
    }   
  ]
}
    Note:

    If the result_code value is 1 and the result_content value is an empty array [], the operation was successful but the specified update source cannot deploy updates through this API.