Are you lazy? Do you like getting more done with less effort and preventing attacks on your websites? Then read on, this article is for you! We have a great technical tip or three about the Barracuda WAF-as-a-Service REST API. I know what you’re thinking, but, believe me, this actually is for you. This is not a whitepaper. This is not a technical manual. This is not a treatise on cutting-edge cloud automation, and it doesn’t have to be. In other words, no average WAF users were hurt in the making of this blog. As in most of what I teach, my mantra continues to be: You don’t have to be an expert!
Barracuda WAF-as-a-Service provides cloud-delivered, enterprise-grade application security without the administrative overhead of a hardware or virtual appliance. Using WAF-as-a-Service, you can secure your applications within minutes, regardless of where they are hosted. There is no infrastructure to deploy, scale, size, or maintain. And while you can click and type in our slick, modern REACT GUI, WAF-as-a-Service also has a great REST API so that you can automate your tasks.
Application Programming Interfaces (APIs for short) empower our world by enabling us to write applications to automatically exchange data and actions with other applications. These programs talk to other programs and can configure settings, observe and measure data, and act and react accordingly. These programs can be as simple as a few lines of bash script or as complex as a fully operational production application.
APIs make our lives easier because with them we can accomplish tasks of all sizes in a highly repeatable and reliable way. APIs will perform these tasks repeatedly, thousands of times, in exactly the same way each time. Without APIs, we would need to manually perform the same task, repeatedly, without any mistakes, and do it at lightning speed. And no matter how friendly our graphical user interface may be, this manual approach is not going to match the speed and accuracy of an API approach anytime soon.
APIs are also very common in our world of networking and security and clouds. Across our recent State of Application Security in 2021 survey, respondents told us they have an average of 33 public-facing APIs, which I find to be a low number but that’s understandable seeing as there are unknown APIs in many organizations.
While protecting APIs is critical because an unprotected API is even more of a risk than an unprotected website, today we are talking about using APIs to configure and manage WAF-as-a-Service. We are going to be focused on the Representational State Transfer (REST) type of API, known as a REST API for short. Here’s how a REST API works:
- A client application initiates an API call to retrieve some information — this is known as a request.
- This request happens over HTTPS and includes a request verb, headers, and sometimes a request body.
- The server receives the request and sends an HTTPS response with the requested information.
- The client application receives the API response and now has the information it requested.
REST APIs are constructed around specifying actions using HTTP methods such as POST, GET, PUT, and DELETE on largely similar Routes. (A “Route” in terms of web APIs is the path to an API endpoint, which is for all intents and purposes very similar to a URL if you are familiar with those.) These APIs allow us to create, retrieve, update, or delete elements of a given service, without having to make a unique URL for each action.
For example, let us say we are managing a pet grooming and healthcare tracking database for a nationwide pet service company. There are tens of thousands of pets in this database.
We have created a REST API for our pet database, so that our developer team writing the web front-end can interact with our database. It is important to accurately track a pet’s medical history, so each pet is given a unique identity number that never changes. We use this unique number rather than the name of the pet because the name may change at some point in the future.
Pets also have nicknames, so given the pet identifier 10369, we might have the following sample REST API transactions to perform some simple tasks to do with nicknames.
|Desired Action||HTTP Method ( and data, if any )||API Route ( basically, a URL )|
|Retrieve the list of nicknames for pet id 10639||GET||/api/2.2/pets/10639/nicknames|
|Add the new nickname “snuffles” to the list of nicknames for pet 10639
|Modify the nickname “snuffles” to “couchslayer”
|Delete the nickname “couchslayer”||DELETE||/api/2.2/pets/10639/nicknames/couchslayer|
What makes this a REST API example is the URL (or “Route”) stays basically the same, just the HTTP method changes depending on what we want to accomplish. We don’t need a different URL (or “Route”) for every action ( get, add, modify, delete ). Instead, we keep the URL basically the same and just change the HTTP Method.
Unlike older API technologies on the web such as XML and SOAP, REST APIs are a modern technology for API development, along with a couple of others I’d like to call out: graphQL and gRPC.
Together these make the “Big Three” for modern API development. Out of these three, REST APIs are by far the most popular. According to the RapidAPI 2019-2020 API Survey , 70.9% of respondents have REST APIs either in production or in a Proof of Concept (POC), compared with only 12.4% for graphQL and only 7.3% for gRPC.
So, having introduced REST APIs quite thoroughly, let’s very briefly introduce Barracuda WAF-as-a-Service.
Barracuda WAF-as-a-Services (WAFaaS) is a full-featured, cloud-delivered application security service that is available through Barracuda and incuded in the Azure Marketplace and AWS Marketplace.
REST API, meet WAF-as-a-Service!
The Barracuda WAF-as-a-Service central REST API starting route is https://api.waas.barracudanetworks.com/
In this article, we are taking a “low code” approach, so you don’t have to be a developer or even a scripter to start using the tips here. We are also going to use the “Crawl, Walk, Run” approach, which is how I like to teach. So, in order, we are first going to use Swagger (the “Crawl”), which is actually a web page, GUI-driven approach, and then we are also going to be using some cURL (the “Walk”) and finally a little Python (the “Run” although it’s more of a jog than a sprint).
Let’s talk about API versions and their appearance in routes. It is not unusual for REST API routes to include a version. For both the cURL and Python approaches, they are going to be using the “v2” version of our API, so their starting route will be https://api.waas.barracudanetworks.com/v2/
We are also going to be using the Swagger interface, which is a web page where we can play around with the API and make some API calls in a GUI fashion. (Yes, I know that’s a bit of a contradiction, but bear with me, it will all make sense in the end.) Swagger does not use the /v2, making the full URL https://api.waas.barracudanetworks.com/.
Swagger is an open source framework that supports automated documentation, code generation, and test-case generation.
The Swagger URL is https://api.waas.barracudanetworks.com/swagger/#/, and you can visit this in your browser.
The first step is to login to use the WAF-as-a-Service using the API Login and Authorize. After you authorize, you can use all the API commands.
Click on login, click Try it Out, and then enter your username and password and click Execute.
Note: Your credentials are protected by SSL but shown in cleartext, so it is very strongly advised to hide your screen, for example, if you are screen sharing. In other words, don’t make a Zoom blunder at this critical juncture!
After you have logged in, scroll down until you see the Response Body, and then select and copy the entire key as shown, everything between the colon and the final quote.
For example, as shown below in yellow highlight, if the key is “AAAAasdlfkjasdlfkjasdflkjasdflkj..asdflkjZZZZ” you will select and copy everything between “auth-api: “ and “-d” (without the quotes). So, you will be copying from the first A all the way to the last Z, with no quotes:
curl -X POST "https://api.waas.barracudanetworks.com/v2/waasapi/api_login/" -H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -H "auth-api:
" -d "email=brett%40wolmarans.com&password=REDACTED"
When you copy, you can use the mouse to highlight and copy, or use ctrl-C, whatever you normally use to copy text — use what works best for you!
Now, with your API Key (also known as “Token”) safely and securely chilling on your clipboard, go ahead and in the top-right corner click Authorize as shown here:
It goes without saying, but I will say it anyway: Do not click the logout button. No matter how tempted you are to do so! Just carefully click Close.
If all went well, you will now see a small icon of a padlock on the right-hand side of your Swagger interface as shown here. The padlock is locked, which (somewhat unintuitively) means you are logged in.
Click on Applications, and then click Try it out. Click Execute
You will see a result with the number of applications, the application ID, and the endpoint ID.
In this example, there are two applications, but only the first is shown in this screenshot.
You can see the application ID for the first application, and the endpoint ID.
You can also see the Server Response code is a 200 — that's very important — the 200 shows you the command worked with no typos!
Voila, you’ve done it! It’s just that easy! For more info on Swagger visit https://swagger.io/. Up next, let’s get up off the floor and start to walk a little bit by examining how to use cURL to perform some REST API actions.
A word on application IDs
Above you can see the Application ID is 11818 for my application. Each of your applications is identified by a unique Application ID, and you are going to need this to build your Routes for your API calls. So, you’re going to see Application ID all over the place as we proceed with more examples.
A word on copy & pasting from Swagger’s cURL examples
Swagger provides you with great cURL examples when you run commands. You can copy and paste these to use in your cURL actions — it makes life easy! For example, if I wanted to do something relatively common such as change an application from “Passive” mode (where it logs attacks but does not block them) to “Active” mode (where attacks will be blocked) I could first do this in Swagger by scrolling down to the “basic security” as shown here. The arrows show where I typed in my application id and where I typed in “Active”.
Now, you can simply copy and paste this, with no changes or typing, and the effect is as follows (the arrows show the id and Active protection mode). No fingernails were chipped in the making of this example — just some right-mouse click action!
On our API journey, we have learned to Crawl with Swagger. Now we shall learn to Walk using cURL!
cURL (client URL) is another method for quick-and-dirty API calls. It supports a variety of protocols and can be used on just about any platform on any hardware that exists today. It is not recommended for production automation but can be more automated than using Swagger through the web browser.
When using cURL, you will have to use the login key token every time, as we want to authorize those calls.
You may wish to use a little utility script to set your login key token as an environment variable. Here is one I cooked up a while back, and it can be obtained from here:
And here is an example of using this login utility script to login. Now, you probably have noticed by now that the way this little utility script is written, the login credentials are being passed in cleartext on the bash command line, and it goes without saying that doing so is a very long way from being a best practice, and while there are some good ways to securely pass credentials to bash scripts, by design none of those are being used here.
So, don’t share your Zoom screen while you are doing this first log in, is what we’re saying!
So, with that significant caveat, once you have logged in, and your WAAS_API_KEY environment variable is set, you can make API calls via cURL without ever having to pass those nasty login credentials, the token takes care of this for you.
Now, with a bit of screen scrolling, you can actually show your Zoom screen with impunity as you happily show off to your colleagues all manner of cURL commands to make your WAFaaS sing and dance, as shown here, without ever revealing your login credentials.
Example of getting all the details of all the applications in your WAFaaS account:
If you don’t want to see all the gory details, you can quickly view the names and id numbers of your applications without getting too fancy. We’re not going for any world speed or efficiency records here, nor are we trying to win a challenge on https://www.topcoder.com/. We’re just trying to illustrate a point, and that point is: this is easy!
Remember how important those application IDs were? That shows you how to get them. This is important because let’s say you wanted to change an application from ”Active” to ”Passive”, you can do so with cURL, but you are going to need the id (not the name) as shown here:
And remember, as everyone who knows me can attest to, I’m lazy and don’t like typing. So, I didn’t laboriously manually type in those long-winded cURL commands — I copied and pasted from the Swagger web GUI, which we covered up above in the “Crawl” section. Very important.
Python is a very popular programming language and the recommended approach for automation. It is up next in our “Crawl, Walk, Run” continuum.
Here is an example of a simple Python script to log in and list the applications. This script can be obtained here:
Running this script as an example shows us something similar to what we obtained using cURL, where we see a list of our applications:
Wrapping it up
In conclusion, not to put too fine a point on it, we have a full-featured REST API for Barracuda WAF-as-a-Service. The API allows you to do the kinds of things that are important building blocks of automation and DevOps, not least of which is performing a task the same way many times over, using types of programmatic interfaces.
We’ve seen three ways to get started with the API, using a “Crawl, Walk, Run” approach. We started very simply using the Swagger interface, progressing to using some cURL commands, and finally taking a look at how to use the API in Python.
But (you may ask) how does this all come together in a full application CI/CD pipeline? I like jogging, but I want to sprint! Can we get some examples of how to build a pipeline that lets us deploy our WAF-as-a-Service configuration using the same DevOps patterns we use to deploy our applications? Well, for the answer to that question and more, we will be taking API topics to the next level in another blog post in the not-too-distant future, so please stay tuned!
And, please, if you have any questions on this basic introduction to our REST API, or if you find any bugs in my examples, don’t hesitate to reach out to me, Brett Wolmarans, at email@example.com