Predefined LEEF Event Attributes
The Log Event Extended Format (LEEF) supports a number of predefined event attributes for the event payload.
LEEF uses a specific list of name-value pairs that are predefined LEEF event attributes. These keys outline fields that are identifiable to JSA. Use these keys on your appliance when possible, but your event payloads are not limited by this list. LEEF is extensible and you can add more keys to the event payload for your appliance or application.
The following table describes the predefined event attributes.
Key |
Value type |
Normalized event field? Yes or No |
Description |
|---|---|---|---|
cat |
String |
Yes |
An abbreviation for event category is used to extend the EventID field with more specific information about the LEEF event that is forwarded to JSA. Cat and the EventID field in the LEEF header help map your appliance event to a JSA Identifier (QID) map entry. The EventID represents the first column and the category represents the second column of the QID map. Note:
The value of the event category must be 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 cat field. The value in the cat field must not be translated when the language of your appliance or application is altered. |
cat (continued) |
String |
Yes |
Example 1: Use the cat key to extend the EventID with additional information to describe the event. If the EventID is defined as a User Login event, use the category to further categorize the event, such as a success or failed login. You can define your EventIDs further with the cat key, and the extra detail from the event can be used to distinguish between events when the same EventID is used for similar event types, for example,
Example 2: Use the cat key to define a high-level event category and use the EventID to define the low-level. This situation can be important when the EventID doesn't match any value in the QID map. When the EventID doesn't match any value in the QID map, JSA can use the category and other keys to further determine the general nature of the event. This "fallback" prevents events from being identified as unknown and JSA can categorize the events based on the known information from the key attribute fields of the event payload, for example,
|
devTime |
Date |
Yes |
The raw event date and time that is generated by your appliance or application that provides the LEEF event. JSA uses the devTime key, along with devTimeFormat to identify and properly format the event time from your appliance or application. If the devTime value is an epoch value of 10 or 13 digits, a devTimeFormat string is not required. Otherwise, the devTime and devTimeFormat keys must be used together to ensure that the time of the event is accurately parsed by JSA. When present in the event payload, devTime is used to identify the event time, even when the syslog header contains a date and time stamp. The syslog header date and time stamp is a fallback identifier, but devTime is the preferred method for event time identification. |
devTimeFormat |
String |
No |
Applies formatting to the raw date and time of the devTime key. The devTimeFormat key is required if your event log contains devTime. For more information, see Custom Event Date Format. |
proto |
Integer or Keyword |
Yes |
Identifies the transport protocol of the event. For a list of keywords or integer values, see the Internet Assigned Numbers Authority website, http://www.iana.org/assignments/protocol-numbers/ protocol-numbers.xml |
sev |
Integer |
Yes |
Indicates the severity of the event. 1 is the lowest event severity. 10 is the highest event severity. Attribute Limits: 1-10. |
src |
IPv4 or IPv6 Address |
Yes |
The IP address of the event source. |
dst |
IPv4 or IPv6 Address |
Yes |
The IP address of the event destination. |
srcPort |
Integer |
Yes |
The source port of the event. Attribute Limits: 0 - 65535 |
dstPort |
Integer |
Yes |
The destination port of the event. Attribute Limits: 0 - 65535 |
srcPreNAT |
IPv4 or IPv6 Address |
Yes |
The source IP address of the event message before Network Address Translation (NAT). |
dstPreNAT |
IPv4 or IPv6 Address |
Yes |
The destination address for the event message before Network Address Translation (NAT). |
srcPostNAT |
IPv4 or IPv6 Address |
Yes |
The source IP address of the message after Network Address Translation (NAT) occurred. |
dstPostNAT |
IPv4 or IPv6 Address |
Yes |
The destination IP address of the message after Network Address Translation (NAT) occurred. |
usrName |
String |
Yes |
The user name that is associated with the event. Attribute Limits: 255 |
srcMAC |
MAC Address |
Yes |
The MAC address of the event source in hexadecimal. The MAC address is made up of six groups of two hexadecimal digits, which are colon-separated, for example,
|
dstMAC |
MAC Address |
Yes |
The MAC address of the event destination in hexadecimal. The MAC address is composed of six groups of two hexadecimal digits, which are colon-separated, for example,
|
srcPreNATPort |
Integer |
Yes |
The port number of the event source before Network Address Translation (NAT). Attribute Limits: 0 - 65535 |
dstPreNATPort |
Integer |
Yes |
The port number of the event destination before Network Address Translation (NAT). Attribute Limits: 0 - 65535 |
srcPostNATPort |
Integer |
Yes |
The port number of the event source after Network Address Translation (NAT). Attribute Limits: 0 - 65535 |
dstPostNATPort |
Integer |
Yes |
The port number of the event destination after Network Address Translation (NAT). Attribute Limits: 0 - 65535 |
identSrc |
IPv4 or IPv6 Address |
Yes |
Identity source represents an extra IPv4 or IPv6 address that can connect an event with a true user identify or true computer identity. Example 1: Connecting a person to a network identity. User X logs in from their notebook and then connects to a shared system on the network. When their activity generates an event, then the identSrc in the payload can be used to include more IP address information. JSA uses the identSrc information in the event along with the payload information, such as username, to identify that user X is bob.smith. The following identity keys depend on identSrcs presence in the event payload: identHostName identNetBios identGrpName identMAC |
identHostName |
String |
Key |
Host name information that is associated with the identSrc to further identify the true host name that is tied to an event. The identHostName parameter is usable by JSA only when your device provides both the identSrc key and identHostName together in an event payload. Attribute Limits: 255 |
identNetBios |
String |
Yes |
NetBIOS name that is associated with the identSrc to further identify the identity event with NetBIOS name resolution. The identNetBios parameter is usable by JSA only when your device provides both the identSrc key and identNetBios together in an event payload. Attribute Limits: 255 |
identGrpName |
String |
Yes |
Group name that is associated with the identSrc to further identify the identity event with Group name resolution. The identGrpName parameter is usable by JSA only when your device provides both the identSrc key and identGrpName together in an event payload. Attribute Limits: 255 |
identMAC |
MAC Address |
Yes |
Reserved for future use in the LEEF format. |
vSrc |
IPv4 or IPv6 Address |
No |
The IP address of the virtual event source. |
vSrcName |
String |
No |
The name of the virtual event source. Attribute Limits: 255 |
accountName |
String |
No |
The account name that is associated with the event. Attribute Limits: 255 |
srcBytes |
Integer |
No |
Indicates the byte count from the event source. |
dstBytes |
Integer |
No |
Indicates the byte count to the event destination. |
srcPackets |
Integer |
No |
Indicates the packet count from the event source. |
dstPackets |
Integer |
No |
Indicates the packet count to the event destination. |
totalPackets |
Integer |
No |
Indicates the total number of packets that are transmitted between the source and destination. |
role |
String |
No |
The type of role that is associated with the user account that created the event, for example, Administrator, User, Domain Admin. |
realm |
String |
No |
The realm that is associated with the user account. Depending on your device, can be a general grouping or based on region, for example, accounting, remote offices. |
policy |
String |
No |
A policy that is associated with the user account. This policy is typically the security policy or group policy that is tied to the user account. |
resource |
String |
No |
A resource that is associated with the user account. This resource is typically the computer name. |
url |
String |
No |
URL information that is included with the event. |
groupID |
String |
No |
The groupID that is associated with the user account. |
domain |
String |
No |
The domain that is associated with the user account. |
isLoginEvent |
Boolean string |
No |
Identifies if the event is related to a user login, for example,
This key is reserved in the LEEF specification, but not implemented in JSA. Attribute Limits: true or false |
isLogoutEvent |
Boolean string |
No |
Identifies if the event is related to a user logout, for example,
This key is reserved in the LEEF specification, but not implemented in JSA. Attribute Limits: true or false |
identSecondlp |
IPv4 or IPv6 Address |
No |
Identity second IP address represents an IPv4 or IPv6 address that is used to associate a device event that includes a secondary IP address. Secondary IP addresses can be in events by routers, switches, or virtual LAN (VLAN) device events. This key is reserved in the LEEF specification, but not implemented in JSA. |
calLanguage Attribute Limits: 2 |
String |
No |
Identifies the language of the device time (devTime) key to allow translation and to ensure that JSA correctly parses the date and time of events that are generated in translated languages. The calLanaguage field can include two alphanumeric characters to represent the event language for the device time of your event. All calLanguage alphanumeric characters follow the ISO 639-1 format, for example,
This key is reserved in the LEEF specification, but not implemented currently in JSA. Attribute Limits: 2 |
calCountryOrRegion |
String |
No |
Extends the calLanguage key to provide more translation information that can include the country or region for the event device time (devTime). The key calCountryOrRegion must be used with the calLanguage key. The calCountryOrRegion field can include two alphanumeric characters to represent the event country or region for the device time of your event. All calCountryOrRegion alphanumeric characters follow the ISO 3166 format, for example,
This key is reserved in the LEEF specification, but not implemented in JSA. Attribute Limits: 2 |
Non-normalized predefined LEEF event attributes are not automatically parsed for all log source
types. However, JSA provides custom properties (either built-in or from the IBM
Security App Exchange) for some of these keys. You can configure custom properties
for non-normalized keys to parse by using Regex. To configure a key to parse, the
input is key=([^\t]+).
The following examples show Regex inputs for non-normalized predefined keys, where the delimiter that follows the caret (^) is a horizontal tab in LEEF V1.0:
The input for vSrc is
vSrc=([^\t]+).The input for vSrcName is
vSrcName=([^\t]+).The input for accountName is
accountName=([^\t]+).
The following examples show Regex inputs for non-normalized predefined keys, where the delimiter that follows the caret (^) is a customized separator character in LEEF V2.0:
If you use # as the delimiter, the input for vSrc is
vSrc=([^#]+).If you use | as the delimiter, the input for vSrc is
vSrc=([^|]+).
JSA 7.3.2 or later includes property auto-detection for custom properties of both predefined and custom LEEF event attributes. Property auto-detection makes it easier to configure custom properties, without the use of Regex.