Security reports

This page applies to Apigee and Apigee hybrid.

View Apigee Edge documentation.

The Security Reports view lets you create reports to identify security threats to your APIs. To generate reports, Apigee scans API traffic data over a specified time interval and searches for unusual traffic patterns that could be caused by malicious agents. Apigee then displays a report showing all suspicious activity. Using this information, you can then take action to block attacks against your APIs.

You can create security reports either in the Apigee UI, as described below, or using the Security reports API. If you use the UI, the data for reports is restricted to the environment you choose. However, using the API, you can also create reports for environment groups.

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

Bot detection

One of the most serious threats to API security comes from bots: automated scripts that send malicious requests to APIs. Advanced API Security searches for specific API traffic patterns, called detection rules, which are based on analysis of real API data, to detect bots.

Security reports data delay

Data flowing into the Apigee Analytics pipeline has a delay of up to 15 to 20 minutes on average. As a result, a security report in which the end time is less than 20 minutes in the past might return incorrect results.

Open the Security reports view

To open the Security reports view:

  • If you are using the Apigee UI in Cloud console: Select Advanced API security > Security reports.
  • If you are using the classic Apigee UI: Select Analyze > API Security > Security Reports. The column names and behavior may differ somewhat in the classic Apigee UI versus the Apigee UI in Cloud console.

This displays the main Security reports view:

Security reports main window.

At the top of the page, you can select:

  • The environment in which you want to create a report.
  • The Report type filter. The options are:
    • All
    • Active
    • Failed
    • Expired

Below those options, the security reports are displayed in the rows of a table. Each row displays the following report details:

  • The Report Name. Click the report name to view the report.
  • The report Status, which can be one of the following:
    • running: The report is currently running and cannot be viewed yet.
    • completed: The report is completed and can be viewed or exported.
    • expired: The report has expired and can no longer be viewed or exported in the UI. To view a report after the expiration date, you must export it before that date. After 30 days, the report is removed from the list of available reports.

  • The Start time and End time display the start and end dates and times for the report.

  • Submitted date: The date and time the request for the report was submitted.
  • Expiration time: The date and time when the report expires and can no longer be viewed in the Apigee UI. The expiration date is 7 days after the time when you created the report. After 30 days, the report is removed from the list of available reports. You cannot view or export reports in the UI after their expiration date.
  • File size: The report file size. You might need to modify the report criteria in order to create a report with a file size below the maximum file size. See Limitations on security reports for information on the maximum file size and specific ways to reduce the file size.
  • Export: Exports/downloads the report in a zip file. Export is only available if the status of the report is completed.

Create a new security report

To create a new security report, start by clicking +Create in the Security reports view. This opens the Create Security Report Job dialog, where you can configure the options for the report as described in the next section.

Security report options

You can specify the following options for a security report:

  • Report Name: A name for the report.
  • Report Date Range: Start time and end time for the report.

    Note: The start and end times of the report must be in the past, and at most one year in the past when the report is created.

  • Metrics: Metric for the report. You can choose from the following metrics and aggregation functions—functions that compute statistics for the metrics.
    Metric Description Aggregation functions
    bot The number of distinct IP addresses for detected bots over one-minute intervals. count_distinct
    bot_traffic The number of messages from IP addresses of detected bots over one-minute intervals. sum
    message_count

    Total number of API calls processed by Apigee in one-minute intervals.

    Note: message_count cannot be used with other metrics, or with the bot_reason dimension, in the same report.

    		 sum
    response_size Size of the response payload returned in bytes. sum, avg, min, max

  • Dimensions: Dimensions let you group metric values together based on related subsets of the data. The following table describes the dimensions that are specific to Advanced API Security reports.

    Dimension Description
    bot_reason
    incident_id (preview)
    security_action (preview) The type security action. Possibly values are ALLOW, DENY, and FLAG.
    security_action_name The name of the security action.
    security_action_headers Headers attached to a request for an ALLOW action.

    Note: The dimension bot_reason, which is specific to Advanced API Security, can be any combination of the individual detection rules. When a bot is detected, bot_reason consists of the subset of the individual detection rules that the bot's traffic matched when it was detected.

    Note: bot_reason and incident_id only work with the following metrics:

    • bot
    • bot_traffic
    • response_size

    See dimensions for other dimensions supported by Advanced API Security reports.

    To add multiple dimensions, just click +Add a Dimension for each dimension you want to add. You can also change the order in which dimensions appear in the report by clicking the up or down arrows to the right of the dimension field.

  • Filters: Filters let you restrict results to metrics with specific values. To create a filter, set the following fields:
    • Select a name for the filter.
    • Select a comparison operator.
    • Select a value.

    See Filters.

After you have selected all the report options, click Create to create the report job.

View a completed report

Once a report is completed, it is displayed in the table as shown below:

Security report displayed in table.

To view the report, either:

  • Click the report name.
  • Click Export in the row for that report.
Note: Bot detection has a processing delay of around 15 to 20 minutes on average.

Example: bot IP addresses report

The following example creates a report that shows the IP addresses of detected bots. To create the report, use the following configuration:

  • Metric: bot, the number of distinct IP addresses identified as sources of bots.
  • Aggregation function: count_distinct
  • Dimension: Resolved Client IP

The completed report is shown below:

Security Report bot IP address report

Note that the table at the bottom of the report lists IP addresses that Advanced API Security has identified as bots.

Example: bot traffic by bot reason report

The next example creates a report of bot traffic—the number of requests from IP addresses that have been identified as the sources of bots—by bot_reason—the set of detection rules that led to the bot being detected. To create the report, use the following configuration:

  • Metric: bot_traffic
  • Aggregation function: sum
  • Dimension: bot_reason

The completed report is shown below:

Security Report bot traffic by bot reason \report

Each bot_reason consists of a subset of the individual detection rules. As you can see in the graph, The detection rule that contributed to the largest amount of bot traffic is the following set of rules:

  • Flooder
  • Brute Guessor
  • Robot Abuser

Example: bot traffic report

The next example creates a report that isn't grouped by a dimension. If you don't want to group data by a dimension, you can set Dimension to environment. Since data is always restricted to the selected environment, this results in a report that has no grouping of data.

  • Metric: bot traffic
  • Aggregation function: sum
  • Dimension: environment
Security Report of bot traffic report

The report displays the total traffic from IP addresses that have been identified as sources of bots, for each one-minute interval throughout the report time range. Note that there is no grouping.

More examples of security reports

The follow table lists some examples of security of reports that you can create using different metrics and dimensions:

Report Metrics Dimensions
All Bot Traffic & Bot Count Report for per environment bot, bot_traffic environment
Bot Traffic & Bot Count Report for different bot reasons bot, bot_traffic bot_reason
Bot Traffic & Bot Count Report for different Countries bot, bot_traffic ax_geo_country
Bot Traffic & Bot Count Report for different ISPs bot, bot_traffic ax_isp
Bot Detection Report (Detailed List View) bot_traffic Resolved Client IP, ax_isp, bot_reason, request_uri, client_id
Bot traffic per Access Token bot_traffic access_token
Bot traffic per API proxy bot_traffic apiproxy
Bot traffic per Agent Family bot_traffic ax_ua_agent_family
Bot traffic per User Agent bot_traffic useragent
Bot traffic per Agent Type bot_traffic ax_ua_agent_type
Bot traffic per Device Category bot_traffic ax_ua_device_category
Bot traffic per OS family bot_traffic ax_ua_os_family
Bot traffic per Client ID bot_traffic client_id
Bot traffic per Proxy Basepath bot_traffic proxy_basepath
Bot traffic per Proxy Path Suffix bot_traffic proxy_pathsuffix
Bot traffic per Request URI bot_traffic request_uri
Bot traffic per Request Verb bot_traffic request_verb
Bot traffic per Response Status Code bot_traffic response_status_code

Limitations on security reports

Security reports have the following limitations:

  • Data flowing into the Apigee Analytics pipeline has a delay of up to 15 to 20 minutes on average. As a result, creating a report in which the End Time is less than 20 mins in the past might return incorrect results.
  • Maximum time range for bot reports is 1 year.
  • The maximum number of metrics you can use in a report is 25, and the maximum number of dimensions you can use is 25.
  • As with the asynchronous custom reports API, there is a limit of 31 MB of data for a report. If you encounter a size limit on a report, you can either:
    • Reduce the time range of the report.
    • Split the data into smaller subsets by filtering on a set of values, and then create multiple reports, one for each subset.
  • The Resolved Client IP dimension can't be listed in the same report with either the ax_geo_city or ax_geo_country dimension, due to privacy concerns.
  • The following metrics are only available via the Security Reports API, but not in the UI: bot_first_detected (min) and bot_last_detected (max).