First steps toward using the APIs

Views:

Become familiar with the APIs by sending sample requests to Trend Vision One.

Procedure

Prepare the development and runtime environment.

Running the sample code in this guide requires:

Network access to Trend Vision One.

A tool for sending requests.

Type	Requirements
cURL command	HTTP client such as Postman, Paw, or cURL
Python script	Python 3.7.x or later Additional libraries: `requests`and `ldap3` You can install the libraries using the `pip`command.

Obtain an authentication token.

If you have access to the User Accounts screen of your organization's Trend Vision One console, see Obtain authentication tokens. Otherwise, contact your system administrator.

Obtain the domain name for your region.

Region	FQDN
Australia	`api.au.xdr.trendmicro.com`
Germany	`api.eu.xdr.trendmicro.com`
India	`api.in.xdr.trendmicro.com`
Japan	`api.xdr.trendmicro.co.jp`
Singapore	`api.sg.xdr.trendmicro.com`
United Arab Emirates	`api.mea.xdr.trendmicro.com`
United Kingdom	`api.uk.xdr.trendmicro.com`
United States	`api.xdr.trendmicro.com`
United States (for Government)	`api.usgov.xdr.trendmicro.com`

Test your authentication token by sending requests to the API:
- Send GET requests
- Send POST requests

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Obtain authentication tokens

Generate authentication tokens in the Trend Vision One console to access the APIs.

Procedure

On the Trend Vision One console, go to Administration → API Keys.
Generate a new authentication token.
1. Click Add API key.
2. Specify the settings of the new API key.
  Tip
  
  Use the principle of least privilege when configuring API keys.
  - Name: A meaningful name that can help you identify the API key (Example: MS_Sentinel_API_Token).
  - Role: The user role assigned to the key. API keys can use either predefined or custom user roles.
  - Expiration time: The time the API key remains valid.
    
    By default, authentication tokens expire one year after creation. However, a master administrator can delete and re-generate tokens at any time.
  - Status: Whether the API key is enabled.
  - Details: Extra information about the API key.
3. Click Add.
Copy and store the authentication token in a secure location.

Important

You cannot see the authentication token again after you click Close.

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Built-in roles

Trend Vision One has built-in roles with fixed permissions that Master Administrators can assign to accounts.

The following table provides a brief description of each role.

Role	Description
Master Administrator	Can access all apps and Trend Vision One features
Operator (formerly Administrator)	Can configure system settings and connect products
Auditor	Has "View" access to specific Trend Vision One apps and features
Senior Analyst	Can investigate XDR alerts, take response actions, approve Managed XDR requests, and manage detection models
Analyst	Can investigate XDR alerts and take response actions

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Send GET requests

Learn how to send GET requests to the List detection models API.

For more information, see the Detection Models section of the API reference.

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

cURL

Retrieve a list of the available detection models using cURL.

Procedure

Use the following information to create the request.
- Request type: GET
- URL: https://api.xdr.trendmicro.com/v2.0/xdr/dmm/models
- Header:
  - Key: Authorization
  - Value: Bearer <your authentication token>

Open the command prompt (Windows) or terminal (Linux, macOS) and execute the following command:

curl -X GET https://api.xdr.trendmicro.com/v2.0/xdr/dmm/models \
-H "Authorization: Bearer <your authentication token>

Tip

You can also use other HTTP clients such as Paw or Postman.

The API returns the following response body:

{
  "data": [
    {
      "modelId": "ti-0001",
      "name": "Threat Intelligence",
      "enabled": true
    },
    ...
  ]
}

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Python

Retrieve a list of the available detection models using a Python script.

Procedure

Create a file named first_steps_get_example.py.

Copy and paste the following code into the file.

import requests
import json
 
url_base = 'https://api.xdr.trendmicro.com'
url_path = '/v2.0/xdr/dmm/models'
token = 'YOUR_TOKEN'
 
query_params = {}
headers = {'Authorization': 'Bearer ' + token, 'Content-Type': 'application/json;charset=utf-8'}
 
r = requests.get(url_base + url_path, params=query_params, headers=headers)
 
print(r.status_code)
if 'application/json' in r.headers.get('Content-Type', ''):
    print(json.dumps(r.json(), indent=4))
else:
    print(r.text)

Locate the following line and change the value:
token = 'YOUR_TOKEN'
Open the command prompt (Windows) or terminal (Linux, macOS) and run the following command:
python first_steps_get_example.py

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Send POST requests

Learn how to send POST requests to the Enable or disable a detection model API.

For more information, see the Detection Models section of the API reference.

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

cURL

Enable or disable detection models based on your organization's security requirements using cURL.

Procedure

Use the following information to create the request.
- Request type: POST
- URL: https://api.xdr.trendmicro.com/v2.0/xdr/dmm/models/{id}
- First header:
  - Key: Authorization
  - Value: Bearer <your authentication token>
- Second header:
  - Key: Content-Type
  - Value: application/json
- Request body:
```
{
  "enable": true
}
```

Open the command prompt (Windows) or terminal (Linux, macOS) and execute the following command:

curl -X POST https://api.xdr.trendmicro.com/v2.0/xdr/dmm/models/{id} \
-H "Authorization: Bearer <your authentication token>" \
-H "Content-Type: application/json" \
-d '{
    "enable": true
}'

Tip

You can also use other HTTP clients such as Paw or Postman.

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

Python

Enable or disable detection models based on your organization's security requirements using a Python script.

Procedure

Create a file named first_steps_post_example.py.

Copy and paste the following code into the file.

import requests
import json
 
url_base = 'https://api.xdr.trendmicro.com'
url_path = '/v2.0/xdr/dmm/models/{modelId}'
url_path = url_path.format(**{'modelId': 'YOUR_MODELID'})
token = 'YOUR_TOKEN'
 
query_params = {}
body = '''
{
    "enable": true
}
'''
headers = {'Authorization': 'Bearer ' + token , 'Content-Type': 'application/json;charset=utf-8'}
 
r = requests.post(url_base + url_path, params=query_params, headers=headers, data=body)
 
print(r.status_code)
if 'application/json' in r.headers.get('Content-Type', ''):
    print(json.dumps(r.json(), indent=4))
else:
    print(r.text)

Locate the following lines and change the values:
- {'modelId': 'YOUR_MODELID'}
- token = 'YOUR_TOKEN'
Open a command prompt (Windows) or terminal (Linux) and run the following command:
```
python first_steps_post_example.py
```

Tip

For the complete Trend Vision One API documentation, visit the Trend Vision One Automation Center.

First steps toward using the APIs

Procedure

Tip

Obtain authentication tokens

Procedure

Tip

Important

Tip

Built-in roles

Tip

Send GET requests

Tip

cURL

Procedure

Tip

Tip

Python

Procedure

Tip

Send POST requests

Tip

cURL

Procedure

Tip

Tip

Python

Procedure

Tip