Cisco Firepower Management Center Virtual Appliance Quick start guide

Firepower Management Center REST API Quick Start Guide, Version

6.7.0

First Published: 2020-10-28

Last Modified: 2020-10-28

Americas Headquarters

Cisco Systems, Inc.

170 West Tasman Drive

San Jose, CA 95134-1706

USA

http://www.cisco.com

Tel: 408 526-4000

800 553-NETS (6387)

Fax: 408 527-0883

THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,

INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH

THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,

CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.

CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT

LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS

HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network

topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional

and coincidental.

All printed copies and duplicate soft copies of this document are considered uncontrolled. See the current online version for the latest version.

Cisco has more than 200 offices worldwide. Addresses and phone numbers are listed on the Cisco website at www.cisco.com/go/offices.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:

https://www.cisco.com/c/en/us/about/legal/trademarks.html. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a

partnership relationship between Cisco and any other company. (1721R)

CONTENTS

About the Firepower Management Center REST API 1

CHAPTER 1

About the Firepower Management Center REST API 1

Enabling the REST API 1

Best Practices 2

Additional Resources 2

About the API Explorer 3

CHAPTER 2

About the API Explorer 3

Authentication to the API Explorer 3

Logging into API Explorer 4

Setting the Domain 4

Accessing the Legacy API Explorer 4

Obtaining Sample Code with CodeGen 5

Downloading the Open API Spec 5

Generating Sample Code with the CodeGen Utility 6

Viewing API Parameters 6

Connecting with a Client 9

CHAPTER 3

Authentication from a REST API Client 9

Requesting an Authentication Token 10

Refreshing an Authentication Token 11

Objects in the REST API 13

CHAPTER 4

Request Structure 13

Bulk Rule Posting 15

Response Structure 16

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

iii

Rate Limiting 18

Payload Limiting 18

Object Overrides 18

Audit Services 19

GET auditrecords 19

Users 20

GET authroles 20

GET SSO Config 20

PUT SSO Config 20

Deployment Services 20

GET deployabledevices 20

GET deployments 21

GET pendingchanges 21

POST deploymentrequests 21

GET jobhistories 21

POST rollbackrequests 21

Device Group Services 22

DELETE devicegrouprecords 22

PUT devicegrouprecords 22

POST devicegrouprecords 22

GET devicegrouprecords 22

Device Clusters 22

GET ftddevicecluster 22

Device HA Pair Services 23

DELETE ftddevicehapair 23

PUT ftddevicehapair 23

POST ftddevicehapairs 23

GET ftddevicehapairs 24

DELETE failoverinterfacemacaddressconfigs 24

GET failoverinterfacemacaddressconfigs 24

POST failoverinterfacemacaddressconfigs 25

PUT failoverinterfacemacaddressconfigs 25

GET monitoredinterfaces 25

PUT monitoredinterfaces 25

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

iv

Contents

Health Services 26

GET Health Alerts 26

GET Health Metrics 26

Device Services 26

POST copyconfigrequests 26

DELETE devicerecords 26

PUT devicerecords 27

POST devicerecords 27

GET devicerecords 27

PUT fpphysicalinterfaces 27

GET fpphysicalinterfaces 27

DELETE fplogicalinterfaces 28

PUT fplogicalinterfaces 28

POST fplogicalinterfaces 28

GET fplogicalinterfaces 28

DELETE inlinesets 29

PUT inlinesets 29

POST inlinesets 29

GET inlinesets 29

GET commands 29

GET Metrics 30

GET staticroutes 30

GET virtualrouters 31

PUT virtual routers 31

POST virtual routers 31

DELETE virtual routers 31

GET virtual BGP 32

GET virtual ipv4staticroutes 32

PUT virtual ipv4 static routes 32

POST virtual ipv4 static routes 33

DELETE virtual ipv4 static routes 33

GET virtual ipv6staticroutes 33

PUT virtual ipv6 static routes 34

POST virtual ipv6 static routes 34

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

v

Contents

DELETE virtual ipv6 static routes 34

GET virtual ospf interface 35

GET virtual ospfv2 routes 35

GET virtual static routes 35

DELETE ipv4staticroutes 35

PUT ipv4staticroutes 35

POST ipv4staticroutes 35

GET ipv4staticroutes 35

DELETE ipv6staticroutes 36

PUT ipv6staticroutes 36

POST ipv6staticroutes 36

GET ipv6staticroutes 36

GET ospf interface 37

GET ospfv2routes 37

GET ospfv3interfaces 37

GET ospfv3routes 37

DELETE virtualswitches 38

PUT virtualswitches 38

POST virtualswitches 38

GET virtualswitches 38

GET Virtual Tunnel Interfaces 39

PUT Virtual Tunnel Interfaces 39

POST Virtual Tunnel Interfaces 39

DELETE Virtual Tunnel Interfaces 39

DELETE vlaninterfaces 40

PUT vlaninterfaces 40

POST vlaninterfaces 40

GET vlaninterfaces 40

PUT fpphysicalinterfaces 41

GET fpphysicalinterfaces 41

PUT physicalinterfaces 41

GET physicalinterfaces 41

GET bridgegroupinterfaces 42

POST bridgegroupinterfaces 42

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

vi

Contents

PUT bridgegroupinterfaces 42

DELETE bridgegroupinterfaces 42

GET redundantinterfaces 43

POST redundantinterfaces 43

PUT redundantinterfaces 43

DELETE redundantinterfaces 43

GET bgp routing 43

GET bgp general settings 44

GET etherchannelinterfaces 44

POST etherchannelinterfaces 44

PUT etherchannelinterfaces 45

DELETE etherchannelinterfaces 45

GET subinterfaces 45

POST subinterfaces 45

PUT subinterfaces 45

DELETE subinterfaces 46

GET fpinterfacestatistics 46

POST interfaceevents 46

GET interfaceevents 46

GET commands 46

Intelligence Services 47

POST collections 47

POST discoveryinfo 47

GET element 48

DELETE incident 48

PUT incident 48

GET incident 48

PUT indicator 48

GET indicator 49

PUT observable 49

GET observable 49

PUT settings 49

GET settings 49

DELETE source 50

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

vii

Contents

PUT source 50

POST source 50

GET source 50

Integration Services 51

PUT cloudeventsconfigs 51

GET cloudeventsconfigs 51

PUT cloudregions 51

GET cloudregions 51

DELETE externallookups 52

PUT externallookups 52

POST externallookups 52

GET externallookups 52

DELETE packetanalyzerdevices 52

PUT packetanalyzerdevices 53

POST packetanalyzerdevices 53

GET packetanlyzerdevices 53

GET External Storage 53

PUT External Storage 53

Object Services 54

GET anyprotocolportobjects 54

GET applicationcategories 54

GET applicationfilters 54

GET applicationproductivities 54

GET applicationrisks 55

GET applications 55

GET applicationtags 55

GET applicationtypes 55

GET aspathlists 56

GET certenrollments 56

GET communitylists 56

GET continents 56

GET countries 57

DELETE dnsservergroups 57

PUT dnsservergroups 57

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

viii

Contents

POST dnsservergroups 57

GET dnsservergroups 57

GET endpointdevicetypes 58

GET expanded community lists 58

GET extended access lists 58

DELETE fqdns 58

PUT fqdns 59

POST fqdns 59

GET fqdns 59

GET geolocation 59

GET global time zones 60

DELETE hosts 60

PUT hosts 60

POST hosts 60

GET hosts 60

DELETE icmpv4objects 61

PUT icmpv4objects 61

POST icmpv4objects 61

GET icmpv4objects 61

DELETE icmpv6objects 62

PUT icmpv6objects 62

POST icmpv6objects 62

GET icmpv6objects 63

DELETE ikev1ipsecproposals 63

PUT ikev1ipsecproposals 63

POST ikev1ipsecproposals 63

GET ikev1ipsecproposals 63

DELETE ikev1policies 64

PUT ikev1policies 64

POST ikev1policies 64

GET ikev1policies 64

DELETE ikev2ipsecproposals 65

PUT ikev2ipsecproposals 65

POST ikev2ipsecproposals 65

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

ix

Contents

GET ikev2ipsecproposals 65

DELETE ikev2policies 65

PUT ikev2policies 66

POST ikev2policies 66

GET ikev2policies 66

DELETE interfacegroups 66

PUT interfacegroups 66

POST interfacegroups 67

GET interfacegroups 67

GET interfaceobjects 67

GET ipv4prefixlists 68

GET ipv6prefixlists 68

GET isesecuritygrouptags 68

GET keychain 68

DELETE keychain 69

PUT keychain 69

POST keychain 69

GET networkaddresses 70

DELETE networkgroups 70

PUT networkgroups 70

POST networkgroups 70

GET networkgroups 71

DELETE networks 71

PUT networks 71

POST networks 72

GET networks 72

GET policy lists 72

DELETE portobjectgroups 72

PUT portobjectgroups 73

POST portobjectgroups 73

GET portobjectgroups 73

GET ports 73

DELETE protocolportobjects 74

PUT protocolportobjects 74

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

x

Contents

POST protocolportobjects 74

GET protocolportobjects 74

DELETE ranges 75

PUT ranges 75

POST ranges 75

GET ranges 75

GET realms 76

GET realmusergroups 76

GET realmusers 76

GET route maps 77

GET securitygrouptags 77

DELETE securityzones 77

PUT securityzones 77

POST securityzones 78

GET securityzones 78

GET siurlfeeds 78

GET siurllists 78

DELETE slamonitors 79

PUT slamonitors 79

POST slamonitors 79

GET slamonitors 79

GET standard access lists 79

GET standard community lists 80

GET time ranges 80

PUT time ranges 80

POST time ranges 80

DELETE time ranges 80

GET time zone objects 81

PUT time zone objects 81

POST time zone objects 81

DELETE time zone objects 81

DELETE tunneltags 81

PUT tunneltags 82

POST tunneltags 82

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

xi

Contents

GET tunneltags 82

GET urlcategories 82

DELETE urlgroups 82

PUT urlgroups 83

POST urlgroups 83

GET urlgroups 83

DELETE urls 83

PUT urls 84

POST urls 84

GET urls 84

GET variablesets 84

DELETE vlangrouptags 85

PUT vlangrouptags 85

POST vlangrouptags 85

GET vlangrouptags 85

DELETE vlantags 86

PUT vlantags 86

POST vlantags 86

GET vlantags 86

Policy Services 87

DELETE accesspolicies 87

PUT accesspolicies 87

POST accesspolicies 87

GET accesspolicies 88

DELETE accessrules 88

PUT accessrules 88

POST accessrules 88

GET accessrules 88

DELETE categories 89

PUT categories 89

POST categories 89

GET categories 89

PUT defaultactions 89

GET defaultactions 90

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

xii

Contents

GET loggingsettings 90

PUT loggingsettings 90

GET filepolicies 90

DELETE ftdnatpolicies 91

PUT ftdnatpolicies 91

POST ftdnatpolicies 91

GET ftdnatpolicies 91

DELETE ftds2svpns 91

PUT ftds2svpns 92

POST ftds2svpns 92

GET ftds2svpns 92

PUT advancedsettings 92

GET advancedsettings 92

DELETE endpoints 93

PUT endpoints 93

POST endpoints 93

GET endpoints 93

PUT ikesettings 94

GET ikesettings 94

PUT ipsecsettings 94

GET ipsecsettings 94

DELETE autonatrules 95

PUT autonatrules 95

POST autonatrules 95

GET autonatrules 95

DELETE manualnatrules 95

PUT manualnatrules 96

POST manualnatrules 96

GET manualnatrules 96

GET natrules 96

PUT inheritancesettings 96

GET inheritancesettings 97

GET intrusionpolicies 97

DELETE prefilterpolicies 97

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

xiii

Contents

PUT prefilterpolicies 97

POST prefilterpolicies 98

GET prefilterpolicies 98

DELETE hitcounts 98

PUT hitcounts 98

GET hitcounts 99

DELETE prefilterrules 99

PUT prefilterrules 99

POST prefilterrules 99

GET prefilterrules 100

GET snmpalerts 100

GET syslogalerts 100

Policy Assignment Services 100

PUT policyassignments 100

POST policyassignments 101

GET policyassignments 101

Status Services 101

GET taskstatuses 101

System Information 101

GET domain 101

GET serverversion 102

Update Packages 102

POST Cancel Upgrades 102

POST Retry Ugrades 102

DELETE upgradepackages 102

GET upgradepackages 102

GET listapplicabledevices 103

POST upgradepackage 103

GET upgradepackages: Monitor 103

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

xiv

Contents

CHAPTER 1

About the Firepower Management Center REST

API

The Firepower Management Center REST API provides a lightweight API to manage a Firepower Management

Center.

•About the Firepower Management Center REST API, on page 1

•Enabling the REST API, on page 1

•Best Practices, on page 2

•Additional Resources, on page 2

About the Firepower Management Center REST API

With the release of Cisco’s Firepower Management Center REST API, you now have light-weight, easy-to-use

option for managing Firepower Threat Defense and legacy Firepower devices through a Firepower Management

Center.

The REST API is an application programming interface (API), based on “RESTful” principles, which you

can quickly enable on any Firepower Management Center running version 6.1 or higher, and use with a REST

client.

After installing a REST client, you can contact the specific Firepower Management Center's REST agent and

use standard HTTP methods to access current configuration information, and issue additional configuration

parameters.

Enabling the REST API

In Firepower Management Center, the REST API is enabled by default. However, if you are intending to use

the REST API, you should confirm that it is enabled.

If you are using UCAPL mode, check that the REST API is not enabled.

Note

Step 1 Navigate to System>Configuration>REST API Preferences>Enable REST API

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

1

Step 2 Check the "Enable REST API" checkbox.

Step 3 Click "Save". A "Save Successful" dialog will display when the REST API is enabled.

Best Practices

Cisco recommends the following best practices for optimal results with the REST API:

• Keep UI users and script users separate. Especially do not use the admin account as an API user.

• Do not give script users more privilege than needed.

• Always validate the content coming from the server.

• Validate/sanitize JSON content, as it may include embedded executable code.

• If you are using CC or UCAPL mode you should disable REST API access to the Firepower Management

Center and managed devices.

Additional Resources

Additional resources for the Firepower Management Center REST API can be found on Cisco DevNet at

https://developer.cisco.com/firepower/.

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

2

About the Firepower Management Center REST API

Best Practices

CHAPTER 2

About the API Explorer

•About the API Explorer, on page 3

•Authentication to the API Explorer, on page 3

•Accessing the Legacy API Explorer, on page 4

•Obtaining Sample Code with CodeGen, on page 5

•Viewing API Parameters, on page 6

About the API Explorer

The API Explorer provides a limited interface for the REST API as well as giving a view of the abilities of

the REST API.

The API Explorer resides on the Firepower Management Center, and can be accessed via the Firepower

Management Center at:

https://<management_center_IP_or_name>:<https_port>/api/api-explorer

Version 6.4 uses a new API Explorer, based on the OpenAPI Specification (OAS). You can still access the

legacy API Explorer if you prefer.

As part of the OAS, you now use CodeGen to generate sample code.

This explorer provides the list of APIs available on the Firepower Management Center, and their details.

Authentication to the API Explorer

The REST API relies on the same authentication as the Firepower Management Center. Each function in the

REST API maps to permissions in the Firepower Management Center.

You can log into the API Explorer using any account on the Firepower Management Center, but you will only

be able to perform the functions for which the account has permissions. For more information on setting

permissions for user roles, see the Firepower Management Center Configuration Guide.

The first time you connect to the API Explorer you may receive an error that the connection is not secure due

to an invalid certificate. You will need to add an exception in your browser to use the certificate and accept

the connection.

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

3

Logging into API Explorer

The REST API uses the same authentication and permission model as the Firepower Management Center.

See the Firepower Management Center Configuration Guide for more information.

Before you begin

Make sure you have an account on your Firepower Management Center with the required permissions to

perform the tasks you want to perform using the REST API.

Step 1 Navigate to the following URL: https://<management_center_IP_or_name>:<https_port>/api/api-explorer

If you experience an extended load time for the logon screen when using a Firefox browser, enter about:support in the

search bar and click the Refresh Firefox option, then view the Firepower Management Center interface with self-signed

certificates in the same Firefox browser. For more information, see

https://support.mozilla.org/en-US/kb/refresh-firefox-reset-add-ons-and-settings.

Step 2 Log in with your username and password and click "Sign In"

What to do next

Locate the desired resource and request.

Setting the Domain

The REST API can perform functions globally, in the default domain, or in specific domains.

Before you begin

You must have a configured Firepower Management Center, an account with permissions to access the REST

API in one or more domains configured on your FMC.

In the upper right, drop down the Domains menu and select the desired domain.

What to do next

Locate the desired resource and request type.

Accessing the Legacy API Explorer

The API Explorer has changed for 6.4.0. While the newer API Explorer retains nearly all of the previous

functionality, some users may prefer the older interface.

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

4

About the API Explorer

Logging into API Explorer

Before you begin

The Legacy Explorer will be removed in future releases of Firepower Management Center. Please use the

Open API Specification for access to current REST API functionality in the future.

Note

Make sure you have an account on your Firepower Management Center with the required permissions to

perform the tasks you want to perform using the REST API.

Log in to the API Explorer at https://<management_center_IP_or_name>:<https_port>/api/api-explorer.

In the upper right-hand corner click on Legacy Explorer.

What to do next

Use the Legacy API Explorer as you would normally.

Obtaining Sample Code with CodeGen

You can use the CodeGen utility on the Open API Spec to generate sample code in a number of different

languages. This utility is an open-source tool you can download online. The resultant code is meant primarily

as an educational and bootstrapping tool.

The CodeGen utility creates sample code for the entire Open API Spec. As such, it generates sample code for

every allowed method and endpoint in the REST API. The sample code can be in a variety of languages,

including HTML, Perl, Python, and Java.

For complete documentation of the CodeGen utility go to https://repo1.maven.org/maven2/io/swagger/

swagger-codegen-cli/

Downloading the Open API Spec

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.

The Open API Spec is a JSON file. It can be read by most text editors.

Before you begin

Have an account on the Firepower Management Center which is able to access the API Explorer.

Make sure that your browser is able to download from sites with self-signed certificates.

Step 1 Navigate to the following URL: https://<management_center_IP_or_name>:<https_port>/api/api-explorer

Step 2 Click on Download Spec in the upper right corner. Depending on your browser configuration, you will either be given a

prompt to save the file, or be shown the file directly.

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

5

About the API Explorer

Obtaining Sample Code with CodeGen

Step 3 Save the file. Be sure to note the destination and filename.

What to do next

Run the CodeGen utility on the downloaded file.

Generating Sample Code with the CodeGen Utility

The Swagger CodeGen utility allows you to generate sample code from an Open API Spec. This sample code

can be in a variety of languages including Java, HTML, Python, and Perl.

Before you begin

Download the Swagger CodeGen Utility. It can be found at

https://repo1.maven.org/maven2/io/swagger/swagger-codegen-cli/

Have a Jave Runtime Environment installed on your computer

Download the Firepower Managemenr Center REST API Open API Spec

Set environment variables to allow you to run the CodeGen utility

From the command line, run the command java -jar ./swagger-codegen-cli-<VERSION>.jar generate -o

<OUTPUT_PATH> -l <LANGUAGE> -i <OPEN_API_SPEC_FILE>

Example:

java -jar ./swagger-codegen-cli-2.3.1.jar generate -o C:\work\code\api_schema\html -l html -i

fmc_swagger.json

<VERSION> is the specific version of the CodeGen utility you are using. It must match the filename of the CodeGen .jar

file.

<OUTPUT_PATH> is the path to which you want to output the generated code.

<LANGUAGE> is the language which you want CodeGen to generate. Suggested options include html,java,perl, and

python. Other options are possible, check the CodeGen documentation for the complete list of choices.

<OPEN_API_SPEC_FILE> is the Open API Spec file which you downloaded. This is the source from which CodeGen is

generating example code. Without it, CodeGen cannot provide output.

What to do next

Find the generated code in the output path and use as desired. Generated code should be considered an example,

and may not perform as desired unless modified to meet your needs.

Viewing API Parameters

Each resource has a set of parameters and fields associated with it. You can view the parameters and fields

by performing any of the supported operations for that resource within API Explorer.

Firepower Management Center REST API Quick Start Guide, Version 6.7.0

6

About the API Explorer

Generating Sample Code with the CodeGen Utility

Page is loading ...

Cisco Firepower Management Center Virtual Appliance Quick start guide

Cisco Firepower Management Center Virtual Appliance Quick start guide

Related papers

Other documents