Learn more:

• Prolexic

• Prolexic Analytics API v1

• Download this API’s RAML and JSON schema descriptors.

Overview

The Prolexic Analytics API exposes analytics data from Prolexic DDoS protection and monitoring services such as alerts and network bandwidth timeseries data.

Who Should Use This API

The Prolexic Analytics API helps you better integrate Prolexic’s data into your local environment. You can track network usage and review traffic spikes during attacks using timeseries data. You can also pull attack reports and alert information into local SIEM instances to streamline emergency response and post-event triage using events data.

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 Prolexic Analytics API, and set the access level to READ-ONLY.

Rate limiting

Prolexic Analytics API endpoints are subject to a rate-limiting constraint, which is currently set to 1000 requests per hour. When this limit is reached, 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. This is consistent with all protected Akamai assets exposed via API calls.

Resources

This section provides details on each API operation.

The following list provides a road map of all the conceptual objects you deal with when interacting with the Prolexic Analytics API, and provides pointers to where you can learn more.

• Metrics: Metrics contain telemetry collected from Akamai networks or your FBM netflow exports.

• Metric Types: Metric types encapsulate the available types of data from the metrics endpoint.

• Attack Reports: Attack reports eports created by the SOCC regarding attack events of interest that occur within your traffic.

• Events: A list of security events with information on the location of the event and additional attack information.

• Critical Events: A list of security events marked with the highest level severity.

API summary

Download the RAML descriptors for this API.

Get metrics data

Lists metrics specified in the type object, falling between given start and end times, sampled at the given rate and attached to given contract. The maximum range between start and end is 90 days.

If some (not all) requested types are invalid, invalid types are silently dropped, and the response only contains data for valid requests. More meaningful errors result if you are requesting data for only one type at a time.

{
    "contract": "venus",
    "start": 1322390037,
    "end": 1400385899,
    "samples": 100,
    "type": {
        "routed": [
            "bandwidthIn"
        ],
        "fbm": [
            {
                "metric": "bandwidth",
                "protocol": "total",
                "subnet": "1.1.1.0/24"
            },
            {
                "metric": "packets",
                "protocol": "tcp",
                "ip": "1.1.1.10"
            }
        ]
    }
}

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metrics acquired successfully",
    "data": [
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        },
        {
            "service": "fbm",
            "metric": "bandwidthIn",
            "protocol": "total",
            "subnet": "1.1.1.0/24",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        },
        {
            "service": "routed",
            "metric": "bandwidthIn",
            "protocol": "tcp",
            "ip": "1.1.1.10",
            "points": [
                [
                    1392609960,
                    211014
                ],
                [
                    1396886760,
                    202529
                ]
            ]
        }
    ]
}

List metric types

Retrieve a list of metric types for a specific customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metric Types list acquired successfully",
    "data": {
        "routed": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "connect": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound packets, packets per second"
                }
            }
        },
        "mitigationPost": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "proxy": {
            "metrics": {
                "latency": {
                    "desc": "Average latency of request"
                },
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "bandwidthOut": {
                    "desc": "Customer outbound traffic, bits per second"
                },
                "connections": {
                    "desc": "Connections count"
                },
                "packetsOut": {
                    "desc": "Customer outbound traffic, packets per second"
                },
                "requests": {
                    "desc": "Requests count"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "mitigationPre": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "fbm": {
            "metrics": {
                "bandwidth": {
                    "desc": "Customer traffic bits per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                },
                "packets": {
                    "desc": "Customer traffic packets per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                }
            }
        }
    }
}

List attack reports

Retrieves a list of attack reports for a customer within the specified time range.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack reports acquired successfully",
    "data": [
        {
            "attackId": 2985,
            "destinationPort": "80",
            "eventStartTime": 1381320180,
            "ticketId": 97585,
            "eventEndTime": 1381349454,
            "eventStartTimeAsString": "2013-10-09 12:03:00",
            "endTime": 1381363451,
            "eventId": 4202,
            "eventEndTimeAsString": "2013-10-09 20:10:54",
            "startTime": 1381063041,
            "eventTypes": [
                "DNS Flood",
                "ICMP Flood",
                "UDP Fragment"
            ],
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17277,
                    "bandwidth": 6500000000,
                    "pps": 700000
                },
                {
                    "location": "HKG",
                    "peakId": 17276,
                    "bandwidth": 3000000000,
                    "pps": 600000
                }
            ],
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.100"
                },
                {
                    "netmask": 32,
                    "ip": "178.132.240.155"
                }
            ]
        },
        {
            "attackId": 2974,
            "destinationPort": "80",
            "eventStartTime": 1380714180,
            "ticketId": 97368,
            "eventEndTime": 1380752215,
            "eventStartTimeAsString": "2013-10-02 11:43:00",
            "endTime": 1380847367,
            "eventId": 4170,
            "eventEndTimeAsString": "2013-10-02 22:16:55",
            "startTime": 1380714180,
            "eventTypes": [
                "SYN Flood"
            ],
            "peaks": [
                {
                    "location": "DCA",
                    "peakId": 17093,
                    "bandwidth": 300000000,
                    "pps": 200
                },
                {
                    "location": "HKG",
                    "peakId": 17092,
                    "bandwidth": 3000000,
                    "pps": 1000
                }
            ],
            "destinations": [
                {
                    "netmask": 32,
                    "ip": "178.132.240.126"
                }
            ]
        }
    ]
}

Get an attack report

Retrieves an attack report for the specified customer and attackId.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack report acquired successfully",
    "data": [
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18594,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "SJC",
            "endTime": 1390261538,
            "eventBw": 500000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 1200,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        },
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18595,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "LON",
            "endTime": 1390261538,
            "eventBw": 90000000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 200000,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        }
    ]
}

List events

Retrieves an events list for a customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "service": "man",
            "eventType": "alert",
            "isOngoing": false,
            "eventStartTime": 1390975985,
            "eventTitle": "chkInt: Interface GigabitEthernet0/18 is down.",
            "severity": 80,
            "eventEndTime": 1393236546,
            "eventInfo": {
                "location": "mia1",
                "lastOccurred": 1393236546,
                "attackId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems"
            }
        },
        {
            "service": "Mitigation",
            "eventType": "attack",
            "isOngoing": true,
            "eventStartTime": 1392922838,
            "eventTitle": "[\"SYN Flood\"]",
            "severity": 100,
            "eventEndTime": 0,
            "eventInfo": {
                "eventTicketId": "70167",
                "attackType": "[\"SYN Flood\"]",
                "endTime": false,
                "attackEventId": "2707",
                "destinationIPs": "[178.132.240.114/32, 178.132.240.155/32, 178.132.240.203/32]",
                "startTime": 1392922838
            }
        }
    ]
}

List critical events

Retrieves a critical events list for a customer.

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "siteType": "DC",
            "source": "wbm",
            "location": "dca1",
            "ip": "192.216.61.102",
            "summary": "WBM TEST 5",
            "instance": "01",
            "interfaceName": "unknown",
            "count": 11,
            "siteCustomerName": "coral",
            "eventId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems",
            "siteName": "dca1",
            "acknowledged": 0,
            "state": 1,
            "recentOccur": 1395842910,
            "expires": 3600,
            "node": "lr1.dca1.plx",
            "importance": 5,
            "notes": "TEST 5",
            "firstOccur": 1393657985,
            "description": "TEST WBM LEVEL 5"
        }
    ]
}

Data

This section provides you with the data model for the Prolexic Analytics API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Metric

Encapsulates the target contract and time constraints for the specified metrics.

Download schema: MetricDataInput.json

Sample POST request:

{
    "contract": "venus",
    "start": 1322390037,
    "end": 1400385899,
    "samples": 100,
    "type": {
        "routed": [
            "bandwidthIn"
        ],
        "fbm": [
            {
                "metric": "bandwidth",
                "protocol": "total",
                "subnet": "1.1.1.0/24"
            },
            {
                "metric": "packets",
                "protocol": "tcp",
                "ip": "1.1.1.10"
            }
        ]
    }
}

Metric members

MetricType

Encapsulates information on the types of metrics available to the contract.

Download schema: MetricType.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Metric Types list acquired successfully",
    "data": {
        "routed": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "connect": {
            "metrics": {
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "packetsIn": {
                    "desc": "Customer inbound packets, packets per second"
                }
            }
        },
        "mitigationPost": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "proxy": {
            "metrics": {
                "latency": {
                    "desc": "Average latency of request"
                },
                "bandwidthIn": {
                    "desc": "Customer inbound traffic, bits per second"
                },
                "bandwidthOut": {
                    "desc": "Customer outbound traffic, bits per second"
                },
                "connections": {
                    "desc": "Connections count"
                },
                "packetsOut": {
                    "desc": "Customer outbound traffic, packets per second"
                },
                "requests": {
                    "desc": "Requests count"
                },
                "packetsIn": {
                    "desc": "Customer inbound traffic, packets per second"
                }
            }
        },
        "mitigationPre": {
            "metrics": {
                "packets": {
                    "desc": "Customer traffic packets per second"
                },
                "bandwidth": {
                    "desc": "Customer traffic bits per second"
                }
            }
        },
        "fbm": {
            "metrics": {
                "bandwidth": {
                    "desc": "Customer traffic bits per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                },
                "packets": {
                    "desc": "Customer traffic packets per second",
                    "subnets": [
                        "1.1.2.0/24"
                    ],
                    "protocols": [
                        "total",
                        "icmp",
                        "igmp",
                        "udp",
                        "tcp"
                    ]
                }
            }
        }
    }
}

MetricType members

Attack

Encapsulates the details of an attack, including location, time, and type of attack.

Download schema: AttackReport.json, AttackReports.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Attack report acquired successfully",
    "data": [
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18594,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "SJC",
            "endTime": 1390261538,
            "eventBw": 500000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 1200,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        },
        {
            "attackId": 1966,
            "destinationPort": "8080",
            "eventStartTime": 1390244438,
            "eventPeakId": 18595,
            "attackTypeName": "RESET Flood",
            "netmask": 32,
            "eventEndTime": 1390261538,
            "location": "LON",
            "endTime": 1390261538,
            "eventBw": 90000000,
            "ticketId": 70946,
            "eventId": 2744,
            "eventPps": 200000,
            "ip": "178.132.242.47",
            "startTime": 1390244438
        }
    ]
}

Attack members

Event

Encapsulates the details of an event and the associated attack information.

Download schema: EventResponse.json

Sample GET response:

{
    "status": true,
    "currentContract": "coral",
    "statusMsg": "Events acquired successfully",
    "data": [
        {
            "service": "man",
            "eventType": "alert",
            "isOngoing": false,
            "eventStartTime": 1390975985,
            "eventTitle": "chkInt: Interface GigabitEthernet0/18 is down.",
            "severity": 80,
            "eventEndTime": 1393236546,
            "eventInfo": {
                "location": "mia1",
                "lastOccurred": 1393236546,
                "attackId": "05ngsdca1--lr1.dca1.plx-wbm_monitor-34610029-systems"
            }
        },
        {
            "service": "Mitigation",
            "eventType": "attack",
            "isOngoing": true,
            "eventStartTime": 1392922838,
            "eventTitle": "[\"SYN Flood\"]",
            "severity": 100,
            "eventEndTime": 0,
            "eventInfo": {
                "eventTicketId": "70167",
                "attackType": "[\"SYN Flood\"]",
                "endTime": false,
                "attackEventId": "2707",
                "destinationIPs": "[178.132.240.114/32, 178.132.240.155/32, 178.132.240.203/32]",
                "startTime": 1392922838
            }
        }
    ]
}

Event members

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.

Error responses

Responses from the API include status and statusMsg parameters indicating the success or failure of a request. For a failed request, the status boolean will be set to false and statusMsg will contain a string explaining the error condition, such as in the following example:

{
    "status": false,
    "statusMsg": "Description of failure"
}

For non–2xx HTTPS returned status codes, the error JSON below is returned as outlined. See HTTP Status Codes below for a list of error codes.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Reply Body:
{
    "type": "https://developer.akamai.com/api/cloud_security/prolexic_analytics/v1.html#ratelimiting"
    "title": "Too many requests"
    "status" : 429,
    "detail": "additional non-http specific info where relevant"
}

HTTP status codes

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