User Guide for Cisco Security MARS Local Controller, Release 4.2.x - Cisco Security MARS XML API Reference [Cisco Security Monitoring, Analysis and Response System]

Table Of Contents

Cisco Security MARS XML API Reference

XML Schema Overview

XML Incident Notification Data File and Schema

XML Incident Notification Data File Sample Output

XML Incident Notification Schema

Usage Guidelines and Conventions for XML Incident Notification

Cisco Security MARS XML API Reference

This appendix provides resources for creating XML applications that integrate Cisco Security MARS XML data into third-party applications.

XML Schema Overview

The XML schema are written in conformance with the standard World Wide Web Consortium (W3C) XML schema language. A schema by definition, describes all data and data structures required to create your application. Many XML development environments provide enough capability to view the schema in a way that you can identify all components, their relationships, constraints, attributes, annotations, and usage guidelines at a glance. Some applications generate hyperlinked reference documentation. By providing sufficient documentation and annotation tags within the schemas, Cisco supports such documentation generating applications.

Table A-1 lists resources for XML development.

Table A-1 XML Resources

Resource Description

URL

W3C XML Schema standards forum with resource links

http://www.w3.org/XML/Schema

General XML description with resource links

http://en.wikipedia.org/wiki/Xml

Online XML Tutorials

http://www.w3schools.com/xml/default.asp

XML Incident Notification Data File and Schema

XML incident notification sends an email notification of an incident with an attached XML data file. The XML data file contains all incident details that can be viewed on the GUI except for Path/Mitigation data. The XML data file can be sent as a plain-text file or as a compressed gzip file. The filename is constructed with the incident ID number, for example CS-MARS-Incident-13725095.xml. The compressed version of the same data file would be CS-MARS-Incident-13725095.xml.gz

An XML application can be written to parse and extract data from the XML incident notification data file for integration into third-party software, such as a trouble ticketing system, or helpdesk software.

Table A-2 lists the documentation for the Cisco Security MARS XML incident notification feature.

Table A-2 Related XML Incident Notification Documents

Resource Description

Resource Location

Configuring XML incident notification on MARS

Chapter 22, "Sending Alerts and Incident Notifications"

A ZIP file containing the XML incident notification schema

http://www.cisco.com/en/US/products/ps6241/prod_technical_reference_list.html

A hyper-linked component reference, generated from the XML incident notification schema

http://www.cisco.com/en/US/products/ps6241/prod_technical_reference_list.html

Sample XML incident notification data generated by MARS

"Cisco Security MARS XML API Reference" Example A-1

XML Incident Notification Data File Sample Output

Example A-1 is XML incident notification data generated by the events that trigger the rule "CS-MARS Database Partition Usage."

Example A-1 XML Incident Notification Data File Contents
<?xml version="1.0" encoding="UTF-8"?>
<CSMARS-NOTIFICATION>
  <Header>
    <Version>1.0</Version>
    <GenTimeStamp>May 15, 2006 8:48:02 AM PDT</GenTimeStamp>
    <CSMARSHostIpAddr_eth0>10.2.3.7</CSMARSHostIpAddr_eth0>
    <CSMARSHostIpAddr_eth1>192.168.1.101</CSMARSHostIpAddr_eth1>
    <CSMARSHostName>MyLatest</CSMARSHostName>
    <CSMARSZoneName />
    <CSMARSVersion>4.2.1</CSMARSVersion>
  </Header>
  <Data>
    <Incident id="597842933">
      <StartTime>May 15, 2006 8:47:26 AM PDT</StartTime>
      <EndTime>May 15, 2006 8:47:26 AM PDT</EndTime>
      <Severity>LOW</Severity>
      <Session id="597744001">
        <Instance>0</Instance>
        <RuleOffset>1</RuleOffset>
        <SessionEndPoints>
          <Source ipaddress="0.0.0.0" />
          <Destination ipaddress="10.2.3.7" />
          <SourcePort>0</SourcePort>
          <DestinationPort>0</DestinationPort>
          <Protocol>-1</Protocol>
        </SessionEndPoints>
        <Event id="597744001">
          <EventType id="125755" />
          <TimeStamp>May 15, 2006 8:47:26 AM PDT</TimeStamp>
          <ReportingDevice id="50" />
          <RawMessage>Mon May 15 08:47:26 PDT 2006 &lt;13&gt;%MARS-3-100026 CS-MARS 
MyLatest : Current database partition pn_event_session_8 utililization has reached 75%; 
next database partition pn_event_session_9 containing data between Thu Apr 20 11:59:13 PDT 
2006 and Fri Apr 21 11:32:17 PDT 2006 will be purged approximately at Mon May 15 11:56:02 
PDT 2006.</RawMessage>
          <FalsePositiveType>NOT_AVAILABLE</FalsePositiveType>
          <EventEndPoints>
            <Source ipaddress="0.0.0.0" />
            <Destination ipaddress="10.2.3.7" />
            <SourcePort>0</SourcePort>
            <DestinationPort>0</DestinationPort>
            <Protocol>-1</Protocol>
          </EventEndPoints>
          <NATtedEndPoints>
            <Source ipaddress="0.0.0.0" />
            <Destination ipaddress="10.2.3.7" />
            <SourcePort>0</SourcePort>
            <DestinationPort>0</DestinationPort>
            <Protocol>-1</Protocol>
          </NATtedEndPoints>
          <FiringEventFlag>true</FiringEventFlag>
        </Event>
      </Session>
      <Rule id="134473">
        <Name>System Rule: CS-MARS Database Partition Usage</Name>
        <Description>This rule indicates that the current CS-MARS database partition 
filled up to 75% of its capacity and the next database partition will be purged soon to 
create space for new events. The estimated purge times are in the event message. This is 
normal CS-MARS activity and will result in old events and incidents to purged from CS-MARS 
database. Users are urged to archive CS-MARS data to prevent permanent data 
loss.</Description>
      </Rule>
      <NetworkAddressObj id="0">
        <IPAddress>0.0.0.0</IPAddress>
        <MAC />
        <DNSName />
        <DynamicInfo>
          <HostName />
          <MACAddress />
          <AAAUser />
          <EnforcementDeviceAndPort />
          <ReportingDevice />
          <StartTime>Dec 31, 1969 4:00:00 PM PST</StartTime>
          <EndTime>Dec 31, 1969 4:00:00 PM PST</EndTime>
          <UpdateTime>Dec 31, 1969 4:00:00 PM PST</UpdateTime>
        </DynamicInfo>
      </NetworkAddressObj>
      <NetworkAddressObj id="167904007">
        <IPAddress>10.2.3.7</IPAddress>
        <MAC>
          <MACAddress>00:30:48:83:25:d9</MACAddress>
          <LastUpdateTime>May 15, 2006 6:59:09 AM PDT</LastUpdateTime>
        </MAC>
        <DNSName>MyLatest</DNSName>
        <Device id="50" />
        <DynamicInfo>
          <HostName />
          <MACAddress />
          <AAAUser />
          <EnforcementDeviceAndPort />
          <ReportingDevice />
          <StartTime>Dec 31, 1969 4:00:00 PM PST</StartTime>
          <EndTime>Dec 31, 1969 4:00:00 PM PST</EndTime>
          <UpdateTime>Dec 31, 1969 4:00:00 PM PST</UpdateTime>
        </DynamicInfo>
      </NetworkAddressObj>
      <EventTypeObj id="125755">
        <Name>1000029</Name>
        <Description>CS-MARS DB partition filling up causing the next partition to be 
purged soon</Description>
        <Severity>LOW</Severity>
        <CVE />
      </EventTypeObj>
      <DeviceObj id="50">
        <Name>MyLatest</Name>
        <NetBiosName />
        <DefaultGateway>10.2.3.1</DefaultGateway>
        <OperatingSystem id="0" />
        <InterfaceAddressObj id="117924">
          <Name>eth0</Name>
          <IPAddress>10.2.3.7</IPAddress>
          <MAC>
            <MACAddress>00:30:48:83:25:d9</MACAddress>
            <LastUpdateTime>May 15, 2006 6:59:09 AM PDT</LastUpdateTime>
          </MAC>
        </InterfaceAddressObj>
        <InterfaceAddressObj id="123040">
          <Name>eth1</Name>
          <IPAddress>192.168.1.101</IPAddress>
          <MAC />
        </InterfaceAddressObj>
      </DeviceObj>
    </Incident>
  </Data>
</CSMARS-NOTIFICATION>
XML Incident Notification Schema

The XML incident notification schema document (csmars-incident-notification-v1_0.xsd) can be downloaded from the the following URL:

http://www.cisco.com/en/US/products/ps6241/prod_technical_reference_list.html

Usage Guidelines and Conventions for XML Incident Notification

All XML incident notification elements are defined in the XML incident notification schema. A WinZip archive containing a component reference document generated from the schema is available for your convenience at the following URL:

http://www.cisco.com/en/US/products/ps6241/prod_technical_reference_list.html

You can generate a similar document with the application of your choice, or view components, their relationships, constraints, attributes, annotations, and usage guidelines within your XML development environment.

MARS uses a best effort approach to create XML incident notification data. If an error occurs during data compilation, MARS does not stop the process, but sends the data, even if it is partial. Validating the data file against the schema would result in errors for these cases.

The following conventions are observed for XML incident notification data:

•Character encoding is Unicode Transformation Format 8 (UTF-8)

•The reported time zone would be the time zone of the local controller reporting the incident

•Raw messages from reporting devices are XML-escaped in the data file. Your XML parser should be able to unescape XML data.

•If there is no value for an element available from MARS, the element is included in the data file as an empty node. For instance, a DNS name may not be available for a device.

•All date formats are Mmm dd, yyyy hh:mm:ss AM TZD

–Mmm is the month (Jan, Feb, Mar. . . Dec)

–dd is the day (1-9, 10-31)

–yyyy is the year (0000-9999)

–hh:mm:ss is hours, minutes, seconds

hh are 1-9, 10-12

mm are 00-60

ss are 00-60

–AM or PM

–TZD is time zone designator (PDT, PST, MDT, MST, etc.)