Digging Deeper into the Cisco ASA Firewall REST API

Security orchestration methods and of course SDN is 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 programmattically 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 and 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:

Requirements

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 priviliges to invoke the REST calls.

For details on ASA REST API configuration:

http://www.cisco.com/c/en/us/td/docs/security/asa/api/qsg-asa-api.html#34855

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 (www.getpostman.com) 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.

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
• RA_POOL
• SERVER_SUBNET

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:

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

The output results verify the addition of the network object.

Troubleshooting

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: http://en.wikipedia.org/wiki/Representational_state_transfer.