Introduction
In late 2020 – The IBM Team released Universal Cloud RestAPI Protocol. I wanted to take the opportunity to: (1) refresh the community’s understanding of the Universal Cloud RestAPI Protocol; and (2) share some best practices and tips from the experts. In preparation for this post, I interviewed our QRadar Integrations Product Owner, Michael Richards and our Protocol Team Lead Dane Frenette on their experiences developing integration with the Universal Cloud Connector. Big THANKS to Mike and Dane for their time and I hope our readers find their suggestions and best practices insightful!
The Universal Cloud RestAPI Protocol (UCRP)
The Universal Cloud Rest API Protocol is a generic protocol designed to enable security teams to ingest data more easily from a wide range of cloud-based REST API applications and services into QRadar for enhanced visibility. The goal of this development effort was to give teams the flexibility to build integrations that QRadar does not support (IBM will continue to develop and maintain integrations for QRadar).
Leveraging the UCRP requires customization of two documents: (1) Workflow XML; and (2) Workflow Parameter XML. The Workflow document defines how the protocol collects events from the desired data source’s target API. The Parameter document contains the parameter values used directly by the Workflow.
Working with the Universal Cloud RestAPI Protocol
See below for tips, tricks, and color commentary from our experts about working with the URest.
Getting Prepared - Best Practices from the Experts
When working with the Universal Cloud RestAPI Protocol, Mike Richards starts by reading the third party documentation and understanding exactly how to interact with the product. Next, Mike suggests reading our IBM documentation which includes documentation and examples of each of the building blocks that will be used in the “Actions” section of the workflow. Please see the Resources Section below for a link to our documentation. Additionally, Mike suggests taking a look at some of the sample workflows available on our GitHub to familiarize yourself with them. The workflows all have similar structure, so understanding the sections will be very helpful [1].
Once you have familiarized yourself with the documentation, Mike suggests outlining your workflow and planning which actions you’d like the script to execute. Your planning should include explicitly deciding which URLS you’d like to hit of the third-party product. Having a clear plan as you begin to write your script will be helpful! As a best practice, Mike recommends leaving XML style comments in your workflow to make it clear exactly what actions are being taken and why. There are several examples in the workflows posted on our GitHub Repo [2]. Good commenting practices should be used. For example, the code should attempt to speak for itself with good variable names and follow a logical flow. Comments should be used where the code may be perceived as hard to read or cannot be written in a way that makes it obvious what is happening. This practice will help you later and will also help your teammates in your absence.
Workflow Structure Overview: Thoughts from the Expert
All workflows follow the same structure, therefore they all have the same top, middle, and bottom. At the very top of the workflow is the header and it is needed for verification in the QRadar UI. Without the header, QRadar would not know that this was a workflow. The header includes details like the doc type, encoding, workflow entity (you can name it whatever is helpful to your organization), and set a name space. Next is the parameter section. This section links the workflow to the “Workflow Parameter Xml” and this is what enables QRadar to connect to the specific instance of your third party tool and pull data from it.
Your “Parameters XML” is a separate script that includes credentials or other settable values that your workflow will pass to the third party tool. Following is the “Action” section which tells what processes to follow every time you loop and is where the bulk of workflow is.
Building your Workflow: Best Practices from the Experts
With your plan in hand you’re now ready to start crafting your workflow.
Parameter Section
It is important to note that if you create a “Secret Parameter” around the Parameter Section of your workflow and set it to “true”, QRadar will then obfuscate the parameters in the logging and anywhere those values might be output. This means that QRadar will jumble characters in the debug, information, and error logging so that when the workflow is executed on a system or in testing, the logs do not contain sensitive information.
Mike recommends that any sensitive values be included in the Parameter XML and NOT the Workflow XML for security reasons. Additionally, any values specific to a given customer’s tenancy should be stored in the Parameter XML and called in the Parameter Section of the Workflow, for example like the URL. Where it can be helped, hardcoding static values into the workflow is not recommended. See image below for an example of a Parameter XML, where value specific to your organization should be stored.
Action Section – Authenticate
The Action section tells what processes to follow every time you loop. When planning your action section, Mike suggests asking the following questions: (1) “Do we need to authenticate first?”; and (2) “How does the service require authentication be completed?”
Often the first action of the script will be to pull a token from an endpoint. That token will subsequently be used in the header of other pulls from another API endpoint to actually pull the data down. Mike mentioned that it is important to note that these tokens “can have a time to live (TTL)” and will expire after a set amount of time. For example, if your token has a five minute life span, you need to add some handling logic to your flow that will automatically request another token after five minutes. For example, the logic flow could be to: (1) catch a failed request, (2) check the reason, and (3) and try again after requesting a new token, if the reason for failure is because the token expired.
Authentication endpoints usually require a username / password, or some previously provided key to grant a token to the calling script. This is where a username / password would be entered. Once the token is granted, you generally just use the token for retrieving data in subsequent API calls.
Action Section – Initialize
After we authenticate the next step is to initialize any variables we will need to iteratively pull data down from the API, such as a bookmark timestamp value. Mike describes initializing as “essentially just getting everything ready to run”. The Initialize section is executed in the same pattern with every query and loop. Initializing requires writing key values to our file that will only execute if a particular value is not already present (has not already been written to the file).
For example, if the initialization requires writing to a file, it will only write to the file the first time. Meaning if we already have a value from a previous loop it does not initialize again. Mike suggests paying special attention to the difference between “initializing” and “setting” in the docs.
Action Section - Retrieval Stage
After we initialize we move into the retrievals stage. Retrieval is the most contextual, so that is where the bulk of the vendor specific logic will be written. This is where Mike finds that it pays to have read the documentation and understand their expected access flow and then using it. During this stage we loop through a set of commands and those are guided by conditions. These commands are generally within a while loop that states something like “While the api call contains events”, or if you choose to set a “shouldContinue” type variable in your loop, you can use that as your condition. See examples for workflow retrieval while loops.
Once one iteration of the while retrieval loop is completed – but before we check the loop condition – we want to set any variables required to get the next section of a data set. Oftentimes there will be a new query link to call that is provided in the previous response, or a marker value telling you what to modify in your original query in order to use. This implementation varies widely across vendors and API specific documentation is required to run this. It is important to have a condition that tells it to continue to loop. and then set it as the next query to execute. Mike suggests using the curl command on a CLI session to: (1) ensure you are hitting the right point without issues; (2) get a sample entity to see the layout; and (3) work out how you want to implement your loop.
Action Section - Retrieval and Timestamps
In the Retrieval Section an API might send QRadar “timestamp” data. The data provided from the API is based on the format the third-party tool uses to send the data. Once the data is retrieved, we have to update bookmarks and therefore we need to increment the “from” value by the smallest value possible in order to minimize the amount of data loss. Bookmarks indicate which data has already been collected by QRadar and it is critical that this is done properly.
For example: when we query an API we ask for data “From” a time, “To” a time (to is usually current time). An API might want “YYYY-MM-DD HHMMss ssss” as their time stamp format (as an example). However, we can’t always easily increment that by 1 millisecond. So the Universal Cloud RestAPI Protocol has access to Java time formatting capabilities, so that we can easily turn that into a single epoch integer value. The process would then be as follows.
- Get timestamp as 6/30/2021 6:43:30
- Convert to epoch (1625078610)
- Increment by 1 to use as new “From” and not miss data (1625078611)
- When we call the API, we convert it back to format in 1
Please note - this process is also highly dependent on the resolution the API uses. For example, if the API only goes down to the second level, we need to make sure we increment at the lowest level that the vendor can actually differentiate on, otherwise we may see data duplication. Mike has shared that this is section where users often have problems; this is where something might go wrong. Mike wanted to emphasize the following side note: it is crucial that the time- stamps are accurate in QRadar. We can’t have overlaps in time. For example, duplicate logs might break a threshold rule.
Action Section - Error Handling
When your workflow tries to retrieve data, if something goes wrong, you may receive a status code and not the data queried for. Therefore, workflows need to include logic around what to do if they receive a status code. Depending on the error handling logic, if a status code is returned – it could stop the workflow and then the error code would be provided to QRadar UI and would be visible in the log source manager. However, status codes may or may not indicate an actual error. Therefore, handling logic is needed to decide if the workflow should abort or not abort based on the status code received and particular use case.
For example, you might want to include logic to abort your actions if your endpoint returns a 400 status code (not found), because generally this means the endpoint isn’t found and that would be a good reason to abort. But maybe you don’t get a 400 but you get a 204 (No Content), you may just want to be aware of it but not cancel it because you might want to keep on querying when there is no data, because there might be some in the next poll. In addition to aborting your workflow as a means of error handling other options to consider might be: error logging, posting a status update, or creating your own logging. All of these methods are outlined in the Actions section of the documentation.
Testing
We’re almost done! Just one more step! Thanks for staying with me! The final step of the workflow is to do some connectivity tests. Some examples include: (1) DNS Resolution; (2) TCP Connection; and (3) HTTP ConnectionThroughProxy. Additionally there is a built-in Event Retrieval test. The results of these tests will be displayed in the Log Source Management App. See image below for an example of tests used in a Workflow.
Pro Tip!
The other big thing that has saved our team is our Command Line Testing Tool (here). The Tool will execute your workflow and provides feedback while you develop and troubleshoot contents of your workflow. Please note that the tool does not interact with the live QRadar Event Pipeline but rather writes to the console. The test will show you the results of your query and is very helpful for troubleshooting the contents of your workflow. Mike points out that when developing you want to use the “-v” command specifically (verbose), as it outputs all of the debugging information that really helps like this: “/opt/qradar/bin/test-workflow.sh -w myworkflow.xml -wp myworkflow.parameter.values.xml -v”.
Conclusion:
Hope you found this helpful! I hope you give the Universal Cloud RestAPI Protocol a try and post your workflows to our GitHub. Will you check out the Universal Rest? If so let me know. Feedback? Email me.
Resources:
- IBM Security QRadar Universal Cloud REST API Documentation
- IBM Security QRadar Universal Cloud REST API GitHub Repository
- IBM Security QRadar Analyst Workflow
- IBM Security QRadar Log Source Management App
- IBM Security QRadar DSM Editor
- Jose Bravo Tutorials:
Universal Cloud REST API Protocol Part One
Universal Cloud REST API Protocol Part Two