This page applies to Apigee and Apigee hybrid.
View
Apigee Edge documentation.
Security reports are reports that 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. The resulting report shows suspicious activity. You can use this information to block attacks against your APIs.
You can create security reports either in Apigee in Cloud console 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.
Metrics and aggregation functions in security reports
You can use the following metrics and aggregation functions, which compute statistics from a metric, for a report.
| Metric | Description | Aggregation function |
|---|---|---|
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: |
sum |
response_size |
Size of the response payload returned in bytes. | sum, avg, min, max |
bot_first_detected |
Date and time the bot was first detected. Only available through the API. | min |
bot_last_detected |
Date and time the bot was last detected. Only available through the API. | max |
Dimensions in security reports
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:
| Dimension | Description |
|---|---|
bot_reason |
Can be any combination of the security
detection rules.
|
incident_id (preview) |
The UUID for a security incident, which is returned by a call to the Incidents API. See Example: Get details for a specific incident.
|
security_action |
The security action. Possibly values are ALLOW, DENY, or
FLAG.
|
security_action_name |
The name of the security action. |
security_action_headers |
Headers that you can use to query for a flag security action. |
In addition to these Advanced API Security-specific dimensions, Advanced API Security also supports additional dimensions, which are described in dimensions.
Reference security reports
This table lists 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.
- Security report jobs that filter on the
incident_idmust include theincident_idas a dimension. - 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).