Automate Security

Getting Started with Application Security APIs and CLI

May 2, 2018 · 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:

[default] host = client_token = akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx client_secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx access_token = akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx

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:

$ docker run -it akamai/cli:1.0 help

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:

$ docker run -ti -v $HOME/.edgerc:/root/.edgerc akamai/cli:1.0 help

or on Windows:

> docker run -ti -v %Homedrive%%Homepath%/.edgerc:/root/.edgerc akamai/cli:1.0 help

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:

-v $HOME/docker/volumes/akamai/cli:/cli

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:

$ docker create -it -v $HOME/.edgerc:/root/.edgerc --name akamai-cli akamai/cli:1.0
$ docker start akamai-
$ docker exec -it akamai-cli akamai help

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:

function akamai { 
    if [[ `docker ps | grep akamai-cli$ | wc -l` -eq 1 ]]; then 
        docker exec -it akamai-cli akamai $@;
    elif docker start akamai-cli > /dev/null 2>&1 && sleep 3 && docker exec -it akamai-cli akamai $@; then 
        return 0; 
        echo "Creating new docker container"
        docker create -it -v $HOME/.edgerc:/root/.edgerc -v $HOME/docker/volumes/akamai/cli:/cli --name akamai-cli akamai/cli > /dev/null 2>&1
&& akamai $@;

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:

$ akamai install appsec

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:

$ docker exec -it akamai-cli akamai install appsec


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.