Risk assessment

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Advanced API Security's risk assessment evaluates the risk of security threats to your APIs. To do so, Advanced API Security calculates security scores, based on your API traffic and the configuration of your API proxies and targets. If the scores are low, which indicates a greater security risk, Advanced API Security gives you recommendations on ways to improve your scores.

Risk assessment has three main goals:

  • Confidentiality: Keep your data private.
  • Integrity: Prevent outsiders from gaining unauthorized access to your APIs.
  • Availability: Make sure your APIs are available 24/7.

You can access risk assessment either through the Apigee UI, as described on this page, or through the Security scores and profiles API.

See Required roles for risk assessment for the roles needed to perform risk assessment 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.

The following sections describe risk assessment:

Security scores

Security scores assess the security of your APIs, as well as their stability over time. For example, a score that fluctuates a lot could indicate that the API behavior is frequently changing, which might not be desirable. Changes in an environment that could cause the score to drop include:

  • Deploying many API proxies without the necessary security policies.
  • A spike in abuse traffic from malicious sources.

Observing changes to your security scores over time provides a good indicator of any unwanted or suspicious activity in the environment.

Security scores are calculated based on your security profile, which specifies the security categories you want your scores to evaluate. You can use Apigee's default security profile, or you can create a custom security profile that includes only the security categories that are most important to you.

Security scores assessment types

There are three assessment types that contribute to the overall security score calculated by Advanced API Security:

  • Source assessment: Assesses the detected abuse traffic, using the Advanced API Security detection rules. "Abuse" refers to requests sent to the API for purposes other than what the API is intended for.

  • Proxy assessment: Assesses how well proxies have implemented various security policies in the following areas:

    See How policies affect proxy security scores for more information.

  • Target assessment: Checks if mutual transport layer security (mTLS) is configured with the target servers in the environment.

Each of these assessment types is assigned a score of its own. The overall score is the average of the scores of the individual assessment types.

How policies affect proxy security scores

For proxy assessments, security scores are based on the policies you are using. How those policies are assessed depends on whether and how they are attached to flows:

  • Only policies that are attached to a flow (preflow, conditional flow, post flow in proxies, or shared flow) affect scores. Policies that are not attached to any flow do not affect scores.
  • Proxy scores take into account shared flows a proxy calls via flow hooks and FlowCallout policies in the proxy, provided the FlowCallout policy is attached to a flow. However, if the FlowCallout is not attached to a flow, policies from its linked sharedflow do not affect security scores.
  • For policies attached to conditional flows, security scores only takes into account whether the policies are present; it does not take into account whether or how the policies are enforced at runtime.

Security profiles

A security profile is a set of security categories (described below) that you want your APIs to be scored on. A profile can contain any subset of the security categories. To view security scores for an environment, you first need to attach a security profile to the environment. You can use either Apigee's default security profile, or you can create a custom security that contains only the security categories of importance to you.

Default security profile

Advanced API Security provides a default security profile that contains all of the security categories. If you use the default profile, security scores will be based on all the categories.

Custom security profile

Custom security profiles let you base your security scores on only those security categories you want included in the score. See Create and edit security profiles to learn how to create a custom profile.

Security categories

Security scores are based on an assessment of the security categories described below.

Category Description Recommendation
Abuse Checks for abuse, which includes any requests sent to the API for purposes other than what it is intended for, such as high volumes of requests, data scraping, and abuse related to authorization. See Abuse recommendations
Authorization Checks to see if you have an authorization policy in place. Add one of the following policies to your proxy:
CORS Checks to see if you have a CORS policy in place. Add a CORS policy to your proxy.
MTLS Checks to see if you have configured mTLS (Mutual transport layer security) for the target server. See Target server mTLS configuration.
Mediation Checks to see if you have a mediation policy in place. Add one of the following policies to your proxies:
Threat Checks to see if you have a threat protection policy in place. Add one of the following policies to your proxies:

Limitations on security scores

Security scores have the following limitations:

  • You can create up to 100 custom profiles per organization.
  • Security scores are only generated if an environment has proxies, target servers, or traffic and also if the Advanced API Security add-on is enabled. Otherwise, "Unable to assess" is shown.

Data delays

The data that Advanced API Security security scores are based on have the following delays, due to the way the data is processed:

  • When you enable Advanced API Security in an organization, it can take up to 6 hours for the scores for existing proxies and targets to be reflected in an environment.
  • New events related to proxies (deployment and undeployment) and targets (create, update, delete) in an environment can take up to 6 hours to reflect in the environment's score.
  • Data flowing into the Apigee Analytics pipeline has a delay of up to 15 to 20 minutes on average. As a result source scores abuse data has processing delay around 15 to 20 minutes.

Open the Risk assessment page

The Risk assessment page displays scores that measure the security of your API in each environment.

Apigee in Cloud console

To open the Risk assessment page:

  1. Open the Apigee UI in Cloud console.
  2. Select Advanced API security > Risk assessment.

This displays the Risk assessment page:

Risk assessment main page.

The page has two tabs, which are described in the following sections:

View security scores

To view security scores, click the Security Scores tab.

Note that no scores are computed for an environment until you attach a security profile, as described in Attach a security profile to an environment. Apigee provides a default security policy, or you can create a custom profile, as described in Create and edit security profiles.

The Security scores table displays the following columns:

  • Environment: The environment in which the scores are calculated.
  • Risk level: The risk level for the environment, which can be low, moderate, or severe.
  • Security score: The total score for the environment, out of 1200.
  • Total recommendations: The number of recommendations provided.
  • Profile: The name of the attached security profile.
  • Last updated: The latest date on which security scores were updated.
  • Actions: Click the three-dot menu in the row for the environment to perform the following actions:
    • Attach profile: Attach a security profile to the environment.
    • Detach profile: Detach a security profile from the environment.

Attach a security profile to an environment

To view security scores for an environment, you must first attach a security profile to the environment as follows:

  1. Under Actions, click the three-dot menu in the row for the environment.
  2. Click Attach profile.
  3. In the Attach Profile dialog:
    1. Click the Profile field and select the profile you wish to attach. If you have not created a custom security profile, the only available profile is default.
    2. Click Assign.

When you attach a security profile to an environment, Advanced API Security immediately starts assessing and scoring it. Note that it may take a few minutes for the score to be displayed.

The overall score is calculated from the individual scores in the three assessment types:

  • Source assessment
  • Proxy assessment
  • Target assessment

Note that all scores are in the range 200 - 1200. The higher the score, the better the security assessment.

View scores

Once you have attached a security profile to an environment, you can view the scores and recommendations in the environment. To do so, click the row for the environment in the main Security Scores page. This displays the scores for the environment, as shown below:

Security scores in an environment.

The view displays four tabs:

Overview

The Overview tab displays the following:

  • Top highlights for each assessment:
    • Proxy: Shows the top recommendation for proxies in the environment. Click Edit Proxy to open the Apigee Proxy Editor, where you can implement the recommendation.
    • Target: Shows the top recommendation for targets in the environment. Click View Target Servers to open the Target Servers tab in Management > Environments page in the Apigee UI.
    • Source: Shows the detected abuse traffic. Click Detected Traffic to view the Detected traffic tab in the Abuse detection page.
  • Summaries for Source Assessment, Proxy Assessment, and Target Assessment, including:
    • The latest score for each assessment type.
    • The Source Assessment pane displays detected abuse traffic and IP address count.
    • The Proxy Assessment and Target Assessment panes display the risk level for those assessments.
  • Click View Assessment Details in any of the summary panes to see the details for that assessment type:
  • Assessment history, which displays a graph of the daily total scores for the environment over a recent time period, which you can choose to be 3 days or 7 days. By default the graph shows 3 days. The graph also shows the average total score over the same period.

Note that a score is only computed for the assessment type if there is something to assess. For example, if there are no target servers, no score will be reported for Targets.

Source assessment

Click the Source Assessment tab to view the assessment details for the environment.

Source assessment pane.

Click the expand icon to the right of Assessment details to view a graph of the source assessment over a recent time period, which you can choose to be 3 days or 7 days.

The Source pane displays a table with the following information:

  • Category: The category for the assessment.
  • Risk level: The risk level for the category.
  • Security score: The security score for the abuse category.
  • Recommendations: The number of recommendations for the category.

Source details

The Source details pane displays details of detected abuse traffic in the environment, including:

  • Traffic details:
    • Detected traffic: The number of API calls originating from an IP address that has been detected as a source of abuse.
    • Total traffic: The total number of API calls made.
    • Detected IP address count: The number of distinct IP addresses that have been detected as sources of abuse.
    • Observation start time (UTC): The start time in UTC of the period during which traffic was monitored.
    • Observation end time (UTC): The end time in UTC of the period during which traffic was monitored.
  • Assessment date: The date the assessment was made.
  • The recommendation for improving the score. See Abuse recommendations for further recommendations on handling abuse traffic.

To create a security action to deal with issues raised by the source assessment, click the Create Security Action button.

Proxy assessment

The API proxy assessment calculates scores for all proxies in the environment. To view the proxy assessment, click the Proxy Assessment tab:

Proxy assessment pane.

The Proxy pane displays a table with the following information:

  • Proxy: The proxy being assessed.
  • Risk level: The risk level for the proxy.
  • Security score: The security score for the proxy.
  • Needs attention: The assessment categories that should be addressed to improve the score for the proxy.
  • Recommendations: The number of recommendations for the proxy.

Click the name of a proxy in the table to open the Proxy Editor, where you can make recommended changes to the proxy.

Proxy recommendations

If a proxy has a low score, you can view recommendations for improving it in the Recommendations pane. To view the recommendations for a proxy, click in the Needs attention column for the proxy in the Proxy pane.

The Recommendations pane displays:

  • Assessment date: The date the assessment was made.
  • The recommendation for improving the score.

Target assessment

The target assessment calculates a mutual transport layer security (mTLS) score for each target server in the environment. Target scores are assigned as follows:

  • No TLS present: 200
  • One-way TLS present: 900
  • Two-way or mTLS present: 1200

To view the target assessment, click the Target Assessment tab:

Target assessment pane.

The Target pane displays the following information:

  • Target: The name of the target.
  • Risk level: The risk level for the target.
  • Security score: The security score for the target.
  • Needs attention: The assessment categories that should be addressed to improve the score for the target.
  • Recommendations: The number of recommendations for the target.

Click the name of a target in the table to open the Target Servers tab in Management > Environments page in the Apigee UI, where you can apply the recommended actions to the target.

Target recommendations

If a target server has a low score, you can view recommendations for improving it in the Recommendations pane. To view the recommendations for a target, click in the Needs attention column for the target in the Target pane.

The Recommendations pane displays:

  • Assessment date: The date the assessment was made.
  • The recommendation for improving the score.

Create and edit security profiles

To create or edit a security profile, select the Security Profiles tab.

Security profiles tab.

The Security Profiles tab displays a list of security profiles, including the following information:

  • Name: The name of the profile.
  • Categories: The security categories included in the profile.
  • Description: The optional description of the profile.
  • Environments: The environments the profile is attached to. If this column is blank, the profile is not attached to any environments.
  • Last updated (UTC): The last date and time the profile was updated.
  • Actions: A menu with the following items:
    • Edit: Edit the profile.
    • Delete: Delete the profile.

View a security profile's details

To view a security profile's details, click its name in the row for the profile. This displays the details of the profile as shown below.

Security profile details.

The first row in the Details tab displays the Revision ID: the latest revision number of the profile. When you edit a profile and change its security categories, the revision ID is increased by 1. However, just changing the profile's description does not increase the revision ID.

The rows below that display the same information shown in the row for the profile in the Security Profiles tab.

The profile details view also has two buttons labeled Edit and Delete, which you can use to edit or delete a security profile.

History

To view the history of the profile, click the History tab. This displays a list of all revisions of the profile. For each revision, the list displays:

  • Revision ID: The revision number.
  • Categories: The security categories included in that revision of the profile.
  • Last updated (UTC): The date and time in UTC when the revision was created.

Create a custom security profile

To create a new custom security profile:

  1. Click Create at the top of the page.
  2. In the dialog that opens, enter the following:
    • Name: The name of the profile. The name must consist of 1 to 63 lowercase letters, numbers, or hyphens, and must start with a letter and end with a letter or number. The name must be different than the name of any existing profile.
    • (Optional) Description: A description of the profile.
    • In the Categories field, select the assessment categories you want to include in the profile.

Edit a custom security profile

To edit a custom security profile:

  1. At the end of the row for the security profile, click the Actions menu.
  2. Select Edit.
  3. In the Edit security profile page, you can change:
    • Description: The optional description of the security profile.
    • Categories: The security categories selected for the profile. Click the drop-down menu and change the selected categories by selecting or deselecting them in the menu.
  4. Click OK.

Delete a custom security profile

To delete a security profile, click Actions at the end of the row for the profile and select Delete. Note that deleting a profile also detaches it from all environments.

Classic Apigee

To open the Security scores view:

  1. Open the classic Apigee UI.
  2. Select Analyze > API Security > Security Scores.

This displays the Security scores view:

Security scores main view.

Note that no scores are computed for an environment until you attach a security profile to the environment. Apigee provides a default security policy, or you can create a custom profile using the Apigee API. See Use a custom security profile for details.

In the picture above, no security profile has been attached to to the integration environment, so the Profile Name column displays Not set for that environment.

The Security scores table displays the following columns:

  • Environment: The environment in which the scores are calculated.
  • Latest Score: The latest total score for the environment, out of 1200.
  • Risk Level: The risk level, which can be low, moderate, or severe.
  • Total Recommendations: The number of recommendations provided. Each recommendation corresponds to a row in the Needs Attention table.
  • Profile Name: The name of the security profile.
  • Assessment Date: The latest date on which security scores were calculated.

Attach a security profile to an environment

To view security scores for an environment, you must first attach a security profile to the environment as follows:

  1. Under Actions, click the three-dot menu in the row for the environment.
  2. Click Attach profile.
  3. In the Attach Profile dialog:
    1. Click the Profile field and select the profile you wish to attach. If you have not created a custom security profile, the only available profile is default.
    2. Click Assign.

When you attach a security profile to an environment, Advanced API Security immediately starts assessing and scoring it. Note that it may take a few minutes for the score to be displayed.

The image below shows the Security Scores view with an environment that has the default security profile attached:

Security Scores main window with a security profile attached.

The row for the environment now displays the latest security score, risk level, the number of recommendations for security actions to take, and the score's Assessment Date.

The overall score is calculated from the individual scores in the three assessment types:

  • Source assessment
  • Proxy assessment
  • Target assessment

Note that all scores are in the range 200 - 1200. The higher the score, the better the security assessment.

View scores

Once you have attached a security profile to an environment, you can view the scores and recommendations in the environment. To do so, click the row for the environment in the main Security Scores view. This displays the scores for the environment, as shown below:

Security scores in an environment.

The view displays:

  • The latest scores for Sources, Proxies, and Targets. Click View Assessment Details in any of these panes to see the assessment for that type.
  • Environment Score History, which displays a graph of the daily total scores for the environment over the past 5 days, as well as the average total score over the same period.
  • The Needs Attention table, which lists assessment types of your APIs in which you can improve security.

Note that a score is only computed for the assessment type if there is something to assess. For example, if there are no target servers, no score will be reported for Targets.

The following sections describe how to view the assessments for each type:

The Needs Attention table

The Needs Attention table, shown above, lists the API categories whose scores are below 1200, along with:

  • The latest score for the category
  • The risk level for the category, which can be low, moderate, or severe
  • The assessment date
  • The assessment type

View recommendations

For each row in the table, Advanced API Security provides a recommendation for improving the score. You can view the recommendations in the Assessment details views for each of the types, Sources, Proxies, or Targets, as described in the following sections:

You can open an Assessment details view in either of the following ways:

  • Click View Assessment Details in any of the panes in the main Security Scores view.
  • In the Needs Attention Table:
    1. Expand the category group in the table:

      Auth row in the Needs Attention table.

    2. Click the category for which you want to view the recommendation. This opens the assessment details view corresponding to the recommendation.

Source assessment

The source assessment calculates an abuse score for the environment. "Abuse" refers to requests sent to the API for purposes other than what the API is intended for.

To view the source assessment, click View in the Sources pane to open the API Source Assessment view:

Source assessment pane.

The Source Score History displays the scores over the last 5 days, along with their average and the latest score. The Assessment details table displays the latest individual scores for the categories of the assessment.

Source recommendations

If a category has a low score, you can view recommendations for improving it. To view a recommendation for the abuse category, click its row in the Assessment details table. This displays the recommendation in the Recommendations pane.

Abuse recommendation in Recommendations pane.

To drill down on the details of the abuse, click View Details. This opens the Detected Traffic view in the Abuse detection page. The Detected Traffic view displays detailed information about detected abuse.

Below the View Details line, the Recommendations pane displays:

  • The recommendation: "Block or allow traffic identified by abuse detection." is displayed.
  • The Actions row displays a link to documentation for abuse recommendations.

Proxy assessment

The API proxy assessment calculates scores for all proxies in the environment. To view the proxy assessment, click View in the Proxies pane to open the API Proxy Assessment view:

Proxy assessment pane.

The Proxy Score History displays the scores over the last 5 days, along with their average and the latest score. The Assessment details table displays the latest individual scores for the categories of the assessment.

Proxy recommendations

If a proxy has a low score, you can view recommendations for improving it. For example, to view recommendations for the hellooauth2 proxy, click its row in the Assessment details table. This displays the recommendations in the Recommendations pane. Two of them are shown below.

Proxy recommendation.

Target assessment

The target assessment calculates an mTLS score for each target server in the environment. Target scores are assigned as follows:

  • No TLS present: 200
  • One-way TLS present: 900
  • Two-way or mTLS present: 1200

To view the target assessment, click View in the Targets pane to open the API Target Assessment view:

Target assessment pane.

The Target Score History displays the scores over the last 5 days, along with their average and the latest score. The Assessment details table displays the latest individual scores for the categories of the assessment.

Target recommendations

If a target server has a low score, you can view recommendations for improving it. To view the assessment of a target server, click its row. This displays the recommendation in the Recommendations pane.

Proxy recommendation.

Abuse recommendations

If the source score is low, Apigee recommends that you review the IPs for which abuse has been detected. Then, if you agree that the traffic from those IPs is abusive, use the Security actions page to block requests from IP addresses that are sources of abuse traffic.

To get more information about the abuse, you can use either of the following resources: