Cisco Intrusion Detection Event Exchange (CIDEE) Specification
Cisco Intrusion Detection Event Exchange (CIDEE) Specification
copyright 2001-2009 Cisco Systems, Inc.
Revised 08-Dec-2009
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 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.
SDEE supports the following types of vendor extensions:
- vendor specified security device event types
- vendor specified extension elements and attributes to existing SDEE XML elements
- 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 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. 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.
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.
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 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.
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.
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.
Retrieve only status events that belong to one or more of the status event categories specified by this parameter. See the include status categories BNF specification.
Do not retrieve status events that belong to one or more of the status event categories specified by this parameter. See the exclude status categories BNF specification.
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:
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
| uri-es-virtual-sensors-pair
| uri-es-include-status-categories
| uri-es-exclude-status-categories )
[ "&" 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
uri-es-virtual-sensors-pair = "virtualSensors"
"=" uri-es-virtual-sensor-list
uri-es-virtual-sensor-list = uri-es-virtual-sensor-name
[ "+" uri-es-virtual-sensor-list ]
uri-es-virtual-sensor-name = +uri-es-virtual-sensor-name-chars ; 64 character limit
uri-es-virtual-sensor-name-chars = alphanum | "-" | "_"
uri-es-status-category = "executionStatus"
| "upgradeStatus"
| "interfaceStatus"
| "notification"
| "configChange"
| "accounting"
| "sensing"
| "health"
| "system"
| "controlTransaction"
| "misc"
uri-es-status-category-list = uri-es-status-category [ "+" uri-es-status-category-list ]
uri-es-include-status-categories = "includeStatusCategories" "=" uri-es-status-category-list
uri-es-exclude-status-categories = "excludeStatusCategories" "=" uri-es-status-category-list
alphanum = alpha | digit
alpha = lowalpha | upalpha
lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" |
"i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" |
"q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" |
"y" | "z"
upalpha = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" |
"I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" |
"Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" |
"Y" | "Z"
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
"8" | "9"
Security Device Event Exchange (SDEE) Specification, version 2008/04 (available upon request)
CIDEE schema document - cidee.xsd
Graphical Representation of the CIDEE schema
Hypertext Transfer Protocol -- HTTP/1.1 (PDF)
Revision History:
08-Dec-2009
1. Updated the CIDEE schema to include these new elements added to evIdsAlert in Cisco IPS versions 7.0(1), 7.1(1), and E4 engine updates:
a. globalCorrelation - introduced in version 7.0(1).
b. modifiedPacket - introduced in the E4 engine.
c. AlertTrigger - introduced in version 7.1(1).
2. Corrected some schema elements to match the Cisco IPS implementation.
a. Reversed the order of the deniedAttackerVictimPair and deniedAttackerServicePair elements.
b. Moved the threatRatingValue element to before interface.
c. Added the type and created attributes to the signature element.
3. Added a graphical representation of the CIDEE schema to the Reference Documents section of this document.
4. Removed the hypertext link to the SDEE specification in the Reference Documents section because it is no longer published by ICSA