The Enterprise Threat Protector API

The Enterprise Threat Protector API offers a programmatic OPEN interface to manage policy settings to protect against enterprise security and acceptable user policy related events. A distributed configuration encapsulates all the rules for how to process DNS requests for your enterprise. Like the Luna Control Center’s Enterprise Threat Protector, this API lets you access security and acceptable user policy event reports and analyse those events. The API allows you to access the same features rapidly and flexibly using your own tools.

What’s In This Guide

This guide is arranged as follows:

  • This Overview helps you get set up with the API’s initial requirements, introduces you to the many concepts you’ll need to know, and details various API conventions.

  • The Uses section provides a comprehensive walk-through of the API’s basic features: retrieve security events, acceptable user policy events, overall traffic a.k.a DNS activities. Apply the information in this section to your own analysis and reporting.

  • The Debug section shows you how to deal with errors and warnings you may likely encounter when accessing reports and analysis data, and shows how to respond to runtime errors with variables. It details the range of potential errors the API may produce, and notes known limitations in the API’s initial Beta release.

  • The Data section specifies the API’s data model, detailing how the JSON objects for each resource are structured.

  • The Resources section specifies the API’s resource model, detailing each API endpoint.

This Overview discusses the following topics:

  • Getting Started tells what you need to know before you start using this API.

  • ETP Concepts provides an overview of the API’s conceptual elements, and how they relate to API interfaces. Read this if you need a high-level overview of what ETP and the Enterprise Threat Protector do.

Getting Started

Before using the Beta API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • Review the OPEN API Introduction on available tools. Note that tools such as edgegrid-curl and edgegrid-python assume a maximum message-body size of 2048 bytes, which for ETP-REPORT needs to increase to 128K. How you do so depends on your chosen tool, for example by setting max-body:131072 in the .egcurl file, or in python by passing in max_body:131072 as part of the EdgeGridAuth() call.

  • Review Open API Provisioning to create your OPEN API access credentials and authorizations, making sure you enable read/write access for the Enterprise Threat Protector API grant. When setting up your credentials for use with ETP-REPORT, make sure to associate it with a user who does not have access to more than one portal account, as that can cause authorization errors.

  • The security token you use to form a custom domain for the request, as discussed in API Identity Model, keys to your account. The entire URL for the GET request will look something like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/etp-report/v1/configs/{configId} Once you have a custom domain that is keyed to your account, you can gather other prerequisite data from the API. See the Uses section for ETP-REPORT’s full range of capabilities.

ETP Concepts

This section provides a road map of all the conceptual objects you deal with when interacting with ETP, and provides pointers to where you can learn more.

  • Configuration: Each customer is automatically assigned with an ETP configuration on signing up. The configuration contains the policy settings for all the customer sites.

  • Site: A site is a collection of exit point IPs a site is attached to a policy.

  • Policy: The security policy is a reusable entity that allows the customer to define how to handle various threats and then reuse that across sites.

  • Response: Responses are what returned to a DNS query. The responses need to match the query that was made and so there is a mapping from query type to response type.

  • Category: A highlevel list of categories used to define and tag the occurred event.

  • List: A list is a collection of domains and IP addresses.