Adding GhostPorts-enabled rules via the API to your firewall policy

Being able to access GhostPorts’ functionality via an API is a very powerful feature of CloudPassage Halo and one that provides users the capability to easily integrate GhostPorts with other applications in their software ecosystem. For example, you can leverage the API to add two-factor authentication for your CloudPassage Halo firewall while using your existing authentication systems.

This article shows how to add a GhostPorts-enabled rule to a firewall policy via the CloudPassage API.

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

Adding a GhostPorts-enabled rule to your firewall policy will allow you to temporarily open up ports on your system that you would want closed at all other times. Also, while those ports are open, only you will be allowed access to them while they will appear closed to everyone else.


The following are pre-requisites for any user to add GhostPorts-enabled firewall rules using CloudPassage’s API functions:

1. Have GhostPorts access to your CloudPassage account enabled. For details on how to enable GhostPorts access, GhostPorts User Guide.

2. Have a Halo Professional subscription with CloudPassage. If you are a Halo Basic user, log into the Halo portal and click the Upgrade link at the top right of your screen.

If you are new to API’s, I would also recommend reading through the Halo API documentation.

Steps to add a GhostPorts-enabled firewall rule:

– You first have to retrieve the firewall policy to which you want to add a GhostPorts-enabled firewall rule. To do so, make an API call using GET on the firewall_policies API endpoint. The call will look something like this:


curl -H "x-cpauth-access:your_api_key"”


– Above API call will generate a response such as:


"firewall_policies": [
           "description": "",
           "id": "9fc7fcf00ccb012fc8d4404096c01709",
           "name": "firewall_policy_to_update",
           "url": "",
           "used_by": []

– From the JSON response object above, locate the firewall policy with “name: firewall_policy_to_update” and extract the “id:” value of the firewall policy

– Create a JSON object (shown below) for adding the new GhostPorts-enabled firewall rule:


        "chain": "INPUT",

        "active": "true",


            "type": "User",
            "username": "your_username",
            "id": "9fc7fcf00ccb012fc8d4404096c01709"

"firewall_service": "7b6355c072b1012ec681404096c01709",

"connection_states": "NEW, ESTABLISHED",

"action": "ACCEPT",

"log": "false",

"position": "1"



Note: “firewall_service”: “7b6355c072b1012ec681404096c01709”  above is an internally generated ID that corresponds to a protocol such as SSH, SMTP, HTTP, etc. Including it in the JSON object above tells the system which protocol packets to allow through for this rule.

– Update the firewall policy with this new rule by invoking the POST method on the firewall_rules API endpoint. The API call will look something like this:

curl -H "x-cpauth-access:your_api_key"

(with the JSON object you created in the body of the POST request)

– Successful rule creation will result in an HTTP response header with status code of 201 and a location URI of the newly created rule:

Status Code: 201


You can test to see if the sequence of API calls above indeed lead to a GhostPorts-enabled firewall rule being successfully added to the firewall policy. To verify, you will need to make another API call and provide the “id” of the firewall policy you added the new rule to. It will be a GET call and will look something like this:

curl -H "x-cpauth-access:your_api_key"

The resulting JSON output will contain the new GhostPort-enabled rule you added.

Alternatively, you can login to the Halo Portal and navigate to Policies > Firewall Polcies > Your Firewall Policy. There you will be able to find the newly added rule.

Note: Reading JSON outputs can be very difficult without the use of a JSON formatting program. There are many available but the one I use is a Python program called json.tool. To make the JSON output more readable, I simply pipe the response to an API call to json.tool like this:

curl -H "x-cpauth-access:your_api_key" | python -m json.tool

Stay up to date

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

Related Posts