Firepower Management Center 4000

Cisco Firepower Management Center 4000 Quick start guide

  • Hello! I am an AI chatbot trained to assist you with the Cisco Firepower Management Center 4000 Quick start guide. I’ve already reviewed the document and can help you find the information you need or explain it in simple terms. Just ask your questions, and providing more details will help me assist you more effectively!
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
the UNIX operating system. All rights reserved. Copyright ©1981, Regents of the University of California.
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)
©Cisco Systems, Inc. All rights reserved.
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
/