The Security Monitor API

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

Visit the OPEN API Introduction section to get started and make Akamai OPEN 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.


Last modified: 12/12/2016