In our previous blogs, I have described several Data Risk Analytics (DRA) integration use cases and how to configure and use the Syslog. In this final blog I discuss the DRA API and how it can be used.
The cool thing about APIs is that you can provide configuration and entry points to the DRA from other systems (as you have seen in the use cases examples) and the even cooler thing is that you can actually enhance your experience by adding extra functionality that currently doesn’t exist.
Let’s dive deeper into the subject.
API Security
DRA APIs use secure communications.
Client and DRA communicate via encrypted traffic using certificate trust (SSL). Requests coming from the clients are served only if they are from authorized users configured in customer Active Directory (AD) server. Each request must have valid credential per HTTP Basic Authentication method, as described in Figure 1.
The format of the basicAuth string the combined DRA API username:password encoded as base64.
For example:
Username: myUser, Password: myPass
Combination: myUser:myPass
Encoded as base64: bXlVc2VyOm15UGFzcw==
Method and API versions:
DRA API adheres to the RESTful format and uses the basic GET/SET/POST/DELETE methods.
There are several API version available. The latest and recommended version is v2.0 which is available since DRA v4.0. It is aligned with Imperva API recommended practices and enhances usability. Note that naming conventions and URL structure of v2.0 is different from previous versions. Although v1.0 and v1.2 are still backward compatible, new functionality might be added only to v2.0.
DRA API user configuration
DRA users are defined in the customers Active Directory by creating a special AD group and assigning users to it.
The default name for AD group is CounterBreach_Api, however it can be changed. From DRA v3.2 it can be done via the GUI, as described in the Active Directory Groups documentation. Prior to v3.2 it can be done via configuration file.
See example in Figure 2.
API Resources
API provides you with the the ability to get and modify most of resources in the DRA product. Resources are divided into 3 groups. In this blog I will use examples using API v2.0 but you can see previous versions of the API in the API Resources documentation.
Security Events
The security events API provides you with the ability to retrieve and update incidents and anomalies (not issues).
To retrieve all the information related to security events you will need to use more than 1 API call. The reason behind it is there is a lot of information available and we want to control the size of the response.
Using the API, you can close and open incidents, update a comment and “Star” and “Un-star” an incident.
For more details, look at Security Events documentation.
Permissions
The permission API provides you with the ability to retrieve and update users and role related information. You can associate IP addresses to individual users of different roles (i.e. Incident responders, Application Owners), you can also update the permissions of the different roles (i.e. which incident types are related to the Application Owners).
For more details, look at Permissions documentation.
Allow List Rules
The allow list rules API provides you with the ability to retrieve and update the allow lists, thus controlling which incidents shall be ignored.
For more details, look at Allow List Rules documentation.
Tips
Below is a list of tips I gathered when using the API.
- If you are just beginning to write tools using the DRA API, use API v2.0 even if it means to upgrade your current DRA version.
API v2.0 gives enhanced capabilities and it is possible that new APIs will only be added to v2.0.
Migration from v1.2 is possible but will require changing of parameter and API names.
- Prior to using an API, be sure to read the documentation including the error codes description. The error code description will provide you with exactly is the expected behavior including what is a valid and what is an invalid request.
- If there is something missing that you need, please open a feature request on the Imperva uservoice platform. Our product managers are waiting for this feedback as they want to expand the API capabilities for DRA.
To Summarize
DRA API can be used in order to integrate DRA with your existing environment, it also provides you with the ability to enhance the DRA capabilities with functionality that currently doesn’t exist. A good example is the open source tool dra-reporter (available in the Imperva github repository) which was implemented using the DRA API (v1.2) to provide a way to create a summary report for the operational and executive team. This tool was implemented before we have provided an integration point with our jSonar product. However it still shows how the DRA functionality can be externally extended quite easily when needed – the sky's the limit.
To Conclude this Blog Series
The DRA Syslog and API allow you to integrate DRA into your operations and business processes in a standard way. Imperva will continue to expand these capabilities in order to enhance these abilities. If you have use-cases that were not described please feel free to share them in the community or reach directly to me. As customers your inputs are the most important - you know best what you need.
Missed the other blogs in this series? Click below to view...
7 Key Use Cases for Data Risk Analytics (DRA) Integration with Syslog and API
Integrating DRA with Syslog - The Deep Dive!
Webinar: DRA Integration with API and Syslog (imperva.com)
#DataRiskAnalytics(formerlyCounterBreach)#AllImperva