Use the Legacy REST API

The REST API that was originally released in a previous version of Deep Security is still available, although it is deprecated and no new features will be added to it. When possible, you should use the Deep Security API to take advantage of new features and continued support.

When to use the legacy REST API

You should continue to use the legacy REST API if it provides the capabilities that you need and those capabilities are not yet provided in the Deep Security API. The following table summarizes the availability of REST API capabilities in the Deep Security API.

Endpoints are continuously being added to the Deep Security API. Periodically check this table for changes.
Click to show or hide the table:
Category Capability Deep Security API support
Authentication Log in and log out Yes – API keys
Log into a tenant account Yes – API keys
Describe and end a session Not available
Administrators Create, describe, list, modify, and delete an administrator Yes – See Administrators in the API Reference
Policy settings Describe, modify, and delete the Anti-Malware settings of a policy Yes – See Modify a Policy in the API Reference
Reset, describe, and modify the scanner settings of a policy Not available
Describe and modify the Application Control settings of a policy Yes – See Modify a Policy in API Reference
Hosts (Computers) Describe, modify, and delete the Anti-Malware settings of a computer Yes – See Modify a Computer in the API Reference
Reset, describe, and modify the scanner settings of a computer Not available
Create, delete, describe, list, modify, and synchronize a smart folder Not available
List the computers in a smart folder Not available
List, disable, describe, and modify relays and relay groups Not available
List the tree of host groups Yes – See List Computer Groups in the API Reference
Describe, modify, and delete scanner settings on a computer Not available
Tenants Create, describe, delete, modify, and list tenants Yes – See the Tenants operations in the API Reference
Malware scan configurations Create, describe, list, modify, and delete a malware scan configuration Yes – See Anti-Malware Configurations in the API Reference
Alerts Describe and list alerts Not available
Describe, list, modify, and reset alert types Not available
Dismiss an alert, and dismiss an alert on a single target Not available
Event-based tasks Create, delete, and list event-based tasks Not available
Roles Add, delete, and modify a role’s host, host group, and policy access Not available
Add and delete a role right Not available
Create, delete, describe, modify, and list roles Not available
Scheduled Tasks Create, delete, describe, modify, and list scheduled tasks Not available
Modify a scheduled task recipient list Not available
Cloud List AWS Marketplace billing records, MMS usage details, and usage summary Not available
Connect to an AWS account, delete, modify, and describe the connection Not available
List, create, delete, describe, modify, and sync cloud accounts (non-AWS) Not available
Application Control Describe, list, and undo a decision log Not available
Create, delete, describe, and list rulesets Not available
Describe a global ruleset, and add and delete global ruleset rules Not available
Describe, list, and review application drift and computer drift Not available
Create, delete, describe, and list software inventories Not available
Describe and modify Trusted Update Mode (Maintenance mode) Not available
Monitoring List instance rates, database protection, host protection, and manager and tenant usage Not available
Intrusion Prevention Create, delete, modify, describe, and list SSL configurations Not available
Connected Threat Defence Clear and modify the list of suspicious objects Not available
Events List and describe Anti-Malware, Integrity Monitoring, Log Inspection, Web Reputation, and Application Control events Not available
List, create, delete, describe, and modify Syslog configurations Not available
SAML Describe a SAML service provider Not available
List, create, delete, describe, and modify SAML identity providers Not available
Assume a role using SAML Not available
Diagnostics Get manager and agent diagnostic packages Not available
Licenses Describe license statuses and update activation codes Not available
Instance rates List DSaaS instance rates Not available
News Feed Describe, list, and dismiss news feed items Not available
Environment List, create, delete, describe, and modify a proxy Not available
Reports List report templates Not available
Scripts List scripts Not available

Set up your environment to use the REST API

Perform the following tasks to prepare your environment for developing with the REST API:

Download the Web Services SDK

Download the Web Services SDK ZIP file and extract it:

The ZIP file contains REST API documentation, a Java client library that helps with developing Java client applications, and samples that use the library. If you use a different language, or you use Java and want to use your own REST client technology, use the REST API reference documentation to learn the syntax for API calls. For each operation, the reference provides the HTTP syntax including the HTTP path and operation (GET, PUT, etc.), and a description of the structure of the data passed to or from the API call.

See the ZIP’s readme file for a complete list of contents and other important information.

Enable the Status Monitoring API (optional)

Most functions of the REST API are available after Deep Security Manager has been installed and started. They do not require any additional configuration. However, there is an exception: if you want to use status monitoring, you must enable it first. The status monitoring API is disabled by default as it does not require authentication.

  1. In Deep Security Manager, go to Administration > System Settings > Advanced.
  2. In the Status Monitoring API section, select Enabled, then click Save.

Create a Web Service role and user

Create a role that has permissions to access the Deep Security web services API endpoints (both SOAP and REST) and any other features that you want to use with the REST API. For security reasons, you should create a role and a user specifically for your API calls.

The REST API enforces all role access controls, such as computer rights, security profile rights, and user rights. For example, when you create a role for the Web Service APIs that allows a user to view certain computers, a REST API client that authenticates as that user can view only the specified computers.

  1. In Deep Security Manager, go to Administration > User Management > Roles.
  2. Click New.
  3. Deselect Allow Access to Deep Security Manager User Interface and select Allow Access to Web Service API.
  4. When all other configuration is complete, click Save.
  5. Go to Administration > User Management > Users and click New.
  6. Provide the required properties for the use. For the Role property, select the role that you just created.
  7. Make a note of the new user account username and password.

Trust the Deep Security Manager certificate

All REST API clients must communicate with Deep Security Manager over HTTPS connections, and your clients must trust the certificate that secures the connections.

If the manager’s certificate is signed by a trusted certificate authority (CA), you do not need to do anything.

If the manager uses a self-signed certificate, you need to import the certificate into the trusted X.509 certificate store of your REST client implementation. For Java programs, you can use a custom trust store or the default trust store of the JRE. For more information, see “Import self-signed certificates” on the Java SDK page.

Develop a REST API client application

Use the programming language of your choice to write code that calls the REST API according to the API’s documentation. You can use any programming language that supports XML or JSON encoding and the HTTP and HTTPS protocols.

Basic API access

All access to the REST API is made through the Deep Security Manager URL https://<host or IP>:<port>/rest. For example, if Deep Security Manager is installed on a computer named dsm.example.com and is listening on the default REST API port number, the URL is:

https://dsm.example.com:4119/rest

For Deep Security as a Service, the REST API endpoint is https://app.deepsecurity.trendmicro.com/rest.

Because the REST API uses standard HTTP mechanisms and some of the operations can be accessed without authentication using HTTP GET, these methods can be accessed from a web browser. For example, the following URL returns the REST API version to the browser:

https://dsm.example.com:4119/rest/apiVersion

However, most REST API calls require authentication. To authenticate calls, you provide a session identifier (SID) either as a query parameter for GET and DELETE methods or in the message body of PUT and POST methods. To get a session ID, call the /rest/authentication/login URL with the user name and password of a user who is allowed to access the API.

Manage your sessions

Take the following actions to manage your sessions:

  • Terminate API sessions when they are no longer required. The Deep Security Manager limits the number of sessions that can be active at one time. Your application should terminate its sessions to avoid reaching the maximum number of concurrent sessions. Call the /rest/authentication/logout URL to end the session
  • Sessions time out after a configurable period. To change the number of concurrent sessions allowed per user and the session timeout, go to Administration > System Settings > Security.

The example Java code below illustrates this process.

Use the provided Java REST API client

The provided Java REST API client is based on the RESTEasy Client Framework and the Apache HTTPComponents project. This framework takes the Java interfaces that have been marked up with JAX-RS annotations and generates implementations of the interfaces that can communicate with the Deep Security Manager. The Java REST  API client takes care of all object serialization and deserialization, HTTP URLs, and HTTP methods for you.

To use the Java REST API client, include the JAR file in the lib folder on the classpath of your application. The JAR file has dependencies on other third-party libraries. For details, see the pom.xml file of the Eclipse project in the samples directory.

The interfaces for all the APIs are found in the Java package com.trendmicro.ds.platform.rest.api. All of the objects sent to or from the API are found in the Java package com.trendmicro.ds.platform.rest.object and sub-packages.

Example Java code

The following example code uses the Java REST API client to authenticate with Deep Security Manager.

Click to show or hide the code:
import javax.ws.rs.core.Response.Status;

import org.jboss.resteasy.client.ClientResponse;
import org.jboss.resteasy.client.ClientResponseFailure;
import org.jboss.resteasy.client.ProxyFactory;
import org.jboss.resteasy.client.core.executors.ApacheHttpClient4Executor;
import org.jboss.resteasy.plugins.providers.RegisterBuiltin;
import org.jboss.resteasy.spi.ResteasyProviderFactory;

import com.trendmicro.ds.platform.rest.api.IAuthenticationAPI;
import com.trendmicro.ds.platform.rest.message.error.ErrorMessage;
import com.trendmicro.ds.platform.rest.object.DSCredentials;

public class AuthenticateSample {

	public static void main(String[] args) {
		// URL for the REST API. Change this as appropriate. 
		String restApiUrl = "https://10.0.0.5:4119/rest";
		
		// The user name to use for authentication. Change this as appropriate.
		String username = "admin";
		
		// The user's password. Change this as appropriate.
		String password = "supersecretpassword";

		// Variable to store the session identifier (SID).
		String sID = null;

		// RESTEasy client framework initialization that only needs to be done once per VM
		RegisterBuiltin.register(ResteasyProviderFactory.getInstance());

		// An object that will execute HTTP requests
		ApacheHttpClient4Executor executor = new ApacheHttpClient4Executor();

		// Create the object that will communicate with the authentication API.
		IAuthenticationAPI authClient = ProxyFactory.create(IAuthenticationAPI.class, restApiUrl, executor);

		// Create the object to pass to the authentication call.
		DSCredentials credentials = new DSCredentials();
		credentials.setUserName(username);
		credentials.setPassword(password);

			try {
				System.out.println("Attempting to authenticate to Deep Security Manager REST API...");
				sID = authClient.login(credentials);
	
				System.out.println("Authentication successful.");
				System.out.println("Authentication session ID string received: " + sID);

			} catch (ClientResponseFailure e) {
				// This is a special type of exception that means the server threw
				// an exception because there was a problem with the credentials.
				// It's important to handle these exceptions explicitly or the
				// connection to the server won't be released back in to the
				// underlying connection pool, meaning any subsequent API calls would fail.
				// See the RESTEasy Client Framework documentation for more details. 
				ClientResponse<?> clientResponse = e.getResponse();

				// Try to parse the error response in to an instance of the special
				// ErrorMessage class and display the result.
				Status status = clientResponse.getResponseStatus();
				System.out.println("Server returned error status code " + status.getStatusCode() + " (" + status + ")");
				ErrorMessage errorMessage = clientResponse.getEntity(ErrorMessage.class);
				System.out.println("Returned error message: " + errorMessage.getMessage());

			} catch (Exception e) {
				// Some other error happened, most likely related to network communication problems.
				System.out.println("There was an error during authentication.");
				e.printStackTrace();
			
			} finally {
				if (sID != null) {
					// Make sure to always log out.
					System.out.println("");
					System.out.println("Ending session...");
					authClient.endSession(sID);
					System.out.println("End session successful.");
					// make sure the session ID isn't accidentally re-used.
					sID = null;
				}
			}
		
			// Cleanup: force the HTTP Client to close any open sockets
			executor.close();

	}
	
}

Use the Sample Java code

Sample Java code is included in the samples folder. The samples are part of an Eclipse project that you can import into your Eclipse workspace:

  1. In Eclipse, click File > Import.
  2. Select General > Existing Projects into Workspace for the import source.
  3. Click Browse and select the samples folder of the Deep Security Web Services SDK as the root.
  4. Ensure the REST API Samples project is selected and click Finish.

To run a sample file within Eclipse, open the file and click Run > Run As > Java Application. The samples require command line arguments that you need to set on the Run Configurations screen.

HTTP status codes

The REST API uses standard HTTP status codes to return the status of requests. The table below shows the response codes that may be used and the circumstances under which they are returned.

HTTP Status Code Meaning
200 OK The request completed successfully.
400 Bad Request The caller did not supply all of the data that the call requires.
401 Unauthorized The caller’s SID has timed out due to inactivity. The authentication process must be repeated.
403 Forbidden Any of the following reasons:

  • The calling does not have access rights to the Web Services APIs.
  • The calling user does not have access rights to call the API that failed.
  • The caller’s SID is invalid.
  • The caller is a user in a Tenant but the API is restricted to primary Tenant Users only.
404 Not Found Any of the following reasons:

  • The caller accessed an invalid URL that is not part of the REST API.
  • The caller specified a resource that does not exist. For example, an attempt was made to delete a tenant by ID and the ID that was provided does not correspond with an existing tenant.
405 Method Not Found The caller has specified an HTTP method that is not allowed for the given URL. For example, using HTTP POST to access an API that provides GET access.
500 Internal Server Error Any of the following reasons:

  • A database error occurred.
  • Some other unhandled error occurred.

Error responses

When an API call returns a status code other than 200 OK, the response body typically  includes JSON code similar to the following example:

{
   "error": {
      "message": "The Activation Code KA47-R947M-KDLUZ-A8WLF-WM6A3-LOL is invalid."
   }
}

Some calls include XML code instead of JSON, as in the following example:

<error>
	<message>Error message string</message>
</error>

The error message can be helpful for debugging the problem but is not suitable for presenting to end users of an application.

API calls that return javax.ws.rs.core.Response

Some API calls are documented as returning an object of type javax.ws.rs.core.Response. These calls can be thought of as returning nothing more than the HTTP status code.

When you use the provided Java REST API client, it is important to retrieve the result of such calls instead of ignoring them. Once you have the Response object, the underlying connection to the server must be manually released back to the connection pool, as described in the RESTEasy Client Framework. For example:

org.jboss.resteasy.client.ClientResponse<?> clientResponse = (ClientResponse<?>)apiObject.methodThatReturnsResponse(methodParameters);
clientResponse.releaseConnection();

Special Considerations

Specify dates in query parameters

When you specify dates in search queries, encode them using the date-encoding rules set out in section 5 of RFC 822, except that years should be encoded as 4 digits instead of 2 as per section 5.2.14 of RFC 1123. For example, encode November 31 2012 at 3:45 PM Eastern Standard Time as 31 Nov 2012 15:45:00 -0500.

In Java, these dates could be encoded using java.text.SimpleDateFormat and the date format pattern "dd MMM yyyy HH:mm:ss zzz".

For example, for a session ID of DC5A4AA79326DF3E149A26EA2DA6B0C7, the following URL queries all host protection information after November 31 2012 at 3:45 PM Eastern Standard Time, where spaces in the date encoding have been URL encoded with %20:

https://dsm.example.com:4119/rest/monitoring/usages/hosts/protection?sID=DC5A4AA79326DF3E149A26EA2DA6B0C7&from=31%20Nov%202012%2015:45:00%20-0500

Multi-tenant permissions

Several of the REST APIs enable you to manage a multi-tenant environment. Beyond the normal role permissions required, these APIs also require that the user that is used to authenticate the API call is on the primary tenant. Attempts to call these APIs with a user from a different tenant returns a response with the status code 403 Forbidden. The following APIs can only be called by a primary Tenant user:

  • /monitoring – the monitoring API
  • /multitenantconfiguration – the multi-tenant configuration API
  • /tenants – the tenant API
  • /tenantdatabaseservers – the tenant database server API
  • /tenanttemplate – the tenant template API