1689163890 Obtaining a bearer token to enable API interaction | cullen4congress

Obtaining a bearer token to enable API interaction

OpenText™ Network Detection & Response (NDR), formerly known as Bricata Network Detection & Response, provides real-time network visibility, metadata generation, and threat detection. Furthermore, it can be used as an effective tool for forensics and threat hunting. The NDR system uses three components: Central Management Center (CMC), data nodes, and sensors:

Central Management Center (CMC):

  • Single glass panel for security event viewing, investigation and analysis
  • alert panel
  • Centralized management of policies and systems
  • Threat hunting repository manager

Data nodes:

  • Threat Hunting Repository Data

Sensors:

  • Stateful and signature-based threat detection
  • IoC-enabled threat detection
  • Network metadata generation
  • Smart PCAP Capture

In this blog, we’ll highlight the capabilities of the NDR API by demonstrating how to create a request to receive a bearer token and how to use it 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 in the NDR CMC to be used for API calls. This example will use a local account called: “apiguy”.
  2. An updated version of google postman.
  3. Access to the NDR CMC.

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

API Reference

The API guide is integrated into the CMC GUI (CMC > Support > API Documentation). The following is the critical information needed to build a bearer token request.

The first important piece of information, located at the 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, immediately followed by a forward slash and the API: https:///api

The next step is to understand what is required from the API request. Scroll down through the API guide to the « auth » section and find the POST command that allows us to retrieve a bearer token.

Screenshot - Post command to retrieve a bearer token

According to the API guide, a POST request should be sent containing a json-formatted body, with username, password, and refresh token status to: https:///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 have created a collection called: “Bearer Token”.

  • NOTE: Postman Collections are collections of API commands that make use of a set of variables defined at the Collection level. This means that any variable created is available to all API commands within a collection.
Screenshot: bearer token

2. From within the bearer token collection, create two variables: « url » and « password ». Fill in the initial values ​​with the API URL for Bricata CMC and the API account password. Be sure to save the collection.

  • NOTE: From this point, the URL and password variables can be called by enclosing them in {} brackets. For example: {{url}}. Hovering over the variables will reveal their content.
Screenshot - Create two variables: URL and Password

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 Token, select the body and create the request to match the following screenshot and save your work:

Screenshot - save your work

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

Screenshot - Add code to test tab and save
  • NOTE: This Java code will parse the response from the CMC and populate an environment level variable called « token » with the bearer’s token.

6. Send the API command. To make sure everything works as expected, the token can be viewed by clicking on the « piece of paper with the eye » icon, at the top right of the window:

screenshot - viewing the token

Troubleshooting

What happens if the token content is not visible or if it returns a non-200 OK NDR CMC message? Here are some troubleshooting tips:

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

Screenshot: code 200

2. For testing purposes, or if you are using a CMC that uses a self-signed certificate, disable verification.

Screenshot - disable verification

3. Use the console to troubleshoot. The console displays the structure of the request body and the 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.

Screenshot - Expand and examine the results

There is now enough information to start building other CMC requests. 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 IP address/FQDN.

1. Start by adding another request to the Collection. Call this request: « Get Sensors ».

2. Change the request type from its default value to GET.

Screenshot - Change the type to GET

3. Notice that Postman automatically fills in the parent collection authorization. In this case, he is using the Bearer Token from the Bearer Token Collection. The JavaScript test automatically populates the environment, not the collection.

4. To fix this, click the Authorization tab, change the Type to « Bearer Token » and fill in the Token value with {{token}}.

Screenshot - Fill the token value with {{token}}

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

Screenshot - Sending a GET to the CMC

And finally, there should be two job applications at Postman. One to get a bearer token and one to get a list of sensors connected to the CMC.

Here we have demonstrated how to create 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’ll use this knowledge to create a BASH script to query the CMC to determine if any of the sensors have seen an IP address. learn more about Network detection and response either Contact Us Learn more.