Halo API Overview

Welcome to the CloudPassage Halo API overview.  In this post, we’ll walk you through an example use-case for the Halo API – implementing a blocklist of IPs from a text file into your firewall using API commands.

** NOTE ** Halo API has changed since this blog post was written – please see Halo API Developer Guide and Using the Halo API for details

This could be very powerful, for example, if you’re using a tool like Snort that can dump bad IPs into a text file. Documentation for the Halo API is available in the support section of the Halo Portal.  Access to the Halo API is available to NetSec and Pro customers — if you’re a basic customer and you’d like to play with the API and other paid features, click “Upgrade” on the top-right of your Halo Portal and sign up for a free trial upgrade.

To get started with our example, create or or edit firewall policy – you’ll need to create a firewall rule with a blocklist zone within the target firewall policy in the Halo GUI – this is the rule you’ll be updating with the API in our example.  Click the “green plus” to create a new inbound rule, click Source and select “Add New” under IP zones in the drop-down menu.  Name the zone “Blocklist” for this example.  You’ll need to add at least one IP to the list, as you can’t save a zone without any IP addresses.

Make this a “DROP” rule, to drop the connections from the banned IPs you’ll be updating here later. Make sure to save the policy changes.

You can see the IP Zone called Blocklist that you just created by clicking IPZones on this page.  You can see here that the Blocklist IP Zone contains the IP address you just added through the GUI.  This is what we’re going to change with the API.

Now, for your text file of banned IPs.  Upload a text file to my system earlier containing the ips you want to add to the fw’s blocked zone.

Now, before we do anything with the API, you’ll need to upload the api library (api-lib) and the api library install script (install-api-lib). For this example, you’ll also want to load in the script we’ve written to update your Blocklist zone ( (We have included the scripts as doc files here so you can inspect them and make them executable on your own)





If you haven’t already made these scripts executable, don’t forget to do so.

chmod 755 install-api-lib api-lib

Run install script:


You’ll be prompted to enter your API key — you can find this in your Halo Portal, under Settings > Site Administration > API key.

So now that you’ve finished the installation of the API library, have a firewall rule in place, and your blocklist set, let’s load the api library into memory. You’ll have to run this command once in every shell script or terminal in which we’ll be working with an API.

. /usr/local/bin/api-lib

Then, type this command to set the destination of your code.

resty ‘*’

Test your API connection by checking the IP Zone you had set up earlier by typing

GetZoneDetails Blocklist

referring to the name of the zone you created in portal.  This will return JSON info. Look for the one IP added to the zone through the GUI.  The command is retrieving information about the IP Zone “Blocklist” that was created via the GUI at the beginning of this video.

Update the IP Zone “Blocklist” with the list of IP’s located in “blocklist.txt” with the script available in this blog post (  Note: you may need to change it slightly, to include the full path to your blocklist file. Again, make sure that the zone name in the script, Blocklist, is the same as the zone you had created in your Halo Portal.


Now after this command, you can check back in on your Halo Portal – the IP Zone has been updated with the IPs from the blocklist file. These IP addresses will be blocked from accessing the servers that are protected by this firewall policy.  If you make any changes to the blocklist file, or another security tool dumps IPs into the blocklist file, just run the update script and those changes will be pushed to your firewall policy in portal.

Stay up to date

Get the latest news and tips on protecting critical business assets.

Related Posts