Risk assessment overview and UI

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

Overview

Advanced API Security risk assessment continuously evaluates API proxy configurations and calculates security scores to help identify and address vulnerabilities in your APIs.

Risk assessment helps you:

• Enforce consistent security standards across all APIs.
• Detect misconfigurations in API setups.
• Improve your overall security score with recommended actions.
• Quickly investigate and resolve security issues via a centralized dashboard.

In addition to assessing the current risk of each proxy, risk assessment can be used to assess the security posture of your APIs over time. An assessment score that fluctuates could indicate that the API behavior is frequently changing, including proxies deployed without necessary security policies, shared flow modifications via flow hook deployments and FlowCallout policy additions, and target server changes in environment or proxy deployments.

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.

Risk Assessment v1 and v2

Risk Assessment is available in two versions: Risk Assessment v1, which is generally available, and Risk Assessment v2, which is in preview. Use of either version requires the Advanced API Security add-on.

The main feature differences between v1 and v2 are:

• v2 includes:
  • Improved reliability, including faster score calculations with recent proxy data
  • Score calculation without the need to first attach a security profile to an environment
  • Simplified score presentation, based on a 0% to 100% scale
  • The concept of assessment check weights, which v1 does not support. See Risk assessment concepts and scoring.
  • Additional assessments over v1, which check more policies when calculating scores. For example, v1 supports five authorization and authentication-related policies while v2 supports eight. Also, v2 includes a Traffic Management category with associated policies and performs additional checks in policies, including for the continueOnError attribute.
  • Checks of nested shared flows and flow hooks to five levels of nesting. v1 does not evaluate policies included via shared flow chaining.
  • Replacement of target scores (target server scores) with proxy-based assessments and recommendations. If a Target is used in a proxy, the security scores for that proxy include the score for the Target Server as well.
  • Custom profiles using the new v2 assessment checks as well as the google-default system profile.
• v2 does not support:
  • Source assessment based on abusive traffic.
  • Metrics and Monitoring are not supported at this time.

Risk Assessment v2

This section describes Risk Assessment v2, the new version of Risk Assessment. Some Risk Assessment concepts and behaviors differ between v1 and v2. For usage with Risk Assessment v1, see Risk Assessment v1 instead.

Risk Assessment v2 concepts and scoring methodology

Risk assessment security scores assess the security risk of your APIs based on the scoring of security assessments and weights in a security profile.

Risk assessment scoring is based on:

• Assessments and assessment checks: The individual checks performed against proxies, and on which proxies are scored. Each check also has a weight, which gives a check more or less significance when assessed against a proxy. Weights are set at minor, moderate, or major for each check. Each weight has a point value which is used to calculate a score:
  • Minor: 1
  • Moderate: 5
  • Major: 15
• Security profile: A collection of assessment checks, against which deployed proxies in an environment are assessed.
• Security score: The score for a proxy after assessment against a security profile.
  
  The score is a value between 0% and 100%. 100% indicates that the proxy is fully compliant with the assessment and no risks were found based on the assessment checks.
  
  The security score is essentially the total of all points awarded for passed assessment checks divided by the total potential points in the profile. The score is a weighted average, so the more policies the security profile has, the less impact each assessment check has on the security score.
  
  The assessment check weight also impacts the security score. Higher weights have more impact on the calculation and lower weights have less impact, using the point value for each weight. If the weights are equal for all assessment checks in the security profile (such as when all assessment checks have a medium weight) then the security score is calculated as a regular average.

• Severity: A severity value for each assessed proxy, based on the security score. The potential severity values are high (0-50%), medium (51-90%), low (91-99%), and minimal (100%/no risk found based on the assessments in the assigned security profile).

Assessment categories and checks

This table shows the assessment categories and individual checks that can be part of security profiles. It also shows recommendations on how to address failed assessments for each.

Assessment category	Description
Auth	"Auth" means both authorization and authentication in this case. Auth assessments check to see if you have an authorization and authentication policies in place and if the continueOnError attribute for auth policies is set to false. Assessment check / name Description Recommendation Auth policies check / auth-policies-check Check whether any of the following auth policies are enabled: AccessControl, BasicAuthentication, HMAC, OAuth, ValidateSAMLAssertion, VerifyAPIKey, VerifyJWS, or VerifyJWT policy. At least one of the required policies to the proxy continueOnError check in auth policies / continue-on-error-auth-policies-check Checks whether the continueOnError field is enabled on all auth policies in the proxy. This involves checking whether an auth policy is in use and this check has no impact if there are no auth policies in the proxy. Set continueOnError to false for all auth policies included in the proxy. AccessControl policy check / access-control-policy-check Whether the AccessControl policy is in use. Add the AccessControl policy to the proxy. BasicAuthentication policy check / basic-auth-policy-check Whether the BasicAuthentication policy is in use. Add the BasicAuthentication policy to the proxy. HMAC policy check / hmac-policy-check Whether the HMAC policy is in use. Add the HMAC policy to the proxy. OAuthV2 policy check / oauthv2-policy-check Whether the OAuth policy is in use. Add the OAuthV2 policy to the proxy. ValidateSAMLAssertion policy check / validate-saml-assertion-policy-check Whether the ValidateSAMLAssertion policy is in use. Add the ValidateSAMLAssertion policy to the proxy. VerifyAPIKey policy / verify-api-key-policy-check Whether the VerifyAPIKey policy is in use. Add the VerifyAPIKey policy to the proxy. VerifyJWS policy / verify-jws-policy-check Whether the VerifyJWS policy is in use. Add the VerifyJWS policy to the proxy. VerifyJWT policy / verify-jwt-policy-check Whether the VerifyJWT policy is in use. Add the VerifyJWT policy to the proxy.
CORS	Checks whether a CORS policy or CORS header in the AssignMessage policy are present. Assessment check / name Description Recommendation CORS policies check / cors-policies-check Check whether a CORS policy or CORS header in AssignMessage policy are present. Add either the CORS policy or AssignMessage policy with the CORS headers to the proxy. CORS policy check / cors-policy-check Check whether a CORS policy is in use. Add the CORS policy to the proxy. CORS AssignMessage policy check / cors-assignmessage-policy-check Check whether CORS headers are added in an AssignMessage policy. Add the AssignMessage policy with CORS headers to the proxy.
Mediation	Checks whether a mediation policy is enabled. Assessment check / name Description Recommendation Mediation policies check / mediation-policies-check Check whether either of the following mediation policies are enabled: SOAPMessageValidation or OASValidation. Add one of the following mediation policies to your proxy: SOAPMessageValidation or OASValidation. SOAPMessageValidation policy check / soap-validation-policy-check Check whether the SOAPMessageValidation policy is in use. Add the SOAPMessageValidation policy to the proxy. OASValidation policy check / oas-validation-policy-check Check whether the OASValidation policy is use. Add the OASValidationCheck policy to the proxy.
Target	Checks whether target server protections are used. For information on target server configuration, see Load balancing across backend servers. Assessment check / name Description Recommendation Target Server TLS check / tls-target-server-check Check for TLS/SSL in target servers. Configure TLS/SSL in all target servers configured in the proxy for secure communications. Target Server mTLS check / mtls-target-server-check Check for mTLS in target servers. Configure mTLS in all target servers configured in the proxy for maximum security. Target Server enforce field check / target-enforce-field-check Check whether the Enforce field is enabled in target server configuration. Configure Enforce field to enforce strict SSL between the Apigee proxy and the target.
Threat	Checks to see if threat prevention policies are used. Assessment check / name Description Recommendation Threat policies check / threat-policies-check Check whether any of the following threat policies are enabled: JSONThreatProtection, RegularExpressionProtection, or XMLThreatProtection. Add one of the required threat policies to your proxy. continueOnError check in threat policies / continue-on-error-threat-policies Check whether continueOnError field is enabled in all threat policies used in the proxy. This involves checking whether a threat policy is in use and this check has no impact if there are no threat policies in the proxy. Set continueOnError to false for all threat policies in use in the proxy. JSONThreatProtection policy check / json-threat-protection-policy-check Check whether the JSONThreatProtection policy is use. Add the JSONThreatProtection policy to the proxy. RegularExpressionProtection policy check / regex-protection-policy-check Check whether the RegularExpressionProtection policy is use. Add the RegularExpressionProtection policy to the proxy. XMLThreatProtection policy check / xml-threat-protection-policy-check Check whether the XMLThreatProtection policy is in use. Add the XMLThreatProtection policy to the proxy.
Traffic	Checks to see if you have traffic management policies in place. Assessment check / name Description Recommendation Traffic management policies check / traffic-management-policies-check Check whether any of the following traffic management policies are enabled: LookupCache, Quota, ResponseCache, or SpikeArrest. Add one of the traffic management policies to your proxy. LookupCache policy check / lookup-cache-policy-check Check whether the LookupCache policy is enabled. Add the LookupCache policy to the proxy. Quota policy check / quota-policy-check Check whether the Quota policy is use. Add the Quota policy to the proxy. ResponseCache policy check / response-cache-policy-check Check whether the ResponseCache policy is in use. Add the ResponseCache policy to the proxy. SpikeArrest policy check / spike-arrest-policy-check Check whether the SpikeArrest policy is use. Add the SpikeArrest policy to the proxy.

Policy attachment and 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 shared flow do not affect security scores.
• Chained shared flows are evaluated up to five levels deep. Any policies included directly in the proxy and in the first five levels of shared flows are counted towards the security score.
• For policies attached to conditional flows, security scores only take into account whether the policies are present; it does not take into account whether or how the policies are enforced at runtime.

Security profiles v2

A security profile is a set of security assessments and weights to score API proxies against. You can use either Apigee's default security profile, called google-default, or you can create a custom security profile that contains only the security categories and weights you want to assess.

When working with security profiles or creating custom security profiles, note that multiple assessment checks within a category are assessed individually.

For example, if there are three authentication policy checks in a security profile and the assessed proxy includes one of the three, the assessment score will include full points for the one found policy and zero points for the other two policies which are not present. In this example, the assessed proxy would not receive full points for authentication policy checks even though it does include an authentication policy. Be careful about security score interpretation and security profile design given this behavior.

Default security profile

Advanced API Security provides a default security profile that contains all of the assessments. When you use the default profile, security scores are based on all of the categories.

The default security profile, google-default, can't be edited or deleted.

Custom security profile

You can create custom security profiles that include only your chosen assessment checks and weights to evaluate against proxies. For instructions on creating and using custom security profiles from the Apigee UI, see Manage custom profiles in the Apigee UI.

For custom security profiles:

• The profile name (also called the profile ID) is required and is shown in the summary table when listing profiles. The name must be 1 to 63 characters, which can be lower case letters, numbers 0-9, or hyphens. The first character must be a lower case letter. The last character must be a lower case letter or number. Custom security profiles must have unique names and can't duplicate existing profile names.
• The profile description is optional and can't exceed 1,000 characters.

Limitations and known issues on security scores v2

Security scores have the following limitations and known issues:

• Security scores are only generated if an environment has deployed proxies.
• Newly deployed proxies and newly enabled organizations and environments do not immediately show scores.
• For custom profiles, you can create a maximum of 100 custom profiles per organization.
• Notification of new assessment calculations and scores is not supported at this time.

Data delays

The data that Advanced API Security security scores have the following processing windows before results are available:

• When you enable Advanced API Security in an organization for the first time, it takes time for the scores for existing proxies and targets to be reflected in an environment. As a guideline, expect 30 to 90 minutes for Subscription organizations and less time for Pay-as-you-go organizations.
• New events related to proxies (deployment and undeployment) and targets (create, update, delete) in an environment take at least 60 seconds and up to 5 minutes (for very large environments) to reflect in the environment's score.

View risk assessments in the Apigee UI

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

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:

The page has these sections:

• Environment: Select the environment on which to view assessments.
• Security profile: Select the default profile (google-default) or a custom profile, if available. See Security profiles for information on security profiles.
• Deployed proxies by severity: Once the environment is set, the page shows a summary of severities across proxies in that environment. See Risk assessment concepts and scoring.
• Assessment details: Shows the security profile, assessment date and time, total assessed configurations, and total deployed proxies for the selected environment. The total assessed configurations count reflects the total number of "checks" performed. This count might be higher than the number of assessments in a profile; some assessments, such as verifying that the "continueOnError” attribute is set to false also check if the related policies are in place and enabled.
• Deployed proxies: A summary of deployed proxies in the environment and their risk assessment scores:
  • Proxy: Name of the proxy.
  • Severity: The risk assessment severity for the proxy. See Security scores and severities for information.

  • Score: The risk assessment score for the proxy. See Risk assessment concepts and scoring for information.
  • Revision: The proxy revision on which the score was assessed.
  • Failed assessments by weight: The number of failed assessments grouped by the assessment weight.
  • Recommendations: Specific recommendations for improving the score on the proxy. Click the number to see the recommendations.

Manage custom profiles in the Apigee UI

This section shows how to view, create, edit, and delete custom profiles using the Apigee UI. Note the limitations on custom profiles listed in Limitations on security scores.

Start by Viewing risk assessments in the Apigee UI.

Create and edit custom profiles

On the Risk Assessment screen, select the Security Profiles tab. To edit an existing profile, click the profile name to see the profile details and then Edit. Or, you can select Edit from the Actions menu in the row for that profile.

To create a new custom profile, click + Create on the security profile list.

When creating or editing a custom profile, you can set these values:

• Name: The name of the security profile. Make sure this is unique for the project.
• Description: (Optional). A description for the security profile.
• Assessment check(s) and Assessment weight(s): One or more assessment checks to evaluate against proxies and a weight for each. See Risk assessment concepts and scoring for a list of the available assessment checks. To add additional assessment checks and weights to the profile, click + Add. To delete a check/weight pair, click the trash icon in the row for that pair.

Duplicate profiles

To duplicate an existing profile (to create a new custom profile), select Duplicate from the Actions menu in the row for that profile or click the profile name from the profiles list to see the profile metadata, and then click Duplicate.

The name of the new custom profile can't match the duplicated profile. See Custom security profile for security profile naming requirements.

Delete custom profiles

To delete an existing custom profile, select Delete from the Actions menu in the row for that profile or click the profile name from the profiles list to see the profile metadata, and then click Delete.

Note that you cannot delete the default system profile (google-default).

Deleting a custom profile is effective immediately and removes the ability to assess proxies against that profile or see previous assessments against that custom profile.

Risk Assessment v1

This section describes Risk Assessment v1. For information on Risk Assessment v2, see Risk Assessment v2 instead.

Security scores

Security scores assess the security of your APIs, as well as their security posture 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:
  • Mediation: Check if one of the following mediation policies is configured for all proxies in the environment: OASValidation or SOAPMessageValidation.
  • Security:
    • Authorization: Checks if one of the following authorization policies is configured for all proxies in the environment:
      • JWS or JWT
      • OAuth
      • VerifyAPIKey
      • BasicAuthentication
    • CORS: Checks if CORS is configured.
    • Threat: Checks if one of the following policies is configured for all proxies in the environment: XMLThreatProtection or JSONThreatProtection.

  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 shared flow do not affect security scores.
• Shared flow chaining is not supported. Policies included via shared flow chaining are not assessed when calculating security scores.
• For policies attached to conditional flows, security scores only take 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 profile 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: JWS or JWT policy OAuth BasicAuth VerifyAPIKey
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: OASValidation SOAPMessageValidation
Threat	Checks to see if you have a threat protection policy in place.	Add one of the following policies to your proxies: XMLThreatProtection JSONThreatProtection

Limitations on security scores v1

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, and traffic.
• Newly deployed proxies do not immediately show scores.

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.

It may take a few minutes for the Risk assessment page to load. The page will take longer to load for environments with a high volume of traffic and a large number of proxies and targets.

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:

• The Abuse detection page, which displays information about security incidents involving abuse traffic.
• The Security reports page. For example, you can create the following reports:
  • IP addresses of bots, as described in Example: bot IP Addresses report.
  • Bot traffic by bot_reason, as described in Example: bot traffic by bot reason report.