Relocate a Security Agent to Another Managed Server

This task retrieves a list of Security Agents and then relocates the first Security Agent in the list to another managed server.

  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 new managed server.
  4. Obtain the host name of the Security Agent that you want to relocate.
  5. Relocate the Security 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 New Server

This task retrieves the entity ID of the new Apex One server to which you want to move the Security Agent.

  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.

    print('Retrieving a list of managed product servers reporting to Apex Central.')
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(r.status_code)
  #insert error handling 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:

    {
    "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": []
        }
    ]
}
  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 Host Name of the Security Agent

This task retrieves the host name of the Security Agent that you want to move to a new Apex One server.

  1. Retrieve the list of Security Agents that are managed by the current 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.

    print('Retrieving a list of Security Agents from Apex Central.')
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(r.status_code)
  #insert error handling code
   
print(json.dumps(r.json(), indent=4))
  3. Locate the specific IP address in the result_content parameter of the response.

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

    {
    "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 a value to host_name_retrieved.

    In this use case, the assigned value is the host_name of the first host in the result list (r).

    host_name_retrieved = r.json()["result_content"][0]["host_name"]

Relocate the Security Agent

This task moves the specified Security Agent to the specified Apex One server.

  1. Relocate the Security Agent to a new server, and assign the response value to r.

    For more information about the "Isolate, Restore, Relocate, or Uninstall Security Agent" API, see https://automation.trendmicro.com/apex-central/api#tag/Update-Agents.

    Important:

    You must assign a value to relocate_to_folder_path.

    print('Relocating a host to a new managed server.')
productAgentAPIPath = '/WebApp/API/AgentResource/ProductAgents'
canonicalRequestHeaders = ''
useQueryString = ''
payload = {
  "host_name":host_name_retrieved,
  "act":"cmd_relocate_agent",
  "allow_multiple_match":True,
  "relocate_to_server_id":ServerGUID,
  "relocate_to_folder_path":"\\NewDomain\\NewFolder"
  }
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 and r.status_code!=201:
  print(r.status_code)
  #insert error handling code

print(json.dumps(r.json(), indent=4))
  3. Verify that the entity_id value is the GUID of the new server.

    If your API request was successful, you will see output similar to the following.

    {
    "result_code": 1,
    "result_description": "Operation successful",
    "result_content": [
     {
       "entity_id":"8a1a84550462-40bc9afc-3770-16ac-cd6c",
       "product":"SLF_PRODUCT_OFFICESCAN_CE",
       "managing_server_id":
          "026332F39EBC-41C19604-02DD-2C5F-EDE5",
       "ad_domain":"",
       "folder_path":"Workgroup",
       "ip_address_list":"192.168.121.132",
       "mac_address_list":"00-0C-29-9B-AB-65",
       "host_name":"OSCECLIENT",
       "isolation_status":"normal",
       "capabilities":[
          "cmd_uninstall_agent",
          "cmd_relocate_agent",
          "cmd_isolate_agent",
          "cmd_restore_isolated_agent"
        ]
    }
  ]
}
    Important:

    Some Security Agents cannot be relocated to another server using the API. If the result_code value is 1 and the result_content value is a null array [], the API request was successful but the specified Security Agent cannot be relocated using the API.