Firepower System Remediation API Guide v6.0
Bias-Free Language
The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
- Updated:
- November 9, 2015
Chapter: Understanding the Remediation Subsystem
Understanding the Remediation Subsystem
The Firepower System® remediation API allows you to create remediations that your Firepower Management Center can automatically launch when conditions on your network violate the associated correlation policy. A remediation is the response your software program executes to mitigate the detected condition. For example, you can block traffic at a router on the source or destination IP address, or initiate a host Nmap scan to assess the host status. If multiple rules in a policy trigger, the Firepower Management Center can launch responses for each rule. A remediation module is the package of files you install on the Firepower Management Center to perform the response. A remediation module can incorporate several remediation types as shown in the graphic below.
In the example shown here, one of the system-provided remediation modules, the Cisco PIX router module, performs two remediation types: it either blocks packets by source IP address or blocks them by destination IP address.
If a remediation module targets multiple devices on your network (routers, hosts, and so forth), you configure your remediation module to perform multiple instances, one per device, when the correlation policy triggers. An instance is an instantiation of the remediation module, with one or more remediation types that correspond to functions in the remediation module code, and with a set of variables needed to run on the target device. For each instance, you specify the remediation type or types it executes and the instance-specific information such as the device’s IP address and password for the remediation to access the target device on your network.
The Firepower System's domains feature allows you to implement multitenancy within your deployment by segmenting user access to managed devices, configurations, and events. For systems that have more than one domain, users can create remediations for different domain levels. A remediation is not visible to ancestor or parallel domains from the one in which it was created. While a user in a child domain can view a remediation created in their ancestor domain, they cannot modify or delete it. A remediation created at the root domain can be viewed and used by all child domains.
Prerequisites
Before using the remediation API for custom remediations, you should be familiar with information in the following categories:
Firepower System
To understand the information in this guide, you should be familiar with the features and nomenclature of the Firepower System, and the functions of certain components:
- the Firepower Management Center role in the Firepower System architecture
- correlation policy management module on the Firepower Management Center
- remediation management module on the Firepower Management Center
See the Firepower System User Guide for further information.
Programming Requirements and Support
You must be able to code your custom remediation in Perl or shell script, or as a precompiled, statically-linked C program (with the exception of links to routines in glibc).
In addition, you must be able to produce a configuration file in XML for each remediation module. This file is called module.template. See the system-provided remediation modules for samples of this file. For module locations on the Firepower Management Center, see Understanding the Remediation Subsystem File Structure.
For each instance you add, the Firepower Management Center generates an instance-specific XML configuration file called instance.conf. Your code must parse this file each time a remediation instance executes.
The following table lists the packages available on the Firepower Management Center as resources for writing and executing your remediation program.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Cisco-Provided Remediation Modules
The following table describes the predefined remediation modules included with the Firepower Management Center. You should use these modules for reference when designing your remediation programs.
The system-provided modules are already installed on the Firepower Management Center and include both the remediation executable (in Perl and C) and completed module.template configuration file for each module. For information on the easy steps to deploy system-provided remediation modules, see the Firepower System User Guide.
The Remediation Subsystem
The remediation subsystem consists of the following components:
- the Firepower Management Center’s web interface, which you use to set up correlation policies and associate them with remediations, and to track the status of remediation processing
- the remediation API, which enables you to define the data that will be provided to your remediation modules
- the remediation daemon, which passed data to the remediation modules at run time and collects execution status information
- remediation modules, which perform specific responses to correlation policy violations
Understanding Remediation Subsystem Architecture
The remediation subsystem has a two-part architecture that is diagrammed in the figure below. The architecture consists of:
- infrastructure components such as the web interface and the remediation daemon which support all remediation modules. The infrastructure components allow you to create and manage all the remediation modules on your Firepower Management Center. The remediation daemon manages the execution of the remediations. See Remediation Subsystem Components for more details.
- the individual remediation modules which you develop to respond to specific correlation policy violations. See Remediation Module Architecture for more details.
Remediation Subsystem Components
The following diagram illustrates the main functions of the remediation subsystem and their interactions.
You create remediations in order to respond to rule violations on your network in an automated mode. The Firepower Management Center web interface allows you to define and activate your correlation policies and associate them with remediations. When a policy violation occurs, the remediation subsystem passes the name of the remediation and the event data specified in the module.template configuration file to the remediation daemon.
The remediation daemon launches the remediation and passes the correlation event data and instance-specific parameters to your remediation program. It also accepts return codes from the remediation program. The Firepower Management Center uses the return codes for status displays.
The remediation program launches a set of instances of the remediation when the associated policy rule triggers. Each instance targets a particular network device. You create instances on the Instance Detail page of the Firepower Management Center web interface. For each instance you provide the necessary instance-specific configuration details such as IP address and password of the target device.
Remediation Module Architecture
Each remediation module that you install on your Firepower Management Center includes one or more remediation types. You assign one or more remediation types to each instance. For information on configuring remediations as responses to policy violations, see the Configuring Remediations chapter in the Firepower System User Guide.
Remediation modules include the following components:
- the remediation program, included in the remediation module package at installation. See Planning and Packaging Your Remediation Module.
- a required XML
module.templatefile, also included in the remediation module package at installation. This file provides module-level information about your module and its data requirements that the remediation subsystem references each time it launches one of the remediation module’s instances. See Communicating with the Remediation Subsystem. - one XML
instance.conffile per instance. The Firepower Management Center auto-generates this file each time you configure a new instance of your remediation module.
Using the Remediation Subsystem
You deploy remediations by adding them as responses to specific rules in correlation policies on your Firepower Management Center. You define the associations of correlation policies and remediations using the Firepower Management Center web interface.
To deploy a remediation module, you must:
1.
Identify the condition you want to mitigate and the actions that appropriately resolve that condition in your environment. These actions are the main functions your custom remediation program must implement.
If you can use a Cisco-provided remediation module, skip directly to step Install the module on the Firepower Management Center using the web interface as described in Installing Your Module, page 2-13..
2. If you need to produce a custom remediation module, familiarize yourself with the data elements obtainable from the remediation subsystem. See Data Available from the Remediation Subsystem.
3. If you develop a custom remediation module you must also create a module template file to be included in your module package. See Communicating with the Remediation Subsystem for the format and syntax of the file.
4. Write your remediation program so that it addresses all the functions necessary for the desired remediations. You can write your remediation module programs in bash, tsch, Perl or C. Develop your program using the technical guidance in Notes for Remediation Program Developers.
5. Package your remediation module as described in Packaging Your Module.
6. Install the module on the Firepower Management Center using the web interface as described in Installing Your Module.
7. Ensure that the individual remediation types in your remediation module are assigned as responses to the correct correlation rules in your active correlation policies. See the Firepower System User Guide for procedure details.
Remediation Resources
In addition to this document, other resources you can use to create your remediation modules include:
- a remediation SDK with sample program code in C or Perl that generates syslog alerts and demonstrates how a module can interact with your network. See Working with the Remediation SDK chapter of this document for detailed information. The SDK can be downloaded from the Support site.
- the
module.templateschema (module.template.xsd), which is located on the Firepower Management Center at/etc/sf/remediation/module.template.xsd.
The following table describes some of the topics explained in the documentation and where to look for more information.
Feedback