Table Of Contents
Monitoring Events from Custom and Unsupported Devices or Versions
Overview of the Device Support Framework
Specify the Provider Configuration
Checklist for Defining and Exporting a Device Support Package
Create a Device Type
Create Device Event Types for a Custom Device Type
Editing a Device Type
Overriding Existing Parsers
Extending Existing Device Types
Add a Reporting Device based on a Custom Appliance Device Type
Add a Reporting Device based on a Custom Software Device Type
Import a Device Support Package
Export a Device Support Package
Remove an Installed Device Support Package
Events and Reports About Device Support Package Activities
MARS Forum on NetPro: An Overview
Uploading a Device Support Package to the MARS Forum
Download a Device Support Package from the MARS Forum on NetPro
Subscribe to Package Sharing Page of the MARS Forum
Example Custom Device Type: Custom Software Application
Monitoring Events from Custom and Unsupported Devices or Versions
Cisco Security Monitoring, Analysis, and Response System (MARS) provides native support for many Cisco and 3rd-party reporting devices and versions of software running on those devices. However, you may need to monitor the events generated by a home-grown application or an unsupported device. To support this ability, MARS allows you to define custom parsers, which represent reporting devices, and to define event types for parsing the SNMP TRAP or SYSLOG events received from those devices.
Beginning with MARS 6.0, these new custom parsing features are referred to as the Device Support Framework (DSF). With DSF you can quickly add support for new device types, improve support for existing device types, and replicate accomplished work from one CS-MARS appliance to another.
The following terms are used throughout this chapter:
•
audit event—A predictable event that can be detected by a system and about which enough details exist to define a record about the event's occurrence. In this usage, audit simply indicates that the event is worthy of inclusion in an audit trail. Events are typically categorized as security, authorization, system, or network events.
•audit record—A record, such as a syslog message, SDEE event, or SNMP trap, generated by a system to detail the occurrence of a specific audit event.
•device type —A collection of device event types, event types, and event grouping definitions that represents a type of device or application (such as Cisco PIX 7.0) and parsing functions to parse events received from that type of device/application.
•custom parser—A feature that employs a user-provided definition of device event type, event type, event grouping and patterns, as well as pattern matching, to parse events from a device/application of the type defined. Currently, custom parsers are supported only for SNMP trap and syslog.
•device event type—A description of a specific event type generated by a device type. These event descriptions instruct the MARS parser on how to process the received events to extract the useful information. A device event type includes an event type mapping, match patterns, severity level settings, and a log ID. A device event type maps between the audit record and an existing or a newly created event type, and then to an event type group, which allows the device event type to be used in inspection rules, queries, and reports. Also known as parser templates.
•event type—The MARS-specific construct that collects similar device event types from all supported device types as well as similar common vulnerabilities and exposures (CVE) definitions. This normalized view shows the relationship among reported device type events and allows MARS to understand that a single activity has occurred although it could be reported as different device event types by multiple devices across the network.
Multiple device event types are normalized to an event type, as seen under Management > Event Management. On this page, you can select a group to see the normalized event type in the Event ID column, its name in the Description column, and the list of device event types that normalize to it under the Device Event ID column.
•device support package—A single package file that contains one or more device types, custom parsers, rules, and report data definitions.
When you define a custom parser, you must define a custom device type and event types. When you define an instance of a custom device type, you are defining a reporting device of that type under Admin > System Setup > Security and Monitoring Devices. You are required to specify the reporting method as either SNMP TRAP or SYSLOG. This designation determines the protocol MARS uses to listen for events from the reporting device.
To receive events from an unsupported reporting device, you must perform the following tasks:
1. Add a custom device or application type. See Create a Device Type.
2. Add one or more device event type templates (log parser template). See Create Device Event Types for a Custom Device Type.
3. Add a reporting device that is based on the custom device or application type definition. See Add a Reporting Device based on a Custom Appliance Device Type or Add a Reporting Device based on a Custom Software Device Type.
This chapter contains the following topics:
•Overview of the Device Support Framework
–Specify the Provider Configuration
–Checklist for Defining and Exporting a Device Support Package
–Create a Device Type
–Create Device Event Types for a Custom Device Type
–Editing a Device Type
–Overriding Existing Parsers
–Extending Existing Device Types
–Add a Reporting Device based on a Custom Appliance Device Type
–Add a Reporting Device based on a Custom Software Device Type
–Import a Device Support Package
–Export a Device Support Package
–Remove an Installed Device Support Package
•Events and Reports About Device Support Package Activities
•MARS Forum on NetPro: An Overview
–Uploading a Device Support Package to the MARS Forum
–Download a Device Support Package from the MARS Forum on NetPro
–Subscribe to Package Sharing Page of the MARS Forum
•Example Custom Device Type: Custom Software Application
Overview of the Device Support Framework
Beginning in release 6.0, MARS extends the custom parser feature support found in earlier versions, which allowed you to parse and inspect SNMP TRAP and SYSLOG events. Specifically, it enables the following new features:
•Extend existing device type parsers by adding new device event types and patterns for those new types.
•Support new event and signature data for existing device types by adding new device event types that use existing native parsers.
•Define new patterns that override native parsing functions of an existing device event type.
•Create a device type that inherits its device event types and parsers from an existing device type. The derived device type retains the Appliance or Software type property from its parent, which cannot be overridden.
•Assign custom event types to a system event type group so any rule, report, or query using that group will include the new custom event types.
•Import and export of custom parsers, rules, and reports as device type-specific packages from a Global Controller or a standalone Local Controller.
Note An internal syslog message summarizes the provider and device data information about each import or export operation.
Warning Import and export from a Local Controller is only allowed in standalone mode. Once the Local Controller is managed by a Global Controller, you can only import and export from the Global Controller.
Using these features, collectively called the Device Support Framework, you can quickly add support for new device types, improve support for existing device types, and replicate accomplished work on different MARS of one customer's MARS appliances, or share work among customers, partners, and vendors.
The device support framework extends the custom log parser feature to enable the following features:
•Add a device/application type
•Add device event type to a device/application type definition
•Derive a device/application type from an existing device/application type
Note The child inherits any changes made to the parent, even after the child is defined.
•Add a device event type with or without pattern definitions for existing device types
•Assign custom event types to system or custom event type groups
•Add a reporting device based on the custom device type
•Edit an existing parser
•Import and export of custom parser
•Import and export of rules and reports
•Download and import customer parser, rules, and reports as device support packages from MARS forum on NetPro website.
•Protect exported device support packages with passwords to prevent unauthorized downloading and decryption.
•Remove custom device support packages
Specify the Provider Configuration
A provider attribute identifies the developer of any particular MARS support for a device type, including such elements as device type, device event type, event type, event type group, inspection rule, rule group, report, report group, and pattern type. This metadata is attached to any exported device support package, and it is rendered in the web interface when you review or import a device support package, or when provider information is available, such as when viewing device type, event type, or other provided element.
When defining a new provider, you can specify more meaningful values for the provider named Local CS-MARS box. When you export a custom device package from a MARS Appliance, it is the Local CS-MARS box provider information that is applied to that package, even if that package is derived from a device that was developed by Cisco.
To define a new provider, follow these steps:
Step 1 Click ADMIN > Custom Setup > Provider Configuration.
Step 2 Select the check box next to Local CS-MARS box entry, and click Edit.
Step 3 Specify values for the following required fields:
•Provider Identifier—A string value that, when combined with the Provider Name, uniquely identifies the provider.
•Provider Name—The name of the provider.
It is the combination of Provider Name and Provider Identifier that uniquely identify a provider.
Note Before you can remove a provider, you must first delete all dependencies manually.
•Display Name—This name is the name used throughout the web interface. For example, it appears in the Provider column of pages that list device support packages.
Step 4 (Optional) Specify values for any of the following optional fields:
•Address—Identifies the postal address of the provider.
•Phone Number—Identifies the phone number of the provider.
•Fax Number—Identifies the fax number of the provider.
•Email—Identifies the e-mail address of the provider.
•URL—Identifies the company URL address of the provider.
•Description—Provides a description of the provider.
Step 5 To save your changes, click Submit.
Checklist for Defining and Exporting a Device Support Package
When developing a new device support package, consider the following:
•Prioritize events and effort—Develop full custom device types for those event logs that are high severity and critical to be understood by MARS. The events in this subset require detailed regular expression parsing of the event. With non-critical events, you may be able to define keyword searches that identify the events clearly enough to be included in rules and reports.
•Group to simplify maintenance—Groups can simplify the definition of device types, such as IPS devices, that have a significant number of signatures or require periodic maintenance due to signature updates. Grouping is largely an abstract concept realized by mapping a device event type to a single event type or event type group. Based on the content of events, you can create groups of signatures that map to a smaller number of event types in MARS, where the event type represents the group of signatures. When the inspection rule or report fires in MARS, you can review the raw message for signature details. For example, you can create custom event types for each protocol or attack type as determined by the message data provided by the specific vendor.
•Reuse existing event types—Map to predefined event types in MARS so that existing reports and rules support the new device event types. If you cannot find a good match among the event types that are already in the system, you can create your own event type and event type groups. Then you can either put the new event types in system event type groups (so system rules and reports using the groups can automatically use the event type), or define new rules and reports to use the new event type or event type group.
Step 1 Verify that the device support package does not already exist
Log on to the MARS NetPro Forum site and conduct a survey to determine whether the device support package you require has been previously developed and posted.
For more information, see
Step 2 Determine which similar device support packages already exist
Even when the MARS NetPro Forum site (or local resources) do not have the exact device support package you require, locating a similar package can be advantageous. You can typically alter an existing device support package file for the required device or version more easily than you could build one from scratch.
For more information, see
Step 3 Verify the Provider Definition.
You can define a custom device support package on either a Global Controller or a stand-alone Local Controller; however, the appliance on which you are defining it has a local provider definition, which is the profile included in the export package. You should customize this profile so you can more easily distinguish your packages from others that you might install.
The local provider definition presents information that is unique to your organization.
For more information, see Specify the Provider Configuration
Step 4 Define a custom device type.
The custom device type is an object defined in MARS that represents an unsupported application or device. It organizes the following information about the device: vendor, model, version, and type (whether it is a hardware device or a software application running on a host). This last distinction is used to determine how a reporting device of that type is added in the web interface.
•Vendor—Identifies the vendor of the appliance or software.
•Model—Identifies the appliance model or software package name.
•Version—Identifies the version of the software, whether standalone or running on an appliance.
•Type—Specifies whether it is an appliance or software running on a host. This value is required because it determines how you define a reporting device of this device type under Admin > Security and Monitoring Devices.
You can define a custom device type for any device that generates SYSLOG or SNMP events and that can forward those events to the MARS Appliance. Once you have defined a custom device type, you can define device event types for that device type.
You can define a custom device type in two different ways.
1. Define a custom device type under the Management > Device Type Management.
2. Define a custom log parser under ADMIN > Custom Setup > Custom Log Parser.
For more information, see Create a Device Type
Step 5 Define one or more custom event types, and ensure defined patterns work if patterns are defined.
A custom event type represents a definition of a specific SYSLOG or SNMP trap event so that MARS can parse and extract the relevant session information from the event. It also maps the event to a custom or existing event type, which in turn is mapped to one or more existing event type groups. The event type groups are already mapped to existing inspection rules, reports, and queries. Once you have defined the device type and described the structure of the events, you need to configure devices of that type into the network topology, configure them to report data to the MARS Appliance, and query the event data using a free-form or predefined query to ensure the defined patterns work as expected.
To define a device event type, you must identify the format of the raw message and define multiple regular expressions that match against the key and value patterns within the message. These patterns are typically mapped to predefined value types, which tell MARS how to store the values extracted so they can be used in inspection rules, queries, and reports.
For more information, see Create Device Event Types for a Custom Device Type
Step 6 Determine the Device Support Package Level of Protection
You determine whether, and how, a device support package is protected. Password protection can permit or deny import of the package as well as determining whether encryption can be unlocked.
For more information, see
Step 7 Export the Device Support Package to an Off-Appliance Location.
After the custom device type and all event types are defined, you can export them to a single file format, which can be used as a backup or to import into other devices that receive events from the same device type. Exported packages are not restricted to a single device type; and therefore, you may have one that includes multiple custom devices types.
A single file is exported. The file contains the device type, event type, rules, and report information. You can import the file into a MARS Appliance to enable event parsing support of the device types contained in the file, as well as to enable rules and reports support if rules and reports are also contained.
For more information, see Export a Device Support Package
Step 8 Verify export/import works, and that parsing works with the imported data.
You can verify that the custom definition works with the logs and reporting. If you're importing or exporting a device type definition, review the report Activity: CS-MARS importing/exporting DSF packages logs to verify that the import succeeded.
For more information, see
Create a Device Type
You can create a device or application type in either of two places in the MARS web interface:
•Click MANAGEMENT > Device Type Management
and then click Add.
•Click ADMIN > Security and Monitor Devices, and then click Add next to the Device/Application Type list.
The device or application type organizes the custom event types that you define. MARS uses this logical group to select which custom event types to apply to events received from a reporting device of this type. You must define a device type before you can define a custom parser.
To create a device type, follow these steps:
Step 1 Click MANAGEMENT > Device Type Management.
The Device Type Management list appears.
Step 2 Click Add.
The Device Type Definition page appears.
Step 3 Select the type of custom parser to define:
•Appliance—Represents a hardware device that sends logs to the MARS Appliance.
•Software—Represents an application running on a host. The host can be configured to send logs to the MARS Appliance.
Step 4 Enter values for the following fields:
•Vendor—Unique name to identify the vendor of the custom parser. Example: Cisco.
•Model—Unique name to identify the model that the custom parser represents. Example: PIX.
•Version—Unique name to identify the software image version running on the appliance or host for which the custom parser is being defined. Example: 7.0.
Tip The Description field is optional and may be used to expand the device/application type definition as desired.
Step 5 Click Submit.
The Device Event Types For page displays. While it appears empty during the initial definition, this page will list the custom event type definitions grouped by this custom device.
Figure 15-1 Device Event Types For: <page_name>
Create Device Event Types for a Custom Device Type
The definition of a device event type includes two parts:
•data work—which instructs MARS what event type it will be mapped to
•regular expression pattern definition (optional)—which, if defined, instructs MARS how to extract relevant data from a raw message.
A device event type maps the event to a predefined or custom event type, which specifies the event priority and identifies the event type groups with which it is associated.
Note Device event types were referred to as log templates in previous releases of MARS.
Before You Begin
This procedure assumes that you have defined a custom device type, as described in Create a Device Type.
Be familiar with the Perl Compatible Regular Expressions (PCRE) syntax. For more information, see Appendix B, "Regular Expression Reference".
Step 1 Click Management > Device Type Management.
Step 2 Select the custom device type for which you want to define a new device event type, and then click Add Device Event Type.
A log template ties directly to the particular message that you want to parse. A log template is composed of one or more patterns that describe the contents of the message. Using the patterns, MARS parses the message when it is received.
The Device Event Type For: <device_type_name> pages appears.
Step 3 Enter a value in the Device Event ID field.
The Device Event ID allows you to map this message number—or another moniker used by the device—to the custom event type definition. Use the Device Event ID to clarify the relationship with the device trap or message ID. This value is a unique string value among all Device Event IDs associated with the selected device type.
Step 4 Enter a description of the device event type in the Description field.
This value is the one that is used throughout the web interface when displaying lists of custom device event types. If you leave this field blank, distinguishing among device event types is made more difficult.
Step 5 Do one of the following:
•Map the log to an existing event type. MARS includes tens of thousands of predefined event types. Select the event type and click the << button to add the event type to the Selected Event Type field.
Tip To display this list, select System from the Choose Event Type From filters and click Get). Alternatively, you can filter on severity level or enter keywords in the search field and click Search. To see additional event types, select a different page number under the Event Type list.
•Define a custom event type and map the log to it by performing the following steps:
a. To define a new event type, click Add below the Event Type list.
The Event Type Definition page appears.
b. Enter values for the following fields and then click Submit:
•Event ID—A unique string that identifies the event relative to all other events defined in MARS. This value appears in the Event ID column on the Management > Event Management page. It is this ID to which the device event IDs are matched.
•Description—Provide a description of this event. It is this description that appears under the event list when selecting an event type.
•Severity—Identifies the severity level of this event type. Select from RED, YELLOW, or GREEN.
•CVE Name—Identifies the name of the Common Vulnerabilities and Exposures Name, if any.
•Event Type Group—Identifies the event type groups to which this event type definition belongs. An event type can belong to one or more event type groups. If you want to define a custom event type group, click Add Group on the Management > Event Management page. It is also on this page that you can click on an event type group in the Groups column to see a description of the group and a list of the other events mapped to this group.
Note For a list of the event type groups that can be used when defining an event type in a device support framework package see DSF Event Type Group Descriptions, page C-1.
Step 6 Once the Selected Event Type field contains a value, click Apply.
The Patterns link is enabled.
Step 7 Click the Patterns link.
Developing a custom device event type requires a bit of work. The first step is to identify a complete raw message example. Next, identify which values in the raw message to parse and store. To obtain each value, MARS parses the raw message looking for a defined pattern known as a value pattern. A value pattern is a mask used to extract the values. It is bounded by another type of pattern called key patterns. After the key pattern, or beginning delimiter, is matched, a value pattern is matched and is stored as the value assigned to that key. The value pattern can be considered the ending delimiter. Then the next key pattern is sought, and so on. Each value is stored as a predefined value type, which include:
•source address
•source port
•destination address
•destination port
•protocol
•NAT source address
•NAT source port
•NAT destination address
•NAT destination port
•NAT protocol
•device time stamp
•received time
•session duration
•transmitted bytes
•reported user
•workstation name
•domain name
As described earlier, the parsing format is a pair of value strings: a Key pattern followed by a Value pattern. The Key and Value patterns are regular expressions based on the Perl Compatible Regular Expressions (PCRE) library, see Appendix B, "Regular Expression Reference" for syntax details. A device event contains multiple Key-Value sub-pattern pairs, which together describe the event in the common value types understood by MARS. The series of Key-Value sub-pattern pairs are concatenated in the order of their positions and used to match against the raw message in an event.
Note If the protocol is ICMP (a portless protocol), the source and destination ports are stored as 0 (zero.)
Step 8 Define a device event type.
Timesaver To show how to define a device even type, the following example presents the 12 patterns required to parse the example raw message below:
Example 15-1 Example Raw Message
Teardown TCP connection 1000 faddr 67.126.151.132/80 gaddr 198.133.219.28/43246 laddr
10.1.1.30/890 (sudha) duration 01:00:02 bytes 1000000 (TCP FINs)
a. First we click Add to input patterns.
In Example 15-1, we see, reading left to right, 12 keys and expected values for which patterns and value types can be defined:
Key
|
Expected Value
|
Common Value Type
|
Teardown
|
TCP
|
protocol
|
connection 1000 faddr
|
67.126.151.132
|
source address
|
/
|
80
|
source port
|
gaddr
|
198.133.219.28
|
destination address
|
/
|
43246
|
destination port
|
laddr
|
10.1.1.30
|
NAT destination address
|
/
|
890
|
NAT destination port
|
(
|
sudha
|
reported user
|
duration
|
01
|
session duration/hours
|
:
|
00
|
session duration/minutes
|
:
|
02
|
session duration/seconds
|
bytes
|
10000
|
transmitted bytes
|
Note A Key can be an empty string.
The Pattern Definition for Device Event Type: Log 1 page (shown below g.) appears.
Tip Steps b. through j. present an example of how to complete a Pattern Definition for the Device Event Type page.
b. The Position field identifies the order of the specified Key-Value sub-pattern when parsing the raw message from left to right, top to bottom. The parser allows arbitrary whitespace between Key and Value patterns and between Key-Value sub-patterns.
c. In Example 15-1, the first Key pattern on which to match is the string "Teardown". To match on this string, use a simple regular expression with no wildcards or repetitions.
Note The Key pattern is "Teardown", which means that when this pattern is found, the parser evaluates the next sequence to find the value to associate with this key.
d. Looking at the value to be paired with the Teardown key, we see "TCP", which identifies the protocol. This field type matches the common value type Protocol, which we select as the Parsed Field value.
e. The Value Type tells the parser what data type to expect, enabling suitable parsing action on the matching sub-pattern string. Selecting Protocol (String) as the value type indicates the protocol field is a string as defined in the file /etc/protocols in a UNIX system. In Example 15-1, "TCP" is the string captured by the Value pattern. In this example, the Value Type indicates that TCP is to be converted into its equivalent protocol number, 6.
f. The Pattern Name field lists the predefined regular expression patterns you can use to extract the value. Several common predefined patterns are defined for each common value type. In Figure 15-2, the value pattern captures all word-character strings that may also include the characters `-`, `/' and `+'.
g. When defining an event type, we do one of the following:
•To use a predefined pattern, we select a predefined pattern from the Pattern Name list, and click Submit.
•To define a custom pattern we perform the following steps:
a. Enter a name in the Or enter new field.
This name allows you to reuse this pattern when defining other device event types. Once it is defined, it will be associated with the value type selected in the Value Type field. You can select this pattern whenever that value type is selected.
b. Enter a description in the Description field.
c. Specify the regular expression pattern used to extract the value from the raw message in the Value Pattern field.
d. Click Submit to complete the Key-Value sub-pattern definition.
The key and value patterns are specified for the protocol.
Figure 15-2 Pattern Definition for Device Event Type (First Position)
Figure 15-3 Patterns for Device Event ID (First Position)
h. To define the Key-Value pair for the second position, we must define a more complicated regular expression. We click Add to begin defining the second pattern. The key pattern is not a simple string. In the example, we want to match on "connection 1000 faddr". To do this, we match first on the string connection and then match on any sequence of digits using the expression \d+. This expression is followed by the string faddr, which rounds out our key pattern match connection \d+ faddr.
Note The example includes the match for an optional plus or minus, [+-]?, in case the digits are signed. The plus or minus sign would have to appear in front of the digits for this pattern to be matched. The ? indicates that this pattern is optional.
The expected value is a source IP address, which we designate by selecting Source Address as the Parsed Field value. The example value is specified using standard dot notation and the address is IP version 4 so we can select IPV4 (Dotted Quad) as the pattern name and IPV4_DOTQUAD as the predefined pattern.
The key and value patterns are defined for the source IP address.
Figure 15-4 Pattern Definition for Device Event Type: Log1 (Second Position)
i. For the third position, we want to match the source port. The unique pattern we can use to match for the key is the forward slash that precedes the port number. The Value Type is Port (Number), which allows us to select the predefined Pattern Name of PORT_NUMBER.
The key and value patterns are defined for the source port.
Figure 15-5 Pattern Definition for Device Event Type: Log1 (Third Position)
j. For each key position in the raw message, we add a new pattern definition until we have defined all 12 key and value patterns.
Step 9 To complete a definition, click Submit.
Once the log template is defined and submitted, you must define a reporting device based on the custom device.
The new event type definition appears.
Editing a Device Type
You can edit a custom device type that is defined on MARS. To do so, select a custom device type under MANAGEMENT > Device Type Management, and then click Edit. This feature allows you to edit the following fields:
•type
•vendor
•model
•version
•description
•any device event type definitions (same as Edit Parser)
Overriding Existing Parsers
You can override existing parsers by navigating to MANAGEMENT > Device Type Management. A list of all device event types will appear.
Figure 15-6 Device Event Types
Select an existing device type and then click Edit Parser. A list of all device events will appear.
Figure 15-7 Device Events List
Select the device event to override, and then click Edit.
Figure 15-8 Device Event Types
You can walk through the pattern definitions to modify them as desired.
Tip Alternatively, you can override existing parsers by selecting an existing device type under MANAGEMENT > Device Type Management and then clicking Edit.The Device/Application Type Definition page appears, click Next. Select from the list of Device Event Types and click Edit.
Extending Existing Device Types
You can extend existing device types (or parsers) using one of the following methods on the MANAGEMENT > Device Type Management page:
•Derive From—You can select an existing device type and click Derive From to define a new device type/parser based on an existing definition. This method allows you to support incremental version updates or to classify the device type as a custom device type, which is distinguishable from the base device type.
•Add Device Event Type—You can select an existing device type and click Add Device Event Type to extend the current definition with additional device event type definitions. This method is useful when you want to support additional message types that were not supported by the original device type definition.
Note The benefit of extending an existing device type is that there is only one device type, so it is simple to manage. However, if there are different event formats for the same device event type to be parsed between an existing device type and a new device type, and you have both device types reporting to MARS, then we recommend that you derive from existing device type to create a new device type, and configure on the MARS GUI different device types for each of the reporting devices.
Add a Reporting Device based on a Custom Appliance Device Type
Adding custom appliance as a reporting device is similar to adding a predefined device type. You can select the appliance type directly from the Device Type list.
To add a reporting device based on a custom appliance device type, follow these steps:
Step 1 Click Admin > Security and Monitor Devices.
Step 2 Click Add to add a new device.
Step 3 Select the custom appliance type from the Device Type list.
Step 4 Complete the following fields and click Submit:
Tip The fields may vary depending on the appliance device type.
•Device Name—The name of the device.
•Reporting IP—The IP address that the reporting device will use to publish its event stream.
•Reporting Method—Select either SNMP TRAP or SYSLOG so as to match the event type generated by the reporting device. This option determines what type of traffic is processed by the custom device type parser.
Step 5 Click Done.
Add a Reporting Device based on a Custom Software Device Type
Adding a custom application as a reporting device is similar to adding a predefined application. You must first define a host and then add the custom application as a reporting application.
The following example adds an instance of the newly defined Apache Webserver1.1 software application.
To add a reporting device based on a custom software device type, follow these steps:
Step 1 Click Admin > Security and Monitor Devices.
Step 2 Click Add to add a new device.
Step 3 Select Add SW security apps on a new host from the Device Type list.
Step 4 Fill in name and other host details and click Apply.
Step 5 Click on Reporting Applications.
Step 6 Select Application (such as Apache Webserver.1.1) from the list and click Add.
Figure 15-9 Adding the Custom Application to MARS
Step 7 Select either SNMP TRAP or SYSLOG as the Reporting Method in the resulting window, and click Submit.
This option determines what type of traffic will be processed by the custom log parser.
Step 8 Click Done.
Import a Device Support Package
MARS is designed to share device support packages with standalone Local Controllers as well as with a Global Controller, which in turn pushes packages down to its managed Local Controllers. You can share device support by importing one or more device support packages that have been developed either within your organization or downloaded from the MARS forum on NetPro.
When you import a device support package, you import the settings that represent a custom device type, including the device type definition and the device event types and their associations with event type groups, rules, and reports.
To import a device support package, follow these steps:
Step 1 Click ADMIN > Custom Setup > Device Support Packages.
The Device Support Packages page appears.
Step 2 Click Import.
The input file name page appears.
Step 3 Specify the file to import either by typing the path and filename or by clicking Browse and navigating to the file. Then click Next.
Tip Alternatively, you can click Launch Package Sharing on Mars forum to launch a browser and explore the MARS Forum. There, you can select and download a device support package file. The file you download can then be imported. For more information on the forum, see Download a Device Support Package from the MARS Forum on NetPro.
Step 4 If the file is protected, a dialog box appears.
Enter the password for importing the package and then click Submit.
Tip At this time you can also enter the password for unlocking protected package data. This allows you to view the parser pattern data.
Step 5 The Import Summary page appears.
If you intend to import a subset of the device types defined in this package file, deselect any of the items that you do not want to import, and then click Import.
Tip You must select any device type from which a device type is derived. MARS checks for dependencies and does not allow you to deselect a device type if it is a parent or ancestor of a selected device type.
The device support package is imported. You can review the imported packaged by clicking ADMIN > Custom Setup > Device Support Packages.
Step 6 If the SHA-1 checksum of the package to be imported does not match the checksum contained within the data xml file, a warning appears:
Click Yes to continue.
The Import Success page appears.
Note The illustrations shown here are typical and are not indicative of a single particular import sequence.
Export a Device Support Package
To export a device support package, you must select the device type or types to export, identify what you want to include in the export, describe the package, and then download the files to an external server. Once you have exported a package, you can import it into a standalone Local Controller or Global Controller.
Before You Begin
Before you can export a device support package, you must have defined the following:
•A custom device type
•One or more custom event types
•One or more user inspection rules
•One or more user reports
•Associations between custom event types and existing system event type group.
•A policy for sharing—or protecting—the device support package.
To export a device support package, follow these steps:
Step 1 Click ADMIN > Custom Setup > Device Support Packages.
The Device Support Packages page appears.
Step 2 Click to select the package file to export.
The Choose items to export page appears.
Step 3 Select the items to export and click Next.
Note In this procedure example we'll select device type. Similar steps occur regardless of the items exported.
The Choose Device Types To Export page appears
Step 4 Select the device types to export and click Next.
Tip You can filter the device types listed by using the Search field or the Select Provider list.
The Export Summary page appears.
Step 5 Verify the summary information and click Next to proceed, or click Back to return to the Device Support Packages page.
•Total Number of Providers—Identifies the number of providers included in this group. This number should be 1 unless you have modified a Cisco-provided device type or have imported device types (and have chosen to export one of those devices) from another Local Controller or provider, such as the MARS forum on NetPro website.
•Total Number of Devices—Identifies the number of custom devices that you have chosen to export in this package.
•Total Number of Device Event Types—Identifies the total number of custom device event types that have been selected. This number is taken from each device selected, where the events are those associated with each device.
•Total Number of Event Types—Identifies the number of system event types that were mapped to the devices that are being exported.
•Total Number of Event Type Groups—Identifies the number of event type groups that include one or more of these custom device event types.
The Package Details page appears.
Step 6 Enter values for the following fields:
•Package File Name—Identifies the name of the file to be created. An example filename is test.zip.
•Package Name—Identifies the name of the package, which will appear in the list of installed packaged on a MARS Appliance that has imported this package.
•Version—Identifies the version number of the custom package. You must revise each exported version.
•Package Description—Summarizes the contents of the package, such as the device types that are included in the package. This field appears in the list of installed packages on a MARS Appliance that has imported this package.
Step 7 To protect the package from unauthorized use, perform the following steps
a. Select Protect Package.
Tip You can choose to protect the package from being imported, from its parser patterns being decrypted, or both.
b. To protect the package from being imported enter a password and then confirm the password entry.
c. To protect the parser patterns from being decrypted, enter a password and then confirm the password entry.
Step 8 Click Export
The Export Success page appears.
Figure 15-10 Export Success Page: Package File Name of Test
Step 9 To download the package to a local computer or to a central server/repository, click on the filename to download the package. If you want to publish this package on MARS forum on NetPro, download the package header file.
Note The header file is only needed if you want to upload this package on MARS forum on NetPro, which requires separate DSF pkg and header files. For more information, see MARS Forum on NetPro: An Overview.
Step 10 Once you have downloaded the needed files, click Done to close the Export page.
Remove an Installed Device Support Package
You can remove a custom device support package that is installed on a MARS Appliance. When removing a package, all imported information remains, only the package itself is removed. Therefore, the ability of the MARS Appliance to parse any events received from a reporting device of that type remains.
To access this page, select ADMIN > Custom Setup > Device Support Packages.
To remove an installed device support package, follow these steps:
Step 1 Select the check box next to the package that you want to remove.
Step 2 Click Delete.
The Confirm Delete page appears.
Step 3 To confirm the deletion, click Yes.
Events and Reports About Device Support Package Activities
The following events appear in the Info/Misc/CS-MARS-DSF-Activity event group and are summarized in the report titled Activity: CS-MARS importing/exporting DSF packages:
Normalized Event type: 1000083,
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100071
Name: CS-MARS-DSF successfully imported a package from a provider
Normalized Event Type: 1000084
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100072
Name: CS-MARS-DSF failed to import a package from a provider
Normalized Event Type: 1000085
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100073
Name: CS-MARS-DSF successfully exported a package
Normalized Event Type: 1000086
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100074
Name: CS-MARS-DSF failed to export a package
Normalized Event Type: 1000087
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100075
Name: CS-MARS-DSF started importing a package from a provider
Normalized Event Type: 1000088
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100076
Name: CS-MARS-DSF started exporting a package
Normalized Event Type: 1000089
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100077
Name: CS-MARS-DSF inserted provider information in provider table
Normalized Event Type: 1000090
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100078
Name: CS-MARS-DSF updated provider information in provider table
Normalized Event Type: 1000091
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100079
Name: CS-MARS-DSF inserted device type information in device type table
Normalized Event Type: 1000092
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100080
Name: CS-MARS-DSF updated device type information in device type table
Normalized Event Type: 1000093
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100081
Name: CS-MARS-DSF inserted event type information in event type table
Normalized Event Type: 1000094
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100082
Name: CS-MARS-DSF updated event type information in event type table
Normalized Event Type: 1000095
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100083
Name: CS-MARS-DSF inserted device event type information in device event type table
Normalized Event Type: 1000096
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100084
Name: CS-MARS-DSF updated device event type information in device event type table
Normalized Event Type: 1000097
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100085
Name: CS-MARS-DSF inserted pattern type information in pattern type table
Normalized Event Type: 1000098
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100086
Name: CS-MARS-DSF updated pattern type information in pattern type table
Normalized Event Type: 1000099
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100087
Name: CS-MARS-DSF inserted event type group information in event type group table
Normalized Event Type: 1000100
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100088
Name: CS-MARS-DSF updated event type group information in event type group table
Normalized Event Type: 1000101
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100089
Name: CS-MARS-DSF inserted inspection rule information in inspection rule table
Normalized Event Type: 1000102
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100090
Name: CS-MARS-DSF updated inspection rule information in inspection rule table
Normalized Event Type: 1000103
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100091
Name: CS-MARS-DSF inserted report information in report table
Normalized Event Type: 1000104
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100092
Name: CS-MARS-DSF updated report information in report table
Normalized Event Type: 1000105
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100093
Name: CS-MARS-DSF inserted inspection rule group information in inspection rule group table
Normalized Event Type: 1000106
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100094
Name: CS-MARS-DSF updated inspection rule group information in inspection rule group table
Normalized Event Type: 1000107
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100095
Name: CS-MARS-DSF inserted report group information in report group table
Normalized Event Type: 1000108
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100096
Name: CS-MARS-DSF updated report group information in report group table
Normalized Event Type: 1000109
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100097
Name: CS-MARS-DSF inserted relationship between event type group to event type
Normalized Event Type: 1000112
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100100
Name: CS-MARS-DSF inserted relationship between inspection rule group to inspection rule
Normalized Event Type: 1000115
Device Event Type: Protego Networks, MARS, 1.0: MARS-3-100103
Name: CS-MARS-DSF inserted relationship between report group to report
MARS Forum on NetPro: An Overview
Device support packages are posted to and downloaded from the Package Sharing page of the MARS forum at the Networking Professionals Connection (NetPro) forum on Cisco.com. The packages uploaded to the Package Sharing page can be
Tip The MARS Forum on NetPro also offers discussion threads, news, and support from Cisco experts in various specialities.
This section contains the following topics:
•Uploading a Device Support Package to the MARS Forum
•Download a Device Support Package from the MARS Forum on NetPro
•Subscribe to Package Sharing Page of the MARS Forum
Uploading a Device Support Package to the MARS Forum
Uploading a device support package file to the NetPro MARS Forum consists of two basic steps:
•Accepting the license agreement
•Selecting and uploading the device support package file
To upload a device support package, follow these steps:
Step 1 Prepare a device support package file for uploading.
Step 2 Log on to Cisco.com.
Tip If you have not registered at this site, you'll have to do that.
Step 3 Navigate to the Networking Professionals Connection (NetPro).
Step 4 Select MARS from the menu on the left.
The MARS forum options display.
Step 5 Select Package Sharing
The Package Sharing page displays.
Step 6 Click Upload Package (located on the right of the bar above the table headings).
The Step 1 of 2 of Upload Package: Approve License page appears.
Step 7 Enter the Copyright Owner Name/Company and the Copyright year in the fields provided.
Step 8 Read the License Agreement text. Select Agree. Then click Next.
The Step 2 of 2 of Upload Package: Select File to Upload page appears.
Step 9 Click Browse to select the file, and then click Upload.
Download a Device Support Package from the MARS Forum on NetPro
To download a device support package, follow these steps:
Step 1 Log on to Cisco.com.
Tip If you have not registered at this site, you'll have to do that.
Step 2 Navigate to the Networking Professionals Connection (NetPro).
Step 3 Select MARS from the menu on the left.
The MARS forum options display.
Step 4 Select Package Sharing
The Package Sharing page displays.
Step 5 Select and click on a package to download.
To more easily view the packages available, you can sort the listing of packages by clicking on most of the table headings, which include for each package:
•Name—the name of the package
•Ver—the version number of the package
•Description—the package description (not a sort field)
•Provider ID—the ID of the package provider
•Date posted—the date the package was posted
•Rating—The rating given to the package by NetPro Forum users
•[downloads]—the number of times the package has been downloaded
The package page appears, showing the posted by and date headings as well as the contents of the package's parameters.
Step 6 After examining the package's parameters to determine its suitability, click the download symbol at the bottom of the package display page.
Step 7 After downloading and unzipping the device support package, you can import it into Mars. For more details see Import a Device Support Package
Subscribe to Package Sharing Page of the MARS Forum
You can subscribe to the Package Sharing Page of the MARS Forum to receive notice when new device support packages are posted.
To subscribe to the Package Sharing Page of the MARS Forum, follow these steps:
Step 1 Log on to Cisco.com.
Tip If you have not registered at this site, you'll have to do that.
Step 2 Navigate to the Networking Professionals Connection (NetPro).
Step 3 Select MARS from the menu on the left.
The MARS forum options display.
Step 4 Select Package Sharing
The Package Sharing page displays.
Step 5 Click Subscribe (located on the right of the bar above the table headings).
Example Custom Device Type: Custom Software Application
You can define a custom software application and add it to the MARS environment.
To define a new custom software application, follow these steps:
Step 1 Click MANAGEMENT > Device Type Management.
The Device Type Management list appears.
Step 2 Click Add.
Figure 15-11 Example: New software based Apache Webserver application.
Figure 15-12 Example: Definition for Apache Webserver1.1
Step 3 Define the log template for a HTTP Status OK log message. And associate a system defined event type. In order to find the event type, specify the search string `HTTP Status' and find it defined as above.
Step 4 The parsing patterns for `HTTP Status OK' are specified to match the following example raw message reported in an event.
155.98.65.40 - - [21/Nov/2004:21:08:47 -0800] "GET /~shash/ HTTP/1.0" 200 1633 "-" "Lynx/2.8.2rel.1 libwww-FM/2.14"
Figure 15-13 Example: Key Pattern for HTTP Status OK
Step 5 The key pattern is empty above since the log message starts with a value pattern.
Figure 15-14 Example: Position 2 Key Pattern for HTTP Status OK
Step 6 The Parsed Field above is a Date/Time field. In addition to Value Pattern, a value format is required since a date/time can be specified in arbitrarily different ways. Details on how to specify the value format are given in Appendix F. Several pattern names with a few of the commonly used date/time formats have been predefined.
Figure 15-15 Example: Position 3 Key Pattern for HTTP Status OK
Figure 15-16 Example: Pattern log for HTTP Status OK
Figure 15-17 Example: User Defined Log Parser for Apache Webserver1.1
After the log template is defined and submitted, you must define a reporting device based on the custom device. For more information, see Add a Reporting Device based on a Custom Appliance Device Type.
