Sunday, July 8, 2018

Ansible REST API - Interacting with Cisco FirePower Management Center (FMC) - 03 Introduction of REST API and Cisco FMC API Explorer

This post belongs to my "Ansible REST API - Interacting with Cisco FMC" series. The following is the table of content of this series:
  1. Introduction and Ansible playbook download
  2. Script flow charts
  3. Introduction of REST API and Cisco FMC API Explorer
  4. Script prerequisites
  5. Request Access Token 
  6. Get policy content, modify content and "PUT' in FMC - Part 1
  7. Get policy content, modify content and "PUT' in FMC - Part 2 
  8. Get deployable devices and deploy policy

Cisco FirePower Management Center starts supporting REST API since version 6.1. But as many other early offerings of Cisco products, it takes time to become mature. At the latest release 6.2.3, the it become much more stable.

If you are not family with REST API, you can go through my post "REST API 101" and get a general idea about what REST API can do and what's the format of REST request and respond.

Cisco FirePower Management Center provides its own API Explorer. You will need a "admin" account to connect to the API interface. The REST API is enabled by default. If the REST API was disabled, you can login to the FMC console and go to "System -> Configuration -> REST API Preferences" and click the "Enable REST API":



Click to expand
In order to access the API Explorer of FMC, open your browser and input the URL as below:

https://{{FMC IP}}/api/api-explorer/

Click to expand
In the following, I will use an example to show how to use the api-explorer. And the photo below shows the steps of getting the device list and device details of the FMC:


Click to expand
First, we select the "Devices" from "API INFO" on the left hand side panel. Then the available API calls and methods will appear in the mid-panel. We can see for "device", we have two type of API calls: "copy config request" & "device records". In this example, we will focus on the "device records".

As we know, in FMC, devices can be registered in the Global domain or other sub-domains. In our example, we want to check the devices which registered in the "Global/Sydney" domain. So we need to select the "Global/Sydney" domain as below:


Click to expand

Once we select the domain, we can see the domain ID will appear in the URL link as below. In the later posts of this API series, we will use this domain ID quite often. So now we keep in mind how to get the domain ID here.
Click to expand
In the above screen-shot, we can see there are 4 types of request method for the "device records". They are DELETE (delete device object), PUT (modify device object), POST (add new device object) and GET (obtain existing device object info). Let's select the "GET" and we have the API CONSOLE shown as below:
Click to expand
In the above API console, we can see the URL, request method, query parameter and request/ response info. Please be note that when sending GET request to FMC, we should always use "expanded: true" in the query parameter as it will give you the detailed info in response. The following shows how the request parameter is appended to the URL:

{"url":"/api/fmc_config/v1/domain/dd731f3e-8297-5b05-7ac3-000000000001/devices/devicerecords?expanded=true"}


In the "Response Text" field, we can see the response body which contain the existing device info of the FMC under the "Global/Sydney" domain. The devices are in in the array "items[]". In each device's JSON, we have the key values such as "id", "links", "name", "description", "model", "accessPolicy " etc. The follow is an example of the response text. The lines highlighted in orange is device "FTD-2". The lines highlighted in light blue is device "FTD-1".


{
  "links": {
    "self": "https://192.168.1.205/api/fmc_config/v1/domain/dd731f3e-8297-5b05-7ac3-000000000001/devices/devicerecords?offset=0&limit=2&expanded=true"
  },
  "items": [
    {
      "id": "11a13c5e-7b9d-11e8-8701-be7fcc61faec",
      "type": "Device",
      "links": {
        "self": "https://192.168.1.205/api/fmc_config/v1/domain/dd731f3e-8297-5b05-7ac3-000000000001/devices/devicerecords/11a13c5e-7b9d-11e8-8701-be7fcc61faec"
      },
      "name": "FTD-2",
      "description": "NOT SUPPORTED",
      "model": "Cisco Firepower Threat Defense for VMWare",
      "modelId": "A",
      "modelNumber": "75",
      "modelType": "Sensor",
      "healthStatus": "green",
      "sw_version": "6.2.3",
      "healthPolicy": {
        "id": "e13c7d40-7083-11e8-97ce-02c515297e64",
        "type": "HealthPolicy",
        "name": "Initial_Health_Policy 2018-06-15 10:07:15"
      },
      "accessPolicy": {
        "name": "syd-test-access-policy",
        "id": "000c2911-ed30-0ed3-0000-030064771115",
        "type": "AccessPolicy"
      },
      "hostName": "192.168.1.207",
      "license_caps": [
        "THREAT",
        "MALWARE",
        "URLFilter"
      ],
      "keepLocalEvents": false,
      "prohibitPacketTransfer": false,
      "metadata": {
        "readOnly": {
          "state": false
        },
        "domain": {
          "name": "Sydney",
          "id": "dd731f3e-8297-5b05-7ac3-000000000001",
          "type": "domain"
        }
      }
    },
    {
      "id": "1b8e0ef8-7081-11e8-ab14-9aaa7606d632",
      "type": "Device",
      "links": {
        "self": "https://192.168.1.205/api/fmc_config/v1/domain/dd731f3e-8297-5b05-7ac3-000000000001/devices/devicerecords/1b8e0ef8-7081-11e8-ab14-9aaa7606d632"
      },
      "name": "FTD-1",
      "description": "NOT SUPPORTED",
      "model": "Cisco Firepower Threat Defense for VMWare",
      "modelId": "A",
      "modelNumber": "75",
      "modelType": "Sensor",
      "healthStatus": "red",
      "sw_version": "6.2.3",
      "healthPolicy": {
        "id": "e13c7d40-7083-11e8-97ce-02c515297e64",
        "type": "HealthPolicy",
        "name": "Initial_Health_Policy 2018-06-15 10:07:15"
      },
      "accessPolicy": {
        "name": "FTD-1-Access-Policy-SYD",
        "id": "000c2911-ed30-0ed3-0000-008589936316",
        "type": "AccessPolicy"
      },
      "hostName": "192.168.1.206",
      "license_caps": [
        "THREAT",
        "MALWARE",
        "URLFilter"
      ],
      "keepLocalEvents": false,
      "prohibitPacketTransfer": false,
      "metadata": {
        "readOnly": {
          "state": false
        },
        "domain": {
          "name": "Sydney",
          "id": "dd731f3e-8297-5b05-7ac3-000000000001",
          "type": "domain"
        }
      }
    }
  ],
  "paging": {
    "offset": 0,
    "limit": 2,
    "count": 2,
    "pages": 1
  }
}


In FMC, every object has its own ID. So getting the correct item ID is very important in the REST API operations. In the above example, we can get the Domain ID, Device ID, Access Policy ID etc.

Although our goal is to use Ansible to interact with the FMC, it's very important to understand how to use the FMC API Explorer. As I mentioned before, different vendors have different API data structure. API Explorer is the guide line of Cisco FMC REST API. From the API explorer, we can learn about the API request/ response format and we can write our Ansible scripts based on these instructions.

In the following post, I will take about the prerequisites of this Ansible Playbook.


Reference:

No comments:

Post a Comment

NSX Load Balancer "Application Rules" Examples:

Load Balancing is one of the features provided by the NSX Edge Services Gateway (ESG). It can provide L7 Load Balancing by utilizing the HA...