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.

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.

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 https://console.cloud.google.com/apigee.
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 once you create a security action, it cannot be deleted. You can disable the action (to prevent it from being enforced), but it will 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.
   • 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
       • API keys
       • API products
       • Access tokens
       • Developers
       • Developer apps
       • User agents
       Notes:

       • For the condition types Detection rules and IP addresses, 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.
       • These conditions are not available in Apigee hybrid at this time: API keys, API products, Access tokens, Developers, Developer apps, User agents.
     • 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, 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.