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 them from JSON into 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 in addition to forwarding 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.

CEF connector diagram

 

Install CEF connector

System requirements

Akamai’s 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 version 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 any of those headers, make sure that, at a minimum, you allow and don't change the Host and Authorization headers.

    Install

    Visit https://developer.akamai.com/tools/siem-integration to get the latest CEF Connector distribution package. Transfer the package using either the Linux command wget http://[server]/CEFConnector-1.0.zip> (replacing [server] with your server name) or using by SFTP (SSH File Transfer Protocol).

    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 ).

    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.

    Learn more about offset and time-based pulls.

    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. No decimals allowed. 
      • Example: 60 (1 minute)
      • Required: Yes
    • akamai.data.requesturlhost
      • Description: Akamai web service URL (example https://cloudsecurity.akamaiapis.net) This value, along with the security configurations IDs, generates the request URL (e.g., https://cloudsecurity.akamaiapis.net/siem/v1/configs/14227?offset=NULL).
      • Allowed Values: This value cannot be blank or commented out.
      • Example: https://cloudsecurity.akamaiapis.net
      • Required: Yes
    • akamai.data.configs
      • Description: Security configurations from which 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 to pull security events that fall within a specified time frame. If timebased is set to true, the from parameter (see the next configuration entry) is required. (Learn more about retrieving past events.)
      • Allowed Values: true or false
      • Example: false
      • Required: Yes
    • akamai.data.timebased.from
      • Description: If the timebased parameter is true, this is 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 has to 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 (again, in epoch format) to a specific period for pulling past security events. If no value or an invalid format is provided, the default value (no value) is used.
      • Allowed Values: Positive integer in epoch format. The 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; no decimals are allowed. Invalid values will default to 200000.
      • Example: 100
      • Required: No
        Note: The sample connector supports transfers of up to 200,000 events per minute.
    • akamai.data.accesstoken
      • Description: Access token copied when provisioning the SIEM API in Akamai 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 Akamai 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 Akamai 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 provisioning the SIEM API in Akamai 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 a | 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, 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()c6a2Label="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: " " is treated the same as "" and a blank space will default.
      • 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: Sets your proxy host and port.
      • Allowed Values: This 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. The receiver is enabled by default, and the port can be altered if needed.
    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, go to the menu and choose Analyze > Search. In the search bar. enter _deviceGroup in ["<device group name>"] . For example: _deviceGroup in ["Akamai 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, scroll down to the bottom and, 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 ser the applied action to alert.

    $eventClassId
    If $appliedAction is 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 Field JSON Field/Value Description
    Device Vendor Akamai  
    Device Version 1.0  
    Device Product akamai_siem  
    Device Event Class ID $eventClassId Calculated field.
    Name $name Calculated field.
    Severity $severity Calculated field.

    CEF Extension fields

    CEF Extension JSON Field/Value Description
    act $appliedAction Calculated field.
    app $httpMessage.protocol  
    c6a2 $ipv6src IPv6 address of the source. Only populated if $attackData.clientIP is in IPv6 format.
    c6a2Label Source IP6 Address  
    cs1 $attackData.rules Rule IDs of rules that triggered for this request.
    cs1Label Rules  
    cs2 $attackData.ruleMessages Messages of rules that triggered for this request.
    cs2Label Rule Messages  
    cs3 $attackData.ruleData User data of rules that triggered for this request
    cs3Label Rule Data  
    cs4 $attackData.ruleSelectors Selectors of rules that triggered for this request.
    cs4Label Rule Selectors  
    cs5 $attackData.clientReputation Client IP scores for Client Reputation.
    cs5Label Client Reputation  
    cs6 $attackData.apiId API ID for API Protection.
    cs6Label API ID  
    devicePayloadId $httpMessage.requestId Globally unique ID of the message.
    dhost $httpMessage.host Value of the HOST header of the incoming client request.
    dpt $httpMessage.port Port number used by the incoming request. Should be equal to the value of AK_IN_PORT.
    flexString1 $attackData.configId ID of the Security Configuration applied to this request.
    flexString1Label Security Config Id  
    flexString2 $attackData.policyId ID of the Firewall Policy applied to this request.
    flexString2Label Firewall Policy Id  
    out $httpMessage.bytes Content bytes served in the client response.
    request $requestURL Calculated field.
    requestMethod $httpMessage.method HTTP method of the incoming request.
    src $attackData.clientIP IP address of the client that connects to make the request.
    start $httpMessage.start Time, in epoch format (and to millisecond precision) when the Edge Server initiated the connection for the message exchange being monitored.
    AkamaiSiemSlowPostAction $attackData.slowPostAction Action taken if a Slow POST attack is detected: either W for Warn or A for deny (abort).
    AkamaiSiemSlowPostRate $attackData.slowPostRate Recorded rate of a detected Slow POST attack.
    AkamaiSiemRuleVersions $attackData.ruleVersions Base64-encoded versions of rules that triggered for this request.
    AkamaiSiemRuleTags $attackData.ruleTags Base64-encoded tags of rules that triggered for this request.

    See WAF rule list for all tags.
    AkamaiSiemApiKey $attackData.apiKey API Key for API Protection.
    AkamaiSiemTLSVersion $httpMessage.tls TLS version, if applicable.
    AkamaiSiemRequestHeaders $httpMessage.requestHeaders All request headers collected.
    AkamaiSiemResponseHeaders $httpMessage.responseHeaders All response headers collected.
    AkamaiSiemResponseStatus $httpMessage.status HTTP Response status sent to the client.
    AkamaiSiemContinent $geo.continent 2-letter code for the continent that the IP address maps to.
    AkamaiSiemCountry $geo.country 2-letter ISO-3166 code for the state, province, or region that the IP address maps to.
    AkamaiSiemCity $geo.city City that the IP address maps to.
    AkamaiSiemRegion $geo.regionCode 2-letter ISO-3166 code for the state, province, or region that the IP address maps to.
    AkamaiSiemASN $geo.asn Autonomous System Number (or numbers) that the IP belongs to.
    AkamaiSiemAPRUuid $userRiskData.uuid Unique identifier of the user whose risk data is being provided.
    AkamaiSiemAPRStatus $userRiskData.status Status code indicating any errors that might have occurred when calculating the risk score.

    See the User Score Status section of this page for details.
    AkamaiSiemAPRScore $userRiskData.score Calculated risk score. Scores range from 0 (no risk) to 100 (the highest possible risk).
    AkamaiSiemAPRRisk $userRiskData.risk Indicators 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.
    AkamaiSiemAPRTrust $userRiskData.trust Indicators that were trusted. For example, the value ugp indicates that the user’s country or area is trusted.
    AkamaiSiemAPRGeneral $userRiskData.general Indicators 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.
    AkamaiSiemAPRAllow $userRiskData.allow Indicates 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.
    AkamaiSiemAppBundleId $clientData,appBundleId Unique identifier of the app bundle. An app bundle contains both the software itself and the accompanying configuration information.
    AkamaiSiemAppVersion $clientData.appVersion Version number of the app.
    AkamaiSiemATelemetryType $clientData.telemetryType Specifies the telemetry type in use. Allowed values are: 
    • 0 -- Web client (standard telemetry)
    • 1 -- Web client (inline telemetry)
    • 2 -- Native app (SDK)
    AkamaiSiemBotScore $botData.botScore Score assigned to the request by Botman Manager.
    AkamaiSiemResponseSegment $botData.responseSegment Numeric 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
    AkamaiSiemCustomData $custom Custom base-64-encoded value. The custom data size limit is 2KB.

    Retrieve past security events using the CEF connector

    Akamai’s 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 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) If you want to retrieve events that fall only within a specified time period then, under akamai.data.timebased.to, enter the end time (in epoch format) for the period. If you enter nothing here, 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 might 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 window to include all events; for example, you might need to make one API call to retrieve events that occurred in the first 6 hours of your time period, and a second API call to retrieve events that occurred in the final 6 hours of your time period.

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

    Uninstall CEF connector

    Stop the Akamai CEF Connector service by running bin/AkamaiCEFConnector.sh stop or /etc/init.d/symboliclink stop.

    Remove the installation folder by running rm –rf CEFConnector-1.0.

    Release notes

    CEF Connector version 1.7.5 released in January 2022. Changes include:

    • Upgrade log4j version to fix CVE-2021-44832 vulnerability.

     

    CEF Connector version 1.7.4 released in December 2021. Changes include:

    • Upgrade log4j version to fix CVE-2021-45105 vulnerability.

     

    CEF Connector version 1.7.3 released in December 2021. Changes include:

    • Upgrade log4j version to fix CVE-2021-45046 vulnerability.

     

    CEF Connector version 1.7.2 released in December 2021. Changes include:

    • Patch for log4j vulnerability.

     

    CEF Connector version 1.7.1 released in July 2021. Changes include:

    • Enhanced CEF connector retry functionality.

     

    CEF Connector version 1.7.0 released in October 2020. Changes include:

    • Support for new Open API domain *.luna.akamaiapis.net.

     

    CEF Connector version 1.5 released in August 2017. Changes include:

    • Debug flag has moved out of CEFConnector.properties. To turn on logging, you now make a quick change to the log4j2.xml. To read how see Logging.
    • All logs now consolidated in the /bin/logs/cefconnector.log file.