About the sample Splunk connector
Combine Splunk and Akamai to gain insights into attacks. Watch the Analytics-driven Cloud Security at Scale with Splunk and Akamai video to learn more.
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 event data from JSON into CIM format. The Splunk instance then analyzes high volumes of data by indexing it.
Install Splunk connector
System Requirements
- Akamai’s Splunk Connector requires Oracle JRE 1.8+. Download the latest from the Oracle Java site (Java Platform, Standard Edition) or install it from a software distribution package on Linux.
- Java is installed on the host running Splunk Enterprise.
- KVStore is installed on the host machine where you want to install your connector.
- Verify 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
Additional hardware requirements include:
- 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.
- 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
-
Go to https://splunkbase.splunk.com/app/4310/ and download the connector.
Tip: On Splunkbase, subscribe to this connector to be 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.
-
In Splunk, in the upper left of the screen, click the Splunk icon.
-
Next to Apps at the top of the navigation bar, click the gear icon.
-
Click Install app from file.
-
Click Choose File.
-
Browse to and select akamai-siem-integration_x.tgz (x being the latest version available) and then click Open.
-
Click Upload.
-
Restart Splunk. You see Akamai SIEM:
-
From the menu, click Settings > Data Inputs.
-
Click the Akamai Security Incident Event Manager API.
-
Click New and complete the following fields:
- Name. Enter any name you want for the input.
- Hostname. Enter the host URL copied when you provisioned the SIEM API.
- Security Configuration(s). Enter the Configuration ID copied when you enabled SIEM in the Akamai Control Center.
- Client Token, Client Secret, and Access Token. Enter the values copied when you provisioned the SIEM API.
- proxy_host. Enter the proxy hostname 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 encounter an issue with event delivery, you can use these fields to retrieve security event data for a specific time period (continue reading to learn how to do this).
-
Limit. To limit the number of security events pulled with each API call, enter an integer value here. If not specified, the API retrieves a maximum of 150,000 records per call.
log level. Specifies the message types that are logged. By default, the log level is set to INFO, but 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, use DEBUG to get more detailed messages that will help you troubleshoot. - Interval. Number of seconds between fetch requests. Enter 60 unless you have entered values in both the Initial Epoch Time and Final Epoch Time fields to retrieve security events for a set time period. In that case, leave the Interval field blank. If it takes more than 60 seconds to fetch the data, increase the interval value to the amount of seconds needed to complete the task.
-
Return to the Splunk home page and click Akamai SIEM. If you see data that means that setup was successful:
-
If you don't see data, go to the menu and click Debug > Akamai Logging dashboard. You see Akamai SIEM Errors on the right:
In the event of a fatal error prohibiting collection of data, review the logs and take corrective action. This log is also available in /{splunk_home}/var/log/splunk. Read how to retrieve past security events.
-
To search for SIEM data within Splunk, use the search app: from the Splunk home page, click Search and Reporting app and 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.
After a data input is enabled, you can't edit that input and run it again. Instead, you must disable the input, clone it, make changes to the clone, then run the new, cloned input.
SIEM API data format for Splunk
CIM Mapping List
Event Type | Source Type | Object Type | Event Type Field or Expression | CIM Mapping Models | CIM Field |
AkamaiSecurityConfigEvent | akamaisiem | FIELDALIAS | attachData.clientIP |
|
Src |
AkamaiSecurityConfigEvent | akamaisiem | FIELDALIAS | httpsMessage.byte |
|
bytes |
Attack Data
Field | Description | Example | Notes |
configId | ID of the Security Configuration applied to the request. | 6724 |
|
policyId | ID of the Firewall policy applied to the request. | scoe_5426 |
|
clientIP | IP address of the client that connects to make the request. | ||
slowPostAction | Action taken if a Slow POST attack is detected: W for Warn or A for deny (abort). | W |
|
slowPostRate | Recorded rate of a detected Slow POST attack. | 10 |
|
rules | Base64-encoded rule IDs of rules triggered for the request. | OTUwMDA0;OTkwMDEx |
Represents
|
ruleVersions | Base64-encoded versions of rules triggered for the request. | ; |
Represents
|
ruleMessages | Base64-encoded messages of rules that triggered for this request. | Q3Jvc3Mtc2l0ZSBTY3 JpcHRpbmcgKFhTUykgQXR0YWNr; UmVxdWVzdCBJbmRpY2F0ZXMgYW4 gYXV0b21hdGVkIHByb2 dyYW0gZXhwbG9yZWQgdGhlIHNpdGU= |
Represents
|
ruleTags | Base64-encoded tags of rules that triggered for the request. | V0VCX0FUVEFDSy9YU1M=;QV VUT01BVElPTi9NSVND |
Represents
See WAF rules list for all tags |
ruleData | Base64-encoded user data of rules that triggered for this request. | YWxlcnQo;Y3VybA== |
Represents
|
ruleSelectors | Base64-encoded selectors of rules that triggered for the request. | QVJHUzph;UkVRVUVTVF9IRU FERVJTOlVzZXItQWdlbnQ= |
Represents
|
ruleActions | Base64-encoded actions of rules that triggered for the request. | QUxFUlQ;REVOWQ== |
Represents
|
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 Message Data
Name | Description | Example |
requestId | Globally-unique ID for the message. | 2ab418ac8515f33 |
start | Time, in epoch format (and 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 | HTTP 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 | 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 response. | 34523 |
responseHeaders | All response headers collected. |
Geo Data
Name | Description | Example |
continent | 2-letter code for the continent that the IP address maps to. | NA |
country | 2-letter ISO-3166 code for the country that the IP address maps to. | US |
city | City that the IP address maps to. | NEWYORK |
regionCode | 2-letter ISO-3166 code for the state, province, or region that the IP address maps to. | NY |
asn | Autonomous System Number (or numbers) that the IP belongs to. | 12271 |
userRiskData Object
User information included in an event if: 1) you are using Account Protector; and, 2) the event occurs on a protected endpoint. If a client request is denied, user risk information might not be calculated and included in the event, depending on when that denial took place.
Name | Description | Example |
uuid | Unique identifier of the user whose risk data is being provided. | 813d54f4-0821-4o0a-a2pp6-0101dd0ec23u |
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. |
0 |
score | Calculated risk scores. Scores range from 0 (no risk) to 100 (the highest possible risk). | 75 |
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. | udfp:1325gdg4g4343g/M |
trust | Indicators that were trusted. For example, the value ugp indicates that the user’s country or area is trusted. | ugp:US |
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. | duc_1h:10 |
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. | 0 |
clientData Object
This data is included only if you are running Botman Premier and the request is matched as a resource purpose with bot protection enabled.
Name | Description | Example |
appBundleId | Unique identifier of the app bundle. An app bundle contains both the software itself and the accompanying configuration information. | AXWDAA |
appVersion | Version number of the app. | 1.1.2 |
telemetryType | Specifies the telemetry type in use. Allowed values are:
|
1 |
botData Object
Akamai Bot Manager information associated with the event. This data is included only if you are running Botman Premier and the request is matched as a resource purpose with bot protection enabled.
Name | Description | Example |
botScore | Score assigned to the request by Botman Manager. | 65 |
responseSegment | Numeric response segment indicator. Segments are used to group and categorize bot scores. Allowed values are:
|
3 |
Custom Data
Name | Value |
custom | Base64-encoded custom value. The size limit for custom data is 2KB. |
Retrieve past security events using the Splunk connector
Akamai’s Splunk 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 any time the Initial Epoch Time and Final Epoch Time fields are blank.
- Time-based. Enables you to retrieve only the events that occurred with a specified time period (requires the use of the Initial Epoch Time field and, optionally, the Final Epoch Time field). 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:
- Open your Splunk connector’s configuration file and, in the Initial Epoch Time field, enter the start time (in epoch format) of the period for which you want to retrieve security event data.
- (Optional) In the Final Epoch Time field, 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 Final Epoch Time is left blank the connector pulls all events from the initial time period to the present and continues to log events as they’re collected.
- To return the connector to offset mode, clear the Initial Epoch Time and Final Epoch time fields and save your changes.
Note that, if regular offset event collection occurred within the time window, you might see duplicate data in Splunk.
Don't see the data you expected? When you set the Initial Epoch Time and Final Epoch Time fields 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 150,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.
Update the sample Splunk connector
To be notified when a new version of the connector is released, go to the Splunkbase page for the SIEM connector app, and click Subscribe. When there's new release, Splunkbase notifies you via email. You can then upgrade directly from within your Splunk server web admin page by doing the following:
- Open Splunk.
- Next to Apps at the top of the navigation bar, click the gear icon.
- On the apps page, you see that the Akamai SIEM Integration app has a new release. Click Update.
- Accept the license agreement.
- Download and install. You may need to restart Splunk following the installation.
Release notes
Version 1.4.13
January 2022
Upgrade log4j version to fix CVE-2021-44832 vulnerability.
Version 1.4.11
December 2021
Upgrade log4j version to fix CVE-2021-45046 vulnerability.
Version 1.4.10
December 2021
Upgrade log4j version to fix CVE-2021-44228 vulnerability.
Version 1.4.9
June 2021
Changes include:
- Feature enhancement "Automatically support new fields provided by SIEM OPEN API response"
- Fixes and improvements
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 the 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 the 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:
- The 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.