SIEM Splunk connector

About the sample Splunk connector

The sample Splunk connector is a Splunk add-on that captures security events from the Akamai Security Events Collector, which exposes a RESTful API that lets the connector pull events in JSON format. The Splunk add-on converts security events data from JSON into CIM format. The Splunk instance then analyzes high volumes of data by indexing it.

splunk diagram

Install Splunk connector

System Requirements

  • Akamai’s Splunk Connector requires Sun JRE 1.8+ to be installed. Download the latest from the Sun Java site (Java Platform, Standard Edition) or install from a software distribution package on Linux.
  • You must have Java installed on the host running Splunk Enterprise https://java.com/en/download/
  • You must install KVStore on the host machine where you want to install your connector
  • Check to make sure that splunk forwarder is NOT installed on your Splunk Enterprise host machine.

Hardware requirements

This application has been tested with the following operating systems:

  • CentOS 7
  • Windows Server 2012 R2
  • Mac OS X El Capitan Version 10.11.6

Some additional hardware requirements:

  • 4 CPU cores
  • 16 GB RAM
  • 2GB Free Disk Space

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 
  • does not interfere with HTTP request headers for those domains. If, due to a strict enterprise security policy, your proxy does change these headers, make sure that at a minimum you allow and don't change the Host and Authorization headers.

Install

  1. Go to https://splunkbase.splunk.com/app/4310/ and download the connector. 
    Tip: On Splunkbase, subscribe to this connector to get notified of future updates. If you want to view or modify (at your own risk) the sample Splunk connector, find it on GitHub at https://github.com/akamai/siem-splunk-connector.
  2. In Splunk, on the upper left of the screen, click the Splunk > icon.
  3. Next to Apps at the top of the navigation bar, click the gear icon.
  4. Click Install app from file.
  5. Click Choose File.
  6. Browse to and select akamai-siem-integration_x.tgz ( x being the latest version available) then click Open.
  7. Click Upload.
  8. Restart Splunk.
    You see AKAMAI SIEM API (Security Information and Event Management).Akamai SIEM option
  9. From the menu, choose Settings > Data Inputs.
  10. Click the Akamai Security Incident Event Manager API.
  11. Click New and complete the following fields:
     
    • Name. Enter any name you want for the input.
    • Hostname. Enter the host URL you copied when you provisioned the SIEM API.
    • Security Configuration(s). Enter the Configuration ID you copied when you turned on SIEM in the Luna portal (allowed SIEM data collection).
    • Client Token, Client Secret, and Access Token. Enter the values you copied when you provisioned the SIEM API.
    • proxy_host. Enter the proxy host name of your proxy server.
    • proxy_port. Enter the port number you use to connect to your proxy server.
    • Initial Epoch Time and Final Epoch time. Leave these fields blank. If you ever encounter an issue with your data field, you can use them to retrieve security event data for a set time period (continue reading to learn how).
    • Limit. If you want to limit the number of security events to pull, you can enter a number here to limit the results for each REST call. If not specified, the API retrieves a maximum of 150000 records per call.
      Note: This sample connector supports transfer of up to 150,000 events per minute.
    • log level is automatically set to INFO. You can change it to WARN, ERROR, FATAL, or DEBUG to get more data for certain situations. For example, if you have a problem with the connector, type DEBUG to get more detailed messages and troubleshoot.
    • Interval. Number of seconds between fetch requests. Enter 60, unless you have entered values in both Initial Epoch Time and Final Epoch Time to retrieve security events from a set time period. In that case, leave the Interval field blank.
      Note: If it takes more than 60 seconds to fetch the data, then increase the interval value to the amount of seconds it takes to fetch the data.
  12. Return to Splunk home and click Akamai SIEM.
    If you see data, setup was successful:Data in Splunk
  13. If you see no data, go to the menu and choose Debug > Akamai Logging dashboard.
    You see Akamai SIEM Errors on the rightSIEM errors in Splunk

    In the event of a fatal error prohibiting collection of data, you’d need to review these logs and take corrective actions. This log is also available in/{splunk_home}/var/log/splunk. Read how to retrieve past security events.

  14. To search for SIEM data within Splunk search app (From Splunk home, click Search and Reporting app), enter the query sourcetype="akamaisiem"

Tip: Akamai strongly recommends installing the Splunk add-on app Lookup File Editor from within Splunk Apps. You need this add-on to switch retrieval mode.

Once a data input is enabled, you can't just edit it and run it again. Disable it, clone the data input, make changes to the clone, then run that new input.

SIEM API data format for Splunk

CIM Mapping List

Event Type Source Type Object Type Event Type Field or Expression CIM Mapping Modles CIM Field
AkamaiSecurityConfigEvent akamaisiem FIELDALIAS attachData.clientIP

  • Vulnerablilities

  • Mallware Attacks

  • All changes

  • Proxy

 Src
AkamaiSecurityConfigEvent akamaisiem FIELDALIAS httpsMessage.byte

  • Vulnerablilities

  • Mallware Attacks

  • All changes

  • Proxy

 bytes

Attack Data

Field Description Example Notes
configId The ID of the Security Configuration applied to the request 6724  
policyId The ID of the Firewall policy applied to the request scoe_5426  
clientIP The IP address of the client that connects to make the request    
slowPostAction If a Slow POST attack is detected, this shows the action taken: either W for Warn or A for deny (abort) W  
slowPostRate If a Slow POST attack is detected, this shows the recorded rate of the Slow POST attack 10  
rules Rule IDs of rules triggered for the request, base64-encoded OTUwMDA0;OTkwMDEx Represents

[950004, 990011]
ruleVersions Versions of rules triggered for the request, base64-encoded ; Represents

[, ]
ruleMessages Messages of rules that triggered for this request, base64-encoded Q3Jvc3Mtc2l0ZSBTY3 JpcHRpbmcgKFhTUykgQXR0YWNr; UmVxdWVzdCBJbmRpY2F0ZXMgYW4 gYXV0b21hdGVkIHByb2 dyYW0gZXhwbG9yZWQgdGhlIHNpdGU= Represents

[Cross-site Scripting(XSS) Attack, Request Indicates an automated program explored the site]
ruleTags Tags of rules that triggered for the request, base64-encoded V0VCX0FUVEFDSy9YU1M=;QV VUT01BVElPTi9NSVND Represents

[WEB_ATTACK/XSS,AUTOMATION/MISC]
ruleData User data of rules that triggered for this request, base64-encoded YWxlcnQo;Y3VybA== Represents

[alert(, curl]
ruleSelectors Selectors of rules that triggered for the request, base64-encoded QVJHUzph;UkVRVUVTVF9IRU FERVJTOlVzZXItQWdlbnQ= Represents

[ARGS:a,REQUEST_HEADERS:User-Agent]
ruleActions Acitons of rules that triggered for the request, base64-encoded QUxFUlQ;REVOWQ== Represents

[ALERT, DENY]
clientReputation Client IP scores for Client Reputation ID=172.19.185.64;WEBATCK=9;DOSATCK=9  
apiID API ID for API Protection API_41  
apiKey API Key for API Protection bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55  

HTTP Mesage Data

Name Value Example
requestId A globally-unique ID created to identify this specific message 2ab418ac8515f33
start This is the time, in epoch format, to millisecond precision, when the Edge Server initiated the connection for the message exchange being monitored 1470923133.026
protocol Protocol of the transaction being monitored http/2
tls TLS version, if applicable. Should be equal to AK_TLS_VERSION TLSv1.2
method Method of the incoming request POST
host Value of the incoming client request's host header www.example.com
port Port number used by the incoming request. Should be equal to the value of AK_IN_PORT 80
path Path used in the incoming URI from the client, not including query strings /examples/1/
query The query strings passed in the incoming URI from the client a=../../../etc/passwd
requestHeaders All request headers collected  
status HTTP Response status sent to the client 301
bytes Content bytes served in the client respons 34523
responseHeaders All response headers collected  

Geo Data

Name Value Example
continent A 2-letter code for the continent that the IP address maps to NA
country An ISO-3166, 2-letter code for the country where the IP address maps to US
city City that the IP address maps to NEWYORK
regionCode An ISO-3166, 2-letter code for the state, province, or region where the IP address maps to NY
asn The AS number or numbers that the IP belongs to 12271

Custom Data

Name Value
custom Base64 custom formatted value. Size limit is 2KB

Retrieve past security events using the Splunk connector

Akamai’s Splunk connector offers 2 modes of operation:

  • Offset-based. Under normal circumstances, this is the mode you want. The connector automatically logs security events as they’re collected. The connector operates in offset mode when the Initial Epoch Time and Final Epoch Time fields are blank.
  • Time-based. If your SIEM connection is disrupted, you may want to go back and replay security events. You can retrieve security event data that occurred within the last 12 hours.

To retrieve missing/past security events, switch from an offset-based to a time-based feed:

  1. Open your Splunk connector’s configuration and in Initial Epoch Time enter the start time (in epoch format) of the period for which you want to review security event data.
  2. In Final Epoch Time (optional) enter the end time for that period (in epoch format). The time window you set can be any interval within the 12 hours preceding the present moment. If you enter nothing here, the connector pulls events up to the present and continues to log events as they’re collected until the connector is restarted.
  3. To return the connector to offset mode, clear the Initial Epoch Time and Final Epoch time fields and save your changes.

If regular offset event collection occurred within the time window, you may see duplicate data in Splunk.

Don't see the data you expected? When you set Initial Epoch Time and Final Epoch Time to retrieve security events for a specific 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 150,000) the connector won't retrieve data. As a workaround, decrease the time window to include all events.

Update the sample Splunk connector

To get notified when a new version of the connector is released, go to the Splunkbase page for the SIEM connector app, and click its Subscribe button. When there's new release, Splunkbase emails you, and you can easily upgrade directly from within your Splunk server web admin page:

  1. Open Splunk.
  2. Next to Apps at the top of the navigation bar, click the gear icon.
  3. On the apps page, you see that Akamai SIEM Integration app has a new release.
  4. Click Update.
  5. Accept the license agreement.
  6. Download and install. You may need to restart.

Release notes

Version 1.4.8

October 2020
Changes include:

  • Performance improvement, verified 600K events per minute on AWS c5n.4xlarge (16 core, 42 GiB RAM, 3.5 gbps EBS Bandwidth, up to 25 gbps Network Bandwidth)
  • Added fix to restart data input when execution time exceeds configured interval

Version 1.4.7

June 2019
Includes a bug fix for Incorrect parsing of header fields and support for Splunk 7.3

Version 1.4.4 

November 2018
Includes a bug fix for java.io.EOFException: Unexpected end of ALIB input streamerror

Version 1.4.2 

October 2018
Includes a bug fix related to proxy support.

Version 1.4.1

September 2018
Changes include:

  • Proxy support
  • Enhancements from version 1.3.0, which was a limited-availability release. It's no longer available, but version 1.4.1 includes all its features.

Version 1.3.0

August 2018 (limited availability release)
Changes include:

  • You can now set log level. For example, if you have a problem, switch to DEBUG mode.
  • You no longer need to enter your Splunk username and password.
  • Client secret is encrypted and is hidden in Splunk interface.
  • Fixed input validation issue.
  • Fixed an issue with SLF4J logging exceptions.
  • Tested on Splunk's new released version 7.1.0.

Version 1.2.0

October 2017 
Changes include:

  • Connector is now Java-based.
  • You must now complete additional fields when creating a data input: Interval between fetch operations and Splunk username and password.
  • Default limit now 150,000 records per call.
  • Some minor changes in how you retrieve past security events.