Cisco Intrusion Detection Event Exchange (CIDEE) Specification

copyright 2001-2006 Cisco Systems, Inc.

Revised 30-August-2006


Abstract

Cisco Intrusion Detection Event Exchange (CIDEE) specifies the extensions to the Security Device Event Exchange (SDEE) that are utilized by Cisco's network-based intrusion prevention systems.


1.0 Overview

The Security Device Event Exchange (SDEE) is a specification for the format of the messages as well as the 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.

SDEE supports the following types of vendor extensions:

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

2.0 CIDEE Events

CIDEE specifies the CID specific security device events as well as the CID 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 use Cisco 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. CID systems may optionally report any or all of the CID 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 CID providers. The XML file, cidee-ex1.xml, shows an example of the evIdsAlert event information returned by a CID provider.

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, CID providers 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 CID clients to affect the retrieval of information from CID 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.

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.

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.

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 alarm traits' HTTP BNF specification for more information.

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.

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.

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.

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:

request-parameters  = ( 
                   uri-es-query-event-count-pair
                   | uri-es-error-sev-pair
                   | uri-es-min-threat-rating-pair
                   | uri-es-max-threat-rating-pair
                   | uri-es-must-have-alarm-traits-pair
                   | uri-es-must-not-have-alarm-traits-pair )
                   [ "&" request-parameters ] 
; note: each pair item may appear no more than once in request-parameters
  
uri-es-query-event-count-pair = "action=queryEventCount"
                                     
uri-es-error-sev-pair = "errorSeverities" "=" uri-es-error-sev-list
uri-es-error-sev-list = uri-es-error-sev | uri-es-error-sev-list 
                        "+" uri-es-error-sev
uri-es-error-sev      = "warning"	
                      | "error"
                      | "fatal"

uri-es-min-threat-rating-pair = "minThreatRating" 
                                "=" uri-es-threat-rating-value
                                     
uri-es-max-threat-rating-pair = "maxThreatRating" 
                                "=" uri-es-threat-rating-value
                                     
uri-es-threat-rating-value = 1*2digit ; decimal value in the range 0-100

uri-es-must-have-alarm-traits-pair = "mustHaveAlarmTraits" 
                                     "=" uri-es-alarm-traits-list

uri-es-alarm-traits-list = uri-es-alarm-trait
                   | uri-es-alarm-trait-range
                   [ "+" uri-es-alarm-traits-list ]
uri-es-alarm-trait    = 1*2digit ; decimal value in the range 0-31
; different products implementing the CIDEE standard may support a smaller range of traits

uri-es-alarm-trait-range = uri-es-alarm-trait "-" uri-es-alarm-trait
; the uri-es-alarm-trait on the left-hand side of the minus sign in the
; uri-es-alarm-trait-range must have a numeric value that is less than 
; or equal to the uri-es-alarm-trait on the right-hand side

uri-es-must-not-have-alarm-traits-pair = "mustNotHaveAlarmTraits" 
                                         "=" uri-es-alarm-traits-list

digit  = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
          "8" | "9"

Reference Documents

Security Device Event Exchange (SDEE) Specification

CIDEE schema document - cidee.xsd

Hypertext Transfer Protocol -- HTTP/1.1 (PDF)