Obtaining a bearer token to enable API interaction

OpenText™ Network Detection & Response (NDR), previously known as Bricata Network Detection & Response, provides real-time network visibility, metadata generation and threat detection. Additionally, it can be used as an effective tool for forensics and threat hunting. The NDR system makes use of three components – Central Management Center (CMC), datanodes and sensors:

Central Management Center (CMC):

• Single pane of glass for visualization, investigation and security event analysis
• Alerts dashboard
• Centralized system and policy management
• Threat hunting repository manager

Datanodes:

• Threat hunting repository data

Sensors:

• Stateful and signature-based threat detection
• IoC-matched threat detection
• Network metadata generation
• SmartPCAP capture

In this blog, we will highlight NDR’s API capabilities by demonstrating how to craft a request to receive a bearer token, and how to use this as a means of authentication for future requests. In our example, Google Postman is leveraged to request the bearer token.

To get started, the following is required:

1. An account on the NDR CMC that will be used for API calls. This example will use a local account called: “apiguy”.
2. An up-to-date version of Google Postman.
3. Access to the NDR CMC.

One of the benefits of the Bricata NDR is the ability to automate interaction with the CMC via the use of API calls. To make use of these calls, users need to pass a bearer token to the CMC along with their request (POST, PUT, GET).

API Reference

The API guide is built into the CMC’s GUI (CMC > Support > API documentation). The following provides the critical information that is needed to craft a request for the bearer token.

The first important piece of information, located at the very top of the API guide, is the URL structure for the API calls: Base URL:/api

The base URL, is the IP address (or FQDN) of the CMC, followed immediately by a forward-slash and api: https://<CMC_IP>/api

The next step is to understand what is required of the API request. Scroll down through the API guide to the “auth” section and look for the POST command that allows us to retrieve a bearer token.

Based on the API guide, a POST request should be sent, containing a json-formatted body, with the username, password and refresh token status to: https://<CMC_IP_address>/api/login.

Using Google Postman

1. Open Google Postman. Select “Collections” and then click the “+” sign to create a new collection. For this exercise, we’ve created a collection called: “Bearer Token”.

• NOTE: Postman Collections are groupings of API commands that make use of a set of variables defined at the Collection level. This means that any variables created are available to all API commands within a Collection.

2. From within the Bearer Token Collection, create two variables: “url” and “password”. Populate the initial values with the API URL for Bricata CMC, and the password for the API account. Make sure to save the collection.

• NOTE: From this point,  the url and password variables can be called by encasing them within curly brackets {}. For example: {{url}}. Hovering over the variables, with the cursor, will reveal their contents.

3. Create a new API Request in the collection called “Token” by selecting the collection, then clicking the three dots, and adding a request.

4. From within Token, select the body, and build out the request to match the following screenshot, and save the work:

5. The final, and optional step is to add the following code to the test tab and save it.

• NOTE: This java code will parse the response from the CMC and populate an environmental-level variable called “token” with the bearer token.

6. Send the API command. To ensure that everything is working as intended, the token can be seen by clicking the “piece of paper with the eye” icon, in the upper-right of the window:

Troubleshooting

What if the Token contents aren’t visible, or if a message comes back from the NDR CMC that is not 200 OK? Here are few troubleshooting tips:

1. Check the status of the request. There will be a code, 200 OK is ideal. That means that the API request that was created is working. Other codes show what is not correct about the request.

2. For testing purposes, or if making use of a CMC that uses a self-signed certificate, disable the verification.

3. Make use of the console for troubleshooting. The console shows the structure of the request body and response body. Expand those sections and examine the results to ensure that a proper request has been made, and to understand how the CMC is responding.

Now there is enough information to start building other requests of the CMC. To test our knowledge, create a simple request to get information about the sensors connected to the CMC. This information includes: ID, friendly device name (from the GUI) and the FQDN/IP Address.

1. Start by adding another request to the Collection. Call this request: “Get Sensors”.

2. Switch the request type from its default to GET.

3. Notice that Postman, auto-populates the authorization from the parent collection. In this case, it is using Bearer Token from the Bearer Token Collection. The JavaScript Test, auto-populates the Environment, not the Collection.

4. To fix this, click the Authorization tab, switch the Type to “Bearer Token”, and populate the Token value with {{token}}.

5. At this point you should be able to send a GET to the CMC and receive a report of the sensors connected to it. In the case of this lab, there is a single sensor connected to the queried CMC.

And finally, there should be two working requests in Postman. One to get a bearer token and another to get a list of the sensors attached to the CMC.

Here we’ve demonstrated how to craft a request to receive a bearer token, and how to use it as a means of authentication for future requests. In the next blog, we will use this knowledge, to build a BASH script to query the CMC, to determine if an IP address has been seen by any of the sensors.  Learn more about Network Detection & Response or contact us to learn more.