This repository is dedicated to useful tooling for the Firepower Threat Defense on-box REST API
Please note that this API is only accessible when an FMC does not manage the device.
pip install ftd_api
Right now, we are only "exposing" the bulk tool. Keep a lookout in this space for more good stuff coming.
If you have installed the package, the bulk tool ftd_bulk_tool
should be in your path already.
usage: ftd_bulk_tool.py [-h] [-c FILE_NAME] [-D] [-a ADDRESS] [-P PORT]
[-u USERNAME] [-p PASSWORD] [-l LOCATION]
[-f {CSV,JSON,YAML}] [--url URL] [-e] [-i ID_LIST]
[-n NAME_LIST] [-t TYPE_LIST] [--filter_local]
{IMPORT,EXPORT,LIST_TYPES}
This tool provides a simple abstraction to handle bulk import/export tasks via
the Firepower Threat Defense REST API.
positional arguments:
{IMPORT,EXPORT,LIST_TYPES}
The various different modes in which the tool runs
optional arguments:
-h, --help show this help message and exit
-c FILE_NAME, --config_file FILE_NAME
A properties file allowing you to specify any of the
tool's options. If the option is set in both places,
the command-line options will override the
configuration file. The format is key=value each on
it's own line. '#' comments are supported.
-D, --debug Enable debug logging
-a ADDRESS, --address ADDRESS
FTD hostname or IP. Default: 'localhost'
-P PORT, --port PORT FTD port. Default: 443
-u USERNAME, --username USERNAME
The username to login with. Default: 'Admin'
-p PASSWORD, --password PASSWORD
The password to login with. Default: 'Admin123'
-l LOCATION, --location LOCATION
Directory path for EXPORT mode. One or more file paths
(comma delimited) for IMPORT mode. Required by IMPORT,
and EXPORT modes
-f {CSV,JSON,YAML}, --format {CSV,JSON,YAML}
Specify the import or output format. Default: 'JSON'
--url URL The URL you would like to export data from instead of
doing a full export. Only valid for EXPORT mode.
-e, --pending Export only pending changes. Only valid for EXPORT
mode. Ignored if 'url' is supplied
-i ID_LIST, --id_list ID_LIST
Comma separated list of ID values to export. This is
essentially a filter by ID on the export. Only valid
for EXPORT mode. Ignored if 'url' or 'pending' are
supplied
-n NAME_LIST, --name_list NAME_LIST
Comma separated list of names to export. This is
essentially a filter by name on the export. Only valid
for EXPORT mode. Ignored if 'url' or 'pending' are
supplied
-t TYPE_LIST, --type_list TYPE_LIST
Comma separated list of types to export. This is
essentially a filter by type on the export. Only valid
for EXPORT mode. Ignored if 'url' or 'pending' are
supplied
--filter_local This instructs the import code to filter by the -t -n
-i options before sending the data to the server, this
can be used as a work around if server side filtering
does not work
If using a bash shell, do the following:
Download the following file:
https://github.com/jaredtsmith/ftd_api/blob/master/docker/general/docker_util.sh
Add the following line to ~/.profile
source ~/docker_util.sh
Adjust the path for where you put the file on your system. As long as you have the docker executable present, this creates a function 'ftd_bulk_tool' which runs the tool from a docker without installing the tool locally.
pip install ftd_api
This installs the library in your machine and adds it to your python path. If you would like to see the current version look here: https://pypi.org/project/ftd-api/
We recommend creating a properties file with the connectivity info for your device typically I'll drop these in my home directory, and it would look something like this:
660.prop
address=myftd.com
port=443
username=admin
password=Admin123
Or to pass the same on the command line, you would add the following arguments:
-a myftd.com -P 443 -u admin -p Admin123
For frequent use, the properties file is faster!
Export the full configuration:
ftd_bulk_tool -c ~/660.prop -l /tmp/export EXPORT
The above command exports in JSON format by default see the -f argument to change the format. The "-c" arg specifies the properties file with connectivity information, the "-l" specifies the directory to export to and the command is "EXPORT".
To export a specific type like "networkobject" you would run the command as follows:
ftd_bulk_tool -c ~/660.prop -l /tmp/export -t networkobject EXPORT
To add additional types, you can pass a comma-separated list just don't put spaces around the comma.
During import there are some object types you may want to exclude:
- internalcertificate - This object type can cause web server restart, so the tool runs more gracefully if this is excluded.
- webuicertificate - This object type triggers a web server restart, so exclude this from your import.
- user - The device thinks this is a password change and invalidates the session, so it is best to exclude the user object.
- managementip - This can impact connectivity to the device while running the script.
There are two ways the tool can exclude objects, one is client-side, and the other is server-side; we've found it more reliable to exclude upfront on the client-side, and you'll generally have fewer issues. That is activated with the --filter_local option, and when filtering locally, you can filter out objects that cannot be filtered server-side like:
- metadata - This is a block at the top that of the import JSON file that causes cross-version import errors. Just exclude this, and you'll be more likely to succeed.
Additionally, there can be version-specific compatibility issues, for example:
From 6.5.0 --> 6.6.0+
Exclude the following object type:
- datasslciphersetting - This had an enumeration change which will cause a parse error.
So to import a 6.5.0 configuration into a 6.6.0 box you would run the following command:
ftd_bulk_tool -c ~/660.prop -l /tmp/export/full_config.txt -t internalcertificate,user,metadata,managementip,webuic
ertificate,datasslciphersetting --filter_local IMPORT
Note: Add -D for debug to see what the HTTP transactions look like under the covers.
In the case of import, the "-t" acts to exclude the list of types as opposed to export where it acts for inclusion.
For those of you wishing to contribute: Fork this repo, clone your fork, then execute the following commands:
cd ftd_api
python3 setup.py sdist
pip3 install -e .
This builds the source distribution and then installs it onto your development system using symlinks (as opposed to installing a copy of it) so that as you modify the code, it takes effect immediately. Note that this works just the way you want it to in a virtualenv
Please add unit tests using standard unittest library and put them in the top level tests
folder. To run the tests from the top-level directory, just run pytest
. Alteratively, you can call unittest directly python -m unittest tests/*.py
, but pytest is definitely prettier ;).
Note that pytest is not an explicit dependency of this package. Thus, you may want to install it: pip install pytest
MIT License - See LICENSE.TXT for full text