Security Monitor API v1

Retrieve real-time security event data to monitor protection of your digital assets.

Learn more:


Overview

Security Monitor gives real-time visibility to security scanning provided by Akamai Web Application Firewall (WAF) and Kona Site Defender (KSD) offerings. Security events logged from WAF/KSD are aggregated and displayed within minutes of their occurrence.

You can utilize the Security Monitor API to visualize and understand how your digital properties are protected. The REST API responds to requests with standard HTTP status codes. Error messages are embedded in the JSON response in the event of a validation failure or when the API fails to process your request.

Getting started

See Get Started to start making Akamai API calls.

URL structure

https://{BASE_URL}/security-monitor/v1/...

Generate the BASE_URL using the Manage APIs tool in Akamai Luna Control Center.

Sample usage: steps to retrieve data

Step 1: retrieve security monitor report pack

A Report pack is a collection of reports. All Security Monitor report packs can be retrieved using the resource given below. You may skip this step, if the report packs are known. A sample request and response is shown below:

GET: /security-monitor/v1/report-packs

[
    {
        "id": 12332,
        "name": "Sample 1",
        "isActive": true,
        "type": "qos",
        "subType": "QoS_Security_Monitor",
        "timezone": "GMT"
    },
    {
        "id": 121234,
        "name": "Sample 1",
        "isActive": true,
        "type": "ma",
        "subType": "QoS_Security_Monitor",
        "timezone": "EST5EDT"
    }
]

Step 2: retrieve report pack details

Next, you will need to retrieve the details of the report pack. Details include report pack name, data stores, data sources, metrics and dimensions used in the report pack.

Data store details help you determine the combination of dimensions and metrics to query. Remember, you cannot combine dimensions and metrics across data stores.

A data source is a set of IDs (Policy IDs) that were assigned by you and Akamai in Luna Control Center for a firewall policy during WAF configuration.

Seen below is how you can use report pack ID as the parameter to make an API call in order to obtain details of the report pack.

GET: /security-monitor/v1/report-packs/{report-packId}

A sample request and its response is shown below.

GET: /security-monitor/v1/report-packs/12332

{
    "id": 12332,
    "name": "Sample 1",
    "isActive": true,
    "type": "qos",
    "subType": "QoS_Security_Monitor",
    "dataSources": [
        {
            "id": 2673,
            "name": "Security Monitor Data Source"
        }
    ],
    "dimensions": [
        {
            "id": 43,
            "name": "Time",
            "type": "standard"
        },
        {
            "id": 958,
            "name": "City",
            "type": "standard"
        },
        {
            "id": 956,
            "name": "Client IP",
            "type": "standard"
        },
        {
            "id": 957,
            "name": "Country",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "id": 546,
            "name": "Contributing Rules"
        },
        {
            "id": 552,
            "name": "Requests Warned",
            "description": "Number of request warned"
        },
        {
            "id": 544,
            "name": "Requests Denied"
        },
        {
            "id": 3,
            "name": "Rules Triggered"
        }
    ],
    "filters": null,
    "dataStores": [
        {
            "id": 939,
            "name": "sample data store 1",
            "type": "standard",
            "description": "Sample Description"
        },
        {
            "id": 952,
            "name": "sample data store 2",
            "type": "custom",
            "description": "Sample Description"
        }
    ],
    "timezone": "GMT"
}

Step 3: retrieve report data

You can retrieve data for a specific report using the call below.

GET: /security-monitor/v1/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

Let’s assume that the dimension IDs 43,957 represent time,country and the metric ID 544 represents the metric “Number of requests denied”. A sample call to fetch data for countries in which requests were denied for Nov 13, 2014 between 12 AM and 12:05 AM is shown below along with its response.

GET: /security-monitor/v1/report-packs/12332/data?dimensions=43&metrics=544&startDate=11/13/2014:00:00&endDate=11/13/2014:00:05&limit=5

{
    "columns": [
        {
            "type": "dimension",
            "name": "Time",
            "description": "Time as per time zone specified in the report",
            "index": 0
        },
        {
            "type": "dimension",
            "name": "Country",
            "description": "Country from which viewer requested media ",
            "index": 1
        },
        {
            "type": "metric",
            "name": "Requests Denied",
            "description": "Number of request denied",
            "index": 2,
            "aggregate": "418",
            "peak": "156",
            "unit": null
        }
    ],
    "rows": [
        [ "1415837040", "US", "156" ],
        [ "1415837040", "CH", "136" ],
        [ "1415836980", "US", "113" ],
        [ "1415836980", "CH", "103" ],
        [ "1415836920", "US", "95" ]
    ],
    "metaData": {
        "aggregation": 60,
        "limit": 5,
        "startTimeInEpoch": 1415836800,
        "hasMoreData": false,
        "timeZone": "GMT",
        "offset": 0,
        "reportPack": "Security Monitor Report Pack",
        "endTimeInEpoch": 1415837100
    }
}

Important notes

  • Request Parameter Encoding: All the request parameter values must be UTF–8 encoded.

  • Country Codes: Security Monitor APIs allows you to work with geographic lists of country codes. You will need to use the codes found on the Akamai EdgeScape country codes page (SupportUser and Developer GuidesEdgeScapeData CodesCountry Codes) in Akamai Luna Control Center

  • Usage Criterion: Security Monitor APIs are available for occasional on-demand fetch of data only. Automated and programmed fetches in a Poll fashion are not supported. Such usage will be scrutinized and may be dropped.

  • Rate Limiting: API endpoints are subject to a rate-limiting constraint, which is currently set at five requests per minute. When this limit is exceeded, an HTTP 429 error (Too Many Requests) is returned. This should be considered carefully when implementing endpoints that act on single list entries in a loop.

Resources

This section provides details on the Security Monitor API’s URL operations.

API summary

Operation Method Endpoint
Report Packs
List Report Packs GET /security-monitor/v1/report-packs
Get a Report Pack GET /security-monitor/v1/report-packs/{reportPackId}
List Data Stores GET /security-monitor/v1/report-packs/{reportPackId}/data-stores
Get a Data Store GET /security-monitor/v1/report-packs/{reportPackId}/data-stores/{dataStoreId}
List Data Sources GET /security-monitor/v1/report-packs/{reportPackId}/data-sources
Report Data
Get a Report GET /security-monitor/v1/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

List report packs

Returns name, id, and timezone for all report packs created for your account. Report packs are a collection of reports fed by data sources and other components. If you already have reports pack details on hand, see List Data Stores.

GET /security-monitor/v1/report-packs

Status 200 application/json

Response:

[
    {
        "id": 12332,
        "name": "Sample 1",
        "isActive": true,
        "type": "qos",
        "subType": "QoS_Security_Monitor",
        "timezone": "GMT"
    },
    {
        "id": 121234,
        "name": "Sample 1",
        "isActive": true,
        "type": "ma",
        "subType": "QoS_Security_Monitor",
        "timezone": "EST5EDT"
    }

See ReportPackCollection for details on data members.

Get a report pack

Details include name of the report pack, data sources, and metrics and dimensions used in the report pack.

GET /security-monitor/v1/report-packs/{reportPackId}

Example: /security-monitor/v1/report-packs/121234

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID

Status 200 application/json

Response:

{
    "id": 12332,
    "name": "Sample 1",
    "isActive": true,
    "type": "qos",
    "subType": "QoS_Security_Monitor",
    "dataSources": [
        {
            "id": 2673,
            "name": "Security Monitor Data Source"
        }
    ],
    "dimensions": [
        {
            "id": 43,
            "name": "Time",
            "type": "standard"
        },
        {
            "id": 958,
            "name": "City",
            "type": "standard"
        },
        {
            "id": 956,
            "name": "Client IP",
            "type": "standard"
        },
        {
            "id": 957,
            "name": "Country",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "id": 546,
            "name": "Contributing Rules"
        },
        {
            "id": 552,
            "name": "Requests Warned",
            "description": "Number of request warned"
        },
        {
            "id": 544,
            "name": "Requests Denied"
        },
        {
            "id": 3,
            "name": "Rules Triggered"
        }
    ],
    "filters": null,
    "dataStores": [
        {
            "id": 939,
            "name": "sample data store 1",
            "type": "standard",
            "description": "Sample Description"
        },
        {
            "id": 952,
            "name": "sample data store 2",
            "type": "custom",
            "description": "Sample Description"
        }
    ],
    "timezone": "GMT"
}

See ReportPack for details on data members.

List data stores

A data store is a collection of dimensions and metrics stored in a database that you can use to create a sub-set and configure reports suited to your requirements. Data store details help you determine the combination of dimensions and metrics to query. Each report pack comes with its standard data stores. You cannot combine dimensions and metrics across data stores.

GET /security-monitor/v1/report-packs/{reportPackId}/data-stores

Example: /security-monitor/v1/report-packs/121234/data-stores

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 939,
        "name": "sample data store",
        "type": "standard",
        "dimensions": [
            {
                "id": 958,
                "name": "City",
                "description": "City from which viewer requested media",
                "type": "standard"
            },
            {
                "id": 956,
                "name": "Client IP",
                "description": "SD Dimension",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 546,
                "name": "Contributing Rules",
                "description": "Contributing Rules"
            },
            {
                "id": 552,
                "name": "Requests Warned",
                "description": "Number of request warned"
            },
            {
                "id": 3,
                "name": "Rules Triggered",
                "description": "Number of rules triggered"
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 8,
        "maxQueryDurationInMinutes": 1440,
        "description": "sample data store description"
    },
    {
        "id": 952,
        "name": "Time only cubes for security_monitor",
        "type": "standard",
        "description": "Time only cubes for security_monitor",
        "dimensions": [
            {
                "id": 43,
                "name": "Time",
                "description": "Time as per time zone specified in the report",
                "type": "standard"
            }
        ],
        "metrics": [
            {
                "id": 552,
                "name": "Requests Warned",
                "description": "Number of request warned"
            },
            {
                "id": 3,
                "name": "Rules Triggered",
                "description": "Number of rules triggered"
            }
        ],
        "aggregationInSeconds": 60,
        "purgeIntervalInDays": 8,
        "maxQueryDurationInMinutes": 1440
    }
]

See DataStore for details on data members.

Get a data store

Details include list of dimensions, list of metrics, aggregation interval, purge interval, and maximum allowed query interval, and so on.

GET /security-monitor/v1/report-packs/{reportPackId}/data-stores/{dataStoreId}

Example: /security-monitor/v1/report-packs/121234/data-stores/939

Parameter Type Sample Description
Required
dataStoreId Number 939 Data store ID.
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

{
    "aggregationInSeconds": 60,
    "description": "sample data store description",
    "id": 939,
    "maxQueryDurationInMinutes": 1440,
    "name": "sample data store",
    "purgeIntervalInDays": 8,
    "type": "standard",
    "dimensions": [
        {
            "description": "City from which viewer requested media",
            "id": 958,
            "name": "City",
            "type": "standard"
        },
        {
            "description": "SD Dimension",
            "id": 956,
            "name": "Client IP",
            "type": "standard"
        }
    ],
    "metrics": [
        {
            "description": "Contributing Rules",
            "id": 546,
            "name": "Contributing Rules"
        },
        {
            "description": "Number of request warned",
            "id": 552,
            "name": "Requests Warned"
        },
        {
            "description": "Number of rules triggered",
            "id": 3,
            "name": "Rules Triggered"
        }
    ]
}

See DataStore for details on data members.

List data sources

A data source is a set of IDs (Policy IDs) that were assigned by you and Akamai in Luna Control Center for a firewall policy during WAF configuration.

GET /security-monitor/v1/report-packs/{reportPackId}/data-sources

Example: /security-monitor/v1/report-packs/121234/data-sources

Parameter Type Sample Description
Required
reportPackId Number 121234 Report pack ID.

Status 200 application/json

Response:

[
    {
        "id": 2673,
        "name": "Security Monitor Data Source",
        "type": "clientside_qos1_sm",
        "dsType": "policyId",
        "values": [
            "111_375", "mob_1183", "16767", "444_374",
            "432_336", "DFN_667", "DRFB_2968", "188279"
        ]
    }
]

See DataSource for details on data members.

Get a report

This operation gets data for a specific report based on filter query parameters. Use filterParams and sortParams to filter and sort data. The values for these parameters must be UTF–8 encoded JSON strings as detailed below.

GET /security-monitor/v1/report-packs/{reportPackId}/data{?startDate,endDate,aggregation,dimensions,metrics,limit,offset,filterParams,sortParams}

Example: /security-monitor/v1/report-packs/121234/data?startDate=03%2F22%2F2014%3A15%3A30&endDate=03%2F23%2F2014%3A15%3A30&aggregation=month&dimensions=958%2C956&metrics=546%2C552%2C3&limit=300&offset=0&filterParams=%5B%7B%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22GB%22%5D%2C%22id%22%3A4%2C%22condition%22%3A%22in%22%7D%2C%7B%22type%22%3A%22metric%22%2C%22values%22%3A%5B16%5D%2C%22id%22%3A155%2C%22condition%22%3A%22gt%22%7D%5D&sortParams=%5B%7B%22type%22%3A%22metric%22%2C%22order%22%3A%22asc%22%2C%22id%22%3A40%7D%5D

Headers:

  • Accept: application/json

Parameter Type Sample Description
Optional
aggregation String month Aggregation in which the data must be grouped. It can be a number representing the aggregation in seconds or one of the following possible values day, week, month, year. If passed as a number, the allowed value is one of the aggregations of the available data stores available from List Data Stores.
dimensions String 958,956 Comma-separated dimension IDs, a maximum of two. Use List Data Stores to get these values.
endDate String 03/23/2014:15:30 End date string in format MM/dd/yyyy:HH:mm. Make sure that the query period between start and end date is under four hours. Specify the time portion in 24-hour format.
filterParams String [{"type":"dimension","values":["GB"],"id":4,"condition":"in"},{"type":"metric","values":[16],"id":155,"condition":"gt"}] The UTF–8 URL-encoded JSON string of the filter parameters based on which the data is filtered. The structure of the JSON is explained above. By default, the data is not filtered.
limit Number 300 Number of rows to return. Value must lie between 1 and 10000 inclusive. If not specified, 300 rows are returned, by default.
metrics String 546,552,3 Comma-separated metric IDs. Use List Data Stores to get these values.
offset Number 0 The offset of the row from which the data starts. This parameter must be used along with limit to get batches of data. For instance, if there are 1000 records in the result, 10 calls can be made with progressing offset. That is, first call with limit=100 and offset=0, second call with limit=100 and offset=100, and so forth. The default value is 0
reportPackId Number 121234 Report pack ID.
sortParams String [{"type":"metric","order":"asc","id":40}] The UTF–8 URL-encoded JSON string of the sort parameters based on which the data is sorted. The structure of the JSON is explained above. By default, the data is sorted by time, if time is selected as one of the dimensions. If time is not one of the dimensions, data is sorted by the first metric in descending order.
startDate String 03/22/2014:15:30 Start date string in the format MM/dd/yyyy:HH:mm. Make sure that the query period between start and end date is under four hours. Specify the time portion in 24-hour format.

All filterParams members are required:

Member Type Description
condition Enumeration Condition specifier. Prepending n negates the condition. For Dimensions: in, nin, contains, ncontains, starts, nstarts, ends, nends. For Metrics: eq, neq, gt, gte, lt, lte.
id Number Identifies the dimension or metric.
type Enumeration The parameter ID provided, either dimension or metric.
values Array List of values used to filter the result.

All sortParams members are required:

Member Type Description
id Number ID of the sorting entity.
order Enumeration Either asc (ascending) or desc (descending) sort order.
type Enumeration Determines if the sorting is based on dimension or metric.

Status 200 application/json

Response:

{
    "columns": [
        {
            "type": "dimension",
            "name": "Time",
            "description": "Time as per time zone specified in the report   ",
            "index": 0
        },
        {
            "type": "dimension",
            "name": "Country",
            "description": "Country from which viewer requested media",
            "index": 1
        },
        {
            "type": "metric",
            "name": "Denied",
            "description": "Number of request denied",
            "index": 2,
            "aggregate": "418",
            "peak": "156",
            "unit": null
        }
    ],
    "rows": [
        [ "1415837040", "US", "156" ],
        [ "1415836980", "US", "113" ],
        [ "1415836920", "US", "95" ],
        [ "1415836860", "US", "54" ]
    ],
    "metaData": {
        "aggregation": 60,
        "limit": 50,
        "startTimeInEpoch": 1415836800,
        "hasMoreData": false,
        "timeZone": "GMT",
        "offset": 0,
        "reportPack": "Security Monitor Report Pack",
        "endTimeInEpoch": 1415837100
    }
}

See Report for details on the data members.

Here is an example of a request. Assume that the dimension IDs 12,34 represent time and country respectively and the metric ID 56 represents the metric Number of requests denied. Assume you also need the following data:

  • Data for the United States only for Nov 13, 2014 between 12 AM and 12:05 AM.

  • Data only for requests denied numbering 51 or more.

  • Data for requests denied sorted in descending order.

The request URL should look like this:

https://{host}/security-monitor/v1/report-packs/123456/data?dimensions=12,34&metrics=56&startDate=11/13/2014:00:00&endDate=11/13/2014:00:05&limit=50
&filterParams=%5B%7B%22id%22%3A78%2C%22type%22%3A%22dimension%22%2C%22values%22%3A%5B%22US%22%5D%2C%22condition%22%3A%22in%22%7D%2C%7B%22id%22%3A651%2C%22type%22%3A%22metric%22%2C%22values%22%3A%5B50%5D%2C%22condition%22%3A%22gt%22%7D%5D
&sortParams=%5B%7B%22id%22%3A651%2C%22type%22%3A%22metric%22%2C%22order%22%3A%22desc%22%7D%5D

In this example, the value of filterParams is a UTF–8 encoded representation of this JSON string:

[
    {
        "condition": "in",
        "id": 12,
        "type": "dimension",
        "values": [
            "US"
        ]
    },
    {
        "condition": "gt",
        "id": 56,
        "type": "metric",
        "values": [
            50
        ]
    }
]

The sortParams value is a UTF–8 encoded representation of this JSON string:

[
    {
        "id": 651,
        "order": "desc",
        "type": "metric"
    }
]

Data

This section provides details on the Security Monitor API’s data members.

ReportPackCollection

Member Type Description
id Number Integer ID of the report pack.
name String Name of the report pack.
subType String This field is meant for internal use and will be removed.
timezone String Timezone in which the data is returned.
type String This field is meant for internal use and will be removed.

ReportPack

Member Type Description
dataSources Array All data sources for the report pack. A data source is a collection of raw log data with detailed information on each access to your digital property made by a user. Each data source object provides information on name of the data source and its ID.
dataStores Array All data stores for the report pack. A data store is a collection of dimensions and metrics stored in a data base. Each data store object provides information on the name, type, short description, and ID of the data store.
dimensions Array All dimensions for the report pack. The dimension is a field that acts like a key in data exploration. It answers questions such as who, what, where, and which. Each dimension object provides information on the name, type, and ID of the dimension.
filters null This field is meant for internal use and will be removed.
id Number Integer ID of the report pack.
metrics Array All metrics for the report pack. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name and ID of the metric. It answers questions on volume of activity or attack.
name String Name of the report pack.
subType String This field is meant for internal use and will be removed.
timezone String Timezone in which the data is returned.
type String This field is meant for internal use and will be removed.

DataStore

Member Type Description
aggregation Number Time (seconds) over which data is aggregated.
description String Text describing the data store.
dimensions Array All dimensions for the data store. Dimension is a field that acts like a key in data exploration. Each dimension object provides information on ID, name, type, and description of the dimension. It answers questions such as who, what, where, and which.
id Number data store ID.
maxQueryDurationInMinutes Number Maximum duration (in minutes) for which a user can query a data store.
metrics Array All metrics for the data store. A metric is a numeric aggregation against one or more dimensions. Each metric object provides information on the name, description, and ID of the metric. It answers questions on volume of activity or attack.
name String Name of the data store.
purgeIntervalInDays Number Number of days for which the data store keeps data.
type String Type of data store. Security Monitor uses standard data stores.

DataSource

Member Type Description
configPath String This field is meant for internal use and will be removed.
dsType String Data Source type. For Security Monitor, the policy ID.
id Number Data Source ID.
name String Name of the Data Source.
values Array List of Policy IDs.

Report

Member Type Description
aggregation Number Time (seconds) over which data is aggregated.
columns Array Each column provides details such as the type (metric/dimension), name, description, index of the column. If the column is of type metric, then aggregate value of the metric and the max value (peak) is also returned.
endTimeInEpoch Number End time of the query in Unix epoch seconds.
hasMoreData Boolean Enabled if there are more data rows (than the rows returned by the query) that satisfy the query.
limit Number Number of data rows returned.
offset Number The offset of the row from which the data starts.
reportPack String Name of the report pack.
rows Array Data rows.
startTimeInEpoch Number Start time of the query in Unix epoch seconds.
timezone String Timezone of the report pack or timezone in which the data is returned.

Errors

This section provides details on the error response format and the range of response codes.

Error responses

The API returns the error JSON below for all non–2xx HTTPS status codes. The response code corresponds to the httpStatus element in the JSON response. This helps you avoid querying the header for the response code.

HTTP/1.1 404 Not Found

Content-Type: application/json
Reply Body:
{
    "httpStatus": 404,
    "detail": "additional non-http specific info where relevant",
    "title": "Resource not found"
}

HTTP status codes

The API can return any one of the following response codes:

Code Description
200 OK
204 No data
400 Bad input parameter. Error message indicates which one and why.
401 Authentication failure
403 Authorization failure
404 Resource not found
405 Request method not expected (generally should be GET)
409 Conflict
410 Requested resource is no longer available.
411 Content-length header not specified
413 Request body exceeds maximum allowable size.
423 Requested resource is locked.
429 Request rate limit exceeded.
500 Internal server error unexpected condition
501 Not supported
503 Too many requests; service is temporarily unavailable.
507 Data size is over allowable limit.

Last modified: 12/12/2016