Trend Micro Incorporated reserves the right to make changes to this document and tothe product described herein without notice. Before installing and using the product,review the readme files, release notes, and/or the latest version of the applicabledocumentation, which are available from the Trend Micro website at:
http://docs.trendmicro.com/en-us/enterprise/control-manager.aspx
Trend Micro, the Trend Micro t-ball logo, OfficeScan, and Control Manager aretrademarks or registered trademarks of Trend Micro Incorporated. All other product orcompany names may be trademarks or registered trademarks of their owners.
Copyright © 2018. Trend Micro Incorporated. All rights reserved.
Document Part No.: CMEM78275/180524
Release Date: May 2018
Protected by U.S. Patent No.: 5,623,600; 5,889,943; 5,951,698; 6,119,165
This documentation introduces the main features of the product and/or providesinstallation instructions for a production environment. Read through the documentationbefore installing or using the product.
Detailed information about how to use specific features within the product may beavailable at the Trend Micro Online Help Center and/or the Trend Micro KnowledgeBase.
Trend Micro always seeks to improve its documentation. If you have questions,comments, or suggestions about this or any Trend Micro document, please contact us [email protected].
Evaluate this documentation on the following site:
http://www.trendmicro.com/download/documentation/rating.asp
i
Table of Contents
Part I: Getting Started GuideChapter 1: Getting Started with Control ManagerAutomation APIs
Using Control Manager Automation APIs ................................................. 1-2
Adding an Application ................................................................................... 1-3
Using the Automation API Demo Project for Visual Studio .................. 1-4
Using the Automation API Demo Project for Python ............................. 1-5
Authorization Token Structure ..................................................................... 1-6
Automation API Responses ........................................................................ 1-10
Part II: API Reference GuideChapter 2: Supported Automation APIs
Control Manager Automation APIs ............................................................ 2-2
ProductServers :: List ..................................................................................... 2-2
ProductAgents :: List ...................................................................................... 2-4
ProductAgents :: Isolate ................................................................................ 2-7
ProductAgents :: Restore ............................................................................. 2-13
ProductAgents :: Relocate ........................................................................... 2-18
ProductAgents :: Uninstall .......................................................................... 2-24
FileUDSO :: Add .......................................................................................... 2-29
Chapter 3: Automation API ReferencesAutomation API Product Values ................................................................. 3-2
Control Manager Automation API Guide
ii
Automation API Isolation Statuses ............................................................. 3-3
Automation API Actions/Capabilities ........................................................ 3-3
Automation API Result Codes ..................................................................... 3-3
Part IGetting Started Guide
1-1
Chapter 1
Getting Started with Control ManagerAutomation APIs
This section discusses how to enable and use Control Manager Automation APIs.
Topics include:
• Using Control Manager Automation APIs on page 1-2
• Adding an Application on page 1-3
• Using the Automation API Demo Project for Visual Studio on page 1-4
• Authorization Token Structure on page 1-6
• Automation API Responses on page 1-10
Control Manager Automation API Guide
1-2
Using Control Manager Automation APIsTrend Micro™ Control Manager™ provides access to some internal productfunctionalities through Control Manager Automation APIs allowing users to integratethird-party solutions. Using the APIs may potentially expose sensitive information, suchas agent and endpoint information, which could result in state-changing effects such asagent isolation. To ensure that only trusted applications can use the APIs, generate anauthentication JSON Web Token (JWT) that the trusted applications send with APIrequests. Control Manager verifies the validity of all API requests from third-partyapplications using the JWT information.
Note
For a list of available APIs and supported functions, see Control Manager Automation APIs onpage 2-2.
Tip
Trend Micro provides a demo project to help you get started with using the ControlManager Automation APIs.
For more information, see the following topics:
• Using the Automation API Demo Project for Visual Studio on page 1-4
• Using the Automation API Demo Project for Python on page 1-5
Perform the following steps to properly utilize the Control Manager Automation APIs:
1. Obtain an “Application ID” and “API key” by adding the integrated productsolution to the Control Manager console.
For more information, see Adding an Application on page 1-3.
2. Create a JSON Web Token (JWT) using the “Application ID” and “API key” andsend the JWT in the authorization header of the request to the intendedAutomation API.
Getting Started with Control Manager Automation APIs
1-3
Note
• The “Application ID” is part of the JWT payload and the
• The “API key” is the secret key used to generate the signature of the JWT.
• The JWT is generated directly by the third-party application.
Important
Do not transmit the “API key” as part of the request.
For more information, see Authorization Token Structure on page 1-6.
3. Verify whether Control Manager accepted the API request.
For more information, see Automation API Responses on page 1-10.
Adding an ApplicationUse the Automation API Access Settings screen to allow external applications toconsume Control Manager Automation APIs.
Procedure
1. Go to Administration > Settings > Automation API Access Settings.
2. Click Add.
3. In the Application Access Settings section, select the Enable applicationintegration using Control Manager Automation APIs check box.
4. Configure the following settings.
• Application name: Specify an easily identifiable name for the application
• Application ID: Used by Control Manager to identify the application
• API key: Used by the application to sign requests sent to Control Manager
Control Manager Automation API Guide
1-4
• API type: Indicates the API functions that the application can access
• Communication time-out: Select the maximum number of seconds allowedfor a request to reach Control Manager after the application generates therequest
5. Click Save.
Using the Automation API Demo Project forVisual Studio
Important
The Automation API demo project requires Microsoft Visual Studio 2015 (or later).
Procedure
1. On a system running Microsoft Visual Studio 2015 (or later), download theAutomation API demo project file from:
http://docs.trendmicro.com/all/ent/tmcm/v7.0/en-us/api/VS2015AutomationAPIDemo.zip
2. Decompress the VS2015AutomationAPIDemo.zip folder.
3. Locate the VS2015AutomationAPIDemo.sln file in the extracted folder anddouble-click to open the file in Visual Studio.
4. Locate the App.config file in the extracted folder and edit the following fields toprovide your test environment information:
• APIBaseAddress
• ApplicationID
• APIKey
Getting Started with Control Manager Automation APIs
1-5
5. Build and execute the demo project.
Using the Automation API Demo Project forPython
ImportantThe Automation API demo project requires Python 3.6 (or later).
Procedure
1. On a system running Python 3.6 (or later), install the following modules:
• pycryptodome
• hashlib
• PyJWT
2. Download the Automation API demo project file from:
http://docs.trendmicro.com/all/ent/tmcm/v7.0/en-us/api/Python3DemoScript.zip
3. Decompress the Python3DemoScript.zip folder.
4. In the extracted Python3DemoScript.py file, locate and specify the followingsettings:
• use_url_base: The URL of the Control Manager server without theWebApp
Example: https://192.168.121.223:443
• use_application_id: The application ID generated by Control Manager
• use_api_key: The API key generated by Control Manager
5. Execute the demo script, which will access the Automation APIs and perform thefollowing actions:
Control Manager Automation API Guide
1-6
• Attempt to get and print product agents withhostname="BENPFUOSCECLIEN"
Note
You can change the hostname criteria directly in the Python script to specifyany product agent.
• Attempt to uninstall a product agent withentity_id="123456780114-694DBF9D-2018-0618-1930"
Note
You can change the entity_id criteria directly in the Python script to specifyany product agent.
Authorization Token StructureYou must create a properly defined JSON Web Token to successfully use AutomationAPIs.
Note
To prevent a third-party from attempting to intercept and reuse the JWT token, you mustconfigure a Communication time-out interval when adding applications to theAutomation API Access Settings screen. Upon receiving the API request, ControlManager compares the “Issued at” (iat) attribute to the time Control Manager receivedthe request. If the request did not arrive before the configured time-out interval, ControlManager rejects the request with a 401 response code.
The following tables outline the required information that you must include in theHeader and Payload sections of the JWT token.
Getting Started with Control Manager Automation APIs
1-7
Table 1-1. Header Section
Content Description
alg The algorithm used to calculate the JWT checksum
Supported algorithms:
• HS256 (HMAC SHA256)
• HS384
• HS512
typ The type of JSON Web Token (JWT)
ImportantControl Manager only accepts JSON Web Tokens (JWT).
Table 1-2. Payload Section
Content Description
appid The Application ID of the third-party application obtained from theAutomation API Access Settings screen
iat The “Issued at” token generation time
The generation time uses the Unix time stamp (number ofseconds since Jan 01 1970 UTC) format.
version The version of this JWT authorization token
ImportantControl Manager only accepts “V1” JWT authorizationtokens.
checksum The checksum of the request
Control Manager Automation API Guide
1-8
Sample of a Decoded JWT Token
Section Content
Header {"alg": "HS256","typ": "JWT"}
Payload {"appid": "2E28ED1BABA2-4D10BB13-F4FA-D5D4-31F3","iat": 1495187266.6215432,"version": "V1","checksum": "J+CMrBKctcXXuQ68GrpFyS1+FXA4gCKs8crdOGJZ24Q="}
Checksum CalculationTo further prevent a third-party from attempting to intercept and reuse the JWT tokenfor a different request, include the checksum field in the token. The following tableoutlines the fields used to calculate the value.
Request Information Used to Generate Checksum
HTTP-Method The HTTP method of the request (in uppercase characters)
• GET
• POST
• PUT
Getting Started with Control Manager Automation APIs
1-9
Request Information Used to Generate Checksum
Raw-URL The path and query string of the request (in lowercase characters)
• Example 1:
URL of the Automation API:
https://<Control_Manager_Server>/WebApp/API/AgentResource/ProductAgents?HostName=TestAgent
Raw-URL:
/webapp/API/agentresource/productagents?hostname=testagent
• Example 2:
URL of the Automation API:
https://<Control_Manager_Server>/WebApp/API/AgentResource/ProductAgents
Raw-URL:
/webapp/API/agentresource/productagents
ImportantIn the event of an empty query string, do not include the "?"character.
Canonical-Request-Headers
The list of all request headers that start with “API”
• Sort alphabetically and convert each header into the followingformat:
LowerCase(Header Name) + ":" + Trim(Header Value)
• Join headers using the “&” separator
NoteIf there are no headers that start with API, leave theCanonical-Request-Headers value as an empty string.
Control Manager Automation API Guide
1-10
Request Information Used to Generate Checksum
Request-Body The body of the request in the format of a UTF-8-encoded JSONstring
For the calculated SHA-256 checksum of HTTP-Method + "|" + Raw-URL + "|" +Canonical-Request-Headers + "|" + Request-Body, the checksum field isthe base64 string representation of the calculated SHA-256 checksum byte array.
Automation API ResponsesAfter sending an authorization request to the intended API, Control Manager returns aresponse indicating whether the request was successful.
The response should always be a JSON-formatted APIResponseObject in the followingformat:
{ "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"(if provided, a JSON object representing the return value of the API)"}
Note
For a complete list of result_code status values, see Automation API Result Codes on page1-12.
Important
The result_description field in the response body is subject to change. If yourapplication depends on Control Manager Automation API responses, use theresult_code value instead of the result_description provided in the responsebody.
Getting Started with Control Manager Automation APIs
1-11
The following table outlines the possible responses:
ResponseStatus
HTTP StatusCode Response Body
Successful 200 { "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":"(if provided, a JSON object representing the return value of the API)"}
NoteFor a complete list of result_code statusvalues, see Automation API Result Codes onpage 1-12.
Unsuccessfuldue to invalidparameters
400 { "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":""}
NoteFor a complete list of result_code statusvalues, see Automation API Result Codes onpage 1-12.
Control Manager Automation API Guide
1-12
ResponseStatus
HTTP StatusCode Response Body
Unsuccessfuldue toauthorizationerror
401 { "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":""}
NoteFor a complete list of result_code statusvalues, see Automation API Result Codes onpage 1-12.
Unknown error 500 { "result_code":(an integer indicating the result of this API call), "result_description":"(a string describing the result code)", "result_content":""}
NoteFor a complete list of result_code statusvalues, see Automation API Result Codes onpage 1-12.
Automation API Result Codes
The following table lists the Control Manager Automation API result codes and thecorresponding descriptions:
Result Code Description
1 Operation successful
-2 Authentication unsuccessful: Authentication token not provided.
Getting Started with Control Manager Automation APIs
1-13
Result Code Description
-3 Authentication unsuccessful: Malformed authentication token
-4 Authentication unsuccessful: Unsupported authentication tokenversion
-5 Authentication unsuccessful: Invalid application ID
-6 Authentication unsuccessful: Authentication token expired
-7 Authentication unsuccessful: Invalid authentication tokensignature
-8 Authentication unsuccessful: Invalid request checksum
-9 Authentication unsuccessful: Unsupported authentication tokensigning algorithm
-21 Invalid input parameters
-22 Action invalid
-50 Unsupported HTTP method
-99 Internal server error
-102 Agent action unsuccessful: Multiple matches not supported
-103 Agent action unsuccessful: Unable to isolate agents reporting toanother Control Manager server
-104 Agent action unsuccessful: Unable to connect to remote server
-105 Agent action unsuccessful: Target server not found
-106 Agent action unsuccessful: Target server managed by a childControl Manager server
-107 Agent action unsuccessful: Target server does not supportcommand
-1101 Suspicious object action unsuccessful: Maximum quantityexceeded
Control Manager Automation API Guide
1-14
Result Code Description
-1102 Suspicious object action unsuccessful: Unable to generate ScanPrefilter for uploaded file, file likely to be blocked by antivirus
Part IIAPI Reference Guide
2-1
Chapter 2
Supported Automation APIsThis section discusses supported Control Manager Automation APIs.
Topics include:
• Control Manager Automation APIs on page 2-2
• ProductServers :: List on page 2-2
• ProductAgents :: List on page 2-4
• ProductAgents :: Isolate on page 2-7
• ProductAgents :: Restore on page 2-13
• ProductAgents :: Relocate on page 2-18
• ProductAgents :: Uninstall on page 2-24
• FileUDSO :: Add on page 2-29
Control Manager Automation API Guide
2-2
Control Manager Automation APIsThe following Control Manager Automation APIs are supported:
API Actions Description
ProductServers ProductServers ::List
Lists managed product servers
ProductAgents ProductAgents ::List
Lists managed product agents
ProductAgents ::Isolate
Isolates agent connections
ProductAgents ::Restore
Restores isolated agent connections
ProductAgents ::Relocate
Relocates agents to another server ordirectory
ProductAgents ::Uninstall
Uninstalls agents
FileUDSO FileUDSO :: Add Adds a suspicious file object to the ControlManager user-defined suspicious object list
For more information about how to use the Control Manager Automation APIs, see thefollowing topics:
• Using Control Manager Automation APIs on page 1-2
• Using the Automation API Demo Project for Visual Studio on page 1-4
ProductServers :: ListRetrieves a list of managed product servers, such as OfficeScan servers.
HTTP Request
GET /WebApp/API/ServerResource/ProductServers
Supported Automation APIs
2-3
Parameters
Name Type Description
Optional Parameters
entity_id String The GUID of the managed product server
ip_address String The IP address of the managed productserver
host_name String The host name of the managed productserver
product String The Trend Micro product that the server isfor
For available values, see Automation APIProduct Values on page 3-2.
HTTP Request Example
GET /WebApp/API/ServerResource/ProductServers?ip_address=192.168.121.131
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body: [Blank]
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywith the following structure:
{ "result_code":1
Control Manager Automation API Guide
2-4
"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" } ]}
The following table describes the available parameters for the result_content list.
Parameter Type Description
entity_id String The GUID of the managed product server
product String The Trend Micro product on the server instance
For available values, see Automation API ProductValues on page 3-2.
ad_domain String The Active Directory domain that the server belongsto (if applicable)
ip_address_list
String The IP address list on the server
host_name String The host name of the server
ProductAgents :: ListRetrieves a list of managed product agents, such as OfficeScan agents.
HTTP Request
GET /WebApp/API/AgentResource/ProductAgents
Supported Automation APIs
2-5
Parameters
Parameter Type Description
Optional Parameters
entity_id String The GUID of the managed product agent
ip_address String The IP address of the managed productagent
mac_address String The MAC address of the managed productagent
host_name String The endpoint name of the managedproduct agent
product String The Trend Micro product that the agent isfor
For available values, see Automation APIProduct Values on page 3-2.
managing_server_id
String The GUID of the product server thatmanages the agent
HTTP Request Example
GET /WebApp/API/ServerResource/ProductAgents?ip_address=192.168.121.132&mac_address=00-0C-29-9B-AB-65&host_name=OSCECLIENT
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body: [Blank]
Control Manager Automation API Guide
2-6
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywhere:
• The "result_code" is 1
• The "result_content" is a list of agents that match all of the specifiedparameters
{ "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" ] } ]}
The following table describes the available parameters for the result_content list.
Parameter Type Description
entity_id String The GUID of the managed product agent
Supported Automation APIs
2-7
Parameter Type Description
product String The Trend Micro product that the agent is for
For available values, see Automation API ProductValues on page 3-2.
managing_server_id
String The GUID of the product server that manages theagent
ad_domain String The Active Directory domain that the agent belongsto (if applicable)
folder_path String The folder path of where the agent is located ont themanaging server (for example, the OfficeScandomain that the agent is listed under)
ip_address_list
String Lists the IP addresses on the agent endpoint
mac_address_list
String Lists the MAC addresses on the agent endpoint
host_name String The endpoint name of the managed product agent
isolation_status
String Indicates the agent isolation status (if applicable).
For available values, see Automation API IsolationStatuses on page 3-3.
capabilities String Lists the API actions that can be performed on theagent
For available values, see Automation API Actions/Capabilities on page 3-3.
ProductAgents :: IsolateTo isolate an agent from the network, specify the act value as cmd_isolate_agentin the HTTP request body.
HTTP Request
POST /WebApp/API/AgentResource/ProductAgents
Control Manager Automation API Guide
2-8
Parameters
Important
The HTTP request body must contain the required parameters.
Parameter Type Description
Required Parameters
act String Specify the value as cmd_isolate_agent.
allow_multiple_match
String Specify one of the following:
• True: Allows multiple matches
• False: Does not allow multiplematches
ImportantIf this parameter is set to False, andthe provided parameters matchmultiple agents, the action will beunsuccessful.
Optional Parameters
entity_id String The GUID of the managed product agent
Use to indicates the agent(s) on which toperform the action
ip_address String The IP address of the managed productagent
Use to indicates the agent(s) on which toperform the action
mac_address String The MAC address of the managed productagent
Use to indicates the agent(s) on which toperform the action
Supported Automation APIs
2-9
Parameter Type Description
host_name String The endpoint name of the managedproduct agent
Use to indicates the agent(s) on which toperform the action
product String The Trend Micro product on the serverinstance
Use to indicates the agent(s) on which toperform the action
For supported values, see Automation APIProduct Values on page 3-2.
HTTP Request Example
POST /WebApp/API/AgentResource/ProductAgents
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body:
{ "entity_id":"8a1a84550462-40bc9afc-3770-16ac-cd6c", "act":"cmd_isolate_agent", "allow_multiple_match":false }
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywhere:
Control Manager Automation API Guide
2-10
• The "result_code" is 1
• The "result_content" is a list of agents that match all of the specifiedparameters before the action ("act") was applied.
{ "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" ] } ]}
The following table describes the available parameters for the result_content list.
Parameter Type Description
entity_id String The GUID of the managed product agent
product String The Trend Micro product that the agent is for
For available values, see Automation API ProductValues on page 3-2.
Supported Automation APIs
2-11
Parameter Type Description
managing_server_id
String The GUID of the product server that manages theagent
ad_domain String The Active Directory domain that the agent belongsto (if applicable)
folder_path String The folder path of where the agent is located ont themanaging server (for example, the OfficeScandomain that the agent is listed under)
ip_address_list
String Lists the IP addresses on the agent endpoint
mac_address_list
String Lists the MAC addresses on the agent endpoint
host_name String The endpoint name of the managed product agent
isolation_status
String Indicates the agent isolation status (if applicable).
For available values, see Automation API IsolationStatuses on page 3-3.
capabilities String Lists the API actions that can be performed on theagent
For available values, see Automation API Actions/Capabilities on page 3-3.
Control Manager Automation API Guide
2-12
API Sequence Diagram
Supported Automation APIs
2-13
ProductAgents :: RestoreTo restore an isolated agent connection to the network, specify the act value ascmd_restore_isolated_agent in the HTTP request body.
HTTP Request
POST /WebApp/API/AgentResource/ProductAgents
Parameters
Important
The HTTP request body must contain the required parameters.
Parameter Type Description
Required Parameters
act String Specify the value ascmd_restore_isolated_agent.
allow_multiple_match
String Specify one of the following:
• True: Allows multiple matches
• False: Does not allow multiplematches
ImportantIf this parameter is set to False, andthe provided parameters matchmultiple agents, the action will beunsuccessful.
Optional Parameters
entity_id String The GUID of the managed product agent
Use to indicates the agent(s) on which toperform the action
Control Manager Automation API Guide
2-14
Parameter Type Description
ip_address String The IP address of the managed productagent
Use to indicates the agent(s) on which toperform the action
mac_address String The MAC address of the managed productagent
Use to indicates the agent(s) on which toperform the action
host_name String The endpoint name of the managedproduct agent
Use to indicates the agent(s) on which toperform the action
product String The Trend Micro product on the serverinstance
Use to indicates the agent(s) on which toperform the action
For supported values, see Automation APIProduct Values on page 3-2.
HTTP Request Example
POST /WebApp/API/AgentResource/ProductAgents
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body:
Supported Automation APIs
2-15
{ "entity_id":"8a1a84550462-40bc9afc-3770-16ac-cd6c", "act":"cmd_restore_isolated_agent", "allow_multiple_match":false }
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywhere:
• The "result_code" is 1
• The "result_content" is a list of agents that match all of the specifiedparameters before the action ("act") was applied.
{ "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":"isolated", "capabilities":[ "cmd_uninstall_agent", "cmd_relocate_agent", "cmd_isolate_agent", "cmd_restore_isolated_agent" ] } ]}
The following table describes the available parameters for the result_content list.
Control Manager Automation API Guide
2-16
Parameter Type Description
entity_id String The GUID of the managed product agent
product String The Trend Micro product that the agent is for
For available values, see Automation API ProductValues on page 3-2.
managing_server_id
String The GUID of the product server that manages theagent
ad_domain String The Active Directory domain that the agent belongsto (if applicable)
folder_path String The folder path of where the agent is located ont themanaging server (for example, the OfficeScandomain that the agent is listed under)
ip_address_list
String Lists the IP addresses on the agent endpoint
mac_address_list
String Lists the MAC addresses on the agent endpoint
host_name String The endpoint name of the managed product agent
isolation_status
String Indicates the agent isolation status (if applicable).
For available values, see Automation API IsolationStatuses on page 3-3.
capabilities String Lists the API actions that can be performed on theagent
For available values, see Automation API Actions/Capabilities on page 3-3.
Supported Automation APIs
2-17
API Sequence Diagram
Control Manager Automation API Guide
2-18
ProductAgents :: RelocateTo relocate agents to another server or another directory on the same server, specify theact value as cmd_relocate_agent in the HTTP request body.
HTTP Request
POST /WebApp/API/AgentResource/ProductAgents
Parameters
ImportantThe HTTP request body must contain the required parameters.
Parameter Type Description
Required Parameters
act String Specify the value ascmd_relocate_agent.
allow_multiple_match
String Specify one of the following:
• True: Allows multiple matches
• False: Does not allow multiplematches
ImportantIf this parameter is set to False, andthe provided parameters matchmultiple agents, the action will beunsuccessful.
Supported Automation APIs
2-19
Parameter Type Description
relocate_to_server_id
String The GUID of the target server for the agentrelocation
ImportantIf the agent is relocated to adirectory on the same server, youmust specify the GUID of the originalserver (managing_server_id).
relocate_to_folder_path
String The target directory for the agent relocation
Optional Parameters
entity_id String The GUID of the managed product agent
Use to indicates the agent(s) on which toperform the action
ip_address String The IP address of the managed productagent
Use to indicates the agent(s) on which toperform the action
mac_address String The MAC address of the managed productagent
Use to indicates the agent(s) on which toperform the action
host_name String The endpoint name of the managedproduct agent
Use to indicates the agent(s) on which toperform the action
Control Manager Automation API Guide
2-20
Parameter Type Description
product String The Trend Micro product on the serverinstance
Use to indicates the agent(s) on which toperform the action
For supported values, see Automation APIProduct Values on page 3-2.
HTTP Request Example
POST /WebApp/API/AgentResource/ProductAgents
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body:
{ "entity_id":"8a1a84550462-40bc9afc-3770-16ac-cd6c", "act":"cmd_relocate_agent", "allow_multiple_match":false, "relocate_to_server_id": "026332F39EBC-41C19604-02DD-2C5F-ZDE6", "relocate_to_folder_path":"\\NewDomain\\NewFolder" }
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywhere:
• The "result_code" is 1
Supported Automation APIs
2-21
• The "result_content" is a list of agents that match all of the specifiedparameters before the action ("act") was applied.
{ "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" ] } ]}
The following table describes the available parameters for the result_content list.
Parameter Type Description
entity_id String The GUID of the managed product agent
product String The Trend Micro product that the agent is for
For available values, see Automation API ProductValues on page 3-2.
managing_server_id
String The GUID of the product server that manages theagent
Control Manager Automation API Guide
2-22
Parameter Type Description
ad_domain String The Active Directory domain that the agent belongsto (if applicable)
folder_path String The folder path of where the agent is located ont themanaging server (for example, the OfficeScandomain that the agent is listed under)
ip_address_list
String Lists the IP addresses on the agent endpoint
mac_address_list
String Lists the MAC addresses on the agent endpoint
host_name String The endpoint name of the managed product agent
isolation_status
String Indicates the agent isolation status (if applicable).
For available values, see Automation API IsolationStatuses on page 3-3.
capabilities String Lists the API actions that can be performed on theagent
For available values, see Automation API Actions/Capabilities on page 3-3.
Supported Automation APIs
2-23
API Sequence Diagram
Control Manager Automation API Guide
2-24
ProductAgents :: UninstallTo uninstall product agents, specify the act value as cmd_uninstall_agent in theHTTP request body.
HTTP Request
POST /WebApp/API/AgentResource/ProductAgents
Parameters
Important
The HTTP request body must contain the required parameters.
Parameter Type Description
Required Parameters
act String Specify the value ascmd_uninstall_agent.
allow_multiple_match
String Specify one of the following:
• True: Allows multiple matches
• False: Does not allow multiplematches
ImportantIf this parameter is set to False, andthe provided parameters matchmultiple agents, the action will beunsuccessful.
Optional Parameters
entity_id String The GUID of the managed product agent
Use to indicates the agent(s) on which toperform the action
Supported Automation APIs
2-25
Parameter Type Description
ip_address String The IP address of the managed productagent
Use to indicates the agent(s) on which toperform the action
mac_address String The MAC address of the managed productagent
Use to indicates the agent(s) on which toperform the action
host_name String The endpoint name of the managedproduct agent
Use to indicates the agent(s) on which toperform the action
product String The Trend Micro product on the serverinstance
Use to indicates the agent(s) on which toperform the action
For supported values, see Automation APIProduct Values on page 3-2.
HTTP Request Example
POST /WebApp/API/AgentResource/ProductAgents
HTTP Request Body
Specify a JSON object containing the following HTTP header:
• HTTP header:
Field Name Value
Authorization Bearer [Generated JWT authentication token]
• Request body:
Control Manager Automation API Guide
2-26
{ "entity_id":"8a1a84550462-40bc9afc-3770-16ac-cd6c", "act":"cmd_uninstall_agent", "allow_multiple_match":false}
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywhere:
• The "result_code" is 1
• The "result_content" is a list of agents that match all of the specifiedparameters before the action ("act") was applied.
{ "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" ] } ]}
The following table describes the available parameters for the result_content list.
Supported Automation APIs
2-27
Parameter Type Description
entity_id String The GUID of the managed product agent
product String The Trend Micro product that the agent is for
For available values, see Automation API ProductValues on page 3-2.
managing_server_id
String The GUID of the product server that manages theagent
ad_domain String The Active Directory domain that the agent belongsto (if applicable)
folder_path String The folder path of where the agent is located ont themanaging server (for example, the OfficeScandomain that the agent is listed under)
ip_address_list
String Lists the IP addresses on the agent endpoint
mac_address_list
String Lists the MAC addresses on the agent endpoint
host_name String The endpoint name of the managed product agent
isolation_status
String Indicates the agent isolation status (if applicable).
For available values, see Automation API IsolationStatuses on page 3-3.
capabilities String Lists the API actions that can be performed on theagent
For available values, see Automation API Actions/Capabilities on page 3-3.
Control Manager Automation API Guide
2-28
API Sequence Diagram
Supported Automation APIs
2-29
FileUDSO :: AddAdds a suspicious file object to the Control Manager user-defined suspicious object list.
HTTP Request
PUT /WebApp/API/SuspiciousObjectResource/FileUDSO
Parameters
Important
The HTTP request body must contain the required parameters.
Name Type Description
Required Parameters
file_name String The name of the suspicious file to upload
file_content_base64_string
String The binary content of the suspicious file,converted to a base64 string
file_scan_action String The scan action to perform on thesuspicious file
note String Additional information about the suspiciousfile
HTTP Request Example
PUT /WebApp/API/SuspiciousObjectResource/FileUDSO
HTTP Request Body
Specify a JSON object containing the following HTTP header and request body:
• HTTP header:
Control Manager Automation API Guide
2-30
Header Value
Authorization Bearer [Generated JWT authentication token]
• Request body:
{ "file_name":"VerySmallFile.txt", "file_content_base64_string":"MTIzMTIz", "file_scan_action":"LOG", "note":"Small file for test" }
Response
If successful, this method returns an HTTP 200 OK status code and a response bodywith the following structure:
{ "result_code":1 "result_description":"Operation successful" "result_content":null}
If unsuccessful, this method returns the following result codes:
Result Code Description
-1101 Suspicious object action unsuccessful: Maximum quantityexceeded
-1102 Suspicious object action unsuccessful: Unable to generate ScanPrefilter for uploaded file, file likely to be blocked by antivirus
Supported Automation APIs
2-31
API Sequence Diagram
3-1
Chapter 3
Automation API ReferencesThis section provides reference tables for Control Manager API parameters and statuscodes.
Topics include:
• Automation API Product Values on page 3-2
• Automation API Isolation Statuses on page 3-3
• Automation API Actions/Capabilities on page 3-3
• Automation API Result Codes on page 3-3
Control Manager Automation API Guide
3-2
Automation API Product Values
Value Description
SLF_PRODUCT_OFFICESCAN_CE Trend Micro OfficeScan Corporate Edition
SLF_PRODUCT_IMSS_NT InterScan Messaging Security Suite forWindows
SLF_PRODUCT_IMSS_UNIX InterScan Messaging Security Suite forUNIX
SLF_PRODUCT_SERVERPROTECT_WINNT
ServerProtect for Windows
SLF_PRODUCT_SERVERPROTECT_LINUX
ServerProtect for Linux
SLF_PRODUCT_IMSA InterScan Messaging Security Appliance
SLF_PRODUCT_IMSVA InterScan Messaging Security VirtualAppliance
SLF_PRODUCT_IS_WEB_SECURITY_SUITE_LINUX
InterScan Web Security Suite for Linux
SLF_PRODUCT_IS_WEB_SECURITY_SUITE_APPLIANCE
InterScan Web Security Suite for Appliance
SLF_PRODUCT_IS_WEB_SECURITY_SUITE_VIRTUAL_APPLIANCE
InterScan Web Security Virtual Appliance
SLF_PRODUCT_TMMS Trend Micro Mobile Security
SLF_PRODUCT_DEEP_DISCOVERY_EMAIL_INSPECTOR
Deep Discovery Email Inspector
SLF_PRODUCT_DEEP_DISCOVERY Deep Discovery Inspector
SLF_PRODUCT_TMDS Trend Micro Deep Security
Automation API References
3-3
Automation API Isolation Statuses
Value Description
normal The network connection of the agent is normal and, if applicable,can be isolated from the network
isolated The agent is currently isolated from the network
endpoint_isolation_pending
The agent isolation command has been issued and agentisolation is pending
connection_restoration_pending
The agent restoration command has been issued and agentnetwork connection restoration is pending
Automation API Actions/Capabilities
Value Description
cmd_isolate_agent Isolates agent connections
cmd_restore_isolated_agent Restores isolated agent connections
cmd_relocate_agent Relocates agents to another server ordirectory
cmd_uninstall_agent Uninstalls agents
Automation API Result CodesThe following table lists the Control Manager Automation API result codes and thecorresponding descriptions:
Result Code Description
1 Operation successful
Control Manager Automation API Guide
3-4
Result Code Description
-2 Authentication unsuccessful: Authentication token not provided.
-3 Authentication unsuccessful: Malformed authentication token
-4 Authentication unsuccessful: Unsupported authentication tokenversion
-5 Authentication unsuccessful: Invalid application ID
-6 Authentication unsuccessful: Authentication token expired
-7 Authentication unsuccessful: Invalid authentication tokensignature
-8 Authentication unsuccessful: Invalid request checksum
-9 Authentication unsuccessful: Unsupported authentication tokensigning algorithm
-21 Invalid input parameters
-22 Action invalid
-50 Unsupported HTTP method
-99 Internal server error
-102 Agent action unsuccessful: Multiple matches not supported
-103 Agent action unsuccessful: Unable to isolate agents reporting toanother Control Manager server
-104 Agent action unsuccessful: Unable to connect to remote server
-105 Agent action unsuccessful: Target server not found
-106 Agent action unsuccessful: Target server managed by a childControl Manager server
-107 Agent action unsuccessful: Target server does not supportcommand
-1101 Suspicious object action unsuccessful: Maximum quantityexceeded
Automation API References
3-5
Result Code Description
-1102 Suspicious object action unsuccessful: Unable to generate ScanPrefilter for uploaded file, file likely to be blocked by antivirus