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.

Install the CEF connector

System requirements

The ​Akamai​ CEF Connector requires Java 8 (JRE 1.8) or above. To verify the installed version, 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.

• akamai.data.requesturlhost
  • Description: ​Akamai​ web service URL. This value, along with the security configurations IDs, generates the request URL (for example, 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 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
• 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
• connector.retry
  • Default Value: 5
  • Description: Maximum number of consecutive retries for non-200 response from SIEM API.
  • Example: 20
  • 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 extension fields

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.