API concepts

To understand this API's various URL resources and the data it exchanges, get familiar with these concepts:

• Configuration: A security configuration specifies hostnames, security policies, custom rules, and match targets. You activate a security configuration to Akamai's edge servers, where it works with your delivery configuration to evaluate requests, and determines how to handle them.

  Security configurations are versioned. This is a handy way to update a configuration, even if it's active on staging or production. Clone a version and edit it. When it's ready, activate and test the new version. As you refine and test your updates, you have an audit trail of changes and can rollback to prior versions. You can also export the details of a configuration version.

• Contracts and Groups: Contracts and groups apply to most Akamai applications. In the Application Security API, contract IDs and group IDs are used when requesting selectable hostnames and creating security configurations. When you create a new configuration in Appsec, you'll choose which product to use by passing the contractId, and you'll select a group in which to save your configuration with a groupId.

• Hostnames: Selecting a hostname lets you specify the web content you want to protect in your configuration. You can get a list of selectable hostnames and add new entries to the selected hostnames object in your configuration.

  You can associate a security configuration with many hostnames, but a single hostname is covered by only one active security configuration at a time.

• Security Policy: Security policies control how to respond to different requests and define the response action that occurs. If necessary, you can create more than one security policy. For example, you may need to apply one set of protections to website pages and a different set to APIs.

• Match Target: Defines which security policy applies to which API, hostname, or path. You can use a match target to focus a policy on a specific set of requests, such as those for .asp, .jsp, or .php file types. When your security configuration assesses a request, it checks to see if the request meets match target criteria. If it does, protections apply. If not, content delivery starts.

• Protections: Rules in a security configuration that inspect a request for specific traits, behavior, or originating machine and then applies an action you set. If a request triggers a rule, the server executes the action you specify. The security configuration file executes before your delivery configuration. The protections currently available in this API are:

  • IP/Geo firewall
  • Rate controls
  • Slow POST
  • Custom rules
  • Web Application Firewall rules
  • Reputation profile (Kona Site Defender add-on)
  • URL protection

• IP/Geo Firewall: IP/Geo controls let you block or allow traffic coming from a specific IP, subnet, or geographic area. In Control Center's Web Application Firewall, the mode option lets you control how to block traffic. This API uses the block member to indicate the same choice. The set of IPs or geographic areas you want to include or exclude is defined separately in network lists that are shared across security configurations. Use the Network Lists API to maintain them. Note: Subnet controls are a legacy item in Control Center and are not available through this API.

• Rate Controls: Monitor and control the rate of requests you receive. Flag traffic too fast to be from a human or that may overwhelm your site.

• Slow POST: A type of traffic that ties up a web server as it waits for additional parts of requests to arrive. This can result in Denial-of-Service attacks featuring extremely slow request rates.

• Custom Rule: Custom rules can handle scenarios not covered by the included standard rules and quickly patch new website vulnerabilities. You can trigger an alert or denial based on various components of the request, such as method, path, file extension, headers, cookies, query string, and POST body variables. Custom rules are configuration-level resources, which means they're available to all policies in a security configuration, but they don't version in lock-step. When you change a custom rule, it affects all inactive versions of your security configuration, but not activated ones. To roll back, you must choose a previously activated version.

• Reputation Profile: Stops malicious clients before they can attack, based on Akamai's visibility into prior behavior of individual and shared IP addresses. This service performs hourly analysis to identify potentially malicious IP addresses, scoring them based on prior interactions with other Akamai customers. When you apply reputation controls, they use this history to alert on or block IP addresses from issuing requests. Reputation profile is part of Client Reputation, an optional add-on to Kona Site Defender that you need on your contract to use.

• URL Protection: Prevents URLs, hostnames, and APIs from going down due to heavy traffic. It performs load shedding on customizable traffic categories, limiting the maximum requests per second (RPS) on URLs.

• Prefetch: This protection causes your application firewall rules to inspect internal requests (those between your origin and Akamai's servers) for file types you specify (usually dynamic content).

• Attack Group: Attack groups, also called Automated Attack Groups or AAGs are an alternative setup for your web application firewall, eliminating the need for you to manually configure and maintain individual firewall rules.

• Attack Group Actions: When conditions for an attack group are met, our system performs a specific action you set: denying the request, recording what triggered the response, or taking no action at all.

• Rules: The Akamai Intelligent Platform handles a large part of the world's web traffic, providing a unique insight into traffic patterns and request behavior. To craft the application-layer protections, our Security Research team leverages insights that come from our Cloud Security Intelligence (CSI) data platform. This data is used to improve rules and create new ones based on the latest threats.

• Rule Actions: When a rule is triggered by a request, our system takes an action, either denying the request, recording the triggered the rule, or taking no action at all.

• Penalty Box: If you're using automated attack groups, you can protect your site or API from abusive clients using the penalty box. When you turn penalty box ON, any client whose request violates an attack group set to action:deny moves to the penalty box. There, the action you select for penalty box (either alert or deny) continues to apply to any requests from that client for the next 10 minutes. After 10 minutes, the client moves out of the penalty box, and its requests are no longer denied, unless another request triggers another deny action again and sends the client back to the penalty box for another 10 minutes.

• Upgrading KRS rules: To best protect your site it's important to keep your rules up to date. However, if you're worried how the new rules may affect your traffic, you can use Evaluation Mode to test them before you upgrade.

• Mode: The mode is the method by which you update your KRS rules. Use KRS to update them manually, or AAG to have them update automatically.

• Evaluation Mode: Evaluation mode lets you test new versions of the Kona Rule Sets before committing to an upgrade, or test the same rules you already have with different exceptions.

• Evaluation Rule: Also known as eval rules. These rules are future versions of rules you currently have. Eval rules are the rules present when you're running evaluation mode. You can preview, or test drive these rules to see how they handle traffic and compare the results against your current rules. When you're using the eval rules operations, you'll notice how similar they are to the KRS rules operations. This is because the newer rules you're evaluating are meant to replace the KRS rules once you decide to upgrade. The only difference between the KRS rules operations and the eval rules operations is that the KRS operations are for your current rules, and the eval operations are for you to test out updates to those rules. What the rules and their actions accomplish are conceptually the same.

• Custom Deny: Instead of using the standard deny action which serves an HTTP 403 Forbidden response, you can create a custom deny action. This lets you:

  • Customize the error message

  • Brand the error page with your own logo

  • Define and serve an HTML, or any response based on XML, JSON, or other data formats

    You'll choose which deny action to take in the Custom Deny operations and, unlike other similar operations, won't have to create any special configurations. Customize either by entering your own HTML or JSON response body, or by serving an HTML page that you currently deliver on Akamai's platform. You can create up to 20 custom deny actions. Note: Custom Deny is not available for properties served on Akamai's China CDN. Any instance of custom deny applied to those properties defaults back to 403 response.

• SIEM: Security Information and Event Management (SIEM) integration lets you capture security events generated on the Akamai platform and analyze them in your favorite SIEM application. You can integrate with Splunk, CEF Syslog, or build a connector for the SIEM application of your choice. The operations in this API let you turn SIEM on or off for your security configurations. To configure other SIEM controls, or for more information, see Security Information and Event Management API.

• Tuning recommendations: Tuning recommendations help improve accuracy and reduce false positives. When the system detects such an issue in your traffic, it automatically recommends an exception setting change. You can review it and either accept the recommendation or defer your choice for a later time.

  Note that once you accept a recommendation, your policy includes it as an exception. But, when you accept a recommendation in Control Center, you save the exception as a second step.

• Tuning recommendation email subscription: Tuning recommendation emails notify subscribers faster than waiting for them to log in. In this API you can subscribe or unsubscribe users to these recommendations for a specific feature. Currently, the only feature is AAG_TUNING_REC for AAG rule sets.

• Discovered APIs: APIs you have not explicitly defined in your API definitions you may want to add to your API Protections. These APIs are found through analyzing the edge server data associated with your account. If you decide to protect these APIs, add them to your API Definitions.

  The detected API list shows data from the last 30 days. To appear in the list, an API must meet these conditions:

  • At least 1000 requests reached the API over the last 30 days
  • The API responded with at least one 2xx status code over the last 30 days

  Once you register the API, it's no longer considered new.

• Hiding discovered APIs: You can hide APIs discovered on your account if you feel they are incorrectly included in the data. When you run Get discovered APIs, the response contains only APIs you've left visible. However, this function is on a per-user basis and your colleagues will still see APIs you've hidden in the response when they run this operation with their own credentials.