Skip to main content

Python API client for Cisco Firepower Management Center (FMC)

Project description

python3 pypi license status published

FireREST

FireREST is a python library to interface with Cisco Firepower Management Center REST API. The goal of FireREST is to provide a simple SDK to programmatically interact with FMC.

Features

  • Authentication and automatic session refresh / re-authentication
  • Rate-limit detection and automatic backoff and retry behavior
  • Automatic squashing of paginated api payloads
  • Sanitization of api payloads for create and update operations (automatically remove unsupported elements like links, metadata from payload)
  • Detailed logging of api requests and responses
  • API specific error handling using various custom exceptions for typical errors (e.g. ResourceAlreadyExists, UnprocessAbleEntityError, ...)
  • Support for resource lookup by name instead of uuid for all CRUD operations

Requirements

  • Python >= 3.9

Quickstart

Installation

> pip install fireREST

Import api client

from fireREST import FMC

Authentication (self-hosted)

FireREST uses basic authentication. In case your authentication token times out, the api client will automatically refresh the session and retry a failed operation. If all 3 refresh tokens have been used up the connection object will try to re-authenticate again automatically.

fmc = FMC(hostname='fmc.example.com', username='firerest', password='Cisco123', domain='Global')

NOTE: By default domain is set to Global

Authentication (cdFMC/CDO)

fireREST uses Bearer token to authenticate. This token can be obtained from CDO cloud portal.

fmc = FMC(hostname='example.app.eu.cdo.cisco.com', password='<CDO Token>', cdo=True)

CRUD Operations

Objects

Create network object
net_obj = {
    'name': 'NetObjViaAPI',
    'value': '198.18.1.0/24',
}

response = fmc.object.network.create(data=net_obj)

NOTE: in case a resource supports the bulk option FireREST will automatically perform a bulk operation if the data provided is of type list

Get all network objects
net_objects = fmc.object.network.get()
Get specific network object
net_objects = fmc.object.network.get(name='NetObjViaAPI')

NOTE: You can access a resource either by name or uuid. If the resource supports a filtering by name FireREST will utilize the filter option, in case a Resource does not support filter params it will iterate through all resources to find a match

Update network object
net_obj = fmc.object.network.get(name='NetObjViaAPI')
net_obj['name'] = 'RenamedNetObjViaAPI'
response = fmc.object.network.update(data=net_obj)

NOTE: FireREST automatically extracts the id field of the provided data dict to update the correct resource.

Delete network object
response = fmc.object.network.delete(name='NetObjViaAPI')

Supported operations

Since FireREST does not try to provide a python object model nearly all api calls up to version 6.7.0 are available which includes but is not limited to the following CRUD operations:

├── assignment
│   └── policyassignment
├── audit
│   └── auditrecord
├── chassis
│   ├── interface
│   ├── networkmodule
│   └── operational
├── deployment
│   ├── deployabledevice
│   │   ├── deployment
│   │   └── pendingchanges
│   ├── deploymentrequest
│   ├── jobhistory
│   └── rollbackrequest
├── device
│   └── devicerecord
│       ├── bridgegroupinterface
│       ├── etherchannelinterface
│       ├── fpinterfacestatistics
│       ├── fplogicalinterface
│       ├── fpphysicalinterface
│       ├── inlineset
│       ├── interfaceevent
│       ├── operational
│       │   ├── command
│       │   └── metric
│       ├── physicalinterface
│       ├── redundantinterface
│       ├── routing
│       │   ├── bgp
│       │   ├── bgpgeneralsettings
│       │   ├── ipv4staticroute
│       │   ├── ipv6staticroute
│       │   ├── ospfinterface
│       │   ├── ospfv2route
│       │   ├── ospfv3interface
│       │   ├── policybasedroute
│       │   ├── staticroute
│       │   └── virtualrouter
│       │       ├── bgp
│       │       ├── ipv4staticroute
│       │       ├── ipv6staticroute
│       │       ├── ospfinterface
│       │       ├── ospfv2route
│       │       └── policybasedroute
│       ├── subinterface
│       ├── virtualswitch
│       ├── virtualtunnelinterface
│       └── vlaninterface
├── devicecluster
│   └── ftddevicecluster
│       └── operational
├── devicegroup
│   └── devicegrouprecord
├── devicehapair
│   └── ftddevicehapair
│       ├── failoverinterfacemacaddressconfig
│       └── monitoredinterface
├── health
│   ├── alert
│   ├── metric
│   ├── tunnelstatus
│   └── tunnelsummary
├── integration
│   ├── cloudeventsconfig
│   ├── cloudregion
│   ├── externallookup
│   ├── externalstorage
│   ├── fmchastatus
│   └── securexconfig
├── intelligence
│   ├── taxiiconfig
│   │   ├── collection
│   │   └── discoveryinfo
│   └── tid
│       ├── element
│       ├── incident
│       ├── indicator
│       ├── observable
│       ├── setting
│       └── source
├── job
│   └── taskstatus
├── netmap
│   ├── host
│   └── vulnerability
├── object
│   ├── anyconnectcustomattribute
│   │   └── override
│   ├── anyconnectpackage
│   ├── anyconnectprofile
│   ├── anyprotocolportobject
│   ├── application
│   ├── applicationcategory
│   ├── applicationfilter
│   ├── applicationproductivities
│   ├── applicationrisk
│   ├── applicationtag
│   ├── applicationtype
│   ├── aspathlist
│   ├── certenrollment
│   ├── certificatemap
│   ├── communitylist
│   ├── continent
│   ├── country
│   ├── dnsservergroup
│   │   └── override
│   ├── dynamicobject
│   │   └── mapping
│   ├── endpointdevicetype
│   ├── expandedcommunitylist
│   ├── extendedaccesslist
│   ├── fqdn
│   │   └── override
│   ├── geolocation
│   ├── globaltimezone
│   ├── grouppolicy
│   ├── host
│   │   └── override
│   ├── hostscanpackage
│   ├── icmpv4object
│   │   └── override
│   ├── icmpv6object
│   │   └── override
│   ├── ikev1ipsecproposal
│   ├── ikev1policy
│   ├── ikev2ipsecproposal
│   ├── ikev2policy
│   ├── interface
│   ├── interfacegroup
│   ├── intrusionrule
│   ├── intrusionrulegroup
│   ├── ipv4addresspool
│   │   └── override
│   ├── ipv4prefixlist
│   ├── ipv6addresspool
│   │   └── override
│   ├── ipv6prefixlist
│   ├── isesecuritygrouptag
│   ├── keychain
│   │   └── override
│   ├── network
│   │   └── override
│   ├── networkaddress
│   ├── networkgroup
│   │   └── override
│   ├── operational
│   │   └── usage
│   ├── policylist
│   ├── port
│   ├── portobjectgroup
│   │   └── override
│   ├── protocolportobject
│   │   └── override
│   ├── radiusservergroup
│   ├── range
│   │   └── override
│   ├── realm
│   ├── realmuser
│   ├── realmusergroup
│   ├── routemap
│   ├── securitygrouptag
│   ├── securityzone
│   ├── sidnsfeed
│   ├── sidnslist
│   ├── sinetworkfeed
│   ├── sinetworklist
│   ├── sinkhole
│   ├── siurlfeed
│   ├── siurllist
│   ├── slamonitor
│   ├── ssoserver
│   │   └── override
│   ├── standardaccesslist
│   ├── standardcommunitylist
│   ├── timerange
│   ├── timezone
│   │   └── override
│   ├── tunneltag
│   ├── url
│   │   └── override
│   ├── urlcategory
│   ├── urlgroup
│   │   └── override
│   ├── variableset
│   ├── vlangrouptag
│   │   └── override
│   └── vlantag
│       └── override
├── policy
│   ├── accesspolicy
│   │   ├── accessrule
│   │   ├── category
│   │   ├── defaultaction
│   │   ├── inheritancesettings
│   │   ├── loggingsettings
│   │   ├── operational
│   │   │   └── hitcounts
│   │   └── securityintelligencepolicy
│   ├── dnspolicy
│   │   ├── allowdnsrule
│   │   └── blockdnsrule
│   ├── dynamicaccesspolicy
│   ├── filepolicy
│   ├── ftdnatpolicy
│   │   ├── autonatrule
│   │   ├── manualnatrule
│   │   └── natrule
│   ├── ftds2svpn
│   │   ├── advancedsettings
│   │   ├── endpoint
│   │   ├── ikesettings
│   │   └── ipsecsettings
│   ├── identitypolicy
│   ├── intrusionpolicy
│   │   ├── intrusionrule
│   │   └── intrusionrulegroup
│   ├── networkanalysispolicy
│   │   ├── inspectorconfig
│   │   └── inspectoroverrideconfig
│   ├── prefilterpolicy
│   │   ├── defaultaction
│   │   ├── operational
│   │   │   └── hitcounts
│   │   └── prefilterrule
│   ├── ravpn
│   │   ├── addressassignmentsettings
│   │   ├── certificatemapsettings
│   │   └── connectionprofile
│   ├── snmpalert
│   └── syslogalert
├── system
│   └── info
│       ├── domain
│       └── serverversion
├── troubleshoot
│   └── packettracer
│       └── file
├── update
│   └── upgradepackage
│       └── applicabledevice
└── user
    ├── authrole
    ├── duoconfig
    └── ssoconfig

Troubleshooting

UnprocessableEntityError

You might see an UnprocessableEntityError exception when you try to execute CREATEor UPDATE operations. Depending on the API endpoint the error message from FMC might not contain enough information to pinpoint what is causing the issue. In this case I would recommend using pigtail on FMC to get more detailed information.

Example

In this example we are trying to create an object override, but the field value is invalid. The subnet mask chosen is not correct, which will cause the FMC API to respond with an UnprocessAbleEntity error.

data = {
    "overrides": {
        "parent": {
            "id": "00505699-76B7-0ed3-0000-077309525737"
        },
        "target": {
            "id": "0ff8161e-096e-11eb-8ec0-cb721f246e60",
            "type": "Device"
        }
    },
    "value": "198.18.201.0/241",
    "name": "NetObjWithOverrides",
    "id": "00505699-76B7-0ed3-0000-077309525737"
}
fmc.object.network.update(data=data)

On FMC we can use the pigtail utility to tail the logfile on the Tomcat webserver hosting the REST API. Using this method we can monitor the APIs response and get some additional information on the error

> expert
admin@fmc:/Volume/home/admin# sudo su -
root@fmc:/Volume/home/admin# pigtail TCAT

Here we see that a Java exception has been thrown, indicating that the request failed due an invalid ip address being passed

TCAT: 02-02 15:36:33 INFO: 172.21.100.145	-	-	443	PUT	/api/fmc_config/v1/domain/b76ff587-9224-65c7-d2af-000000000000/object/networks/00505699-76B7-0ed3-0000-077309525737	-	400	-	301	169	https://fmc.example.com	FireREST/1.0.0	-
TCAT: 02-02 15:34:33 [ajp-nio-127.0.0.1-9009-exec-1] ERROR com.cisco.api.external.rest.common.resource.ContainerServerResource - **Invalid IP Address**
TCAT: 02-02 15:34:33 APIException:Invalid IP Address

Authors

Oliver Kaiser (oliver.kaiser@outlook.com)

Maintainers

Rafal Chrabaszcz (rchrabas@cisco.com)

License

GNU General Public License v3.0 or later.

See LICENSE for the full text.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

firerest-1.2.3.tar.gz (66.8 kB view details)

Uploaded Source

Built Distribution

firerest-1.2.3-py3-none-any.whl (144.5 kB view details)

Uploaded Python 3

File details

Details for the file firerest-1.2.3.tar.gz.

File metadata

  • Download URL: firerest-1.2.3.tar.gz
  • Upload date:
  • Size: 66.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.13.5 Darwin/24.5.0

File hashes

Hashes for firerest-1.2.3.tar.gz
Algorithm Hash digest
SHA256 1d37f0ceb7e0460fa5456227ef95105081735d4fd21d4999628715d7874489d2
MD5 4a2b1cb2a66425b73c2e6e9d9bd3fac8
BLAKE2b-256 d57c1fd1ee939e112c9072dad7eb95cfdbe7eeb8a2f7141c87339687a5207870

See more details on using hashes here.

File details

Details for the file firerest-1.2.3-py3-none-any.whl.

File metadata

  • Download URL: firerest-1.2.3-py3-none-any.whl
  • Upload date:
  • Size: 144.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.13.5 Darwin/24.5.0

File hashes

Hashes for firerest-1.2.3-py3-none-any.whl
Algorithm Hash digest
SHA256 f2ab064405dc4a00a4d8596620611f2278db050a6c613ed788bc110150b3533b
MD5 2e8e7b568944684a1273e68d56a501ab
BLAKE2b-256 32b426dafe68005baf172c64658415bf9d0b614e031f1ad3c075315c32a6a0ba

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page