Security actions

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Preview — Advanced API Security Actions

This feature is covered by the Pre-GA Offerings Terms of the Google Cloud Terms of Service. Pre-GA features may have limited support, and changes to pre-GA features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Support for the Preview launch of Advanced API Security Actions is available through the Apigee - Google Cloud Community forum.

The Security actions page lets you create security actions that define how Apigee handles detected traffic, based on information from the Abuse detection page. For example, you can create a security action to deny requests from an IP address that has been identified as a source of abuse. When a request from that address is received, Apigee blocks it from gaining access to your APIs. You can also create a security action to deny requests that have been tagged with specified detection rules.

In addition to deny actions, you can also create flag actions, which add headers to detected requests, or allow actions, which override a deny action in specific cases. See Security actions.

See Required roles for security actions for the roles needed to perform security actions tasks.

To use this feature, you must enable the add-on. If you are a Subscription customer, you can enable the add-on for your organization. See Manage Advanced API Security for Subscription organizations for more details. If you are a Pay-as-you-go customer, you can enable the add-on in your eligible environments. For more information, see Manage the Advanced API Security add-on.

Note: Security actions is available for Apigee and Apigee hybrid versions 1.11 and later.

Note: Blocked or flagged requests count toward your API call volume.

How security actions work

In the Security actions page, you can take action to explicitly allow, deny, or flag requests from specific clients. Apigee applies these actions to requests before your API proxies process them. Typically, you take action either because requests conform to patterns of unwanted behavior, or (in the case of the allow action) because you want to override a deny action for specific IP addresses.

The flag action allows requests to pass to your APIs, but adds up to five headers to flagged requests, so you can track them to observe their behavior.

To identify which requests to take action on, you can use the Abuse detection Detected traffic or Incident views, which show IP addresses that are sources of abuse. You can take action to block requests from those IP addresses.

Security actions

You can take the following types of security actions.

Action	Description	Precedence order
Allow	Allows certain requests that would otherwise be blocked by a deny action. For example, suppose you have created a security action to deny traffic that has been tagged with a detection rule. You could create an allow action to override the deny action for requests from a specific IP address that you trust.	1
Deny	Blocks all requests that meet the conditions of the action, for example, originating at a specified IP address. When you choose to deny requests, Apigee responds to the client with a response code that you can choose.	2
Flag	Flag requests that meet the condition of the action so that your backend services can take action on them. When you flag a client's requests, Apigee adds up to five headers, which you define, to the request. Your backend services can process the API calls according to these flags, for example, by redirecting the calls to a different flow. The flag action provides a way to signal your backend services that an API call is suspicious.	3

Precedence order

When a request meets the condition of more than one security action, the precedence order of the actions determines which action is performed. For example, suppose a request meets the conditions of both an allow and a deny action. Since the precedence order of an allow action is 1 and the precedence order of a deny action is 2, the allow action takes precedence, so the request is allowed access to the API.

As an example, you might want to allow requests from the IP address of an internal or trusted client, even if those requests matched a separate deny action. The precedence order ensures that an allow action for the trusted IP address would override any deny action.

Note: If you are using both security actions and the AccessControl policy to manage traffic based on IP address, the security action always executes before the AccessControl policy. After that, neither impacts the other; the security action has no influence on the AccessControl policy and vice versa.

Proxy-specific security actions

A security action can apply to all proxies in an environment or only to a specific proxy or proxies within the environment. See Limitations on security actions for limitations on proxy-specific security actions.

Limitations on security actions

Security actions are enforced at the Apigee environment level. For each environment, security actions have the following limitations:

• At most 1000 enabled actions for an environment are allowed at any time.
• You can add at most 5 flag headers for each action.
• Proxy-specific security actions support a maximum of 100 proxies.
• Proxy-specific security actiions are not supported in Apigee hybrid at this time.

Latencies

Security actions have the following latencies:

• When you create a security action, it can take up to 10 minutes for the action to take effect. Once an action has taken effect and has been applied to some API traffic, you will be able to view the action's effects in the Security action details page. Note: Even if the action has taken effect, you won't be able to determine that from the Security action details page unless the action has been applied to some API traffic.
• Enabled security actions incur a small increase (less than 2 percent) in API proxy response time.

Open the Security actions page

To open the Security actions page:

1. Open the Apigee UI in Cloud console.
2. Select Advanced API Security > Security actions.

This opens the main Security actions page, as shown below:

Note: The image above shows security actions that have already been created. If you have not yet created any security actions, no rows will be displayed in the table.

In the Security actions page you can:

• Create a new security action.
• Pause all enabled security actions.
• Enable or disable an individual security action, using the three-dot menu in the row for the action.

The Security actions page displays a list of security actions, with the following details:

• Name: The name of the action.
• Status: The status of the action, which can be Enabled, Paused, or Disabled.
• Action: The security action.
• Expiration (UTC): The expiration date of the action.
• Last updated (UTC): The last date and time the action was updated.
• A three-dot menu where you can enable or disable a security action. To do so, click the menu in the row for the action and select Enable or Disable. Disabled security actions do not affect API requests.

Create a security action

This section explains how to create a security action. Note that currently, once you create a security action, it cannot be deleted and the settings cannot be changed. You can disable the action (to prevent it from being enforced), but it will still appear in the Apigee UI.

Note: When you create a security action, it can take up to five minutes for the action to take effect.

To create a new security action:

1. At the top of the Security actions page, click Create to open the Create security action dialog, as shown below.

   

2. Under General settings, enter the following settings:
   • Name: A name for the security action.
   • Description (optional): A brief description of the action.
   • Environment: The environment in which you want to create the security action.
   • Proxies (optional): The proxies that you want the security action to apply to. Limit the proxy list by name using the Filter field.
     • Leave the Proxies field empty to apply the security action to all current and future proxies in the environment.
     • Select individual proxies to apply the security action to only those proxies regardless of any new proxies added to the environment later.
     • Use Select all to select all current proxies in the environment. Any proxies added later will not be automatically included in the rule.
   • Expiration: The date and time when the action expires, if any. Select either Never, or Custom, and then enter the date and time when you want the action to expire. You can also modify the time zone.
3. Click Next to display the Rule section, as shown below:

   

   In this section, you create the rule for the security action. Enter the following:

   • Action type: The type of the security action, which can be one of the following:
     • Allow: The request is allowed.
     • Deny: The request is denied. If you select Deny, you can also specify the response code that is returned when a request is denied. This can be either:
       • Predefined: Select an HTTP code.
       • Custom: Enter a response code.
     • Flag: The request is allowed, but also flagged with a special HTTP header that a proxy looks for to determine whether the request requires special handling. To define the header, under Headers If you select Flag, you can also create the following under Headers:
       • Header name
       • Header value
   • Conditions: The conditions under which the security action is carried out. Under New condition, enter the following:
     • Condition type: Can be either Detection rules or one of the following attributes:
       • IP addresses/CIDR ranges, which can include IP addresses and IPv4 CIDR ranges at the same time.
       • API keys, one or more API keys.
       • API products, one or more Apigee API products.
       • Access tokens, one or more access tokens.
       • Developers, one or more Apigee developer email addresses.
       • Developer apps, one or more Apigee developer apps.
       • User agents, one or more user agents.
       • HTTP methods, HTTP methods such as GET or PUT.
       • Region codes, a list of region codes to act on. See ISO 3166-1 alpha-2 codes.
       • Autonomous system numbers (ASN), a list of ASN numbers to act on, such as "23". See Autonomous system (Internet).
       Notes:

       • For the condition types Detection rules and IP addresses/CIDR ranges, you can create at most two conditions that have those types. For any other condition type, you can create at most one condition.
       • To use any of the attributes listed above, other than Detection rules or IP addresses, you need to add either the Verify API Key policy or the OAuthV2 policy. See How API keys work for more information.
       • For Apigee hybrid, these conditions are available in version 1.12 and later: API keys, API products, cccess tokens, developers, developer apps, and user agents. These conditions are available in version 1.13 and later: autonomous system numbers, CIDR ranges, HTTP methods, and region codes.
     • Values: Enter one of the following:
       • If Condition type is Detection rules, select a set of detection rules that a request must have triggered for the security action to be applied to it.
       • If Condition type is an attribute, enter the values of the attribute that you want the security action to be applied to. For example, if the attribute is IP addresses/CIDR ranges, enter the IP addresses of the sources of the requests you want the security action to be applied to. You can enter a comma-separated list of either IPv4 and IPv6 addresses.
4. Click Create to create the security action.

Pause all enabled actions

To pause all enabled security actions, click Pause Enabled Actions at the top of the Security Actions page. When security actions are paused, they do not affect API requests. Use this feature when you need to diagnose an issue with all security actions. To disable an individual security action, use the three-dot menu in the row for the security action.

To resume all enabled security actions, click Resume Paused Actions.

Note: When you resume all enabled actions, any disabled actions remain disabled.

View security action details

To view recent API traffic data related to a security action, select the row for the security action in the main Security actions page. This displays the Security action details page, which has two tabs:

• Overview
• Attributes

Overview

Select the Overview tab to display the Overview page:

The Overview page displays information about recent API traffic during the time period you select at the top of the page: 12 hours, 1 day, 1 week, or 2 weeks.

Note: The Environment traffic trends graph is restricted to a recent time interval that contains all observed traffic. This interval might be shorter than the interval you select.

The page displays the following traffic data:

• Action type: The type of the action: deny, allow, or flag.
• Total environment traffic: The total number of requests in the environment.
• Total detected event traffic: The number of requests related to the event.
• Total traffic affected by the action:
  • For a deny action, the number of denied requests.
  • For a flag action, the number of flagged requests.
  • For an allow action, the number of allowed requests.

The page also displays the following graphs:

• Environment traffic trends: Graphs of detected traffic, flagged traffic, and total environment traffic. See the note above.
• Top rules
• Top countries
• Action details

Attributes

Select the Attributes tab to display the Attributes page:

The Attributes page displays data for the security action by attributes—also known as dimensions— which are groupings of the data that let you view the security action in different ways. For example, the API products attribute lets you view the security action by API product.

The information displayed in the Attributes page is similar the Attributes view for the Abuse detection Incident details page.