Abstract

1.0 Overview

The Security Device Event Exchange (SDEE) is a specification for the message formats and the messaging protocol used to communicate the events generated by security devices. SDEE is designed to be flexible in order to allow vendors to extend the standard in such way that extended implementations are compatible with standard implementations and other extended implementations.

vendor specified filter criteria for selecting the events to be retrieved from SDEE providers

Cisco Intrusion Detection Event Exchange (CIDEE) specifies the extensions to SDEE that are utilized by Cisco Intrusion Prevention System (IPS) products. The CIDEE standard specifies the extensions that may be supported by Cisco IPS products. Specific products may implement a subset of CIDEE extensions. However, any extension that is designated as being required MUST be supported by all Cisco IPS products.

2.0 CIDEE Events

CIDEE specifies the Cisco IPS specific security device events as well as the Cisco IPS extensions to SDEE's evIdsAlert element in the CIDEE schema documentation. Each type of event element reported by CIDEE systems uses the vendor attribute to identity the vendor originating the alert. All CIDEE providers must useCisco for the first five letters of the vendor attribute's value.

2.1 CIDEE Specific Events

The SDEE standard supports the inclusion of vendor specified security device event elements as children of the SDEE events element. CIDEE defines the following security device event elements. Cisco IPS products may optionally report any or all of the Cisco IPS specific security device event elements.

Event element

<evError>

Description

Error event

Purpose

Generated by the CIDEE provider when the provider detects an error or warning condition. The <evError> event contains error code and textual a description of the error.

Event element

<evStatus>

Description

Status message event

Purpose

Generated by CIDEE providers to indicate that something of potential interest occurred on the host. Different types of status messages may be reported in the status event  one message per event. Each type of status message may contain a set of data elements that are specific to the type of occurrence that the status message is describing. The information in many of the status messages may be useful for audit purposes. Note that errors and warnings are not considered status information and should be reported using <evError> rather than <evStatus>.

Content

The <evStatus> event contains a message specific element that is derived from the AbstractStatusDetail type and is a member of the statusDetail substitution group - see the CIDEE schema documentation for more details.

Event element

<evShunRqst>

Description

Shun request event

Purpose

This event is generated to indicate that a shun action is to be initiated by the service that handles network shunning.

The CIDEE specific events identified in this section are qualified with the CIDEE schema's namespace. Qualifying the CIDEE specific events with the CIDEE schema's namespace ensures that the qualified names of these events will not clash with the names of extension events used by other vendors.

2.2 CIDEE Extensions to SDEE's evIdsAlert Event

In addition to specifying CIDEE specific event types, the CIDEE schema documentation specifies the extensions to SDEE's evIdsAlert element that are utilized by Cisco IPS products. The XML file, cidee-ex1.xml, shows an example of the evIdsAlert event information returned by a Cisco IPS product.

The evIdsAlert element has a child element named signature. CIDEE restricts the use of the use signature element's id attribute. The SDEE schema specifies that id the attribute's value may be a string. However, Cisco IPS products shall use a value that is a textual representation of a numeric value with the range 0-65535. The purpose of this restriction is to support clients that rely on the signature id being a numeric value. For example, some clients use this numeric signature id as a database index.

3.0 CIDEE Specific Request Parameters

SDEE specifies the request parameters that clients may use to affect the retrieval of information from SDEE providers. The SDEE standard allows vendors to specify their own unique request parameters. Vendor specified request parameters can be used by clients to tune the retrieval of information in a way that is tailored to the provider's system. CIDEE specifies the following request parameters that may be used by Cisco IPS clients to affect the retrieval of information from Cisco IPS providers.

3.1 Additional Action Values

SDEE uses the action request parameter to specify the action to be performed by the SDEE provided. The SDEE specification specifies the core set of actions supported by SDEE providers. This section specifies an optional set of extension actions that may be support by Cisco intrusion prevention products. A SOAP fault with the subcode value "errUnacceptableValue" will be returned in the response in case the requested extension action is not supported by a particular product. The following optional extension actions are specified for Cisco intrusion prevention products.

queryEventCount

This action value requests that the SDEE provider return the number of events currently available on the provider that match the event query parameters specified in the request. The SDEE and CIDEE event query parameters may be included in the request to specify the criteria for the events to be counted. The number of matching events is returned in the eventCount element which is a child of the SOAP body element as specified by the CIDEE schema.

3.2 Event Retrieval Request Parameters

Clients use SDEE query or subscription retrieval requests to retrieve events from SDEE compliant providers. SDEE providers that implement CIDEE extensions may support the use of following request parameters for clients to specify the criteria for the events to be retrieved. Clients specify the event retrieval criteria in the SDEE query request or the SDEE subscription-open request.

The event criteria parameters serve to limit which events are retrieved from an IPS. The event criteria parameters are grouped by event type as follows.

3.2.1 Alert Event Request Parameters

The following request parameters can be used to restrict the retrieval of alert events. The retrieval of other types of events is not affected by the following request parameters.

mustHaveAlarmTraits

This token specifies the minimum set of alarm traits that an evIdsAlert event must have in order to be retrieved.

An alarm trait is a decimal value in the range 0-31 that may be associated with zero or more alert signature types. Each alert signature type may have zero or more associated alarm traits. An evIdsAlert event will have all alarm traits that are associated with the event's signature type. Different products implementing the CIDEE standard may support a smaller range of traits.

Only evIdsAlert events that have all of the alarm traits in the list of alarm traits specified by the mustHaveAlarmTraits' value may be retrieved. See the alarm traits' HTTP BNF specification for more information. While the events to be retrieved must have all of the required alarm traits, events with additional alarm traits may also be retrieved.

mustNotHaveAlarmTraits

This token specifies the set of alarm traits that an evIdsAlert event must not have in order to be retrieved. Only evIdsAlert events that have none of the alarm traits in the list of alarm traits specified by the mustHaveAlarmTraits' value may be retrieved. See the virtual sensors HTTP BNF specification for more information.

minThreatRating and maxThreatRating

This token limits the retrieval of evIdsAlert events to those events that have threat rating values in the range specified by the minThreatRating and maxThreatRating values. The minThreatRating value specifies the minimum threat rating value that events must have to be retrieved. The maxThreatRating value the maximum threat rating value that events must have to be retrieved. Each parameter must have a numeric value in the range 0-100 (inclusive). When not specified, the default minThreatRating value is zero, while the default maxThreatRating value is 100.

virtualSensors

This token specifies the list of virtual sensors from which events may be retrieved. When this token is included in the request, only evIdsAlert events originating from a virtual sensor in the list will be retrieved. When the token in omitted, events will be retrieved from all virtual sensors. The virtual sensor list consists of one or more virtual sensor names concatenated together using the '+' character. See the virtual sensor list HTTP BNF specification for more information.

The alarm traits set is specified, in a request parameter's value, as a collection of individual alarm trait values concatenated using the "+" character. Alarm trait values in the set can also be expressed as a range of traits with the lesser trait value preceding the "-" character followed by the greater trait value. The set can consist of a mix of individual trait values and ranges of trait values concatenated together. For example, a set of alarm traits consisting of the trait values 1, 3, 5, 6, 7 and 9 could be expressed as 1+3+5-7+9. If the mustHaveAlarmTraits parameter had this example set of alarm traits as its value, then only events that have all of the alarm traits in the set could be retrieved. Similarly, if the mustNotHaveAlarmTraits parameter had this example set of alarm traits as its value, then only events that did not have any of the alarm traits in the set could be retrieved. Note that the set of alarm traits is expressed differently in the event data from how it is expressed as a request parameter value. The CIDEE schema documentation specifies how the set of alarm traits is expressed in the event data.

3.2.2 Error Event Request Parameters

The following request parameters can be used to restrict the retrieval of error events. The retrieval of other types of events is not affected by the following request parameters.

errorSeverities

This token limits the retrieval of evError events to those events that have a severity that is specified in the set of severities specified by the errorSeverities' value. See the error severities' HTTP BNF specification for more information.

3.2.3 Status Event Request Parameters

The following request parameters can be used to restrict the retrieval of status events. The retrieval of other types of events is not affected by the following request parameters.

The annotation for each status event in the CIDEE schema indicates which status category or categories the event belongs to.

Because it is redundant to include both of these parameters in a request, clients should only include one of these parameters in a request.

3.2.4 Combined Event Criteria in a Request

The event criteria parameters for each type of event can be combined together to form the overall event criteria. Clients may specify the event retrieval criteria using both the CIDEE specific request parameters and the request parameters specified in the SDEE standard. Only events that meet all of the query criteria will be retrieved.

SDEE providers may optionally process any or all of the CIDEE specific event retrieval criteria.

3.3 HTTP BNF for Request Parameters

In the HTTP protocol binding, request parameters are communicated in the query portion of the HTTP request's URI line. The syntax for the URI line is specified using a BNF language with the extensions specified in RFC 2616.

The following extended BNF specifies the syntax of the CIDEE specific request parameters: