Use the Legacy REST API

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.

Related:

• On Premises:Legacy REST API reference documentation
• AWS Marketplace: Legacy REST API reference documentation
• Azure Marketplace: Legacy REST API reference documentation

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

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.

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.

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