BashPlus for Incapsula - monstruooo/bashplus GitHub Wiki

Summary:

• Getting started with the bash+ Incapsula extension
• Introduction into bash+ for Incapsula by example
• Listing Incapsula sites, accounts and configuration
• Printing original configuration json
• Notes on incap updatedb
• Making API requests with incap api
• Additional Commands

You start by sourcing the file common.functions. This will source all other files that contain bash+ functions

Once you have the functions in your shell and you run the command incap for the first time, you will be prompted for credentials. These are saved as variables inside your shell until you leave the current session

Finally, you download your Incapsula configuration by running command incap updatedb

incap updatedb will be explained in more detail later in one of the next sections Once the Incapsula configuration downloaded, you can list all your sites by running incap ls sites

You can filter the list using grep.

There is no site whose name or origin includes oskar at this point.

Next, lets create a new Incapsula site using command incap site mk

This time when we filter incap ls sites with grep, the new site shows up

This is a real world case of the Incapsula extension of bash+ in action.

The request came to disable TCP-pre-pooling on all sites under a certain Incapsula account (Incapsula account is a group of sites).

So you go to Incapsula online API Doc Manual and find relevant instructions

Basically, to disable pre pooling you need to send a POST request to https://my.incapsula.com/api/prov/v1/sites/performance/advanced

Your request should look like this:

api_id=<Your API id>&api_key=<Your API key>&site_id=<Your site id>&param=tcp_pre_pooling&value=false

To run such a request you use command incap api. The command simplifies your task. You only need to copy relevant arguments from the API Manual. Your command would look like this:

incap api “site_id=<Your site id>&param=tcp_pre_pooling&value=false” /api/prov/v1/sites/performance/advanced

The only parameter missing with this command is the site id. In the next page you will find the ids of all sites of that account

You can list your sites and their configuration using command incap ls. For this example, you run incap ls accounts to receive the list of your accounts

Next, you run incap ls accounts <account id> and receive the list of all sites under that account

To save all site ids into the variable , you run:

ids=$( incap ls accounts <account id> | egrep -o ^[0-9]+)

And finally you run the entire command as:

for id in $ids ; do 
    incap api  “site_id=${id}&param=tcp_pre_pooling&value=false”  /api/prov/v1/sites/performance/advanced
done

At the top level bash+ for Incapsula displays 4 pseudo directories: accounts, sites, origins and cache

You have already seen how to work with sites and accounts by now. One additional command is incap ls sites <site id> prints a summary of the site configuration

Origins work on the same principle as accounts. There is a list of all origins your sites point to.

You can also print all sites that point to a certain IP or hostname. This is useful when you need to get the ids of all sites that should be migrated from one data center to another

incap ls origins <origin>

incap ls origins is not only easier to work with. incap ls sites/accounts truncates long hostnames to keep the output in a table. incap ls origins <origin ip/hostname> will output exactly the sites you need with no place for errors

You can print the original json of Incapsula configuration using incap cat command incap cat accounts will print the json of all your accounts

incap cat sites will print jsons of all files. Not showing here

incap cat sites <site id/domain> will print the json of that site

incap cat sites <site id/domain> print configuration stored locally. If you want to be 100% sure that you are not missing any changes, for example done by other people thru Incapsula web site, use incap site status <site id>. This command will download the latest configuration of the site from Incapsula API

Incapsula identifies all sites by their ids and not by their names. At the moment, Incapsula API doesn’t have a command that can query the site id by the site’s name. Instead, you should download the entire configuration of all your sites to be able to map names to ids.

Even if such a command existed, there are still advantages to have your Incapsula configuration locally cached because this allows you to search your sites by their account or origin IP, like in the examples above, or any other parameter.

It’s a good practice to sync your Incapsula configuration every once in a while. However, bash+ generally keeps your local cache updated with the following tricks.

First of all, when you create or modify a site, Incapsula API returns the updated configuration in a json format. incap api automatically detects if the response contains the site configuration and updates your cache.

Two, when you delete a site using command incap site rm <site id>, the site is deleted from your local cache as well. Below is a few examples:

You have already seen that incap api is evoked as incap api <post data> <url/uri> It’s important to keep in mind that incap api doesn’t print output on success. It only prints error messages when requests fail.

If you do need access to the output of the request, it’s stored in a special reserved variable called res. In the example below we access this variable to read the TXT record for ssl validation.

Another variable res_code saves the exit code of the last incap api call. res_code can have the following values:

• 0 - Success
• 1 - API returned error
• 2 - Request failed and the error message received is not json. Most likely you misspelled the url and the response is an html page
• 10+ - Error codes of curl program which bash+ uses for requests. They are calculated by adding 10 to the original exit code of curl

On errors incap api prints res_code, the history list of the last 10 functions including the last request and the arguments of the last request

bash+ also provides some auxiliary functions, such as json2bash for reformatting json in case you may find it more comfortable to work with json