SIEM CEF connector

About the sample CEF connector

The sample CEF connector receives security events in near real time using the SIEM API and converts those events from JSON format to CEF format. The connector pulls from a single API endpoint (based on a pull rate you can configure) and processes security events generated from security policies within multiple security configurations.

You can configure the connector to save security events locally or you can forward those events to a destination host over UDP or TCP using the Syslog protocol. For Syslog, the connector leverages the CEF format. CEF is an open messaging standard introduced by ArcSight, Inc. CEF-Syslog works with ArcSight and other SIEM solutions that support the syslog/CEF format.

The CEF ConnectorThe CEF Connector

Install the CEF connector

System requirements

The ‚ÄčAkamai‚Äč CEF Connector requires Oracle JRE 1.8+. The latest JRE can be downloaded from the¬†Oracle Java site¬†(Java Platform, Standard Edition) or installed from a software distribution package on Linux. To verify that JRE is installed and available, use the command java -version.

Hardware requirements

This application is designed to run on a Linux server with at least:

  • 2 CPU cores
  • 6GB RAM
  • 2GB Free Disk Space
  • A Linux Kernel greater than 2.6

Proxy server

To access the SIEM API from behind a proxy server, ensure that your proxy:

  • Allowlists the domains *.cloudsecurity.akamaiapis.net and *.luna.akamaiapis.net.
  • Doesn't interfere with HTTP request headers for those domains. If, due to a strict enterprise security policy, your proxy changes these headers, make sure that, at a minimum, you allow and don't change the Host and Authorization headers.

Install

To install The CEF connector, complete the following steps:

  1. Go to Connectors and tools to get the latest CEF Connector distribution package.
  2. Transfer the package using either the Linux command wget http://[server]/CEFConnector-1.0.zip (replace [server] with your server name) or using SFTP (SSH File Transfer Protocol).
  3. Unzip the distribution package anywhere on the file system. You can install Unzip from a software distribution package on Linux (for example, by using the command yum install unzip ).
  4. To install the service, create a symbolic link to the bin/AkamaiCEFConnector.sh shell script in /etc/init.d. You can execute the shell script with the following commands: start | stop | status | resetdb .

ūüďė

The resetdb command deletes cefconnector.db, which contains the last successful offset data pull. Removing that file causes the connector to process offset=NULL as long as the timebased setting is false. If timebased is true, a new offset is saved after the first successful pull.

Configure your SIEM event data pull

Set up and manage your connector through the source pull configuration settings located in the config/CEFConnector.properties file.

  • connector.refresh.period
    • Default Value: 60
    • Description: Defines the pull rate from the ‚ÄčAkamai‚Äč source in seconds.
    • Allowed Values: Positive integer value greater than 0.
    • Example: 60 (1 minute)
    • Required: Yes
  • akamai.data.requesturlhost
  • akamai.data.configs
    • Description: Security configurations the API pulls events from. Add multiple security configuration IDs by separating the IDs with a semicolon (;).
    • Example: 12345;67890
    • Required: Yes
  • akamai.data.timebased
    • Description: Set to false to pull security events continuously by offset token (this should be the usual, everyday setting) and set to true in order to pull security events that fall within a specific time frame. If timebased is set to true , the timebased.from parameter (see the next configuration entry) is required.
    • Allowed Values: true or false
    • Example: false
    • Required: Yes
  • akamai.data.timebased.from
    • Description: If the timebased parameter is true, this a required field. Enter the time (in epoch format) to start pulling past security events. This can be any time within the 12 hours preceding the present moment. If regular offset event collection occurred within the time window, you might see duplicate data in your SIEM software.
    • Allowed Values: Positive integer in epoch format. Value must be less than the timebased.to value.
    • Example: 1491588763
    • Required: Yes, if the timebased parameter is true , No, if the timebased parameter is false .
  • akamai.data.timebased.to
    • Default Value: No value
    • Description: If the timebased parameter is true, you can optionally enter the end timestamp (in epoch format) to a specific period for pulling past security events. If no value or an invalid format is provided, the default value is used.
    • Allowed Values: Positive integer in epoch format. Value must be greater than or equal to the value in timebased.from.
    • Example: 1491588763
    • Required: No
  • akamai.data.limit
    • Default Value: 200000
    • Description: Maximum number of security events that can be pulled with a single API call. Use this field to prevent overload and to protect your SIEM system from being flooded with event data. If no value is provided or if an invalid value is provided, the default limit defined by the SIEM API is used
    • Allowed Values: Positive integer values. Invalid values default to 200000.
    • Example: 100
    • Required: No
      Note: This sample connector supports transfer of up to 200,000 events per minute.
  • akamai.data.accesstoken
    • Description: Access token copied when provisioning the SIEM API in ‚ÄčControl Center‚Äč.
    • Allowed Values: This value cannot be blank or commented out.
    • Example: akab-fc7lrkvv57lgxjpx-mizhsadsasdasym
    • Required: Yes
  • akamai.data.clienttoken
    • Description: Client token copied when provisioning the SIEM API in ‚ÄčControl Center‚Äč.
    • Allowed Values: This value cannot be blank or commented out.
    • Example: akab-fc7lrkvv57lgxjpx-mizhsadsasdasym
    • Required: Yes
  • akamai.data.clientsecret
    • Description: Client secret copied when provisioning¬†the SIEM API in ‚ÄčControl Center‚Äč.
    • Allowed Values: This value cannot be blank or commented out.
    • Example: LWcGK6h2121GdfdDSD8m+4wllsdfdsG8wgFS+dfDfZQ=
    • Required: Yes
  • akamai.data.baseurl
    • Description: URL copied when you provisioned the SIEM OPEN API in ‚ÄčControl Center‚Äč.
    • Allowed Values: This value cannot be blank or commented out.
    • Example: akab-dsfdsdypmwkj7a-eqkdfgfdsswsfaoclec.cloudsecurity.akamaiapis.net
    • Required: Yes
  • akamai.cefformatheader
    • Description: CEF Header Values, with individual values¬†separated by using the | character. (If the | character is part of a static string, then it must be escaped with a \ ). Values can be static or generated from the following functions: requestURL(), eventClassId(), name(), severity(), appliedAction(),ipv6src().
    • Allowed Values: This value can't be blank or commented out.
    • Example: CEF:0|Akamai|akamai_siem|1.0|eventClassId()|name()|severity()
    • Required: Yes
  • akamai.cefformatextension
    • Description: CEF Extension Values, with individual values¬†separated by a blank space. Values can be static; generated from available functions (eventClassId() , name(), severity() , appliedAction() , ipv6src()); or pulled from the JSON API. The JSON API is defined by ${} and each JSON object is separated by a period. Static values are defined by quotation marks. Function-generated values are defined by () and must be one of the available functions defined in the documentation.
    • Allowed Values: This value can't be blank or commented out.
      Example:
      act=appliedAction()
      app=${httpMessage.protocol}c6a2=ipv6src()c6a2
      Label="Source IPv6 Address"
      cs1=${attackData.rules} cs1Label="Rules"
      cs2=${attackData.ruleMessages} cs2Label="Rule Messages"
      cs3=${attackData.ruleData} cs3Label="Rule Data"
      cs4=${attackData.ruleSelectors} cs4Label="Rule Selectors"
  • Required: No
  • akamai.base64fields
    • Description: Defines any base64 encoded JSON API objects.
    • Example: ${attackData.ruleVersions};${attackData.rules};${attackData.ruleActions}
    • Required: No
  • akamai.urlencoded
    • Description: Defines any URL-encoded JSON API objects.
    • Example: ${attackData.ruleVersions};${attackData.rules};${attackData.ruleActions}
    • Required: No
  • akamai.multivaluedelim
    • Default Value: , (comma)
    • Description: Delimiter that separates multi-valued CEF fields.
    • Allowed Values: Blank spaces can be specified as a delimiter by using either " " or "".
    • Example:, (comma), \u0020 (white space), \n (newline), \t (tab
    • Required: No
  • connector.consumer.count
    • Default Value: 3
    • Description: Maximum number of consumer threads.
    • Example: 10
    • Required: No
  • connector.proxy.host
  • connector.proxy.port
    • Description: Set your proxy host and port.
    • Allowed Values: This value should be left blank if you don't have a local proxy.
    • Required: No

Set up in Arcsight

  1. Log in to Arcsight with administrator rights.
  2. Click Configuration > Data > Receivers.
  3. Add a new TCP CEF Receiver with a distinct name (e.g.,¬†‚ÄčAkamai‚Äč CEF Data). By default, this assigns the receiver to listen on IP/HOST, port 546 (if that port isn't already in use), employing UTF-8 encoding, and the source type CEF. If necessary, the port value can be changed at any time. Note, too that, by default, the receiver is enabled upon when it's created..
  4. Click Configuration > Data > Device Groups to group security events by device. Add a new Device Group and select a device from the list of auto-populated devices. If the connector is installed locally and is sending logs to localhost, the device is Logger Internal Event Device with the receiver name you added in Step 3.
  5. To view the device group security logs, click Analyze > Search. In the search bar. enter _deviceGroup in ["<device group name>"] . For example: _deviceGroup in ["<<COMPANY_NICKNAME>> SIEM -On Server Connector"].

Logging

Set log configurations in the config/log4j2.xml file:

  • log-path: Path location of the log files. Use either a relative or a specific path (for example:¬†logs).
  • log-name: File name for your logs (for example:¬†filename).
  • SizeBasedTriggeringPolicy: Log size rollover limit (for¬†example:¬†1MB).
  • DefaultRolloverStrategy: Maximum number of log files stored for each log (info, warn, and error). For¬†example:¬†20.
  • CEFHost: Remote CEF Syslog Server Host (for example:¬†127.0.0.1).
  • CEFPort: Remote CEF Syslog Server Port (for example:¬†514).
  • CEFProtocol: Remote CEF Syslog Server Protocol (for example:¬†UDP/TCP).

To run in debug mode:

  1. In the log4j2.xml file, under Loggers, find <Root level="info".
  2. Change info to debug and save the file.

Logs are in the /bin/logs/cefconnector.log file.

SIEM API data format for CEF

The security events data available from the ‚ÄčAkamai‚Äč endpoint arrives in JSON format. Each line is a separate JSON object representing a single request.

Calculated fields

$appliedAction
If attackData.ruleActions contains any action other than alert or deny, use it (there will be only one action). Otherwise, check to see if there is a deny action and if so, set the applied action to 'deny. If not, check if attackData.slowPostAction equals A. If it does set the applied action to abort; otherwise, set the applied action to alert.

$eventClassId
If $appliedAction in ('alert', 'monitor') then detect. Otherwise, mitigate.

$name
If $eventClassId = detect then Activity detected. Otherwise Activity mitigated.

$severity
If $eventClassId = detect then 5. Otherwise 10.

$requestURL
If $httpMessage.tls is not empty then request = 'https://' + $httpMessage.host. Otherwise request = 'http://' + $httpMessage.host.

If $httpMessage.path is not empty then request = $request + $attackData.path. If $httpMessage.query is not empty then request = $request + '?" + $httpMessage.query.

CEF fields

CEF FieldJSON Field/ValueDescription
Device Vendor‚ÄčAkamai‚Äč
Device Version1.0
Device Productakamai_siem
Device Event Class ID$eventClassIdCalculated field.
Name$nameCalculated field.
Severity$severityCalculated field.

CEF extension fields

CEF ExtensionJSON Field/ValueDescription
act$appliedActionCalculated field.
app$httpMessage.protocol
c6a2$ipv6srcIP v6 address of the source. Only populated if $attackData.clientIP is in IP v6 format.
c6a2LabelSource IP6 Address
cs1$attackData.rulesRule IDs of rules that triggered for this request.
cs1Label$attackData.rules
cs2$attackData.ruleMessagesMessages of rules that triggered for this request
cs2LabelRule Messages
cs3$attackData.ruleDataUser data of rules that triggered for this request.
cs3LabelRule Data
cs4$attackData.ruleSelectorsSelectors of rules that triggered for this request.
cs4LabelRule Selectors
cs5$attackData.clientReputationClient IP scores for Client Reputation.
cs5LabelClient Reputation
cs6$attackData.apiIdAPI ID for API Protection.
cs6LabelAPI ID
devicePayloadId$httpMessage.requestIdGlobally unique ID of the message.
dhost$httpMessage.hostValue of the HOST header of the incoming client request.
dpt$httpMessage.portPort number used by the incoming request. Should be equal to the value of AK_IN_PORT
flexString1$attackData.configIdID of the Security Configuration applied to this request.
flexString1LabelSecurity Config ID
flexString2$attackData.policyIdID of the Firewall Policy applied to this request .
flexString2LabelFirewall Policy Id
out$httpMessage.bytesContent bytes served in the client response.
request$requestURLCalculated field.
requestMethod$httpMessage.methodHTTP method of the incoming request.
src$attackData.clientIPIP address of the client that made the request.
start$httpMessage.startTime, in epoch format (and to millisecond precision), when the Edge Server initiated the connection for the message exchange being monitored.
AkamaiSiem
SlowPostAction
$attackData.slowPostActionAction taken if a Slow POST attack is detected: either W for Warn or A for deny (abort).
AkamaiSiem
SlowPostRate
$attackData.slowPostRateRecorded rate of a detected Slow POST attack.
AkamaiSiem
RuleVersions
$attackData.ruleVersionsBase64-encoded versions of rules that triggered for this request.
AkamaiSiem
RuleTags
$attackData.ruleTagsBase64-encoded tags of rules that triggered for this request.. See WAF rule list for all tags
AkamaiSiem
ApiKey
$attackData.apiKeyAPI Key for API Protection.
AkamaiSiem
TLSVersion
$httpMessage.tlsTLS version, if applicable.
AkamaiSiem
RequestHeaders
$httpMessage.requestHeadersAll request headers collected.
AkamaiSiem
ResponseHeaders
$httpMessage.responseHeadersAll response headers collected.
AkamaiSiem
ResponseStatus
$httpMessage.statusHTTP Response status sent to the client.
AkamaiSiem
Continent
$geo.continent2-letter code for the continent that the IP address maps to.
AkamaiSiem
Country
$geo.country2-letter ISO-3166 code for the country the IP address maps to.
AkamaiSiem
City
$geo.cityCity that the IP address maps to.
AkamaiSiem
Region
$geo.regionCode2-letter ISO-3166 code for the state, province, or region the IP address maps to.
AkamaiSiem
ASN
$geo.asnAutonomous System Number (or numbers) that the IP address belongs to.
AkamaiSiem
Uuid
$userRiskData.uuidUnique identifier of the user whose risk data is being provided.
AkamaiSiem
Status
$userRiskData.statusStatus code indicating any errors that occurred when calculating the risk score. See the User Score Status section of this page for details.
AkamaiSiem
Score
$userRiskData.scoreCalculated risk scores. Scores range from 0 (no risk) to 100 (the highest possible risk).
AkamaiSiem
Risk
$userRiskData.riskIndicators that increased the calculated risk score. For example, the value udfp represents the risk of the device fingerprint based on the user's behavioral profile.
AkamaiSiem
Trust
$userRiskData.trustIndicators that were trusted. For example, the value ugp indicates that the user’s country or area is trusted.
AkamaiSiem
General
$userRiskData.generalIndicators of general behavior observed for relevant attributes. For example, duc_1h represents the number of users recorded on a specific device in the past hour.
AkamaiSiem
Allow
$userRiskData.allowIndicates whether the user is on the allow list. A 0 indicates that the user was not on the list; a 1 indicates that the user was on the list.
AkamaiApp
BundleId
$clientData.appBundleIdUnique identifier of the app bundle. An app bundle contains both the software itself and the accompanying configuration information.
AkamaiApp
Version
$clientData.appVersionVersion number of the app.
Akamai
TelemetryType
$clientData.telemetryTypeSpecifies the telemetry type in use. Allowed values are:

  • 0 -- Web client (standard telemetry)
  • 1 -- Web client (inline telemetry)
  • 2 -- Native app (SDK)
AkamaiBot
Score
$botData.botScoreScore assigned to the request by Botman Manager.
AkamaiResponse
Segment
$botData.responseSegmentNumeric response segment indicator. Segments are used to group and categorize bot scores. Allowed values are:

  • 0 -- Human
  • 1 -- Cautious response
  • 2 -- Strict response
  • 3 -- Aggressive response
  • 4 -- safeguard
AkamaiSiem
CustomData
$customCustom base-64-encoded value. The custom data size limit is 2KB.

Retrieve past security events using the CEF connector

The ‚ÄčAkamai‚Äč CEF connector offers 2 modes of operation:

  • Offset-based. The most-commonly used mode: the connector automatically logs security events as they‚Äôre collected. The connector operates in offset mode when the akamai.data.timebased configuration is set to false .
  • Time-based. Enables you to retrieve only the events that occurred with a specified time period.¬†For example, if your SIEM connection is disrupted you can retrieve any (or all) security events that occurred within the last 12 hours.

To retrieve missing or past security events, switch from an offset-based to a time-based feed by completing the following procedure:

  1. Open your connector’s configuration file: config/CEFConnector.properties.
  2. Change the akamai.data.timebased configuration to true.
  3. Under akamai.data.timebased.from, enter the start time (in epoch format) for which you want to pull past security events. This can be any time within the 12 hours preceding the present moment.
  4. (Optional) To retrieve events that fall only within a specific time period, enter the end time (in epoch format) as the value of the akamai.data.timebased.to setting . If this setting is left blank, the connector pulls events up to the present and continues to log events as they’re collected.

If regular offset event collection occurred within the time window you set, duplicate data may appear in your SIEM reports.

Don't see the data you expected? When you configure the connector to retrieve security events for a specific time period, the connector makes only one call to the API. If the number of events in the specified time window exceeds the value in the Limit field (or the default limit of 200,000) the connector won't retrieve data. As a workaround, decrease the time period tfor retrieving events; for example, you might need to make one API call to retrieve events that occurred in the first six hours of your time period, and a second API call to retrieve events that occurred in the final six hours of your time period.

To return the connector to offset mode, change the akamai.data.timebased setting to false.

Uninstall the CEF connector

To stop the CEF Connector service, run the command bin/AkamaiCEFConnector.sh stop or /etc/init.d/symboliclink stop.

To remove the installation folder, run the command rm ‚Äďrf CEFConnector-1.0.


Did this page help you?