Cisco ASAv firewall REST API – Resource Manipulation

Introduction

After the initial article about ASAv REST API we are going to explore how we can granularity manipulate various resources such as objects and object-groups. You will learn how to create modify, verify and delete each object type.

This can be useful when building an automation tool that needs to perform various configuration changes programmatically.

Service Object

Service objects are one of the most common objects types used in firewall. They can define OSI Layer 4 TCP and UDP ports as well as other protocols such as ARP, or GRE. We are going to demonstrate some basic operations that can be carried out with this type of object. CLI reference is also provided for comparison with REST API.

Create

CLI Reference

object service UDP-88
 service udp destination eq 80

Request Format

Header:
URL: https//<management-ip>/api/object/networkservices
Method: POST

Body:

{
  "kind": "object#TcpUdpServiceObj",
  "name": "UDP-88",
  "value": "udp/80"
}

Response Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 09:52:01 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

As you can see, when we created new object we got its location URI. We will reference this address when doing changes or object removal. For service object the reference name is the object ID.

Modify

CLI Reference

object service UDP-88
 service udp destination eq 88

Request Format

Header:
URL: https//<management-ip>/api/objects/networkservices/UDP-88
Method: PATCH

Body:

{
  “kind”: “object#TcpUdpServiceObj“,
  “name”: “UDP-88“,
  “value”: “udp/88
}

Response Header Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 09:52:48 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Patch request can be used to change resource attributes such as value or name.

Retrieve

CLI Reference

show run | be object service UDP-88
 Note: As ASA CLI does not include show object id command, this was the easiest way how to list object in running configuration.

Request Format

Header:

URL: https://<management-ip>>/api/objects/networkservices/UDP-88
Method: GET

Body: Empty

Response Format

Header:
Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 158
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 09:58:14 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Body:
{
   “kind”: “object#TcpUdpServiceObj“,
   “name”: “UDP-88“,
   “value”: “udp/88“,
   “objectId”: “UDP-80
}

GET request does not require anything in request body and when referencing certain object ID such as UDP-88 it will return just single resource. To get list of all resources under parent resource just remove the ID from the end of URL.

Delete

CLI Reference

no object service UDP-88

Request Format

Header
URL: https://<management-ip>/api/objects/networkservices/TCP-88
Method: DELETE

Body: Empty

Response Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 10:02:05 GMT
Server: CiscoASARestApiServer

With REST API Delete request, rules still apply that you cannot remove an object that is being used or referenced elsewhere in configuration.

Service Object Group

As name implies service object groups glue together multiple objets. This eases the configuration and provides a little abstraction and simplification when constructing access rules.

Create

CLI Reference

object-group service krb5-udp
 description Default Kerberos UDP port
 service-object object UDP-88

Request Format

(Object within object group)

Header:
URL: https://<management-ip>/api/objects/networkservicegroups
Method: POST

Body:

{
"kind": "object#NetworkServiceGroup",
"name": "krb5-udp",
"members":
[
{
"kind": "objectRef#TcpUdpServiceObj",
"objectId": "UDP-88"
}
],
"description": "Default Kerberos UDP port"
}

Response Format

Header:
Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 124
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 10:35:10 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Request Format

(Object group within another object group)

CLI Reference

object-group service krb5-udp
 group-object krb5-udp

Header:

URL: https://<management-ip>/api/objects/networkservicegroups
Method: POST

Body:

{
"kind": "object#NetworkServiceGroup",
"name": "active-directory",
"members":
[
{
"kind": "objectRef#NetworkServiceGroup",
"objectId": "krb5-udp"
}
],
"description": "Default Active Directory ports"
}

Response Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 11:06:44 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Modify

CLI Reference

object-group service krb5-udp
 group-object krb5-udp
 group-object krb5-tcp

Request Format

(To change/add objects withing a group)

URL: https://<management-ip>/api/objects/networkservicegroups/active-directory
Method: PATCH

Body:

{
"kind": "object#NetworkServiceGroup",
"name": "active-directory",
"members":
[
{
"kind": "objectRef#NetworkServiceGroup",
"objectId": "krb5-udp"
},
{ "kind": "objectRef#NetworkServiceGroup", "objectId": "krb5-tcp" } ], "description": "Default Active Directory ports" }

Response Format

Header:
Status Code: 204 No Content
Content-Length: 0
Location: https://10.201.230.5/api/objects/networkservicegroups/active-directory
Server: CiscoASARestApiServer
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 18 Feb 2015 11:57:32 GMT

Retrieve

CLI Reference

show object-group id active-directory

Request Format

 

URL: https://<management-ip>>/api/objects/networkservicegroups/active-directory
Method: GET

Body: Empty

Response Format

Header:

Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 512
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 12:01:52 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Body:
{
   “kind”: “object#NetworkServiceGroup“,
   “name”: “active-directory“,
   “members”:
   [
       {
           “kind”: “objectRef#NetworkServiceGroup“,
           “objectId”: “krb5-tcp
       },
       {
           “kind”: “objectRef#NetworkServiceGroup“,
           “objectId”: “krb5-udp
       }
   ],
   “description”: “Default Active Directory ports“,
   “objectId”: “active-directory
}

Delete

(Entire object group)

CLI Reference

no object-group service active-directory

Request Format

URL: https://<management-ip>/api/objects/networkservicegroups/active-directory

Method: DELETE

Body: Empty

Response Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 12:11:13 GMT
Server: CiscoASARestApiServer
(Delete Object within a object group)

CLI Reference

object-group service active-directory
 no  group-object krb5-tcp

Request Format

Header:

URL: https://<management-ip>/api/objects/networkservicegroups/active-directory
Method: PATCH

Body:

{
     “kind”: “object#NetworkServiceGroup“,
     “name”: “active-directory“,
     “members”:
     [
         {
             “kind”: “objectRef#NetworkServiceGroup“,
             “objectId”: “krb5-udp
         }
      ],
      “description”: “Default Active Directory ports
}

Note: To delete an object within an object group, you can use Put operation with all existing objects except the ones you need to delete.In this particular example I am only leaving krb5-udp in the group.

Response Format

Header:
Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 374
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 12:07:46 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Object Network

Create

CLI Reference (host)

object network win-dc-01
 host 10.0.0.10

REST Request Format (host)

 

URL: https://<management-ip>/api/objects/networkobjects

Method: POST

Body:

{
  “host”: {
    “kind”: “IPv4Address“,
    “value”: “10.0.0.10
  },
  “kind”: “object#NetworkObj“,
  “name”: “win-dc-01
}

REST Response Header Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 14:40:47 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

CLI Reference (network)

object network web-tier
 subnet 172.16.0.0 255.255.255.0

REST Request Format

Method: POST
Body:
{
  “host”: {
    “kind”: “IPv4Network“,
    “value”: “172.16.0.0/24
  },
  “kind”: “object#NetworkObj“,
  “name”: “web-tier
}

REST Response Header Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 14:48:08 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Modify

CLI Reference (host)

object network win-dc-01
 host 10.0.0.11

Request Format

(To change/add objects withing a group)

Header

URL: https://<management-ip>/api/objects/networkobjects/win-dc-01
Method: PATCH

Body:

{
  “host”: {
    “kind”: “IPv4Address“,
    “value”: “10.0.0.11
  },
  “kind”: “object#NetworkObj“,
  “name”: “win-dc-01
}

Response Format

Header:
Status Code: 204
Content-Length: 0
Location: https://10.201.230.5/api/objects/networkobjects/win-dc-01
Server: CiscoASARestApiServer
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 18 Feb 2015 14:43:44 GMT

Retrieve

CLI Reference

show run | be object network win-dc-01

Request Format

Method: GET
Body: Empty

Response Format

Header:

Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 191
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 14:49:59 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Body:
{
   “kind”: “object#NetworkObj“,
   “name”: “win-dc-01“,
   “host”:
   {
       “kind”: “IPv4Address“,
       “value”: “10.0.0.11
   },
   “objectId”: “win-dc-01
}

Delete

CLI Reference

no object network win-dc-01
Request Format
Method: DELETE
Body: Empty

Response Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 14:52:26 GMT
Server: CiscoASARestApiServer

Network Object Group

Create

CLI Reference

object-group network dc-win-servers
 network-object object dc-win-01

REST Request Format (host)

URL: https://<management-ip>/api/objects/networkobjectgroups
Method: POST

Body:

{
     “kind”: “object#NetworkObjGroup“,
     “name”: “dc-win-servers“,
     “members”:
     [
         {
             “kind”: “objectRef#NetworkObj“,
             “objectId”: “win-dc-01
         }
     ],
     “description”: “Corporate AD Servers
}

REST Response Header Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 15:02:28 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Modify

CLI Reference (host)

object-group network dc-win-servers
 network-object object dc-win-01
 network-object object dc-win-02

Request Format

(To change/add objects withing a group)
Header:
Method: PATCH

 

Body:

{
           “kind”: “object#NetworkObjGroup“,
           “name”: “dc-win-servers“,
           “members”:
           [
               {
                   “kind”: “objectRef#NetworkObj“,
                   “objectId”: “win-dc-01
               },
               {
                   “kind”: “objectRef#NetworkObj“,
                   “objectId”: win-dc-02
               }
           ],
           “description”: “Corporate AD Servers
}

Response Format

Header:
Status Code: 204
Content-Length: 0
Location: https://10.201.230.5/api/objects/networkobjectgroups/dc-win-servers
Server: CiscoASARestApiServer
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 18 Feb 2015 15:09:07 GMT

Retrieve

 

CLI Reference

show object-group id dc-win-servers

Request Format

 
Method: GET
Body: Empty

Response Format

Header:

Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 465
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 15:12:39 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Body:
{
   “kind”: “object#NetworkObjGroup“,
   “name”: “dc-win-servers“,
   “members”:
   [
       {
           “kind”: “objectRef#NetworkObj“,
           “refLink”: “https://10.201.230.5/api/objects/networkobjects/win-dc-01“,
           “objectId”: “win-dc-01
       },
       {
           “kind”: “objectRef#NetworkObj“,
           “refLink”: “https://10.201.230.5/api/objects/networkobjects/win-dc-02“,
           “objectId”: “win-dc-02
       }
   ],
   “description”: “Corporate AD Servers“,
   “objectId”: “dc-win-servers
}

Delete

CLI Reference

no object-group network dc-win-servers

Request Format

Header:
Method: DELETE
Body: Empty

Response Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 15:16:43 GMT
Server: CiscoASARestApiServer

To delete an object within an object group you can use the same approach with Patch operations and listing only objects that you want to keep in object group.

Access Control List

Create

CLI Reference

access-list global_access remark Allow web-tier to Domain Controllers
access-list global_access extended permit object-group active-directory object-group web-and-db-tier object-group dc-win-servers log
access-group global_access global

REST Request Format (host)

Header:
Method: POST
Body:
{
        “sourceAddress”: {
        “kind”: “objectRef#NetworkObjGroup“,
        “objectId”: “web-and-db-tier
      },
      “destinationAddress”: {
        “kind”: “objectRef#NetworkObjGroup“,
        “objectId”: “dc-win-servers
      },
      “sourceService”: {
        “kind”: “objectRef#NetworkServiceGroup“,
        “objectId”: “active-directory
      },
      “destinationService”: {
        “kind”: “objectRef#NetworkServiceGroup“,
        “objectId”: “active-directory
      },
      “permit”: true,
      “active”: true,
      “remarks”: [“Allow web-tier to Domain Controllers“],
      “ruleLogging”: {
        “logInterval”: 300,
        “logStatus”: “Informational
      }
}
To create another line in same global ACL just modify the Request body and a new line will be added in the end of ACL. A reference value will be returned.

REST Response Header Format

Header:
Status Code: 201 Created
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 15:35:20 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept

Modify

CLI Reference

access-list global_access remark Allow Domain Controllers to Web-Tier
access-list global_access extended permit object-group active-directory object-group dc-win-servers object-group web-and-db-tier log
access-group global_access global

Request Format

(To change/add objects withing a group)
Header:
URL: https://<management-ip>/api/access/global/rules/3028343169
Method: PATCH

Body:

{
        “sourceAddress“: {
        “kind”: “objectRef#NetworkObjGroup“,
        “objectId”: “dc-win-servers
      },
      “destinationAddress“: {
        “kind”: “objectRef#NetworkObjGroup“,
        “objectId”: “web-and-db-tier
      },
      “sourceService”: {
        “kind”: “objectRef#NetworkServiceGroup“,
        “objectId”: “active-directory
      },
      “destinationService”: {
        “kind”: “objectRef#NetworkServiceGroup“,
        “objectId”: “active-directory
      },
      “permit”: true,
      “active”: true,
      “remarks”: [“Allow Domain Controllers to Web Tier“],
      “ruleLogging”: {
        “logInterval”: 300,
        “logStatus”: “Informational
      }
}

Response Format

Header:
Status Code: 204
Content-Length: 0
Location: https://10.201.230.5/api/access/global/rules/2372118638
Server: CiscoASARestApiServer
Accept-Ranges: bytes
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Date: Wed, 18 Feb 2015 15:44:50 GMT

Retrieve

 

CLI Reference

show access-list global_access

Request Format

 
Method: GET
Body: Empty

Response Format

Header:

Status Code: 200 OK
Accept-Ranges: bytes
Content-Length: 2088
Content-Type: application/json; charset=UTF-8
Date: Wed, 18 Feb 2015 15:55:03 GMT
Server: CiscoASARestApiServer
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Body:
{
   “kind”: “collection#ExtendedACE“,
   “rangeInfo”:
   {
       “offset”: 0,
       “limit”: 2,
       “total”: 2
   },
   “items”:
   [
       {
           “kind”: “object#ExtendedACE“,
           “selfLink”: “https://10.201.230.5/api/access/global/rules/3028343169“,
           “permit”: true,
           “sourceAddress”:
           {
               “kind”: “objectRef#NetworkObjGroup“,
               “objectId”: “web-and-db-tier
           },
           “destinationAddress”:
           {
               “kind”: “objectRef#NetworkObjGroup“,
               “refLink”: “https://10.201.230.5/api/objects/networkobjectgroups/dc-win-servers“,
               “objectId”: “dc-win-servers
           },
           “sourceService”:
           {
               “kind”: “objectRef#NetworkServiceGroup“,
               “objectId”: “active-directory
           },
           “destinationService”:
           {
               “kind”: “objectRef#NetworkServiceGroup“,
               “objectId”: “active-directory
           },
           “active”: true,
           “remarks”:
           [
               “Allow web-tier to Domain Controllers
           ],
           “ruleLogging”:
           {
               “logInterval”: 300,
               “logStatus”: “Informational
           },
           “isAccessRule”: true,
           “position”: 1,
           “objectId”: “3028343169
       },
       {
           “kind”: “object#ExtendedACE“,
           “selfLink”: “https://10.201.230.5/api/access/global/rules/2372118638“,
           “permit”: true,
           “sourceAddress”:
           {
               “kind”: “objectRef#NetworkObjGroup“,
               “refLink”: “https://10.201.230.5/api/objects/networkobjectgroups/dc-win-servers“,
               “objectId”: “dc-win-servers
           },
           “destinationAddress”:
           {
               “kind”: “objectRef#NetworkObjGroup“,
               “objectId”: “web-and-db-tier
           },
           “sourceService”:
           {
               “kind”: “objectRef#NetworkServiceGroup“,
               “objectId”: “active-directory
           },
           “destinationService”:
           {
               “kind”: “objectRef#NetworkServiceGroup“,
               “objectId”: “active-directory
           },
           “active”: true,
           “remarks”:
           [
               “Allow Domain Controllers to Web Tier
           ],
           “ruleLogging”:
           {
               “logInterval”: 300,
               “logStatus”: “Informational
           },
           “isAccessRule”: true,
           “position”: 2,
           “objectId”: “2372118638
       }
   ]
}

Delete

CLI Reference

no access-list global_access remark Allow Domain Controllers to Web Tier
no access-list global_access extended permit object-group active-directory object-group dc-win-servers object-group web-and-db-tier log

Request Format

Header:
Method: DELETE
Body: Empty

Response Format

Header:
Status Code: 204 No Content
Accept-Ranges: bytes
Content-Length: 0
Date: Wed, 18 Feb 2015 15:52:34 GMT
Server: CiscoASARestApiServer

Conclusion

ASA REST API is a very powerful interface, and as times goes I am sure that for customers that invested in this firewall product it will be the preferred way how to program their security policies automatically during application deployment.
Advertisements

One thought on “Cisco ASAv firewall REST API – Resource Manipulation

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s