Security Information and Event Management API 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.

Schemas

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.

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

Member Type Required Description
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.

Member Type Required Description
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.

Member Type Required Description
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 above 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"
    }
]

The following sample Python code produces the JSON array above:

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.

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

Last modified: 11/9/2017