
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:
Download this API’s RAML and JSON schema descriptors.
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:
allows 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
andAuthorization
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/ |
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 per request,
while your configurations might generate many more in periods of high traffic.
GET /siem/
Sample: /siem/
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.
If you want data for more than one
configId
value, join them with a semicolon character, like this:/siem/configs/{config_id1};{config_id2}
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 specifyNULL
for an initial default set.If you want data for a range of time rather than an offset-based query, specify
from
andto
values as epoch seconds.Optionally set the
limit
parameter to cap the number of data records.
Make a GET request to
/
.siem/ v1/ configs/ {configId}{?from, limit, offset, to} 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.
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.
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/ |
offset , limit |
Since a prior request, limited. | /siem/ |
from |
Since a point in time. | /siem/ |
from , limit |
Since a point in time, limited. | /siem/ |
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/ |
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. |
✓ | 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. |
✓ | Encapsulates location data for the attack’s source. |
httpMessage |
Event. |
✓ | 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 Q3Jvc3Mtc2l0ZSBTY3Jp . 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;UkVRV . See Configuration rule data for information on decoding this value. |
ruleTags |
String | ✓ | Represents a set of categories for the triggered rule, for example V0VCX0FU . 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:
If the member name is prefixed
rule
, URL-decode the value. The result is a series of base64-encoded chunks delimited with semicolons, such asYWxlcnQ=;YWxlcnQ=;ZGVueQ==
.Split the value at semicolon (
;
) characters.base64-decode each chunk of split data. The example from the first step would yield a sequence of
alert
,alert
, anddeny
.
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. |