QRadar LEEF Format Guide V1.0
QRadar LEEF Format Guide V1.0
QRadar LEEF Format Guide V1.0
LEEF 1.0
Note: Before using this information and the product that it supports, read the information in Notices and
Trademarks on page 19.
Copyright IBM Corp. 2013 All Rights Reserved US Government Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
CONTENTS
ABOUT THIS GUIDE
Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
About IBM Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Ready for IBM Security Intelligence Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
IBM PartnerWorld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Documentation conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Technical documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Statement of good security practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
The IBM Security QRadar Log Event Extended Format (LEEF) Guide provides
information on how to construct and implement syslog events for QRadar products
in Log Event Extended Format (LEEF).
Unless otherwise noted, all references to QRadar refer to IBM Security QRadar
and IBM Security QRadar Log Manager.
Intended audience
This guide is intended for appliance vendors, software developers, and product
managers. This guide assumes that you have access to QRadar software through
the IBM PartnerWorld program or have been invited to join the IBM Security
QRadar SIEM DSM Beta program.
About IBM
Programs
The LEEF format is supported by IBM Partner World and the Ready for IBM
Security Intelligence Program
For information about the Ready for IBM Security Intelligence Program, you can
send an email to SIPP@ca.ibm.com or visit one of the following websites:
The Ready for IBM Security Intelligence ProgramTM is an open enrollment program
for vendors of security products, such as software or hardware manufacturers. The
program relies on shared tools to enable development, testing, troubleshooting,
and advanced integrations techniques that allow security products and QRadar to
communicate events effectively.
The Ready for IBM Security Intelligence offering helps promote a vibrant
ecosystem to nurture and support business partner products that extend the core
value of IBM Security solutions for the design, development, and delivery of
software and systems to support new security capabilities for our customers.
The Ready for IBM Security Intelligence Program is intended as a joint
commitment to collaborate and support security and event integrations for the
benefit of shared customers. The program provides an avenue for sellers, product
managers, engineers, and documentation personnel to communicate and resolve
integration issues, answer questions, share documentation, or test security
integrations. The LEEF format was designed under the Ready for IBM Security
Intelligence Program to allow for integration of security events with QRadar.
IBM PartnerWorld
Documentation
conventions
Technical
documentation
Statement of good
security practices
LEEF events can be created by any vendor with this documentation to have their
product generate events.
Appliances or applications that generate LEEF events allow QRadar to easily
integrate, identify, and process LEEF formatted events provided to QRadar. LEEF
events require UTF-8 character encoding.
Events in LEEF format can be provided to QRadar with the following protocols:
Syslog
The method you select to provide LEEF events determines if the events can be
automatically discovered in QRadar. Automatically discovered events provide
ease of configuraton for customers as it reduces the amount of manual
configuration required in QRadar.
As LEEF events are received, QRadar analyzes the event traffic in an attempt to
identify the device or appliance. This process is referred to internally as traffic
analysis. It typically takes at minimum 25 LEEF events to identify and create a new
log source in QRadar. Until traffic analysis identifies the event source, the initial 25
events are categorized as SIM Generic Log DSM events with the event name set
as Unknown Log Event. After the event traffic is identified, then QRadar creates a
log source to properly categorize and label any events forwarded from your
appliance or software. Events sent from your device are viewable in QRadar on the
Log Activity tab.
Note: If a log source cannot be identified after 1,000 events, then QRadar creates
a system notification and removes the log source from the traffic analysis queue.
QRadar is still capable of collecting the events, but a user must intervene and
create a log source manually to identify the event type.
Components of
LEEF events
Syslog header
The Log Event Extended Format (LEEF) is a customized event format for IBM
Security QRadar that contains readable and easily processed events for QRadar.
The LEEF format consists of the following components.
The syslog header is an optional field. The syslog header contains the timestamp
and IPv4 address or host name of the system providing the event. The syslog
header is an optional component of the LEEF format. If you include the syslog
header, you must separate the syslog header from the LEEF header with a space.
Examples:
LEEF header
Date<space>IP address
The LEEF header is a required field for LEEF events. The LEEF header is a pipe
delimited (|) set of values that identifies your software or appliance to QRadar.
Examples:
Event attributes
LEEF:Version|Vendor|Product|Version|EventID|
LEEF:1.0|Microsoft|MSExchange|4.0 SP1|15345|
The event attributes identify the payload information of the event produced by your
appliance or software. Every event attribute is a key and value pair with a tab
separating individual payload events. The LEEF format contains a number of
predefined event attributes, which allow QRadar to categorize and display the
event.
Examples:
key=value<tab>key=value<tab>key=value<tab>key=value<tab>
Note: If your appliance is not capable of using tab separators in the Event
attritubes as a delimiter, then a substitution can be made. In special cases, we can
substitute caret ( ^) or pipe ( | ) characters as delimiters. If your appliance or
software requires an alternate delimiter, please contact us for engineering support.
Table 1-1 LEEF format description
Type
Entry
Delimiter
Description
Syslog
Header
Date
Space
The date and timestamp of the host providing the event to QRadar. The
date field should conform to the mmm dd hh:mm:ss format:
For example, Jan 18 11:07:53.
A space must separate the date and IP address fields.
Type
Entry
Delimiter
Description
Syslog
Header
IP address
Space
192.168.1.1
myhostname
LEEF:version
Pipe
LEEF
Header
Vendor or
manufacturer
name
Pipe
LEEF
Header
The product field is a text string that identifies the product sending the
event log to QRadar.
For example, LEEF:1.0|Microsoft|MSExchange|Version|EventID|
Note: The Vendor and Product fields must contain unique values when
specified in the LEEF header.
LEEF
Header
Product
version
Pipe
Type
Entry
Delimiter
Description
LEEF
Header
EventID
Pipe
LEEF:1.0|Microsoft|MSExchange|2007|7732|
LEEF:1.0|Microsoft|MSExchange|2007|Logon Failure|
Restrictions:
The value of the event ID must be a consistent and static across
products that support multiple languages. If your product supports
multi-language events, you can use a numeric or textual value in the
EventID field, but it must not be translated when the language of your
appliance or application is altered. The EventID field cannot exceed 255
characters.
Event
Predefined
Attributes Key Entries
Tab
Predefined LEEF
event attributes
The Log Event Extended Format (LEEF) supports a number of predefined event
attributes for the event payload.
The LEEF format uses a specific list of name and value pairs that have been
predefined as LEEF event attributes. These keys outline fields identifiable to
QRadar and the use of the field for the LEEF format. It is recommended that your
appliance use these keys when possible, but your event payloads are not limited
by this list. The LEEF format is extensible and allows for additional keys to be
added to the event payload for your appliance or application.
Key
Value Type
cat
String
Attribute
Limits
Normalized
Event Field Description
Yes
10
Key
Value Type
devTime
Date
Attribute
Limits
Normalized
Event Field Description
Yes
devTimeFormat
String
No
proto
Integer or
Keyword
Yes
Integer
1-10
Yes
src
IPv4 or IPv6
Address
Yes
dst
IPv4 or IPv6
Address
Yes
srcPort
Integer
0 to 65535 Yes
dstPort
Integer
0 to 65535 Yes
srcPreNAT
IPv4 or IPv6
Address
Yes
dstPreNAT
IPv4 or IPv6
Address
Yes
srcPostNAT
IPv4 or IPv6
Address
Yes
11
Key
Value Type
dstPostNAT
IPv4 or IPv6
Address
usrName
String
srcMAC
MAC
Address
Attribute
Limits
255
Normalized
Event Field Description
Yes
Yes
Yes
dstMAC
MAC
Address
Yes
srcPreNATPORT
Integer
0 to 65535 Yes
dstPreNATPORT
Integer
0 to 65535 Yes
srcPostNATPORT
Integer
0 to 65535 Yes
dstPostNATPORT
Integer
0 to 65535 Yes
identSrc
IPv4 or IPv6
Address
Yes
identHostName
identNetBios
identGrpName
identMAC
12
Key
Value Type
Attribute
Limits
Normalized
Event Field Description
identHostName
String
255
Yes
identNetBios
String
255
Yes
identGrpName
String
255
Yes
identMAC
MAC
Address
Yes
vSrc
IPv4 or IPv6
Address
No
vSrcName
String
255
No
accountName
String
255
No
srcBytes
Integer
No
dstBytes
Integer
No
srcPackets
Integer
No
dstPackets
Integer
No
totalPackets
Integer
No
role
String
No
13
Key
Value Type
realm
String
Attribute
Limits
Normalized
Event Field Description
No
policy
String
No
resource
String
No
url
String
No
groupID
String
No
domain
String
No
isLoginEvent
Boolean
string
No
true or
false
Examples:
isLoginEvent=true
isLoginEvent=false
Boolean
string
true or
false
No
isLogoutEvent=true
isLogoutEvent=false
IPv4 or IPv6
Address
No
14
Key
Value Type
Attribute
Limits
Normalized
Event Field Description
calLanguage
String
No
String
No
calLanguage=de calCountryOrRegion=DE
devTime=Di 09 Jun 2006 12:30:55
calLanguage=en calCountryOrRegion=US
devTime=Tue 30 Jun 09 14:56:11
15
Vendors and partners have the option to define their own custom event keys and
include them in the payload of the LEEF format.
A custom key value pair attributes can be used in an event payload when there is
no default key to represent information about an event for your appliance. Custom
event attributes should only be created when there is no acceptable mapping to a
predefined event attribute. For example, if your appliance monitors access, you
might require the filename accessed by a user where no filename attribute exists in
LEEF by default.
CAUTION: Event attribute keys and values can only appear once per payload.
Using a key value pair twice in the same payload can cause QRadar to ignore the
value of the duplicate key.
Custom event keys are non-normalized, which means that any specialized key
value pairs you include in your LEEF event are not displayed by default on the Log
Activity tab of QRadar. To view custom attributes and non-normalized events on
the Log Activity tab of QRadar, the QRadar user must create a custom event
property. Non-normalized event data is still part of your LEEF event, is searchable
in QRadar, and is viewable in the event payload. For more information on creating
a custom event property, see the QRadar Administration Guide.
Best practices
LEEF is very flexible and allows you to create custom key value pairs for events,
but you should follow some best practices to avoid potential parsing issues.
Note: Items marked allowed can be included in a key or value, but is not in
violation of the LEEF format nor is it a best practice when creating custom event
keys.
The following list contains custom key and value best practices:
Use alphanumeric (A-Z, a-z, and 0-9) characters, but avoid tab, pipe, or caret
delimiters in your event payload keys and values (key=value).
-
Correct - usrName=Joe.Smith
Incorrect - usrName=Joe<tab>Smith
Correct - filename=pic07720.gif
A user defined key cannot use the same name as a LEEF predefined key. For
more information, see Table 1-2.
16
Correct - deviceProcessHash=value
Correct - malwarename=value
Allowed - EBFDFBE14D4=value
The create a customized event format, your device must supply the raw date
format using the devTime event attribute in the payload of the event.
The devTime event attribute requires formatting using devTimeFormat to display
the event in QRadar. The suggested devTimeFormat patterns are listed as follows:
devTimeFormat Pattern
Result
Notices
Trademarks
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not grant you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte character set (DBCS) information,
contact the IBM Intellectual Property Department in your country or send inquiries,
in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
20
Trademarks
21
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of
International Business Machines Corp., registered in many jurisdictions worldwide.
Other product and service names might be trademarks of IBM or other companies.
A current list of IBM trademarks is available on the Web at Copyright and
trademark information at http:\\www.ibm.com/legal/copytrade.shtml.
The following terms are trademarks or registered trademarks of other companies:
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Oracle and/or its affiliates.