copyright 2001-2006 Cisco Systems, Inc.
Revised 30-August-2006
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.
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.
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.
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.
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.
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.
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.
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.
mustHaveAlarmTraits
- Restricts the retrieval of
evIdsAlert
events. 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 themustHaveAlarmTraits
' 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
- Restricts the retrieval of
evIdsAlert
events. This token specifies the set of alarm traits that an
evIdsAlert
event must not have in order to be retrieved. OnlyevIdsAlert
events that have none of the alarm traits in the list of alarm traits specified by themustHaveAlarmTraits
' value may be retrieved. See the alarm traits' HTTP BNF specification for more information.
errorSeverities
- Restricts the retrieval of
evError
events. 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 theerrorSeverities
' value. See the error severities' HTTP BNF specification for more information.
minThreatRating
and maxThreatRating
- Restricts the retrieval of
evIdsAlert
events.This token limits the retrieval of
evIdsAlert
events to those events that have threat rating values in the range specified by theminThreatRating
andmaxThreatRating
values. TheminThreatRating
value specifies the minimum threat rating value that events must have to be retrieved. ThemaxThreatRating
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 defaultminThreatRating
value is zero, while the defaultmaxThreatRating
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.
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"
Security Device Event Exchange (SDEE) Specification