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.
The FireSIGHT System® remediation API allows you to create remediations that your Defense 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 Defense Center can launch responses for each rule. A remediation module is the package of files you install on the Defense Center to perform the response. A remediation module can incorporate several remediation types as shown in the graphic below.
For example, 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.
Before using the remediation API for custom remediations, you should be familiar with information in the following categories:
To understand the information in this guide, you should be familiar with the features and nomenclature of the FireSIGHT System, and the functions of certain components:
See the FireSIGHT System User Guide for further information.
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 Defense Center, see Understanding the Remediation Subsystem File Structure.
For each instance you add, the Defense 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 Defense Center as resources for writing and executing your remediation program.
|
|
|
|
|
|
|
|
|
|
|
|
|
The following table describes the predefined remediation modules included with the Defense Center. You should use these modules for reference when designing your remediation programs.
The system-provided modules are already installed on the Defense 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 FireSIGHT System User Guide.
The remediation subsystem consists of the following components:
The remediation subsystem has a two-part architecture that is diagrammed in the figure below. The architecture consists of:
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 Defense 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 Defense 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 Defense Center web interface. For each instance you provide the necessary instance-specific configuration details such as IP address and password of the target device.
Each remediation module that you install on your Defense 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 Responses for Correlation Policies chapter in the FireSIGHT System User Guide.
Remediation modules include the following components:
module.template
file, 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. instance.conf
file per instance. The Defense Center auto-generates this file each time you configure a new instance of your remediation module.You deploy remediations by adding them as responses to specific rules in correlation policies on your Defense Center. You define the associations of correlation policies and remediations using the Defense 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 Defense 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 Defense 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 FireSIGHT System User Guide for procedure details.
In addition to this document, other resources you can use to create your remediation modules include:
module.template
schema ( module.template.xsd
), which is located on the Defense 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.