Send Your First Request Using the API
To become familiar with the API, send some simple requests to Deep Security Manager.
Set up your development environment
The environment where you develop your software requires the following items:
- Network access to a running Deep Security Manager, either one that you installed or one provisioned by Deep Security as a Service.
- An SDK client library, if you choose to use one. Go to the Python SDK page, the JavaScript SDK page, or the Java 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 Deep Security Manager
Deep Security Manager uses API keys for authenticating HTTP requests. Each request that you make requires an api-secret-key
header that contains a secret key, as in the following example request:
GET /api/policies HTTP/1.1 Host: localhost:4119 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 GET and POST examples below show how to create and configureApiClient
.
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.
Create an API key
Create an API key to use for authenticating your requests with Deep Security Manager. When you create an API key, you provide a name, the role to associate with the key, and optionally an expiry date. For more information, see Create and Manage API Keys.
Upon creation of an API key, you are provided 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. If you lose the secret you must create a new API key or create a new secret for the key.
- In Deep Security Manager, click Administration > User Management > System API Keys.
- Click New and enter the property values for the key.
- Click Next. The secret is presented. This is the only time that you can obtain the secret.
- Copy the secret and securely store it.
- Click Close.
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 examplehttps://localhost:4119/api/policies
- First header:
- Key:
api-secret-key
- Value:
<your key secret>
- Key:
- Second header:
- Key:
api-version
- Value:
v1
- Key:
Example curl command:
curl -X GET https:// localhost:4119/api/policies -H 'api-secret-key: 5:W+lC8YHIaYHeQuDbJZLkqwM5b8xjxla2pHtBNoiifF8=' -H 'api-version: v1'
If your Deep Security Manager is using a self-signed certificate to establish a secure connection, in the Postman settings, turn off SSL certificate verification. For Paw, in the Network preferences clear Validate SSL Certificates. For curl, include the --insecure
option.
Use a client library
The following example code creates an ApiClient
object that configures authentication with Deep Security Manager. A PoliciesApi
object is then created and used to list all policies.
For the sake of clarity the example hard-codes authentication credentials, which is an extremely bad practice. Never hard-code your credentials.
- 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 the Deep Security Manager :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 Deep Security Manager host information to the api client configuration configuration = api.Configuration() configuration.host = 'https:// 192.168.17.149:4119/api' # 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://192.168.17.149:4119/api'
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
- Create a file named FirstStepsGetExample.js and copy the following example code to the file.
exports.getPolicies = function(hostNameAndPort, apiSecretKey) { return new Promise((resolve, reject) => { // Deep Security module const api = require("@trendmicro/deepsecurity"); // Create the client const defaultClient = api.ApiClient.instance; defaultClient.basePath = "https:// " + hostNameAndPort + "/api"; const defaultAuthentication = defaultClient.authentications["DefaultAuthentication"]; defaultAuthentication.apiKey = apiSecretKey; // Allow connection that is 'secured' with self-signed certificate - for development only process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; // Create a PoliciesApi object const policiesApi = new api.PoliciesApi(); // List policies. Use version v1 of the API policiesApi.listPolicies("v1") .then(policies => { resolve(policies); }) .catch(error => { reject(error); }); }); };
- Create another file named App.js and copy the following code to the file:
const path = require("path"); const FirstStepsGetExample = require(path.resolve(__dirname, "./FirstStepsGetExample.js")); FirstStepsGetExample.getPolicies("localhost:4119", "3:zNi5ag8xPGpfEMElV0GxAIpTs5Ji8BQoCtXaTAgKkVM=") .then( policies => { console.log(policies); }) .catch(error => { console.log(error); });
- In the App.js file, change the URL and secret key parameters of the call to
FirstStepsGetExample.getPolicies
according to your environment. - Open a Command Prompt (Windows) or terminal (Linux) and enter the following command:
node App.js
- If you are seeing the error
TypeError: Cannot read properties of undefined (reading 'text')
, it means that the SDK cannot establish a connection between APIClient and the Deep Security Manager (DSM) host. Check that the DSM host name is correct.
TypeError: Cannot read properties of undefined (reading 'text') at \nodejs-DSM-sdk\src\ApiClient.js:471 at Object.onceWrapper (node:events:646:26) at ClientRequest.emit (node:events:526:28) at TLSSocket.socketErrorListener (node:_http_client:442:9) at TLSSocket.emit (node:events:526:28) at emitErrorNT (node:internal/streams/destroy:157:8) at emitErrorCloseNT (node:internal/streams/destroy:122:3) at processTicksAndRejections (node:internal/process/task_queues:83:21)
- Create a file named FirstStepsGetExample.java and copy the following example code to the file.
package com.trendmicro.deepsecurity.docs; import com.trendmicro.deepsecurity.ApiClient; import com.trendmicro.deepsecurity.ApiException; import com.trendmicro.deepsecurity.Configuration; import com.trendmicro.deepsecurity.api.PoliciesApi; import com.trendmicro.deepsecurity.auth.ApiKeyAuth; import com.trendmicro.deepsecurity.model.Policies; import com.trendmicro.deepsecurity.model.Policy; public class FirstStepsGetExample { /* * Retrieves all policies and prints the names. */ public static void main(String[] args){ // Create the client ApiClient dsmClient = Configuration.getDefaultApiClient(); dsmClient.setBasePath("https:// 192.168.60.128:4119/api"); ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) dsmClient.getAuthentication("DefaultAuthentication"); DefaultAuthentication.setApiKey("3:/tiKl3+6ritnk4tQXipq5ufIls5nCFqoGoUcWl+imTU="); // Create a PoliciesApi object PoliciesApi policiesApi = new PoliciesApi(); try { // List policies. Use version v1 of the API. Policies policies = policiesApi.listPolicies(false, "v1"); for (Policy policy : policies.getPolicies()){ System.out.println(policy.getName()); } } catch (ApiException e) { e.printStackTrace(); } } }
- Locate the following code and change the URL and secret key according to your environment:
dsmClient.setBasePath("https://192.168.60.128:4119/api");
DefaultAuthentication.setApiKey("3:/tiKl3+6ritnk4tQXipq5ufIls5nCFqoGoUcWl+imTU=");
- To compile the Java class, open a Command Prompt (Windows) or terminal and enter the following command:
javac -d . -cp <path to java client library> FirstStepsGetExample.java
- To execute the class, enter the following command:
- Windows:
java -cp ".;<path to java client library>" com.trendmicro.ds.docs.api_examples.FirstStepsGetExample
- Linux:
java -cp ".:<path to java client library>" com.trendmicro.ds.docs.api_examples.FirstStepsGetExample
- Windows:
Perform a POST request: search firewall rules
Perform a POST request to search for firewall rules. In the API reference, the SearchFirewallRules 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 we search 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://<Deep Security Manager hostname>:<port>/api/firewallrules/search
, for examplehttps://localhost:4119/api/firewallrules/search
- First header:
- Key:
api-secret-key
- Value: your key secret
- Key:
- Second header:
- Key:
api-version
- Value:
v1
- Key:
- Third header:
- Key:
Content-Type
- Value:
application/json
- Key:
Also, add the following raw code to the body:
{ "searchCriteria": [{ "idTest":"equal", "idValue":3 }] }
Example curl command:
curl -X POST https:// localhost:4119/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 thesearchFirewallRules
method of aModuleFirewallApi
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 Deep 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 Deep 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 Deep Security Manager host information to the api client configuration configuration = api.Configuration() configuration.host = 'https://192.168.17.149:4119/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://192.168.17.149:4119/api'
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
- Create a file named first_steps_post_example.py and copy the following example code to the file.
- Create a file named FirstStepsPostExample.js and copy the following example code to the file.
exports.searchFirewallRules = function(hostNameAndPort, apiSecretKey) { return new Promise((resolve, reject) => { // Deep Security module const api = require("@trendmicro/deepsecurity"); // Create the client const defaultClient = api.ApiClient.instance; defaultClient.basePath = "https:// " + hostNameAndPort + "/api"; const defaultAuthentication = defaultClient.authentications["DefaultAuthentication"]; defaultAuthentication.apiKey = apiSecretKey; // Allow connection that is 'secured' with self-signed certificate - for development only process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; // Define the search criteria const searchCriteria = new api.SearchCriteria(); searchCriteria.fieldName = "name"; searchCriteria.stringValue = "%DHCP%"; searchCriteria.stringTest = api.SearchCriteria.StringTestEnum.equal; searchCriteria.stringWildcards = true; // Create a search filter to find the rule const searchFilter = new api.SearchFilter(); searchFilter.searchCriteria = [searchCriteria]; // Add the search filter to a search options object const searchOptions = { searchFilter: searchFilter, overrides: false } // Create a FirewallRulesApi object const fwRulesApi = new api.FirewallRulesApi(); // Perform the search and handle the returned promise fwRulesApi.searchFirewallRules("v1", searchOptions) .then(data => { resolve(data.firewallRules); }) .catch(error => { reject(error); }); }); };
- Create another file named App.js and copy the following code to the file:
const path = require("path"); const FirstStepsPostExample = require(path.resolve(__dirname, "./FirstStepsPostExample.js")); FirstStepsPostExample.searchFirewallRules("localhost:4119", "3:zNi5ag8xPGpfEMElV0GxAIpTs5Ji8BQoCtXaTAgKkVM=") .then( firewallRules => { for (let i in firewallRules) { console.log(`${firewallRules[i].ID} ${firewallRules[i].name}`); } }) .catch(error => { console.log(error); });
- In the App.js file, change the URL and secret key parameters of the call to
FirstStepsPostExample.searchFirewallRules
according to your environment. - Open a Command Prompt (Windows) or terminal (Linux) and enter the following command:
node App.js
- If you are seeing the error
TypeError: Cannot read properties of undefined (reading 'text')
, it means that the SDK cannot establish a connection between APIClient and the Deep Security Manager (DSM) host. Check that the DSM host name is correct.
TypeError: Cannot read properties of undefined (reading 'text') at \nodejs-DSM-sdk\src\ApiClient.js:471 at Object.onceWrapper (node:events:646:26) at ClientRequest.emit (node:events:526:28) at TLSSocket.socketErrorListener (node:_http_client:442:9) at TLSSocket.emit (node:events:526:28) at emitErrorNT (node:internal/streams/destroy:157:8) at emitErrorCloseNT (node:internal/streams/destroy:122:3) at processTicksAndRejections (node:internal/process/task_queues:83:21)
- Create a file named FirstStepsPostExample.java and copy the following example code to the file.
package com.trendmicro.deepsecurity.docs; import com.trendmicro.deepsecurity.ApiClient; import com.trendmicro.deepsecurity.ApiException; import com.trendmicro.deepsecurity.Configuration; import com.trendmicro.deepsecurity.api.FirewallRulesApi; import com.trendmicro.deepsecurity.auth.ApiKeyAuth; import com.trendmicro.deepsecurity.model.FirewallRule; import com.trendmicro.deepsecurity.model.FirewallRules; import com.trendmicro.deepsecurity.model.SearchCriteria; import com.trendmicro.deepsecurity.model.SearchFilter; public class FirstStepsPostExample { /* * Searches for firewall rules that contain 'DHCP' in the name. */ public static void main(String[] args){ // Create the client ApiClient dsmClient = Configuration.getDefaultApiClient(); dsmClient.setBasePath("https:// 192.168.60.128:4119/api"); ApiKeyAuth DefaultAuthentication = (ApiKeyAuth) dsmClient.getAuthentication("DefaultAuthentication"); DefaultAuthentication.setApiKey("3:fkZjcAuvj9ZWhdXgVvFl4Q3DymDZTKHOE3EDDqYPwdg="); // Create the search criteria SearchCriteria searchCriteria = new SearchCriteria(); searchCriteria.setFieldName("name"); searchCriteria.setStringValue("%DHCP%"); searchCriteria.setStringTest(SearchCriteria.StringTestEnum.EQUAL); searchCriteria.setStringWildcards(true); // Create the search filter SearchFilter searchFilter = new SearchFilter(); searchFilter.addSearchCriteriaItem(searchCriteria); // Use FirewallRulesApi to search FirewallRulesApi fwRulesApi = new FirewallRulesApi(); try { FirewallRules fwrules = fwRulesApi.searchFirewallRules(searchFilter, "v1"); for (FirewallRule fwrule : fwrules.getFirewallRules()){ System.out.println(fwrule.getName()); } } catch (ApiException e) { e.printStackTrace(); } } }
- Locate the following code and change the URL and API key secret according to your environment:
dsmClient.setBasePath("https://192.168.60.128:4119/api");
DefaultAuthentication.setApiKey("3:/tiKl3+6ritnk4tQXipq5ufIls5nCFqoGoUcWl+imTU=");
- To compile the Java class, open a Command Prompt (Windows) or terminal and enter the following command:
javac -d . -cp <path to java client library> FirstStepsPostExample.java
- To execute the class, enter the following command:
- Windows:
java -cp ".;<path to java client library>" com.trendmicro.ds.docs.api_examples.FirstStepsPostExample
- Windows:
java -cp ".;<:path to java client library>" com.trendmicro.ds.docs.api_examples.FirstStepsPostExample
- Windows:
Get the Deep Security Manager version
Each response to a correctly-authenticated request includes the version of the Deep Security Manager instance. The X-DSM-Version header includes the version, similar to the following example:
X-DSM-Version=Deep Security/12.0.81