Getting Started with Application Security APIs and CLI

by Eric Graham
In a world where web applications are continuously evolving and deploying at a breakneck pace, automating web application security is more important than ever.  That’s why we’re excited to share our Application Security API and corresponding Akamai CLI for Application Security for use in beta to help you automate your security. It’s easy to get started. What follows is a very brief introduction that’ll get you up and running in just a few minutes. Here are the steps we’ll cover:

  1. Establishing or updating your credentials
  2. Getting started with the Akamai CLI
  3. Setting up your credentials within the Akamai CLI
  4. Installing the appsec command
  5. A quick tip: making API responses more readable
  6. Wrapping up

1. Establishing or Updating Your Credentials

In order to use the Application Security API and appsec CLI command, you must have read-write permissions for the Application Security API as shown in the image below.  If this is your first time using Akamai APIs, detailed instructions on setting up your credentials can be found here.  

Once you’ve completed the process of either creating or updating your credentials to include this permission, you should have a local file containing rows like this:

For the purposes of this article, I have renamed that file “.edgerc” and moved it to my home directory.  You should see an output like this:With the proper permissions and credentials in place, you’re now ready to use the Akamai CLI  appsec command.

2. Getting Started with the Akamai CLI

For those who are new to to the Akamai CLI, there are lots of ways to get started!  For this article I will be using my favorite approach, the docker container akamai/cli.  This removes the environment-specific nuances, and is an easy way to have a working setup in minutes.

 The instructions below were generated using the dockerhub build from May 1, 2018. To get started, just download and run the container by entering the following in your terminal:

3. Setting up Your Credentials Within the Akamai CLI

Using the .edgerc file created earlier, we can pull them into the container using the --volume  or  -v  flag:

or on Windows:

4. Persistence with the Docker Container

If you run the container using docker run, your changes to the Akamai CLI install (e.g. package installs) will be ephemeral, and they won’t persist to future invocations.

To ensure that your changes are persistent, you have two options. The simplest is to store the Akamai CLI storage directory on the host machine, again using the -v  flag.

For example, if we create a directory called docker/volumes/akamai/cli in our home directory, we pass the flag:

Now, any packages installed, or configuration changes, will be stored on your local host.

Alternatively, you can use docker create , docker start , and docker exec  to create an ephemeral container, however, should Docker lose state, or the container image get deleted, you will lose all changes made inside the container:

You can also combine these two approaches, so that even if docker loses the state, or the image is deleted, or you want to update to a new version of the image, you can spin up a new container and attach the existing Akamai CLI storage directory again. In this case, you’ll add the additional -v  flag to docker create just like with docker run above.

Lastly, if you are using bash or zsh, you can wrap this into a single function that will transparently create/start/exec  as necessary, and expose the docker container as if it were a native command:

Note: we recommend you edit the docker create call to add the Akamai CLI storage directory as noted above.

4. Installing the Appsec Command

Now that you have an instance of the Akamai CLI docker running with appropriate credentials, we will install the appsec command to manage and modify your security configurations.

If you’re using the native binary, or the function above, you will run:

If you’re using the commands directly, assuming you have already run docker create/start, prefix all calls to “akamai” with “docker exec -it akamai-cli” like so:

5. A Quick Tip: Making API Responses More Readable

The Akamai team built the CLI so that it can be driven by common automation tools like Jenkins.  That means some of the responses are easily read by machines, but not necessarily humans. Here’s an example for configurations: we will send the command asking to list the available configs. The command looks like this:

What’s returned is a set of configuration ID’s.  This is a key parameter for other operations; however, as a human, it is not particularly helpful! How about some more information around what these configs are? To get this, I’ll include the flag: --json

This flag returns an object that has not just the ID’s, but also some names.  

However, that response is still not very human-friendly. This is where the quick tip comes in:  there’s a fantastic terminal utility called jq which will format the json responses to be easily readable by humans instead of just machines.

Going forward, we will be making extensive use of json objects to represent the configurations and the various actions you take around them, so I highly recommend you install the jq  utility.  The command to do so is straightforward:

With jq  installed, whenever you use the --json  flag pipe the output to jq!

6. Wrapping Up

That’s it, you should be up and running!  You can add hosts, modify match targets, reorder match targets, create and activate custom rules, pull information on configurations and policies, and more. Here are some of the commands available to you:

There’s much more to come as we ship additional Akamai API’s and corresponding CLI commands, as we try to meet more and more of the needs of customers like you.

Eric Graham is a senior product line director at Akamai Technologies.

Categories: CLI, Security, Technology

Suggested Article