Send request using the API

To become familiar with the API, you can send some simple requests to Workload Security.

Set up your development environment

The environment where you develop your software requires the following:

• Network access to Workload Security.
• An SDK client library, if you choose to use one. Go to the Python SDK page to download the client library and learn how to add it to your development environment.
• The runtime environment for the programming language of your client library.

To start exploring the API right away, instead of using a client library, you can use an HTTP client such as Postman, Paw, or curl.

Authenticate with Workload Security

Workload Security uses API keys for authenticating HTTP requests.

The way you authenticate HTTP requests depends on whether you are using a new Trend Cloud One account or a legacy account. For information, see Changes to Trend Cloud One accounts.

Create an API key

To create an API key to use for authenticating your requests with Workload Security, see the following:

• For legacy accounts, see Create and Manage API Keys.
• For new Trend Cloud One accounts, see Manage API keys.

Upon creation of an API key, you are provided with a unique secret key that is associated with the API key. You include this secret key in the HTTP request for authenticating. You must store the secret key when it is provided because at no other time are you able to obtain it.

Authenticate requests

Each HTTP request that you make requires an authorization in the header. How you perform that authorization depends on whether you are using a legacy API key or a Trend Cloud One API key.

Authenticate with a Trend Cloud One API key

If you are using a Trend Cloud One API key, each request that you make requires an authorization header that contains a secret key, as show in the following example request:

GET /api/policies HTTP/1.1
Host: https://workload.<region>.cloudone.trendmicro.com/
Authorization: ApiKey 1tBOlis4aGpMyygC26YKZMgU2fW:7864DcPqkWFHNngXHnn9VgWSuGtUoj52n3tTZSqkvucLDJ9jJJvbrBZMBJBigsS5wT
api-version: v1

Authenticate with a legacy API key

If you are using a legacy API key, each request must contain an api-secret-key header that contains a secret key, as shown in the following example request:

GET /api/policies HTTP/1.1
Host: https://workload.<region>.cloudone.trendmicro.com/
api-secret-key: 2:vJC6lckDygB6FYURIvR0WK2ZTAhIY8rb0Amy9UMn4mo=
api-version: v1

When using a client library, you obtain an instance of ApiClient and configure it to use your secret key. The configuration is global, so that all calls to the API thereafter are authenticated using the secret key. The following GET and POST examples show how to create and configure ApiClient.

The manager uses the secret to authenticate your request. Each API key is associated with a role that determines the actions that you can perform.

Perform a GET request: list policies

To start exploring the API, go to the List Policies operation in the Policies section of the API reference. Notice that List Policies is a GET request on the policies endpoint:

Use an HTTP client

To send the request right away use Postman, Paw, or curl. Use the following information to create the request:

• URL: https://<manager_host_name>:<port>/api/policies, for example https://workload.<region>.cloudone.trendmicro.com/api/policies
• First header:
  • Key: api-secret-key (for legacy accounts) or Authorization (for new accounts)
  • Value: <your_key_secret> (for legacy accounts) or ApiKey <your_key_value> (for new accounts)
• Second header:
  • Key: api-version
  • Value: v1

Example curl command for legacy account:

curl -X GET workload.<region>.cloudone.trendmicro.com/api/policies -H 'api-secret-key: 5:W+lC8YHIaYHeQuDbJZLkqwM5b8xjxla2pHtBNoiifF8=' -H 'api-version: v1'

Use a client library

The following example creates an ApiClient object that configures authentication with Workload Security. A PoliciesApi object is then created and used to list all policies.

Create a file named first_steps_get_example.py and copy the following example code to the file:

import deepsecurity as api
from deepsecurity.rest import ApiException as api_exception

def get_policies_list(api, configuration, api_version, api_exception):
    """ Gets a list of policies on Workload Security

    :return: A PoliciesApi object that contains a list of policies.
    """
    # Create a PoliciesApi object
    policies_api = api.PoliciesApi(api.ApiClient(configuration))

    # List policies using version v1 of the API
    policies_list = policies_api.list_policies(api_version)
    # View the list of policies
    return policies_list

if __name__ == '__main__':
    # Add Workload Security host information to the api client configuration
    configuration = api.Configuration()
    configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'

    # Authentication
    configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

    # Version
    api_version = 'v1'

    print(get_policies_list(api, configuration, api_version, api_exception))

Locate the following code and change the URL and secret key according to your environment:

configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'
configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

Open a Command Prompt (Windows) or terminal (Linux) and enter the following command:

python first_steps_get_example.py

Perform a POST request: search firewall rules

Perform a POST request to search for firewall rules. In the API reference, the Search Firewall Rules operation (Firewall Rules section) for the firewallrules endoint is a POST request to the path firewallrules/search.

The API reference also shows a series of parameters that you use in the request body. For Search Firewall Rules, each parameter is a search criterium. In this example, the search is performed for the ID of 3.

Use an HTTP client to post

Use the following information to create the request in Postman or Paw:

• Request type: POST
• URL: https://<workload_security_hostname><port>/api/firewallrules/search, for example https://workload.<region>.cloudone.trendmicro.com/api/firewallrules/search
• First header:
  • Key: api-secret-key (for legacy accounts) or Authorization (for new accounts)
  • Value: your key secret
• Second header:
  • Key: api-version
  • Value: v1
• Third header:
  • Key: Content-Type
  • Value: application/json

Also, add the following raw code to the body:

{
  "searchCriteria": [{
    "idTest":"equal",
    "idValue":3
  }]
}

Example curl command:

curl -X POST workload.<region>.cloudone.trendmicro.com/api/firewallrules/search \
-H 'Cache-Control: no-cache' \
-H 'api-secret-key: 3:zNi5ag8xPGpfEMElV0GxAIpTs5Ji8BQoCtXaTAgKkVM=' \
-H 'api-version: v1' \
-H 'content-type: application/json' \
-d '{
  "searchCriteria": [{
    "idTest":"equal",
    "idValue":3
  }]
}'

Use a client library to post

The following example creates a SearchFilter object that defines search criteria. The SearchFilter object is then used as a parameter of the searchFirewallRules method of a ModuleFirewallApi object.

Create a file named first_steps_post_example.py and copy the following example code to the file:

import deepsecurity as api
from deepsecurity.rest import ApiException as api_exception

def search_firewall_rules(api, configuration, api_version, api_exception):
    """ Searches the firewall rules for any rule that contains DHCP in the rule name.

    :param api: The Workload Security API modules.
    :param configuration: Configuration object to pass to the api client.
    :param api_version: The version of the API to use.
    :param api_exception: The Workload Security API exception module.
    :return: A list containing all firewall rules that match the search criteria.

    """

    # Define the search criteria
    search_criteria = api.SearchCriteria()
    search_criteria.field_name = "name"
    search_criteria.string_value = "%DHCP%"
    search_criteria.string_test = "equal"
    search_criteria.string_wildcards = True

    # Create search filter to find the rule
    search_filter = api.SearchFilter(None,[search_criteria])

    # Create a FirewallRulesApi object
    firewall_rules_api = api.FirewallRulesApi(api.ApiClient(configuration))

    # Perform the search
    firewall_rules = firewall_rules_api.search_firewall_rules(api_version, search_filter=search_filter)
    firewall_rules_list = []
    for rule in firewall_rules.firewall_rules:
        firewall_rules_list.append(rule)

    return firewall_rules

if __name__ == '__main__':
    # Add Workload Security host information to the api client configuration
    configuration = api.Configuration()
    configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/api'

    # Authentication
    configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

    # Version
    api_version = 'v1'
    print(search_firewall_rules(api, configuration, api_version, api_exception))

Locate the following code and change the URL and secret key according to your environment:

configuration.host = 'https://workload.<region>.cloudone.trendmicro.com/'</code></li>
configuration.api_key['api-secret-key'] = '2:l069trAePqPRxZUfBqyw442z1DWm9s4u0F/g9bewnFE='

Open a Command Prompt (Windows) or terminal (Linux) and enter the following command:

python first_steps_post_example.py

Get the Workload Security version

Each response to a correctly-authenticated request includes the version of the Workload Security instance. The X-DSM-Version header includes the version, similar to the following example:

X-DSM-Version = Deep Security/12.0.81

Next Steps

• Run the Code Examples
• Notes about Resource Property Values
• About the Overrides Parameter
• Search for Resources