Digging Deeper into the Cisco ASA Firewall REST API

Cisco ASA Restful API how-to article

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:


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:


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

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.


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.

Join the CSO newsletter!

Error: Please check your email address.

Tags programming languagesVirtualisecuritycisco

More about ASACisco

Show Comments

Featured Whitepapers

Editor's Recommendations

Solution Centres

Stories by Jamey Heary

Latest Videos

  • 150x50

    CSO Webinar: Will your data protection strategy be enough when disaster strikes?

    Speakers: - Paul O’Connor, Engagement leader - Performance Audit Group, Victorian Auditor-General’s Office (VAGO) - Nigel Phair, Managing Director, Centre for Internet Safety - Joshua Stenhouse, Technical Evangelist, Zerto - Anthony Caruana, CSO MC & Moderator

    Play Video

  • 150x50

    CSO Webinar: The Human Factor - Your people are your biggest security weakness

    ​Speakers: David Lacey, Researcher and former CISO Royal Mail David Turner - Global Risk Management Expert Mark Guntrip - Group Manager, Email Protection, Proofpoint

    Play Video

  • 150x50

    CSO Webinar: Current ransomware defences are failing – but machine learning can drive a more proactive solution

    Speakers • Ty Miller, Director, Threat Intelligence • Mark Gregory, Leader, Network Engineering Research Group, RMIT • Jeff Lanza, Retired FBI Agent (USA) • Andy Solterbeck, VP Asia Pacific, Cylance • David Braue, CSO MC/Moderator What to expect: ​Hear from industry experts on the local and global ransomware threat landscape. Explore a new approach to dealing with ransomware using machine-learning techniques and by thinking about the problem in a fundamentally different way. Apply techniques for gathering insight into ransomware behaviour and find out what elements must go into a truly effective ransomware defence. Get a first-hand look at how ransomware actually works in practice, and how machine-learning techniques can pick up on its activities long before your employees do.

    Play Video

  • 150x50

    CSO Webinar: Get real about metadata to avoid a false sense of security

    Speakers: • Anthony Caruana – CSO MC and moderator • Ian Farquhar, Worldwide Virtual Security Team Lead, Gigamon • John Lindsay, Former CTO, iiNet • Skeeve Stevens, Futurist, Future Sumo • David Vaile - Vice chair of APF, Co-Convenor of the Cyberspace Law And Policy Community, UNSW Law Faculty This webinar covers: - A 101 on metadata - what it is and how to use it - Insight into a typical attack, what happens and what we would find when looking into the metadata - How to collect metadata, use this to detect attacks and get greater insight into how you can use this to protect your organisation - Learn how much raw data and metadata to retain and how long for - Get a reality check on how you're using your metadata and if this is enough to secure your organisation

    Play Video

  • 150x50

    CSO Webinar: How banking trojans work and how you can stop them

    CSO Webinar: How banking trojans work and how you can stop them Featuring: • John Baird, Director of Global Technology Production, Deutsche Bank • Samantha Macleod, GM Cyber Security, ME Bank • Sherrod DeGrippo, Director of Emerging Threats, Proofpoint (USA)

    Play Video

More videos

Blog Posts

Market Place