Skip to main content

Please log into UltraDNS for full Help Center and Community access

Retrieving an UltraDNS Audit Log Report via REST API

Updated

Table of Contents

Setting up Postman

Authentication

Retrieving the Audit Log Report

Using cURL From the Command Line to Obtain Reports

Many customers have asked us how they can import UltraDNS activity into their Security Information and Event Management (SIEM) system, or event logging systems. Luckily, UltraDNS has robust API support for importing a multitude of Reports and Audit Logs.

Some of the more frequently used reports available via the UltraDNS REST API include:

• Projected Query Volume Report
• Zone Query Volume Report
• Host Query Volume Report
• Volume Change Report
• Audit Log Report 

 

This article will focus on how to retrieve an UltraDNS report, specifically the Audit Log Report, via our REST API.

We will be using Postman for this tutorial, as it is a common tool used to run API calls. Once you get the feel for how the API is used, you can easily script your SIEM to retrieve the audit log on a daily basis.

Setting up Postman

First, let’s get Postman.

  • According to www.postman.com, “Postman is a collaboration platform for API development. Postman's features simplify each step of building an API and streamline collaboration so you can create better APIs—faster.”

To download Postman, go to https://www.postman.com/downloads/.

  • You do not need to create an account to follow the steps outlined in this tutorial.

Once you have installed Postman, you need to add the UltraDNS Reporting Collection to Postman. The UltraDNS Collection for Postman is a series of pre-compiled API calls that make it easy for you to modify a couple of parameters, press a few buttons, and be able to retrieve the information you are requesting.

  • You can download the UltraDNS Reporting Collection from GitHub by using the following link: https://www.getpostman.com/collections/6ba215a1c608095d4e43. Depending on the browser being used, you may see a bunch of text on the screen, or a properly formatted JSON sample. Either way, save the page as a JSON file.

Next, let's import the Reporting API collection into Postman.

  • Click on Collections from the left-hand navigation pane, and then select Import at the top of the screen.

Import_Collection-1.png

 

Once you click Import, the Import menu will open.

 

Import_Collection-2.png

 

You can import the collection by dragging the JSON file into the window, or click the Upload Filles button and select the JSON file.

Once completed, you will see the UltraDNS Reporting Service APIs – Production collection has been imported, and you will see it in the Collections section of Postman.

 

Import_Collection-3.png

 

Running API Calls

Authentication

Before being able to run any of the Reporting API calls, you'll first need to retrieve an authentication token, which is required to gain access (permission) to the API service(s). Follow the below steps to run your first API call.

  • Expand/Open the UltraDNS Reporting Service APIs– Production collection (click the arrow to open the collection).

Click on the Reporter Get Token API call.

Import_Collection-4.png

 

In the section labeled Body (below the API method), provide your UltraDNS account Username and Password in the value column.

  • Note: So that you can track changes made specifically by the API account, you can create an API-only account in the UltraDNS Web UI or API and use those credentials here.

Import_Collection-5.png

 

After providing your Username and Password, click the Send button to perform the API call.

Import_Collection-6.png

 

The response will give you your Authentication Token (access_token below), which you will use for further API queries.

  • You can also see that this token is good for 3600 seconds (one hour). After this token expires, you will either need to get another token or use the Get Refresh Token call from the Collection.

Import_Collection-7.png

 

Through the magic of Postman, your access token is stored as a variable, so it can be used for any further API calls in the collection. The token is automatically sent with any API query in the collection so it is authenticated.

 

Retrieving the Audit Log Report

The UltraDNS Reporting collection has several queries available to retrieve UltraDNS Audit Log Report details, in two different formats.

  • CSV - A Comma-Separated Values (CSV) file is a delimited text file that uses commas to separate each of the values. Each line of the file is a data record.
  • JSON - A JavaScript Object Notation (JSON) file that stores simple data structures and objects.

Get Daily Audit Report JSON
Get Daily Audit Report CSV
Get Weekly Audit report JSON
Get Weekly Audit Report CSV
Get Date Range Audit Report JSON

To retrieve the previous Day’s Audit Log Report, all you need to do is select the Get Daily Audit Report call in the format you like (JSON or CSV) and click Send.


The Audit Log details are posted in the Response (Body) section. Additionally, the details can be saved to a file by clicking on the Save Response button.

Import_Collection-8.png

 


Similarly, you can retrieve the previous weeks’ Audit Log Report (for an account) by clicking on the Get Weekly Audit Report call.

  • Notice that when you do this, the filter in the Params tab is date_range:1w (1 week) instead of date_range:1d (1 day) for the Daily Report.

To retrieve the Audit Log for a specific date range, click on the Get Date Range Audit API Report call.

The following are examples of how to customize the date range for your report results.

  • To retrieve the Audit Log from March 1, 2021, at 00:00:00 GMT to March 30, 2021, at 00:00:00 GMT, change the filter parameter in the Params tab, using the format {date_range:startdate-enddate} where the start and end date are formatted as YYYYmmddhhmmss (Year, Month, Day, Hours, Minutes, Seconds).
    • i.e. 
      date_range: 20210301000000-202103030000000

By default, only 50 Audit Log entries are returned. This value can be increased, however, to a maximum of 250 entries by adding the Limit attribute to the call and specifying the desired value.

 

Import_Collection-9.png

 

Using cURL From the Command Line to Obtain Reports

cURL (curl) is a command-line tool for getting or sending data, including files using URL syntax. It is also a tool a SIEM might utilize to retrieve information from a REST API. The URL used in a REST API call can be seen to the left of the Send button that you have been using in Postman. Sending this URL in the command line using curl will allow you to obtain the same reports.

  • Note you will need to send the authorization header in your request, which would include your access_token to retrieve the report. For example, to retrieve the daily audit log, your curl syntax would look like this:
curl -X GET -H "Authorization: Bearer {access_token}” 
“https://reports.ultradns.com/v1/reports/dns_configuration/audit?filter=date_range:1d”
  • -H is the additional header to go along with the request. In this case, the Authorization Bearer access token, {access_token} = your access token.
  • -X GET is the get request for the audit log.

The curl request to retrieve a token would take the form:

curl --location --request POST 'https://api.ultradns.com/authorization/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'grant_type=password' \ 
--data-urlencode 'username=username' \ 
--data-urlencode 'password=password!'
  • The username and password are the credentials for your account.

We hope this helps you on your journey using the UltraDNS REST API. If you have any further questions, please feel free to contact Vercara Support at https://www.vercara.com/support.

 

Was this article helpful?
0 out of 1 found this helpful
Return to top

Related articles