my cheat sheet on Cisco Security APIs

Security comprises many different parts of an enterprise's infrastructure. Replacing human slow, and error prone corroboration of security incidents with a fast and automated API interaction can greatly increase the overall resilience and impenetrability of your defences.

For details see Advanced Malware Protection

For details see SecureX

FMC offers an API Explorer that is available on every Firepower Management Center by browsing to:

• https://<mgt-center-ip-or-name>:<https-port>/api/api-explorer
• https://<mgt-center-ip-or-name>:<https-port>/api/api-explorer

As you can see, it is a REST API. The reserveable sandbox API is available: https://fmcrestapisandbox.cisco.com/api/api-explorer/ but you must reserve the sandbox to get the credentials for a 4 hour session. That sandbox is available here: https://devnetsandbox.cisco.com/RM/Topology (search for FMC)

The API Explorer will let you generate code snippets for both Perl and Python

Update: The Open API Spec is a standardized specification of a REST API. The Open API Spec for the Firepower Management Center REST API contains details about the endpoints, fields, parameters, and requirements of the API. You can use the API Spec to generate sample code as well as find specific information about API functionality.

Every REST API call must include an authentication token to verify that the caller is authorized to perform the requested action.

Initially, you need to obtain an access token by supplying the admin username/password. This is called a password-granted access token, that is, grant_type = password.

Steps:

1. Create the JSON object for the password-granted access token grant. Specify the admin username and password
2. Use POST https://server/api/fdm/v3/fdm/token to obtain the access token. Use curl, postman, python, whatever you want.
3. Retrieve the access and refresh tokens from the response. A good response has a status code 200.

You can use the password-granted access token as described above. However, you can also request a custom access token With a custom token, you can:

• supply a subject name to help differentiate token usage (for own purposes).
• You can also request specific validity periods if the default values returned for password tokens do not fit your requirements.

(Notice the difference to API keys that have no expiration time. You have to go to a web page and manually invalidate an API key.)

Before you can start, you need to first 1) get a password-granted access token.

1. create the json object for custom access token grant

   {
   
      "grant_type": "custom_token",
      "access_token": "string",
      "desired_expires_in": 0,
      "desired_refresh_expires_in": 0,
      "desired_subject": "string",
      "desired_refresh_count": 0
   }
   

   Or realistically:

   {
     "grant_type": "custom_token",
     "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDI4MzI2NjcsInN1YiI6ImFkbWluIiwianRpIjoiMGM3ZDBmNDgtODIwMS0xMWU3LWE4MWMtMDcwZmYzOWU3ZjQ0IiwibmJmIjoxNTAyODMyNjY3LCJleHAiOjE1MDI4MzQ0NjcsInJlZnJlc2hUb2tlbkV4cGlyZXNBdCI6MTUwMjgzNTA2NzQxOSwidG9rZW5UeXBlIjoiSldUX0FjY2VzcyIsIm9yaWdpbiI6InBhc3N3b3JkIn0.b2hI6fVA_GbmhCOPM-ZUx6IC8SgCk1AkHXI-llV0r7s",
     "desired_expires_in": 2400,
     "desired_refresh_expires_in": 3000,
     "desired_subject": "api-client",
     "desired_refresh_count": 3
   }
   

   The token can be refreshed 3 times, after that you need to generate another token.

   1. POST that json to obtain the access token. For example, if I was using curl, I would:

      curl -X POST \
        --header 'Content-Type: application/json' \
        --header 'Accept: application/json' \
        -d '{ 
          "grant_type": "custom_token", 
          "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDI4MzU5NjgsInN1YiI6ImFkbWluIiwianRpIjoiYmMyNjM4N2EtODIwOC0xMWU3LWE4MWMtYzNlYTZkZjJjZThjIiwibmJmIjoxNTAyODM1OTY4LCJleHAiOjE1MDI4Mzc3NjgsInJlZnJlc2hUb2tlbkV4cGlyZXNBdCI6MTUwMjgzODM2ODYwNiwidG9rZW5UeXBlIjoiSldUX0FjY2VzcyIsIm9yaWdpbiI6InBhc3N3b3JkIn0.acOE_Y4SEds-NE4Qw99fQlUzdoSkhsjInaCh0a9WK38",
          "desired_expires_in": 2400, 
          "desired_refresh_expires_in": 3000, 
          "desired_subject": "api-client", 
          "desired_refresh_count": 3  
        }' https://ftd.example.com/api/fdm/v3/fdm/token
      

      1. Retrieve the access tokens from the response, (if status is 200 ok)

         For example this is a response to retrieve an access token.

         {
           "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDI4MzU5OTEsInN1YiI6ImFwaS1jbGllbnQiLCJqdGkiOiJjOWIxYzdjYi04MjA4LTExZTctYTgxYy02YmY0NzY3ZmRmZGUiLCJuYmYiOjE1MDI4MzU5OTEsImV4cCI6MTUwMjgzODM5MSwicmVmcmVzaFRva2VuRXhwaXJlc0F0IjoxNTAyODM4OTkxMzMxLCJ0b2tlblR5cGUiOiJKV1RfQWNjZXNzIiwib3JpZ2luIjoiY3VzdG9tIn0.9IVzLjGffVQffHAWdrNkrYfvuO6TgpJ7Zi_z3RYubN8",
           "expires_in": 2400,
           "token_type": "Bearer",
           "refresh_token": "eyJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1MDI4MzU5OTEsInN1YiI6ImFwaS1jbGllbnQiLCJqdGkiOiJjOWIxYzdjYi04MjA4LTExZTctYTgxYy02YmY0NzY3ZmRmZGUiLCJuYmYiOjE1MDI4MzU5OTEsImV4cCI6MTUwMjgzODk5MSwiYWNjZXNzVG9rZW5FeHBpcmVzQXQiOjE1MDI4MzgzOTEzMzEsInJlZnJlc2hDb3VudCI6MywidG9rZW5UeXBlIjoiSldUX1JlZnJlc2giLCJvcmlnaW4iOiJjdXN0b20ifQ.qseqjg3Uo183YvfN_77iJZELEqwpWw5AbKAqAnCIcSA",
           "refresh_expires_in": 3000
         }
         

After you obtain either a password-granted or custom access token, you must include it on each API call in the Authorization: Bearer header to the HTTPS request.

For example, a curl command to perform GET /object/networks might look like the following:

BASH curl -k -X GET \ -H 'Accept: application/json' \ -H 'Authorization: Bearer eyJhbGciOiJIUz… …vuO6TgpJ7Zi_z3RYubN8' \ https://ftd.example.com/api/fdm/v3/object/networks

For more, including how to refresh an access token using json and calls see this developer.cisco.com link.