Digging Deeper into the Cisco ASA Firewall REST API

How-to primer for the Cisco ASA API

Security orchestration methods, and of course SDN, are driving the need for programmable interfaces in  security products. The Cisco ASA Firewall added a REST API back in December with the 9.3(2) code release. I've asked Mason Harris from Cisco to write up a quick how-to primer on the ASA API capabilities. Thank you Mason for the great information.

Author: Mason Harris CCIE #5916, Solutions Architect, Global Enterprise

Over the years I've seen many different custom methods used to manage ASA firewalls. Most of them involve some version of command line interface (CLI) scripting since nearly all ASA features and functions are available in this manner. Perl and Expect scripts are the common scripting languages in use today for managing ASAs.

Historically the ASA has been a closed platform in the sense syslog has been the only choice for event management. Last year a fully functional virtualized ASA (ASAv) was introduced with the ASA 9.2.1 release. Combined with this virtualized offering and the increase in Sofware Defined Networking (SDN) and Network Function Virtualization (NFV), the next logical step was for Cisco to develop an API to programmatically manage an ASA firewall. This gives customers a very flexible platform where common elements could be created and repurposed to orchestrate and automate deployments.

The ASA 9.3(2) release introduced a RepresentationalState Transfer (REST) API that offers a standards-based approach to managing the ASA. Using HTTPS as its transport, REST provides an easy way to send and receive data from a device. This data could be configuration changes, monitoring or other queries and uses JSON (JavaScript Object Notation) as the interface.

There are five request methods supported:

  1. GET – retrieve data from an object
  2. PUT – adds data to an existing object
  3. POST – creates the object with specified parameters
  4. DELETE – deletes the object and any conditions
  5. PATCH – applies partial modifications to the object


Use of the REST API requires an ASA running 9.3(2) or 9.4(1) code and the latest REST API plugin from cisco.com. Note that older, first-generation ASAs do not support releases above 9.1.

The API plugin executes as a module in flash memory and must be explicitly enabled via the CLI (see image below).

Additionally, the ASA HTTP server functionality must be invoked to start the listener process and there must be at least one local user with privileges to invoke the REST calls.

Cisco API1

For details on the ASA REST API configuration, see here.

In order to test some of the capabilities of the API, a browser plugin is required that will be able to act as the REST client. In my lab I'm using Postman, which is a great tool for testing APIs.

Once the basic setup is complete, I recommend examining the API documentation package at https://<ASA_IP_Address>/doc. This utility gives a brief explanation of each call and also offers an export capability to Python, Perl, or Java.

api console

Adding a New Network Object

Let's walk through a simple configuration example of adding a network object to the ASA. First let's query the ASA and see what, if any, existing network objects are in the current configuration. By checking the API doc page we can see that this is a GET (read) operation to the /api/objects/networkobjects object. Basically this is asking for a listing of all the network objects on the ASA. Reference the output below:


As we can see from the output, there are three network objects configured:

  • NETWORK_OBJ_10.1.1.0_24

Let's add a fourth network object on the ASA called “SANDBOX_NET”. Note that the network objects are not required to be in all caps, this is just for readability in the ASA configuration.

Next, using your favorite REST client you'll POST the new network object to /api/objects/networkobjects using the appropriate REST syntax. What if you're are new to REST and JSON?

The API document page provides sample requests for common tasks. The one shown here is found in the network object pages.


Don't have a REST client plugin for your browser? Use the handy console utility built into the API doc pages:

Cisco API

And finally to verify that the new “SANDBOX_NET” object was actually created.

screenshot 2015 05 12 14.10.56

The output results verify the addition of the network object.


The ASA provides a sophisticated debugging facility for the REST API as seen here:


In this example the creation of a new network object is failing and debugging is enabled to determine the cause. (Note: Please use care enabling debug commands due to increased potential for CPU consumption). See the debug output below.


As can be seen from the output, the network object “SANDBOX_NET” already exists and is being rejected as a duplicate entry.

Parting Thoughts

A REST API on the ASA enables another standards based method for making configuration adds, moves or changes to the firewall. There is also a buld edit feature as well as a catch-all CLI object for methods that aren't explicitly supported via the API. The API is supported on both the virtualized ASA (ASAv) and the physical appliance which allows for a consistent provisioning approach.

Using the API with the ASAv provides a value in environments where orchestration tools can spin up firewalls dynamically to meet demand or scalability leveraging SDN and NFV concepts for both physical and virtual firewalls. It provides a valuable option for companies that no longer can rely on CLI or existing management elements for provisioning and operating their production devices.

Finally, for those wanting to get more experience with the API I would suggest downloading an ASAv image and the API binary. It's a great way to get some experience with the API as well learn more about JSON and how it can be used to automate configuration updates.

for more information on REST, click here.

Must read: Hidden Cause of Slow Internet and how to fix it
View Comments
Join the discussion
Be the first to comment on this article. Our Commenting Policies