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.
In addition to deploying Cisco-provided remediation modules, you can install and run your own custom remediations to automate responses to violations of associated correlation policies. Cisco provides a software developer kit (SDK) that you can download from the Support Site to help you get started.
Using the SDK and the information in this chapter of the Cisco Remediation API Guide, you can:
Caution: The syslog module in the SDK is not intended for production use.
Please note that you can use the Cisco-provided modules already loaded on the Defense Center as a reference resource while you develop. All of these modules are accessible at /var/sf/remediation_modules
on the Defense Center. Each installed module has a .tgz
package in this directory. For information on the modules, see Cisco-Provided Remediation Modules.
The remediation SDK has a syslog alert remediation module in two versions, Perl and C. To use it, you need a syslog server running and receiving remote traffic.
The module provides two remediation types:
Simple_Notification
- generates syslog alerts with the source IP address, source port (if available), and IP protocol (if available) for the triggering event. Complete_Notification
- generates a syslog alert with the same fields as the simple notification, and also includes the destination IP address, destination port, and a severity indicator for the triggering event. As with all remediation modules, you enter a small amount of configuration in the web interface to add instances of the module. Each instance targets a particular device on your network (in this case a syslog server) and runs the remediation for the instance. To run the Complete_Notification
remediation type, you select a syslog facility level not required for the Simple_Notification
remediation type.
See the following table for a list of the Perl version files.
See the following table for a list of the C version files.
To download the remediation SDK:
1. Access the support website at https://support.sourcefire.com/downloads.
2. Select a software version, then under Product Category, select Software. The download link for the remediation SDK is in the api portion of the page.
3. Unpack the.zip file in a convenient folder on your client machine.
The steps below form a checklist of tasks that need to be performed to create, install, and configure a custom remediation module. Some of the steps involve procedural and descriptive details that are explained in cross-referenced sections of the Remediation API Guide or the FireSIGHT System User Guide.
To develop, install, and configure a custom remediation module, you must:
1. Identify the condition you want to mitigate and the actions that appropriately resolve the detected condition in your environment.
2. Familiarize yourself with data elements that can be obtained from the remediation subsystem. See Data Available from the Remediation Subsystem for definitions of all available fields that the Defense Center can provide for your remediation.
You should also understand the return code functionality built into the remediation subsystem. See Defining Exit Statuses for information.
3. Generate a high-level design that identifies all the remediation actions (remediation types) that your program needs to address.
4. Write your remediation program so that it addresses all the functions necessary for the desired remediations. Remediation module programs may be written in bash, tsch, Perl or C. Develop your program using the technical guidance provided in Notes for Remediation Program Developers.
5. Create the module template file for your remediation module. For an understanding of the data elements and syntax of the module template, see the chapter Communicating with the Remediation Subsystem.
You can save time by editing an existing module.template
file to start with.
6. Package your remediation module as described in Packaging Your Module.
7. Install the module on the Defense Center using the Policy and Response component as described in Installing Your Module. You will load the package on the Defense Center and proceed as if you were configuring one of the Cisco-provided modules.
8. Ensure that the individual remediation types in your remediation module are assigned as responses to the correct correlation rules in your defined correlation policies. See the FireSIGHT System User Guide for procedure details.
When you have defined the required scope and functionality of your remediation program and understood the data elements available for your remediation actions, you can write the remediation program.
Remediation module programs may be written in bash, tsch, Perl or C.
The following table indicates where to find information on topics of interest.
The remediation daemon on the Defense Center specifies the remediation name as the first argument on the command line when it launches the remediation program. The code snippet below from the SDK Perl program, syslog.pl,
shows one way your program can branch to the appropriate remediation function. The program runs either SimpleNotification()
or CompleteNotification()
, based on the content of $remediation_config,
which is set by the first field from the remediation daemon. The sample also shows the use of return codes which are discussed in Handling Return Codes.
You declare the names of all remediation types in the module.template
file, and associate remediation types with each instance as you add the instance via the web interface. The remediation type that is executed by the instance is recorded in the instance.config
file which is stored in the instance.config
subdirectory described in Understanding the Remediation Subsystem File Structure.
The root directory of each remediation module is derived from the remediation module name and version number, both of which are declared in the module.template
file. See The config Element for details on the elements of module.template
.
If you install a module packaged in syslog.tgz with the name syslog
and version 1.0
in module.template
, the system puts the module in the following directory: /var/sf/remediation/syslog_1.0
. That directory contains the module.template
file and the remediation program binary for the module.
When you add an instance of the remediation and name the instance log_tokyo
, the system creates the following directory:
and places a file named instance.conf
in it. The instance.conf
file, which is in XML format, contains the configuration information for the log_tokyo
instance.
The following Linux command sequence illustrates the directory structure described above.
Note that the instance.conf
file contains the name of the remediation type that the log_tokyo
instance runs. In the above example, the user who added the log_tokyo
instance could have configured it to run either remediation type defined for the syslog remediation module: Simple_Notification
or Complete_Notification
.
For details on the elements in the instance.conf XML file, see Instance Configuration Data.
When the Defense Center executes a remediation instance, the remediation daemon launches the remediation program from the instance subdirectory and supplies data from the instance.conf
file to the remediation program as command line arguments.
An example will illustrate the process. If a policy violation launches a syslog instance named log_tokyo
, which calls the remediation named Simple_Notification with a source IP address of 1.1.1.1 and a destination IP address of 2.2.2.2, the Defense Center sets the working directory to /var/sf/remediations/Syslog_1.0/log_tokyo
(that is, the instance.conf
subdirectory) and executes the remediation binary, syslog.pl
. The daemon’s command line syntax will be as follows:
Note in particular that the syslog.pl
executable is in the parent directory of the instance.conf
subdirectory.
When the command runs in this way, the syslog.pl
binary can load the information in instance.conf
file because it is in the current directory. If the binary needs to load any modules or other files in the parent directory ( /var/sf/remediations/Syslog_1.0
in this case), the code must explicitly load them from the parent directory; that is, it must provide a path starting with "../"
. Otherwise the binary will not be able to find the files that it needs.
In Perl, you can also deal with this issue using the lib()
function as follows:
"
../"
);
Your program must be able to open, read, parse, and close the instance.conf
file.
When the remediation daemon passes event data to your remediation module, it passes the name of the remediation followed by the correlation event data in the order in which the fields are specified in module.template
. In module.template
, each field to be passed to your module is declared using the < pe_item>
tag.
If a pe_item
is set to optional in module.template
and is undefined (meaning there is no value for the specific pe_item
), the remediation daemon passes “undefined” or null to your module. If pe_item
is set to required in module.template
but is undefined, the remediation daemon logs a message to the remediation log stating that no value is available, and does not execute your remediation module binary. You can view the remediation log in the web interface where it is called the Table View of Remediations. See the FireSIGHT System User Guide for details on how to access and use this view.
The remediation daemon handles undefined data items differently, depending on whether an item is marked as optional
or required
in module.template
. Undefined means that the Defense Center database has no value for the item. The daemon’s processing is as follows:
pe_item
is set to optional
in module.template
, the daemon passes “undefined” or null to your module. pe_item
is set to required
in module.template
, the daemon does not execute the remediation and logs a message to the remediation log stating that no value is available.The Defense Center waits for a return code for each instance and records the code in the remediation log. For information on predefined and custom return codes, see Defining Exit Statuses.
The Table View of Remediations in the web interface of the Defense Center displays the results of each launched remediation. See the FireSIGHT System User Guide for information on accessing and using the Table View of Remediations.
You can enable the remediation API features described in the table below by setting their corresponding elements in the module.template
file. For configuration details, see Defining the Global Configuration.