Security Information and Event Management API v1

Returns security events generated on the Akamai platform so you can aggregate them in your SIEM application to optimize security settings.

Learn more:

Overview

The Security Information and Event Management API allows you to capture security events generated on the Akamai platform in your SIEM application.

Who should use this API

Use this API to get security event data generated on the Akamai platform and correlate it with data from other sources in your SIEM solution. Capture security event data incrementally, or replay missed security events from the past 12 hours. You can store, query, and analyze the data delivered through this API on your end, then go back and adjust your Akamai security settings. If you’re coding your own SIEM connector, it needs to adhere to these specifications in order to pull in security events from Akamai Security Events Collector (ASEC) and process them properly.

Get started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

  • To enable this API, choose the API service named SIEM, and set the access level to READ-WRITE.

  • Ensure that the Manage SIEM user role is assigned to your account in Control Center. Follow the instructions in the SIEM Integration Guide.

The connector you build should support accessing SIEM API based on the authentication scheme of the Akamai API protocol. Make sure the connector you build is configurable and able to authenticate itself to the API.

More specifically, the connector configuration needs to support these user-provided values:

  • Hostname (for API endpoint)
  • Client Token
  • Client Secret
  • Access Token

See this Java library that supports authentication of the API clients. Find more code samples that demonstrate the proper way to perform the authentication in the Akamai client libraries.

Also ensure that your SIEM solution takes at most 2 minutes to ingest all logs that you request in a single API call. After 2 minutes, edge servers stop sending the response which may give you incomplete data. This may also prevent you from getting the offset value in the ResponseContext object that appears at the end of each response. If you ever get an incomplete response, rerun this API’s Fetch security events operation with the previously included offset value and a lower limit. This way you can get a full response with an updated offset value.

The SIEM API requires a unique security configuration ID (configId) for each security configuration for which you want to fetch security event data. You’ll find these values in each security configuration’s SIEM Integration section.

In order for the SIEM API to return security events, you need to first turn on SIEM Integration and enable data collection. Follow the instructions in the SIEM Integration Guide to understand how to turn on SIEM Integration.

To get some sample connector code and debugging help, download the SIEM Test Client from the SIEM Integration Page. You can use this test client on the server where your third-party SIEM tool runs to confirm that you can fetch events using the SIEM API. See the test client’s README file for details.

NOTE: Eventually, the SIEM API may apply simple rate limiting that caps the number of client requests. Requests in excess of that rate would result in a 429 error response. The API doesn’t produce an X-RateLimit-Reset HTTP header, so it’s solely up to the API client to throttle its request rate.

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

  • whitelists the domains *.cloudsecurity.akamaiapis.net

  • doesn’t 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.

Note that some security event response values require decoding. Find details in the Configuration rule data section.

Resources

This section provides details on the SIEM API’s single fetch operation, and the parameters you specify in the request URL to configure the report.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Fetch security events GET /siem/v1/configs/{configId}{?offset,limit,from,to}

Fetch security events

Get security events data from your security configurations. Get data in one of two modes: offset or time-based. Both modes order event logs based on their storage time in the database, not the time when the events actually occurred. This may result in delayed event logs in subsequent offset requests, or older event logs in time-based requests. If the connection is disrupted, use time-based mode to go back and replay security events within the last 12 hours. Use offset and limit parameters in offset mode. Use from, to and limit parameters in time-based mode. The potentially large response contains a series of JSON objects, each separated with a linebreak and each corresponding to a security event. The last line of the response is a ResponseContext object that provides total records fetched, an offset to use a starting point for the next batch of data, and limit which shows if the fetch operation reached the limit you set. Run this operation continuously as long as it returns new logs to ensure you don’t miss any. The API may return a maximum of 600,000 logs, while your configurations might generate many more in periods of high traffic.

GET /siem/v1/configs/{configId}{?offset,limit,from,to}

Sample: /siem/v1/configs/12892%3B29182%3B82912?offset=c0bc409010aa6928e57cd5a3000433b9&limit=10&from=1488816442&to=1488816784

Parameter Type Sample Description
URL path parameters
configId String 12892;29182;82912 Unique identifier for each security configuration. To report on more than one configuration, separate integer identifiers with semicolons.
Optional query parameters
from Integer 1488816442 The start of a specified time range, expressed in Unix epoch seconds. This is a required parameter to get time-based results for a set period, and you can’t use it in offset mode.
limit Integer 10 Defines the approximate maximum number of security events each fetch returns, in both offset and time-based modes. The default limit is 10000 and the maximum limit available is 600000. Listing an unlimited number of logs isn’t possible. Expect requests to return a slightly higher number of security events than you set in the limit parameter, because data is stored in different buckets.
offset String c0bc409010aa6928e57cd5a3000433b9 This token denotes the last message. If specified, this operation fetches only security events that have occurred from offset. This is a required parameter for offset mode and you can’t use it in time-based requests.
to Integer 1488816784 The end of a specified time range, expressed in Unix epoch seconds. You can’t use this parameter in offset mode and it’s an optional parameter in time-based mode. If omitted, the value defaults to the current time.

Status 200 application/json

Object type: Event

Download schema: siemEvent.json

Response body:

{
    "format": "json",
    "type": "akamai_siem",
    "version": "1.0",
    "attackData": {
        "clientIP": "52.91.36.10",
        "configId": "14227",
        "policyId": "qik1_26545",
        "ruleActions": "YWxlcnQ%3d%3bYWxlcnQ%3d%3bZGVueQ%3d%3d",
        "ruleData": "dGVsbmV0LmV4ZQ%3d%3d%3bdGVsbmV0LmV4ZQ%3d%3d%3bVmVjdG9yIFNjb3JlOiAxMCwgREVOWSB0aHJlc2hvbGQ6IDksIEFsZXJ0IFJ1bGVzOiA5NTAwMDI6OTUwMDA2LCBEZW55IFJ1bGU6ICwgTGFzdCBNYXRjaGVkIE1lc3NhZ2U6IFN5c3RlbSBDb21tYW5kIEluamVjdGlvbg%3d%3d",
        "ruleMessages": "U3lzdGVtIENvbW1hbmQgQWNjZXNz%3bU3lzdGVtIENvbW1hbmQgSW5qZWN0aW9u%3bQW5vbWFseSBTY29yZSBFeGNlZWRlZCBmb3IgQ29tbWFuZCBJbmplY3Rpb24%3d",
        "ruleSelectors": "QVJHUzpvcHRpb24%3d%3bQVJHUzpvcHRpb24%3d%3b",
        "ruleTags": "T1dBU1BfQ1JTL1dFQl9BVFRBQ0svRklMRV9JTkpFQ1RJT04%3d%3bT1dBU1BfQ1JTL1dFQl9BVFRBQ0svQ09NTUFORF9JTkpFQ1RJT04%3d%3bQUtBTUFJL1BPTElDWS9DTURfSU5KRUNUSU9OX0FOT01BTFk%3d",
        "ruleVersions": "NA%3d%3d%3bNA%3d%3d%3bMQ%3d%3d",
        "rules": "OTUwMDAy%3bOTUwMDA2%3bQ01ELUlOSkVDVElPTi1BTk9NQUxZ"
    },
    "geo": {
        "asn": "14618",
        "city": "ASHBURN",
        "continent": "288",
        "country": "US",
        "regionCode": "VA"
    },
    "httpMessage": {
        "bytes": "266",
        "host": "www.hmapi.com",
        "method": "GET",
        "path": "/",
        "port": "80",
        "protocol": "HTTP/1.1",
        "query": "option=com_jce%20telnet.exe",
        "requestHeaders": "User-Agent%3a%20BOT%2f0.1%20(BOT%20for%20JCE)%0d%0aAccept%3a%20text%2fhtml,application%2fxhtml+xml,application%2fxml%3bq%3d0.9,*%2f*%3bq%3d0.8%0d%0auniqueID%3a%20CR_H8%0d%0aAccept-Language%3a%20en-US,en%3bq%3d0.5%0d%0aAccept-Encoding%3a%20gzip,%20deflate%0d%0aConnection%3a%20keep-alive%0d%0aHost%3a%20www.hmapi.com%0d%0aContent-Length%3a%200%0d%0a",
        "requestId": "1158db1758e37bfe67b7c09",
        "responseHeaders": "Server%3a%20AkamaiGHost%0d%0aMime-Version%3a%201.0%0d%0aContent-Type%3a%20text%2fhtml%0d%0aContent-Length%3a%20266%0d%0aExpires%3a%20Tue,%2004%20Apr%202017%2010%3a57%3a02%20GMT%0d%0aDate%3a%20Tue,%2004%20Apr%202017%2010%3a57%3a02%20GMT%0d%0aConnection%3a%20close%0d%0aSet-Cookie%3a%20ak_bmsc%3dAFE4B6D8CEEDBD286FB10F37AC7B256617DB580D417F0000FE7BE3580429E23D%7epluPrgNmaBdJqOLZFwxqQLSkGGMy4zGMNXrpRIc1Md4qtsDfgjLCojg1hs2HC8JqaaB97QwQRR3YS1ulk+6e9Dbto0YASJAM909Ujbo6Qfyh1XpG0MniBzVbPMUV8oKhBLLPVSNCp0xXMnH8iXGZUHlUsHqWONt3+EGSbWUU320h4GKiGCJkig5r+hc6V1pi3tt7u3LglG3DloEilchdo8D7iu4lrvvAEzyYQI8Hao8M0%3d%3b%20expires%3dTue,%2004%20Apr%202017%2012%3a57%3a02%20GMT%3b%20max-age%3d7200%3b%20path%3d%2f%3b%20domain%3d.hmapi.com%3b%20HttpOnly%0d%0a",
        "start": "1491303422",
        "status": "200"
    }
}

You should already have a set of one or more configId values for each configuration you want data from. See Get started for more information.

  1. If you want data for more than one configId value, join them with a semicolon character, like this: /siem/configs/{config_id1};{config_id2}

  2. Specify how you want to fetch data in one of two ways:

    • If you have an offset value from running a previous report and want another progressive batch, specify it as a parameter. Otherwise specify NULL for an initial default set.

    • If you want data for a range of time rather than an offset-based query, specify from and to values as epoch seconds.

    • Optionally set the limit parameter to cap the number of data records.

  3. Make a GET request to /siem/v1/configs/{configId}{?from,limit,offset,to}.

  4. The response body contains a series of JSON objects, one per line. Each line (except the last one) represents a security Event object containing information about attackData, httpMessage, and geolocation.

  5. If you want more information on the request that triggered a firewall policy rule and generated a security event, see the attackData, httpMessage, and geo sections in JSON objects representing each security event.

  6. If you want to receive the next report as a progressive batch from where there current fetch leaves off, store the offset value from the ResponseContext JSON object on the last line of the response body.

The sample request for the Fetch security events operation shows all possible query parameters, but you wouldn’t use them all together in the same request. This table shows typical combinations for different types of requests:

Query parameters Yield data Sample request
offset Since a prior request. /siem/v1/configs/7777?offset=1500390779
offset, limit Since a prior request, limited. /siem/v1/configs/7777?offset=1500390779&limit=1000
from Since a point in time. /siem/v1/configs/7777?from=1499835600
from, limit Since a point in time, limited. /siem/v1/configs/7777?from=1499835600&limit=1000
from, to Over a range of time. /siem/v1/configs/7777?from=1499835600&to=1499875200
from, to, limit Over a range of time, limited. /siem/v1/configs/7777?from=1499835600&to=1499875200&limit=1000

If a single request contains parameters for both modes, time-based mode takes precedence.

Multi-JSON response format

Here’s a condensed view of the response format. Each event is listed on its own line, and the last line provides metadata on the whole batch. This ResponseContext object shows total records, an offset that marks the last record fetched, and optionally a limit value if set.

Data

This section provides details on the API’s JSON response object, which reports details on each detected attack. In this read-only reporting API, data members marked required are always present in GET responses.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

✓ Member is required in requests, or always present in responses, even if its value is empty or null.
○ Member is optional, and may be omitted in some cases.

Event

This object encapsulates each security event. Each line of response body output represents one of these objects, except for the last, which is a ResponseContext object.

Download schema: siemEvent.json

Sample JSON line within response body, expanded:

{
    "format": "json",
    "type": "akamai_siem",
    "version": "1.0",
    "attackData": {
        "clientIP": "52.91.36.10",
        "configId": "14227",
        "policyId": "qik1_26545",
        "ruleActions": "YWxlcnQ%3d%3bYWxlcnQ%3d%3bZGVueQ%3d%3d",
        "ruleData": "dGVsbmV0LmV4ZQ%3d%3d%3bdGVsbmV0LmV4ZQ%3d%3d%3bVmVjdG9yIFNjb3JlOiAxMCwgREVOWSB0aHJlc2hvbGQ6IDksIEFsZXJ0IFJ1bGVzOiA5NTAwMDI6OTUwMDA2LCBEZW55IFJ1bGU6ICwgTGFzdCBNYXRjaGVkIE1lc3NhZ2U6IFN5c3RlbSBDb21tYW5kIEluamVjdGlvbg%3d%3d",
        "ruleMessages": "U3lzdGVtIENvbW1hbmQgQWNjZXNz%3bU3lzdGVtIENvbW1hbmQgSW5qZWN0aW9u%3bQW5vbWFseSBTY29yZSBFeGNlZWRlZCBmb3IgQ29tbWFuZCBJbmplY3Rpb24%3d",
        "ruleSelectors": "QVJHUzpvcHRpb24%3d%3bQVJHUzpvcHRpb24%3d%3b",
        "ruleTags": "T1dBU1BfQ1JTL1dFQl9BVFRBQ0svRklMRV9JTkpFQ1RJT04%3d%3bT1dBU1BfQ1JTL1dFQl9BVFRBQ0svQ09NTUFORF9JTkpFQ1RJT04%3d%3bQUtBTUFJL1BPTElDWS9DTURfSU5KRUNUSU9OX0FOT01BTFk%3d",
        "ruleVersions": "NA%3d%3d%3bNA%3d%3d%3bMQ%3d%3d",
        "rules": "OTUwMDAy%3bOTUwMDA2%3bQ01ELUlOSkVDVElPTi1BTk9NQUxZ"
    },
    "geo": {
        "asn": "14618",
        "city": "ASHBURN",
        "continent": "288",
        "country": "US",
        "regionCode": "VA"
    },
    "httpMessage": {
        "bytes": "266",
        "host": "www.hmapi.com",
        "method": "GET",
        "path": "/",
        "port": "80",
        "protocol": "HTTP/1.1",
        "query": "option=com_jce%20telnet.exe",
        "requestHeaders": "User-Agent%3a%20BOT%2f0.1%20(BOT%20for%20JCE)%0d%0aAccept%3a%20text%2fhtml,application%2fxhtml+xml,application%2fxml%3bq%3d0.9,*%2f*%3bq%3d0.8%0d%0auniqueID%3a%20CR_H8%0d%0aAccept-Language%3a%20en-US,en%3bq%3d0.5%0d%0aAccept-Encoding%3a%20gzip,%20deflate%0d%0aConnection%3a%20keep-alive%0d%0aHost%3a%20www.hmapi.com%0d%0aContent-Length%3a%200%0d%0a",
        "requestId": "1158db1758e37bfe67b7c09",
        "responseHeaders": "Server%3a%20AkamaiGHost%0d%0aMime-Version%3a%201.0%0d%0aContent-Type%3a%20text%2fhtml%0d%0aContent-Length%3a%20266%0d%0aExpires%3a%20Tue,%2004%20Apr%202017%2010%3a57%3a02%20GMT%0d%0aDate%3a%20Tue,%2004%20Apr%202017%2010%3a57%3a02%20GMT%0d%0aConnection%3a%20close%0d%0aSet-Cookie%3a%20ak_bmsc%3dAFE4B6D8CEEDBD286FB10F37AC7B256617DB580D417F0000FE7BE3580429E23D%7epluPrgNmaBdJqOLZFwxqQLSkGGMy4zGMNXrpRIc1Md4qtsDfgjLCojg1hs2HC8JqaaB97QwQRR3YS1ulk+6e9Dbto0YASJAM909Ujbo6Qfyh1XpG0MniBzVbPMUV8oKhBLLPVSNCp0xXMnH8iXGZUHlUsHqWONt3+EGSbWUU320h4GKiGCJkig5r+hc6V1pi3tt7u3LglG3DloEilchdo8D7iu4lrvvAEzyYQI8Hao8M0%3d%3b%20expires%3dTue,%2004%20Apr%202017%2012%3a57%3a02%20GMT%3b%20max-age%3d7200%3b%20path%3d%2f%3b%20domain%3d.hmapi.com%3b%20HttpOnly%0d%0a",
        "start": "1491303422",
        "status": "200"
    }
}

Event members

Member Type Required Description
Event: This object encapsulates each security event. Each line of response body output represents one of these objects, except for the last, which is a ResponseContext object.
attackData Event.attackData ✓ Characterizes the nature of each attack and provides details on the set of configuration rules that intercepted it. Each rule-related member encodes a conceptual array of faceted data for more than one rule. See Configuration rule data for details.
custom String ○ A value you can customize to distinguish subsets of content. Contact Akamai Professional Services for help configuring the custom field. Size limit is 2KB. See Configuration rule data for information on decoding this value.
format Enumeration ✓ The format of the data representing this security event, json in this context.
geo Event.geo ✓ Encapsulates location data for the attack’s source.
httpMessage Event.httpMessage ✓ Provides context on each attack’s HTTP request.
type Enumeration ✓ Characterizes the source of this report data. Value is always akamai_siem.
version String ✓ The version number for this report’s JSON data format, for example 1.0.
Event.attackData: Characterizes the nature of each attack and provides details on the set of configuration rules that intercepted it. Each rule-related member encodes a conceptual array of faceted data for more than one rule. See Configuration rule data for details.
apiId String ○ For attacks on API services, this is a unique identifier under which the API is protected. It corresponds to the apiEndPointId value in the API Endpoint Definition API, for example API_41.
apiKey String ○ For attacks on API services, this is the security you specify. It corresponds to the apiKeyName value in the API Endpoint Definition API, for example bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55.
clientIP String ✓ The IP address of the client making the request, for example 72.229.28.185.
clientReputation String ○ For Client Reputation customers, provides information on the client IP’s reputation, for example ID=172.19.185.64;WEBATCK=9;DOSATCK=9. See the Client Reputation Integration Guide for details.
configId String ✓ Unique identifier for the security configuration that applied to this request, for example 6724.
policyId String ✓ Unique identifier for the firewall policy applied to this request, for example scoe_5426. Each security configuration may contain more than one policy.
ruleActions String ✓ Identifies whether the request was aborted (deny) or allowed to pass with a warning logged (alert), for example QUxFUlQ;REVOWQ==. See Configuration rule data for information on decoding this value.
ruleData String ✓ User-supplied values that led each rule to trigger, typically suspect text that appears somewhere in the request, or a specified Client Reputation score, for example YWxlcnQo;Y3VybA==. See Configuration rule data for information on decoding this value.
ruleMessages String ✓ The message reported by each triggered rule, for example Q3Jvc3Mtc2l0ZSBTY3JpcHRpbmcgKFhTUykgQXR0YWNr;UmVxdWVzdCBJbmRpY2F0ZXMgYW4gYXV0b21hdGVkIHByb2dyYW0gZXhwbG9yZWQgdGhlIHNpdGU=. See Configuration rule data for information on decoding this value.
rules String ✓ A series of identifiers for rules within the configuration that triggered for this request, for example OTUwMDA0;OTkwMDEx. See Configuration rule data for information on decoding this value.
ruleSelectors String ✓ Identifies the location in the request that triggered each rule, such as the name of an HTTP header, for example QVJHUzph;UkVRVUVTVF9IRUFERVJTOlVzZXItQWdlbnQ=. See Configuration rule data for information on decoding this value.
ruleTags String ✓ Represents a set of categories for the triggered rule, for example V0VCX0FUVEFDSy9YU1M=;QVVUT01BVElPTi9NSVND. See Configuration rule data for information on decoding this value.
ruleVersions String ✓ The version of each triggered rule, for example 4,4,4,4,4,1. See Configuration rule data for information on decoding this value.
slowPostAction Enumeration ○ For any detected slow POST attack, indicate the resulting action, either W for a warning, or A for abort (deny). This member appears only when slow POST protection triggers.
slowPostRate String ○ For any detected slow POST attack, indicates the recorded rate of the attack in bytes per second, for example 10. This member appears only when slow POST protection triggers.
Event.geo: Encapsulates location data for the attack’s source.
asn String ✓ The AS number or numbers that the IP belongs to, for example 12271.
city String ✓ The city to which the IP address maps, for example NEWYORK.
continent String ✓ A two-letter code for the continent to which the IP address maps, for example NA.
country String ✓ A two-letter ISO 3166 code for the country to which the IP address maps, for example US.
regionCode String ✓ A two-letter ISO 3166 code representing the state, province, or region to which the IP address maps, for example NY.
Event.httpMessage: Provides context on each attack’s HTTP request.
bytes String ✓ The number of bytes served in the response, represented as an integer string, for example 34523.
host String ✓ The incoming client request’s Host header, for example www.example.com.
method Enumeration ✓ The request’s HTTP method, either GET, POST, PUT, DELETE, HEAD, or OPTIONS.
path String ✓ The server path from the client’s requested URL, excluding query strings, for example /examples/1/.
port Enumeration ✓ The port number for the incoming request, either 80 or 443.
protocol String ✓ The request protocol, for example http/2.
query String ✓ The client request’s full query string, for example option=com_jce%20telnet.exe.
requestHeaders String ✓ The full set of request headers, URL-encoded.
requestId String ✓ A unique identifier for each request, for example 2ab418ac8515f33.
responseHeaders String ✓ The full set of response headers, URL-encoded.
start String ✓ A string representation of the epoch time when the edge server initiated the connection for the request, for example 1497291979.
status String ✓ The HTTP response status code sent to the client, for example 301.
tls String ○ TLS version if applicable. Should be equal to AK_TLS_VERSION, for example TLSv1.2.

Configuration rule data

This API’s Event response data reflects information about the security configuration that intercepted the request. These configurations contain component rules that are represented in a raw form of URL- and base64-encoded data, partly to accommodate a potentially arbitrary character set used in the attack. Encoded data for these rules appears within each response object’s Event.attackData section:

"attackData": {
    "configId": "14227",
    "policyId": "qik1_26545",
    "clientIP": "52.91.36.10",
    "rules": "OTUwMDAy%3bOTUwMDA2%3bQ01ELUlOSkVDVElPTi1BTk9NQUxZ",
    "ruleVersions": "NA%3d%3d%3bNA%3d%3d%3bMQ%3d%3d",
    "ruleMessages": "U3lzdGVtIENvbW1hbmQgQWNjZXNz%3bU3lzdGVtIENvbW1hbmQgSW5qZWN0aW9u%3bQW5vbWFseSBTY29yZSBFeGNlZWRlZCBmb3IgQ29tbWFuZCBJbmplY3Rpb24%3d",
    "ruleTags": "T1dBU1BfQ1JTL1dFQl9BVFRBQ0svRklMRV9JTkpFQ1RJT04%3d%3bT1dBU1BfQ1JTL1dFQl9BVFRBQ0svQ09NTUFORF9JTkpFQ1RJT04%3d%3bQUtBTUFJL1BPTElDWS9DTURfSU5KRUNUSU9OX0FOT01BTFk%3d",
    "ruleData": "dGVsbmV0LmV4ZQ%3d%3d%3bdGVsbmV0LmV4ZQ%3d%3d%3bVmVjdG9yIFNjb3JlOiAxMCwgREVOWSB0aHJlc2hvbGQ6IDksIEFsZXJ0IFJ1bGVzOiA5NTAwMDI6OTUwMDA2LCBEZW55IFJ1bGU6ICwgTGFzdCBNYXRjaGVkIE1lc3NhZ2U6IFN5c3RlbSBDb21tYW5kIEluamVjdGlvbg%3d%3d",
    "ruleSelectors": "QVJHUzpvcHRpb24%3d%3bQVJHUzpvcHRpb24%3d%3b",
    "ruleActions": "YWxlcnQ%3d%3bYWxlcnQ%3d%3bZGVueQ%3d%3d"
},

Each rule-prefixed member represents a conceptual array of one facet of these rules, but encoded as a string. All rule members list facets of data for the same number of rules, or else empty data items. If you need to relate the data set to your configuration’s set of component rules, you need to decode and collate the values.

Follow these steps for data members that appear within the event’s attackData section:

  1. If the member name is prefixed rule, URL-decode the value. The result is a series of base64-encoded chunks delimited with semicolons, such as YWxlcnQ=;YWxlcnQ=;ZGVueQ==.

  2. Split the value at semicolon (;) characters.

  3. base64-decode each chunk of split data. The example from the first step would yield a sequence of alert, alert, and deny.

As a shortcut when processing large data sets, cache encoded strings that correspond to significant values you’re looking for. For example, an encoded ZGVueQ%3d%3d string within a ruleActions indicates the request was denied.

The JSON array below reflects a conversion using the steps above, based on the encoded rule members within the sample Event object’s attackData section. In this example, each collated member name is adapted from the original set of data:

[
    {
        "rule": "950002",
        "ruleAction": "alert",
        "ruleData": "telnet.exe",
        "ruleMessage": "System Command Access",
        "ruleSelector": "ARGS:option",
        "ruleTag": "OWASP_CRS/WEB_ATTACK/FILE_INJECTION",
        "ruleVersion": "4"
    },
    {
        "rule": "950006",
        "ruleAction": "alert",
        "ruleData": "telnet.exe",
        "ruleMessage": "System Command Injection",
        "ruleSelector": "ARGS:option",
        "ruleTag": "OWASP_CRS/WEB_ATTACK/COMMAND_INJECTION",
        "ruleVersion": "4"
    },
    {
        "rule": "CMD-INJECTION-ANOMALY",
        "ruleAction": "deny",
        "ruleData": "Vector Score: 10, DENY threshold: 9, Alert Rules: 950002:950006, Deny Rule: , Last Matched Message: System Command Injection",
        "ruleMessage": "Anomaly Score Exceeded for Command Injection",
        "ruleSelector": "",
        "ruleTag": "AKAMAI/POLICY/CMD_INJECTION_ANOMALY",
        "ruleVersion": "1"
    }
]

This sample Python code produces the preceding JSON array:

import json, urllib, base64, re

# Get a JSON string for a SIEM event:
f = open("siem_event.json")
json_string = f.read()

event = json.loads(json_string)
attack_section = event['attackData']
rules_array = []

for member in attack_section:
    if member[0:4] != 'rule': continue
    # Alternate field name converted from plural:
    member_as_singular = re.sub("s$", "", member)
    url_decoded = urllib.unquote(attack_section[member]).decode('utf8')
    member_array = url_decoded.split(";")
    if not len(rules_array):
        for i in range(len(member_array)):
            rules_array.append({})
    i = 0
    for item in member_array:
        rules_array[i][member_as_singular] = base64.b64decode(item)
        i += 1

print json.dumps(rules_array, indent=4, ensure_ascii=True)

ResponseContext

This object features contextual metadata about the set of security events included in each response and appears on the last line of the response body.

Download schema: siemResponseContext.json

Sample final JSON line of the response body, expanded:

{
    "total": 10000,
    "offset": "71cca;3phZmEdPj6YEqml0rvbdWDZGW3mCiJIwjyhkJfsLFM2gVYPgE8-N_0CiLI9gwH0_4OJ87xDQ3b-gIsx_kEBdf7aaC_AvDpG9fMxypeaCma10FKrY9VKE",
    "limit": 10000
}

ResponseContext members

Member Type Required Description
ResponseContext: This object features contextual metadata about the set of security events included in each response and appears on the last line of the response body.
limit Integer ✓ Appears if the size limit was reached during data fetch.
offset String ✓ Identifies the last processed security event in a response. To fetch only those security events that occurred since the last pull, enter this value as an offset parameter.
total Integer ✓ The number of security events included in the response.

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

To facilitate issue investigation and troubleshooting, make all the data returned in case of a failed response (which is any HTTP error code other than 200 OK) accessible to the SIEM administrator and users. When creating your SIEM connector, show error messages, relevant server IPs, and so on. At the very least, show the error code and error message in your connector user interface.

Error responses

The SIEM API responds with JSON objects that adhere to the HTTP Problem Details specification. Here’s a sample rate-limiting error response:

{
  "type": "https://problems.cloudsecurity.akamaiapis.net/siem/v1/too-many-requests",
  "title": "Too many requests",
  "instance": "https://akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.cloudsecurity.akamaiapis.net/siem/v1/configs/14227?offset=71cca;GWJY-imjtGH-XXXXXXXXXX",
  "detail": "Too many requests made from clients of this account",
  "method": "GET",
  "serverIp": "72.246.153.146",
  "clientIp": "23.79.236.10",
  "requestId": "2eebd8",
  "requestTime": "2015-08-21T18:11:34Z"
}

HTTP status codes

This table lists the full range of response codes the API may generate.

Code Description
200 The operation was successful. If there’s no data for the requested criteria, the response may contain an empty array.
400 Bad Request. The response message states the cause, which could be missing mandatory API parameters or illegal parameter values.
403 The connecting client lacks permission to make the request.
404 At least one of the objects specified, such as a specified configId, doesn’t exist.
416 Invalid range request. See response message for details.
428 Request must be conditional. Response message provides guidance.
429 You have exceeded the rate limit on requests.
500 Any other error. Response message states the specific reason.
503 The service on which this API depends is temporarily unavailable.