Bot Defense

Bot Defense protects your Internet applications from automated attacks by identifying and mitigating malicious or bad bots. For more information about Bot Defense, see About Bot Defense.

When you deploy Bot Defense, F5 recommends that you set up a test environment to configure and test different configuration options before you set up your production environment.

After you decide on your final configuration options and are certain they provide the results you want, you can then set up a production environment.

Your configuration and testing process should include the following steps:

1. Enable Bot Defense in the Distributed Cloud Console.
2. Thoroughly review Bot Defense deployment prerequisite information and decide what resources you want to protect.
3. Build a test system to test different configuration options. If you plan to use Bot Defense with BIG-IP v14-16, you can follow the instructions in the Bot Defense Quick Start to help you quickly set up your test system. Otherwise, see Configure Bot Defense for configuration instructions.
4. Build your production system. After you finish working with your test system, configure your production system based on the settings you tested and finalized in your test system.
5. Test your production system and confirm that it is functioning as you intended.
6. When you are ready to go live with your production system, update your DNS settings to route traffic to your production system.

   Important: Make sure you have permission to change DNS settings for your organization or that you coordinate with an administrator that has the necessary permissions.

7. Check for false positive results to make sure Bot Defense is correctly identifying traffic. This step allows you to see how Bot Defense is handling live requests rather than just your test requests.
8. When you are sure that Bot Defense is properly configured and functioning as you intended, you can enable mitigation actions for your endpoints.

---

Prerequisites

• You must have a valid Distributed Cloud Console account. For information, see Create a Distributed Cloud Console Account.

• You must have an Organization plan. To see plan information, from the Distributed Cloud Console Home page, click Billing.

• You or another admin must have the following assigned roles:

  • f5xc-bot-defense-admin: For advanced administrative access, including Bot Defense subscription management.
  • f5xc-bot-defense-user-role (or ves-io-power-developer-role or greater): For general administration, such as managing protected applications.
  • f5xc-bot-defense-monitor-role (or ves-io-monitor-role or greater): For read-only operations such as dashboard and report access.

  You can also create custom roles that include access to the required API groups. Use the above roles for guidance on the required API groups. For a complete list of the API groups included in the above roles, see View RBAC Policy Rules and API Groups.

• You must have permission to change DNS settings for your organization.

• Depending on how you host your applications, you must have sufficient permissions to configure Bot Defense with your BIG-IP, application platform or content delivery network.

---

Decide What Resources You Want to Protect

During your planning process, you must decide which applications and application pages you want to protect. Bot Defense can protect both web and mobile endpoints. For information on the following configuration options, see Configure Bot Defense.

• For applications that route traffic through F5 Distributed Cloud Mesh, you can use the Distributed Cloud Console to configure the Bot Defense service on your HTTP load balancers.

• For applications that route traffic through BIG-IP, you can download a BIG-IP iApp template to enable Bot Defense with BIG-IP.

• For applications that route traffic through BIG-IP:

  • If you use BIG-IP version 17.0 or later, you can configure Bot Defense directly on BIG-IP.
  • If you use BIG-IP version 14-16, you can download a BIG-IP iApp template to enable Bot Defense with BIG-IP.

• For web pages hosted on third-party content delivery networks, you can configure Bot Defense on Adobe Commerce Cloud, Amazon CloudFront, Salesforce Commerce Cloud or Cloudflare.

• For many other third-party applications, you can configure Bot Defense using a custom connector.

• For mobile endpoints, you can either embed the F5 Mobile SDK in the application you want to protect, or you can use the F5 Mobile SDK Integrator to automatically integrate the F5 Mobile SDK with your application with no coding required.

---

Enable Bot Defense

To use Bot Defense, you must first enable it in the Distributed Cloud Console.

1. On the Distributed Cloud Console Home page, click Billing.
2. Click Manage > Billing Plan and scroll to the Organization Plan.
3. Under the Organization Plan, click Bot Defense. The Bot Defense landing pages appears.

   Note: If Bot Defense is already enabled, the Bot Defense Monitor page appears and you can begin using Bot Defense.

4. From the Bot Defense landing page, click Request Service.

---

Best Practices

Common best practices

• When configuring endpoints, use wildcards to terminate the match. For example: /login*

  This prevents attackers from adding a slash to the end of the request (for example, /login/) when both variants reach the same application endpoint.

• The mitigating response should try to mimic how the application responds when the request is invalid (for example, when invalid credentials are used).

Web application best practices

• Identify all URL paths to be protected by Bot Defense.
• Use wildcards cautiously. Avoid enabling Bot Defense protection for more URLs than required by adding wildcards.

---

Protect Mobile Endpoints

To protect mobile endpoints with Bot Defense, you must complete the following high-level steps:

1. Review the best practices for protecting mobile endpoints.
2. Download the base configuration for the F5 Mobile SDK.
3. Complete one of the following tasks to integrate the F5 Mobile SDK with your mobile application:
   • Integrate the F5 Mobile SDK library into your Android or iOS application.
   • Use the Mobile SDK Integrator, which enables you to integrate the F5 Mobile SDK with your application without making code changes.

Mobile application best practices

When you configure protection for mobile endpoints, F5 recommends that you follow these best practices:

• Add Bot Defense headers only to those requests which are also configured for Bot Defense protection in WAAP or iApp. This helps avoid filling up bandwidth unnecessarily.

• Before you onboard a mobile application, identify all URLs that must be protected.

• F5 recommends that you integrate the F5 Mobile SDK with applications that have forced-upgrade capability. This allows you to upgrade users to the version of the application that you have integrated with the F5 Mobile SDK.

• F5 recommends that you integrate the SDK as described in the F5 Mobile SDK documentation. If you need to deviate from those recommendations, see the F5 knowledge base for other integration considerations or contact F5 Support.

• Initialize the F5 Mobile SDK as early as possible in the application lifecycle to ensure the SDK is initialized and ready to add headers before a protected request is made.

• If you use push notifications on Android, you must be aware of special integration considerations when push notifications are sent to many applications at once. See your Android documentation for information.

• So that you can examine traffic filtered by a specific version of your application, F5 recommends that you include an application version marker in the User-Agent header of the request.

  Example: User-Agent: sometext MyApp/3.3 sometext

• For all responses returned to protected requests, execute parseResponseHeaders().

• Each set of headers contains a unique token. Do not send the same set of headers more than once.

• The F5 Mobile SDK is obfuscated. If you use code obfuscation, exclude the F5 Mobile SDK so it is not obfuscated again.

• If your application uses WebView to access the protected content, consider using the JavaScript solution to add telemetry headers to protected requests. See the F5 knowledge base for information about how to use JavaScript with WebView or contact F5 Support.

• To help you identify SDK integration problems early during development, in your test environment, F5 recommends that you keep your mitigation actions set to Block.

Add a Mobile Base Configuration

To use the F5 Mobile SDK or Mobile SDK Integrator to protect mobile endpoints, you must create a mobile base configuration file and bundle it with your mobile application before you release the application in the app store. The mobile base configuration file contains configuration information needed to initialize the SDK and is used during the first launch of an application that uses the SDK. After the initial launch of the application, the SDK calls the Bot Defense server and downloads new configuration information each time the application launches.

You can create and download the mobile base configuration in either Bot Defense or in Web App and API Protection (WAAP).

To download the Mobile Base Configuration file:

1. Do one of the following:
   • In Bot Defense, click Manage > Mobile > Mobile Base Configurations.
   • In WAAP, click Manage > Bot Defense Management > Mobile Base Configurations.
2. In the Actions column, click the Action menu (…) next to your operating system and click Download Mobile Base Configuration file.
3. Save the file in a location you can access easily.

Next Steps

After you download the mobile base configuration file, provide it to your application developers so they can bundle the file with your mobile application that uses the F5 Mobile SDK or Mobile SDK Integrator before you release the application in the app store.

Then either work with your developers to integrate the F5 Mobile SDK with your application or configure the F5 Mobile SDK Integrator to automatically integrate the F5 Mobile SDK with your application.

Add Bot Defense SDK to your mobile applications

To protect your native applications from malicious automation, you can integrate the F5 Mobile SDK with your native applications, which allows applications to route traffic to Bot Defense for evaluation. You can download iOS and Android versions of the SDK from either Bot Defense or Web App and API Protection (WAAP) in the Distributed Cloud Console.

To download the F5 Mobile SDK

1. Perform one of the following steps:
   • In Bot Defense, click Manage > Mobile > Mobile SDKs.
   • In WAAP, click Manage > Bot Defense Management > Mobile SDKs.
2. In the Actions column, click the Action menu (…) next to the SDK for your operating system and click Download Mobile SDK.

For instructions on how to integrate the F5 Mobile SDK, see the following documentation included in the SDK download file:

• F5 Mobile SDK for iOS Integration Guide (XC_iOS_IntegrationGuide.pdf)
• F5 Mobile SDK for Android Integration Guide (XC_Android_IntegrationGuide.pdf)

Note: You can also integrate Bot Defense with Flutter, React Native, Xamarin, Xamarin.forms, and Cordova. Contact F5 Support for information about integrating with these frameworks.

Keep the following best practices in mind when you update your app to integrate the F5 Mobile SDK:

• Use getRequestHeaders and parseResponseHeaders API, rather than the generateHeaders and analyzeResponse. This API is simpler and meets the needs of Bot Defense.
• For body, you can pass in nil on iOS and null on Android.
• For Bot Defense Standard Edition, getRequestHeaders always returns headers, regardless of which URL is passed. For this reason, your developer should only add headers to requests that require protection.
• Similarly, parseResponseHeaders should be called for every response to the protected requests.

Integrate the F5 Mobile SDK using the Mobile SDK Integrator

The Mobile SDK Integrator is a no-code solution for integrating the F5 Mobile SDK with your mobile application, which saves you both the time and expense of a traditional SDK integration. For more information, see F5 Mobile SDK Integrator.

You can download the Mobile SDK Integrator either from Bot Defense or from Web Application and API Protection (WAAP).

To download the Mobile SDK Integrator:

1. On the Distributed Cloud Console Home page, click Billing.

2. Click Manage > Billing Plan and scroll to the Organization Plan.

3. Under the Organization Plan, click Mobile SDK Integrator. The Mobile SDK Integrator landing page appears.

   Note: If Mobile SDK Integrator is already enabled, the Mobile SDK Integrator download page appears.

4. From the Mobile SDK Integrator landing page, click Request Service.

After F5 fulfills your service request to enable Mobile SDK Integrator, perform the following steps:

1. From the Distributed Cloud Console dashboard, do one of the following:
   • Click Bot Defense and then click Manage > Mobile > Mobile SDK Integrator.
   • Click Web App & API Protection and then click Manage > Bot Defense Management > Mobile SDK Integrator.
2. From the Actions column next to the operating system for your app, click the Action menu (…) and then click Download Mobile SDK Integrator.
3. Extract the contents of the download file.

Next Steps

After you download and extract the Mobile SDK Integrator, from the extracted file directory, open the documentation for your operating system:

• Android: F5-XC-Mobile-SDK-Integrator-Android.pdf
• iOS: F5-XC-Mobile-SDK-Integrator-iOS.pdf

Review the documentation for additional information about the contents of the extracted download file directory, system requirements and instructions for using the Mobile SDK Integrator.

---

Test your Bot Defense configuration

Use the following information to help ensure that Bot Defense is properly configured, that it is injecting JavaScript tags in your application pages correctly, or that you have correctly integrated the mobile SDK.

Verify that Bot Defense is injecting JavaScript tags in your application pages

To confirm that Bot Defense added JavaScript tags to an entry page, use the following procedure to inspect the page in your browser and look for Bot Defense-specific headers.

1. Open one of the application pages you chose to protect.

2. Use the developer tools in your browser or view the page source to inspect the page and confirm that Bot Defense has inserted JavaScript tags with the query string parameters: ?matcher, ?cache, and ?async. For example:

   yourscript.js?matcher
yourscript.js?cache
yourscript.js?async

If the JavaScript tags appear correctly, then Bot Defense is injecting JavaScript tags into your application pages. If you do not see all three JavaScript tags, check your configuration to confirm it is correct. If necessary, contact F5 Support for additional assistance.

Verify Mobile SDK integration

If you chose to integrate the F5 Mobile SDK with your mobile application, perform the following tasks to verify that you integrated it correctly:

• Review the SDK integration documentation that you received from F5 and confirm that you followed all integration steps.

• SDK Initialization

  1. Deploy the application on a device for the first time (if the device already has the application, remove it before this test).
  2. Start the application.
  3. On the Bot Defense Dashboard or the Traffic Analyzer, filter by your client IP address and look for a GET request configuration fetch from your application. If you do not find the GET request, recheck your configuration. For additional assistance, contact F5 Support.

• Decorated Request

  1. Make a request for every protected URL.
  2. On the Bot Defense Dashboard, filter by your client IP address. All protected requests should be marked as “Human.”

• Mitigation

  1. Temporarily alter the application code so that it does not call getRequestHeaders.
  2. Launch the application and make protected requests.
  3. On the Bot Defense Dashboard, filter by your client IP address. All protected requests should be marked as “Automation.” A GET request configuration fetch should appear immediately after each blocked mitigated request.
  4. Update your code to call getRequestHeaders again.

If you successfully completed all test cases, then your integration is working correctly.

Note: F5 recommends that you incorporate these mobile SDK test-cases into your standard regression testing.

Before you release a new application into your production environment, F5 recommends that you set the mitigation action for the application to Continue or Flag and then perform a false positive analysis on your traffic.

---

Analyze Bot Defense Results

After you enable Bot Defense in your production environment, before you enable mitigation actions for your web and mobile applications, you must confirm that Bot Defense is working as expected and that no legitimate traffic is marked as automation. F5 recommends that you also explore your traffic reports and examine anything unexpected. Resolve all issues before you enable the Block or Redirect mitigation actions.

Analyze protected website traffic

Perform the following tests to help confirm that Bot Defense is identifying web traffic correctly.

• Review the Bot Defense dashboard to see the types of traffic identified by Bot Defense. From the Bot Defense Home page, click Overview > Monitor.

  • In the Protected Apps Overview widget, check that your protected application is listed and that the amount of traffic is appropriate.
  • In the Traffic Overview widget, check that the level of human, benign bot, bad bot and other activity is appropriate.
  

  Figure: Bot Defense dashboard

  From the time-period drop-down menu, select Last 24 hours. In the Traffic Visualized section, check whether traffic marked as malicious increases during the day and decreases at night. If so, this might indicate human traffic.

  

  Figure: Timeframe controls

• From the Bot Defense Home page, click Report > Traffic Analyzer.

  • Look at the distribution of IP addresses and the countries of origin. Decide if this distribution looks like it comes from your normal user base.
  • Look at the User Agent column and decide if there are any suspicious user agents present. You can also use this technique to identify wanted automation (benign bots), such as test tools or SEO bots.
  • Click Add Filter. From the drop-down menu, select Bot Reason, select In, select Token Missing and click Apply. Review the traffic and determine if it looks legitimate.

  If a normal user request is missing a token, it could mean that the Bot Defense JavaScript did not run, that another JavaScript on the page interfered with the Bot Defense JavaScript, or that the request was made before the Bot Defense JavaScript loaded.

  When this happens, change the Web Client JavaScript Mode for the endpoint to Sync JS with no Caching, and change the JavaScript Location for the endpoint to After <head>.

  These configuration changes help rule out interference from other JavaScripts that are being executed on the page, help eliminate any potential race conditions when the Asynchronous option is used and minimize any potential network issues.

  

  Figure: Traffic Analyzer report

  If you see legitimate traffic flagged as automation, determine if you can add it to an Allow list.

Analyze protected mobile traffic

Perform the following tests to help confirm that Bot Defense is identifying mobile traffic correctly.

1. Confirm that the number of protected requests with no telemetry headers is low or non-existent and that requests with headers are marked as Human.
2. Confirm that configuration update requests are made at an expected rate. Each configuration fetch corresponds to approximately one user session.

Review your traffic reports and examine any unexpected results. Resolve all issues before you enable mitigation actions.

Analyze protected requests

Perform a false positive analysis to determine if Bot Defense marks any legitimate traffic to your mobile application as non-human.

1. In the Bot Defense Traffic Analyzer report, add the User Agent filter.
2. Select In and then select your application version.
3. Then click Apply.

Important: Make sure the Bot Reason and Traffic Type columns are displayed.

In the list of filter results, is any traffic marked as non-human? For example, is traffic identified as Benign Bot or Bad Bot? If yes:

• If the Bot Reason column displays Token Missing, look at the IP distribution and decide if the traffic looks like user traffic or automation. Is the traffic limited to a particular platform (iOS or Android)?
• If the Bot Reason column displays something other than Token Missing, but the traffic looks human, this is unexpected behavior. Investigate or contact support@cloud.f5.com for assistance.
• If the IP Address distribution looks organic and is not concentrated on only a few specific IP addresses, this might indicate that there is a problem with your SDK integration.
• In the Path column, carefully examine the URLs that are being marked as illegitimate. If traffic from the URLs that are marked as malicious increases during the day and decreases at night, this might indicate human traffic. Additionally, if the traffic is from a wide range of IP addresses, it can also indicate human traffic.

If the flagged traffic is an expected automation, for example, for a monitoring service, determine if you can add the IP addresses to an Allow list.

Review configuration update request frequency

Mobile applications that are integrated with the F5 Mobile SDK fetch new configuration settings from Bot Defense at specific times during the application lifecycle, including:

• At application launch
• At mitigation
• After four hours (if the application is in the foreground).

Typically, there is approximately one configuration fetch during each active user session. Since some users launch an app but do not proceed further, and others have two sessions within the same four-hour period, it is normal to see an average of 0.5-2 sessions per configuration fetch.

How you view configuration fetches depends on how you host your application pages you want to protect. The following sections provide information about how to find the number of configuration fetches in each platform.

Note: For all third-party platforms, including Cloudflare, Amazon CloudFront, Adobe Commerce Cloud and Salesforce Commerce Cloud, use the native logging and reporting capabilities of your platform to view configuration fetches. For information, see the documentation for your platform.

View configuration fetches in Web App & API Protection

When you use Bot Defense enabled on an HTTP load balancer in Web App and API Protection (WAAP), you can use the Security Dashboard in WAAP to view configuration fetches requested by the mobile application you integrated with the F5 Mobile SDK.

To view the number of configuration fetches:

1. Log into Web App & API Protection (WAAP) and check to make sure you are in the correct namespace.

2. From the Web App & API Protection navigation panel, click Overview > Dashboards > Security Dashboard.

3. In the Load Balancers widget, click the name of the load balancer that services your production traffic.

4. Click the Requests tab.

5. Add one of the following filters:

   • For Android applications, enter req_path in /v1/android/update.
   • For iOS applications, enter req_path in /v1/ios/update.

6. Look at the number of items returned by your search. The number of items should be equal to the number of user sessions you observed during the same period.

   For example, the number of configuration fetches should be equal to the number of login requests you observed during your false positive analysis.

View configuration fetches in BIG-IP

For BIG-IP versions 14-17 and later, use your native BIG-IP log files to view configuration fetches. For information on viewing BIG-IP log files, see your BIG-IP documentation. View configuration fetches in your third-party platform

Next steps

After you confirm that Bot Defense is functioning as expected, that legitimate traffic is not being marked as automation, and that your mobile applications are communicating properly with Bot Defense, you can enable mitigation actions. For information see Configure Mitigation Actions.

---

Configure Mitigation Actions

When Bot Defense detects automated traffic, you can configure the system to take any of the following actions:

• Continue: Allows traffic to continue to the origin server where your application resides. You can choose to add a header that enables you to monitor traffic in reporting and analytics dashboards.

  Note: When you configure Bot Defense on Web App and API Protection (WAAP), this option is called Flag.

• Redirect: Redirects automated traffic to a different page. You provide the appropriate Status Code and URI where you want to redirect the bot. Use this option to deceive bots into thinking their request successfully went through. You can also redirect to a page with more information for human users that may have been incorrectly redirected.

• Block: Prevents automated traffic from reaching the origin server where your application resides. You can customize the status code, content type, and body of the response message or use the default values provided by the system.

  Important: In the message you display to blocked requests, do not mention “automation”, F5, or Bot Defense so that you do not expose additional information attackers.

Note: Mobile clients only allow Continue and Block. If you select Web and Mobile Client, you can select mitigation actions for each client type.

F5 recommends that you select a mitigation response that mimics how the application responds when a request is invalid (for example, when invalid credentials are used).

If you enable Bot Defense through an HTTP load balancer in Web App & API Protection (WAAP), you can configure Bot Defense to distinguish between malicious automation (bad bots) and benign bots (good bots). This allows you to apply mitigation actions only to malicious automation or to both malicious and benign bots.

Enable mitigation actions

When you initially set up your Bot Defense deployment, F5 recommends that you set your mitigation actions to Continue (Flag), which logs, but does not block, any traffic. When you complete your testing and are sure that the system is properly configured and functioning as intended, you can enable the Block or Redirect mitigation actions to protect your application pages from malicious traffic.

Important: Before you enable mitigation actions, F5 strongly recommends that you complete a false positive analysis of your traffic.

To enable mitigation actions for malicious traffic:

1. Update the mitigation actions in your web and mobile endpoint configurations.
2. If you configured web scraping protection, make sure to update the mitigation actions in your web scraping configuration.

For information about how to configure mitigation actions on your specific platform, see Configure Bot Defense and then view the configuration documentation for your platform.

Important: To disable mitigation actions, reset the mitigation action to Continue.

---

Manage Bot Defense

The following sections explain how to perform tasks that are periodically required to manage your Bot Defense deployment.

Test changes to your deployment

When you make changes to your deployment, F5 recommends that you make them in a test environment before you deploy them in your production environment.

If you protect a new web-based endpoint:

1. When you add the endpoint to your test system, verify that Bot Defense injects JavaScript tags correctly. For information, see Verify that Bot Defense is injecting JavaScript tags in your application pages.
2. When you add the endpoint to your production system, you must confirm that Bot Defense is working as expected and that no legitimate traffic is marked as automation before you enable mitigation actions. For information, see False positive analysis.

If you protect a new mobile application, you must perform a false positive analysis before you enable mitigation.

Manage protected applications

Use the Distributed Cloud Console to manage your protected applications, for example, to update your configuration, add a protected endpoint or to delete the protected application. For information about specific settings, see Configure Bot Defense and then view the documentation for your platform.

Important: Be sure to adequately test all changes to your deployment.

View and edit protected applications in Bot Defense

1. From the Distributed Cloud Console Home page, select Bot Defense.
2. Click Manage > Applications.
3. To view configuration information for an application, from the Applications page, in the Actions column, click the Action menu (…) for the application you want to view and click Manage Configuration.
4. To edit application configuration information, click Edit Configuration.
5. In the Connector Type section, click Edit Configuration to view and edit configuration information.

View and edit protected applications in Web App and API Protection (WAAP)

1. From the Distributed Cloud Console Home page, click Web App and API Protection.
2. Click Manage > Load Balancers > HTTP Load Balancers.
3. From the HTTP Load Balancers page, in the Actions column, click the Action menu (…) for the load balancer you want to manage and then click Manage Configuration.
4. To edit Bot Defense configuration information for the load balancer, click Edit Configuration and then click Bot Protection and Edit Configuration.

---

Bot Defense Dashboards & Reporting

F5 Distributed Cloud Bot Defense includes multiple ways to view detailed information about the traffic that Bot Defense analyzes. Automated Threat Summaries deliver insights to you automatically each month, while a variety of dashboards provide you with instant, detailed access to analysis of your data.

Note: Bot Defense dashboard and report widgets display the message, "'Undefined' Data Discovered" when requests reach a protected endpoint that does not have an assigned endpoint label. Make sure you use the latest connector configuration and that you apply an endpoint label to all endpoints.

Note: Bot Defense dashboard and report widgets display the message, "Data Gap Discovered" when there is no data to display. Make sure Bot Defense is configured correctly and that you select a time period for the dashboard or report for which you have collected data.

Automated Threat Summaries

Automated Threat Summaries are emailed reports that summarize your monthly network traffic and Bot Defense activity. Automated Threat Summaries include information about the percentage of your traffic that is automated, the numbers of good and bad bots detected, the number of human visitors to your protected applications and endpoints, and a breakdown of your overall web traffic that is analyzed by Bot Defense.

To enable Automated Threat Summaries:

1. From the Distributed Cloud Console Home page, click Bot Defense.
2. From the Bot Defense navigation menu, click Manage > Reports > Reports Management and then click Add Report.
3. Enter a Name for the report and then, from the Report Type drop-down menu, select Bot Defense.
4. Click Add Item and then choose the User Group to which you want to send the report. If you need to create a new user group to receive the report, see Users.
5. Click Save and Exit.

Load Balancer Bot Defense Dashboard

After you enable Bot Defense, the Load Balancer Bot Defense dashboard provides a snapshot of bot and human activity in your web traffic on your HTTP load balancers.

To view the Web App & API Protection Bot Defense dashboard:

1. From the Web App & API Protection navigation menu, click Overview > Dashboards > Security Dashboard.
2. In the Load Balancer widget, from the list of load balancers, click the name of the load balancer you want to view and then click Bot Defense.

The Load Balancer Bot Defense dashboard includes the following information:

• Traffic Types: The total number of transactions in the selected time window and how many were bad bots, benign bots or humans. Hover over the donut graph for percentage information for each type of traffic.

  • Human: Traffic from human users and therefore not automated.
  • Benign Bot: Bots that are harmless or non-malicious, such as SEO bots or test tools.
  • Bad Bot: Bots that are malicious, often causing harm to legitimate users, businesses, or organizations.
  • Telemetry Client: Traffic that comes from loading the Bot Defense JavaScript in application pages or from configuration requests (fetches) from mobile applications integrated with the F5 Mobile SDK.
  • Challenged: Traffic from challenges served to clients on protected GET transactions to determine if the clients are human or automated.

  Hover over the donut graph for percentage information for each type of traffic.

• Traffic Overview: The transactions per minute of human and bot traffic for the selected time period. Hover over the area chart or bar graph for the number of each type of event at a specific time.

• Top Bad Bots: The five bots that made the most malicious requests in the selected time period, including the source IP, ASN and number of individual events. You can view each bot's Source IP, AS Organization, and User Agent.

• Top Benign Bots: The benign bots that appear most often in your web traffic during the selected time period, including the name of the bot, type, and the number of individual events and percentage of events attributed to a specific bot.

• Top Visited Endpoints: The five endpoints being attacked most frequently by bad bots, including the host name, endpoint path, and number of malicious requests in the selected time period.

You can specify the time period displayed in the dashboard and add the following additional filters to customize your view:

• AS Organization
• Bot Reason
• Country
• Host
• IP Address
• Path
• Traffic Channel
• Traffic Type
• User Agent

To view additional Bot Defense data for this specific load balancer, such as an overview of protected apps, human traffic by geographic region, an overview of specific bad bot events impacting your applications, and information about the intent of an attack, click View in Bot Defense. Then, from the navigation menu, click Overview > Monitor to view the Bot Defense Dashboard.

Bot Defense Dashboard

The Bot Defense dashboard is a snapshot of all human and bot activity in the web traffic analyzed by Bot Defense for a specified time period.

To view the Bot Defense dashboard, in Bot Defense, from the navigation menu, click Overview > Monitor.

By default, the dashboard displays data from the last six hours. You can customize the time period and the region that displays. You can also save and share filters that you apply to the dashboard.

The Bot Defense dashboard includes the following information:

• Traffic By Type: Total number of traffic events that reach your protected endpoints and the number of each event type. Hover over the donut chart to see the percentage of each type.

  • Human: Traffic from human users and therefore not automated.
  • Benign Bot: Bots that are harmless or non-malicious, such as SEO bots or test tools.
  • Bad Bot: Bots that are malicious, often causing harm to legitimate users, businesses, or organizations.
  • Telemetry Client: Traffic that comes from loading the Bot Defense JavaScript in application pages or from configuration requests (fetches) from mobile applications integrated with the F5 Mobile SDK.
  • Challenged: Traffic from challenges served to clients on protected GET transactions to determine if the clients are human or automated.

  Hover over the donut graph for percentage information for each type of traffic.

• Traffic by Category: The traffic detected for each endpoint category for the selected time-period. Hover over the donut chart to see percentage information for each category.

• Traffic by Action: Total number of automated traffic events that reach your protected endpoints and how many times each mitigation action is applied to these events. Hover over the donut chart to see percentage information.

• Protected Apps: A breakdown of bad bot traffic by defended application. Hover over the donut chart to see percentage information.

Use the dashboard controls to view additional data.

Traffic Type

• Traffic Visualized: Total number of events impacting the applications you protect with Bot Defense over the specified time range as an area chart, bar graph or line graph. Hover over the charts for information about a specific time.
• Top Benign Bots Found: Top benign bots that are visiting your protected applications, including the name and type of bot and total events for each bot.
• Bot API Latency Across Top Protected Apps: Information about traffic latency measured between the top protected application and origin server, including average time, application name, latency per application, number of transactions and trend information.

Endpoint Category

• Traffic Category Visualized: Shows the traffic detected per endpoint category for the time-period selected. Hover over the chart to see totals and percentages for a specific time.
• Top Endpoint Labels: Shows the top 10 endpoint labels on which traffic was detected, and the percentage of traffic detected on the endpoint label in relation to all traffic detected on your system.
• Top Visited Endpoints: Shows the five endpoints that are being attacked most frequently by bad bots. The table includes the host name, endpoint path, and number of malicious requests in the selected time period.

Bad Bot

• Actions Breakdown: A time series chart for mitigated and flagged bad bot events across all protected endpoints displayed as an area chart, bar chart or line graph.
• Top Actions: The number of events to which each mitigation action was applied.
• Top Sources of Bad Bot Traffic: Bad bot traffic analysis by source type, including number of events, IP address and geolocation. Display by Source IP, ASN or User Agent.
• Threat Type: An overview of bad bot traffic by threat type over a selected time period. View as an area or line chart. Hover over the charts to see the number and percentage of each type of attack for a specific time.
• Top Threat Types: An overview of bad bot traffic by threat type listed in descending order.
• Top 5 Sources of Threat Types: A list of the top five sources of each bad bot attack type. Information includes source IP address, autonomous system number (ASN), geolocation, number of events from each source and the percentage of the total for that attack type attributed to the source.

Geolocation

• Traffic from Humans: A map that shows where your human traffic comes from. Hover over each country for additional information about your traffic.

When you filter the Bot Defense dashboard by a single load balancer, click View in Web App & API Protection to view the Load Balancer Bot Defense dashboard for that load balancer.

Traffic Analyzer

The Traffic Analyzer report provides detailed insight into human, benign bot (good bot), bad bot and other traffic on the HTTP load balancer. View traffic as a bar chart or an area chart. Hover over the charts to view traffic totals for specific times.

To view the Traffic Analyzer, in Bot Defense, from the navigation menu, click Report > Traffic Analyzer.

In addition to the chart showing transactions per minute for a specified time window, you can also view details about every HTTP request sent through Bot Defense. Each HTTP request includes the following information:

• Time
• Country
• IP address
• ASN
• AS Organization
• User Agent
• Host
• Path
• Method
• Traffic Channel
• Traffic Type
• Threat Type
• Bot Reason
• Action Taken
• Header Reference

Rearrange and sort the columns by selecting them. Show or hide columns by selecting the gear icon to the upper right of the list. By default, the report displays data from the last six hours. You can customize the time period and the region that displays. You can also save and share filters that you apply to the report.

Bad Bot Report

The Bad Bot Report provides information about malicious automation in your web traffic.

To view the Bad Bot Report, in Bot Defense, from the navigation menu, click Report > Bad Bot Report.

By default, the report displays data from the last six hours. You can customize the time period and the region that displays. You can also save and share filters that you apply to the dashboard.

The Bad Bot Report includes the following information:

• Traffic Metrics: An overview of the different characteristics of the bad bot traffic that Bot Defense has detected across your protected applications and endpoints.
• Actions Taken: The number of events to which each mitigation action was applied, including percentage and trend information.
• Threat Type: An overview of bad bot threat traffic based on key OWASP attack types to help you see how attackers are targeting your endpoints. Also provides up/down trend information to show you the threat types that are peaking during the selected time range.
• Events per Application: The number of bad bot events grouped by application. Hover over the chart for totals and percentages for each application.
• Bad Bot Reasons: The top reasons why Bot Defense associated an event with a bad bot, including the number of events for each reason code and percentage, to help you understand how bad bots are attacking your endpoints.
• Bad Bot Traffic: An overview of bad bot traffic by threat type over a period of time.
• Bad Bot Events per Application: An overview of bad bot events that occurred on each protected application. View data as an area chart, bar chart or line graph. Hover over the charts for event totals and percentages on each application at a specific time.
• Bad Bot Traffic Breakdown: An overview of bad bot events impacting your applications across the specified time range. View data as an area chart, bar chart or line graph. Hover over the charts for totals and percentages for a specific time. You can also view bad bot events organized by operating system (OS), browser, user agent (UA), autonomous system number (ASN) or IP address. Explore and investigate detailed event data, including threat types and reason code information. Expand each row to reveal additional total and percentage information. Use Search to find specific events.
• Endpoints with Bad Bot Traffic: An overview of bad bots attacking your protected endpoints.

Protection Coverage Report

The protection coverage report provides information about your protected applications and endpoints and the traffic accessing them.

To view the protection coverage report, in Bot Defense, from the navigation menu, click Report > Protection Coverage Report.

By default, the report displays data from the last six hours. You can customize the time period and the region that displays. You can also save and share filters that you apply to the dashboard.

The Protection Coverage Report includes the following information:

• Endpoint Summary: A summary of your protected applications and endpoints during your selected time period.
• Endpoints Category Breakdown: An overview of traffic passing through your secured endpoints. Use the drop-down menu to display data for specific flow categories and associated flow labels. Hover over the horizontal bars for information about traffic sources, action taken on the traffic, and the traffic channel (web, mobile and so on).
• Protected Traffic Flow: A visual representation of all traffic visiting your protected endpoints.
• All Protected Endpoints: Information about all of your endpoints that are protected by Bot Defense, including domain, associated application, number of events that took place on the endpoint, and percentage of your total traffic that passed through the endpoint.

Peer Comparison Dashboard

The Peer Comparison dashboard helps you understand how your bot protection compares to similar peer companies. Data includes comparisons of total traffic breakdowns, top benign bots, top reason codes (how Bot Defense determined the automation was malicious), and top threat types. For example, the Threat Types widget shows you your top bad bot traffic compared to an average of the top bad bot traffic at peer companies.

Use peer comparison data to help you identify areas where you might want to tune your configuration to help ensure the highest protection from current and future attacks.

To view peer comparison data, from the Bot Defense navigation panel, click Report > Peer Comparison.

You can select the time period, sort the data in descending order based on either your threat information or your peer threat information, and view absolute values or view data as a percentage of traffic.

The Peer Comparison dashboard includes the following information:

• Total Traffic Breakdown: The total number of events impacting the applications you protect with Bot Defense compared to the average number of events impacting peer companies. Hover over the bar chart for exact numbers and percentages of each traffic type.
• Top Benign Bots: The top benign bots (good bots) in your web traffic during the selected time period compared to the average number of those benign bots at peer companies, including the name of each bot and the number of individual events attributed to a specific bot. Hover over the bar chart for exact numbers and percentages of each type of bot.
• Top Bad Bot Reasons: A list of the top bot reason codes indicating how an attack was executed compared to the average of those codes at peer companies. Hover over the bar chart for exact numbers and percentages of each code.
• Top Threat Types: An overview of the different types of bad bot traffic impacting your applications compared to the average number of those types of bad bots impacting peer companies. Hover over the bar chart for exact numbers and percentages of each threat type.

Note: Peer comparison information is not available for MSP and FedRAMP customers or for customers with private instances, and the Peer Comparison dashboard does not appear in the Bot Defense navigation menu.

Consumption Report

The Consumption Report allows you to see how many transactions Bot Defense has processed for the past year.

To view the Consumption Report, in Bot Defense, from the navigation menu, click Report > Consumption Report.

This report displays the following information by month or by quarter:

• Traffic: All the traffic on the customer’s web applications that are monitored by Bot Defense.
• Initial Config: Traffic that is generated by the Bot Defense JavaScript that is embedded on the end-user’s mobile app.
• JavaScript: Traffic that is generated by the Bot Defense JavaScript that is embedded on the end-user’s web browser.

The report displays data for the past year, starting from a year previous to the current month until the previous month. For example, if the current month is December 2022, data is presented from December 2021-November 2022. Hover over the chart to see information for a given month or quarter.

The following summary data for the previous 24 months is displayed at the top of the report:

• Highest: The highest number of transactions monitored in a given month in the past year, compared with the highest number of transactions monitored in a given month in the previous year.
• Lowest: The lowest number of transactions monitored in a given month in the past year, compared with the lowest number of transactions monitored in a given month in the previous year.
• Average: The monthly average number of transactions monitored in the past year, compared with the monthly average number of transactions monitored in the previous year.

You can display data as either an area chart or bar chart. Hover over the charts to see data from specific months.

Use the drop-down menu to switch between Monthly and Quarterly views.

---

Save and Manage Dashboard Filters

The Bot Defense Dashboard (Monitor) and Traffic Analyzer report allow you to quickly and easily save and view past dashboard filter combinations. You can share your saved filters with other users and also view filters saved by other users.

Filters are specific to the report where they are created. For example, a filter created and saved for the Traffic Analyzer report is only available for that report.

Note: You cannot save filters in Bot Defense enabled in Web Application & API Protection.

Save a Dashboard Filter

1. Use the Add Filter option to filter the data displayed by your report.

2. After you set a new filter that you want to save, click the Save Filters icon.

   

   Figure: Save filters icon

3. Enter a Name and Description for the filter and then click Save and Exit.

   

   Figure: Name and Description fields

   The newly saved filter is available from the Saved Filters list to view and share with other administrators.

   

   Figure: Saved filters

View Saved Filters

To view a previously saved filter, click Saved Filters and then select a filter from the list.

Note: Filters with custom date ranges older than 30 days expire and cannot be used.

You can also view filters saved by other users.

1. On the dashboard or report that you want to view, click Saved Filters.

2. Click View More Details.

3. Click Others and then click a filter from the list to view the filter.

   

   Figure: View other users' filters

Share a Saved Filter

1. From the Bot Defense navigation panel, click Manage > Saved Filters.
2. From the Saved Filters list, click the name of the filter you want to share.
3. Click Copy URL and provide the URL another administrator to enable them to view your filter.

---

Configure Bot Defense (Connectors)

Your Bot Defense configuration process depends on how you host the application pages that you want to protect. Before you begin the configuration process, make sure you have thoroughly reviewed the section, Best Practices to help you make the correct configuration decisions.

Important: When you configure Bot Defense, F5 recommends that you set all mitigation actions to Flag or Continue until you finish testing that the system is configured properly and working as intended.

• For applications that route traffic through F5 Distributed Cloud Mesh (WAAP), see Configure Bot Defense on an HTTP load balancer (WAAP).
• For applications that route traffic through BIG-IP, see one of the following topics:
  • Enable Bot Defense on BIG-IP v14-16 (iApp Connector).
  • Enable Bot Defense on BIG-IP v17.0 or later.
• For applications hosted on a third-party content delivery network, see one of the following topics:
  • Enable Bot Defense on Adobe Commerce Cloud (Magento).
  • Enable Bot Defense on Amazon CloudFront.
  • Enable Bot Defense on Cloudflare.
  • Enable Bot Defense on Salesforce Commerce Cloud.
• For all other applications, you can configure Bot Defense with a custom application.

Next Steps

When you finish configuring Bot Defense, review Bot Defense results to help ensure the system is properly configured and working as intended. See the following information:

• Test your Bot Defense configuration
• Analyze Bot Defense results

---

Configure Bot Defense on an HTTP load balancer (WAAP)

The following information explains how to configure Bot Defense on an HTTP load balancer that you have configured with F5 Distributed Cloud.

Prerequisites

• You must have an active F5 Distributed Cloud account. If you do not have an account, see Create a Distributed Cloud Console Account.
• You must have Bot Defense enabled in the Distributed Cloud Console. See Enable Bot Defense.
• You must have Web App & API Protection (WAAP) enabled and have an HTTP load balancer configured.

WAAP or Distributed Mesh best practices

• If your site is served from an apex domain, configure a redirect from the apex domain to the FQDN domain (for example, customer.com redirects to www.customer.com). This is required because your domain must point to a Distributed Cloud-provided CNAME. Pointing a CNAME from an apex domain is not recommended as that prevents you from having SOA and all other DNS records at apex.
• Do not use IP-based session persistence to load-balance internally. F5 Distributed Cloud has a range of egress IPs and if you have IP-based load balancing at the origin, this may break your session persistence. Use cookie-persistence, if possible.
• Lock down your infrastructure to Distributed Cloud egress IPs only. This prevents attackers from bypassing Distributed Cloud altogether and hitting your origin directly.
• Validate your internal tools (such as logging tools or fraud tools) see the traffic accurately when going through Bot Defense.
• If you have a CDN (such as CloudFront) implemented before F5 Distributed Cloud (Client > CDN > F5 Distributed Cloud > Origin), ensure:
  • The Bot Defense JavaScript file is excluded from the cached entities.
  • The CDN passes the origin User-Agent rather than injecting CDN User-Agent, such as "Cloud Front".

Configure a Bot Defense Test System in Web App & API Protection

The following video explains how to set up a basic test system for Bot Defense in Web App & API Protection. To configure a production system, see additional configuration options included in the sections below.

Enable Bot Defense on an HTTP Load Balancer

1. From the Distributed Cloud Console dashboard, click Web App & API Protection.
2. From the navigation menu, confirm that you are in the correct namespace.
3. Click Manage > Load Balancers > HTTP Load Balancers.
4. From the Actions column, click the Actions (…) menu next to the load balancer where you want to configure Bot Defense and then click Manage Configuration.
5. Click Edit Configuration and then click Bot Protection.
6. In the Bot Protection section, from the Bot Defense drop-down menu, select Enable.

Important: For load balancers with types “HTTPS with Custom Certificate” and “HTTPS with Automatic Certificate” set the Path normalize field to Enable path normalization. This is the default setting for new load balancer objects.

Next Steps

Configure protected application endpoints. For information, see the following sections:

• To protect web-based endpoints, see Configure Protected App Endpoints.
• To protect mobile endpoints, see Configure F5 Mobile SDK Settings for WAAP.

Configure Protected App Endpoints

To protect web-based endpoints, such as a web page, in the Bot Protection section, perform the following steps:

1. From the Bot Defense Region drop-down menu, select the region where the origin server for the application is located.

2. (Optional) Enable Show Advanced Fields. In the Timeout field, enter the number of milliseconds Bot Defense should wait for the inference check to complete before timing out. The default value is 1000.

3. In the Bot Defense Policy section, click Configure.

4. In the Protected App Endpoints section, click Configure and then click Add item.

5. Enter the following information for each endpoint:

   • Name: Enter the name of the message. Must follow DNS-1035 format.

   • HTTP Methods: Select the HTTP methods you want to monitor on this endpoint.

     • ANY: Includes GET(XHR/Fetch), POST and PUT. Does not include GET(Document). To select all methods including GET(Document), instead of ANY, you must select each method from the list.
     • GET(XHR/Fetch): Use when the protected application makes an XHTTPRequest or Fetch API call to get the content of the page. GET requests are protected only if they are sent by XHTTPRequest from a page with Bot Defense JavaScript injected, not from direct navigation using the address bar or link.
     • POST
     • PUT
     • GET(Document): Use to protect pages on a web site that can be accessible by GET requests without visiting the main page. When you configure an endpoint using GET(Document), Bot Defense displays an interstitial page that is transparent to the user but that allows it to collect telemetry data about the requests. Note that you cannot use GET(Document) with mobile endpoints.

     You can select multiple methods.

   Note: If you select both GET(XHR/Fetch) and GET(Document), only GET(XHR/Fetch) requests are monitored. If you need to monitor both methods, add the endpoint separately for each method.

   Important: If you choose to protect all pages and endpoints (/*), F5 recommends that you select specific HTTP methods to monitor and that you do not select the ANY option. Protecting all HTTP methods for all pages can adversely impact performance.

   • Endpoint Label: F5 strongly recommends that you select endpoint labels to allow more granular attack intent identification and reporting when Bot Defense detects automation.

     For example, to identify a multi-factor authentication flow on an endpoint, select Specify Endpoint label category > Authentication > Login MFA.

     For a full list of available endpoint labels, see Endpoint Labels.

     Note: For web scraping labels, select Specify Endpoint label category > Search and select an available flow label.

   • Protocol: Select the protocols you want to protect. Select HTTP, HTTPS or Both.

   • Domain Matcher: Specify the domains you want to protect. Enter an exact value, a suffix value, or a regex value.

   • Path: Enter the path to the endpoint you want to protect. For example, enter /login. Enter a prefix, exact path, or regex value.

   • Traffic Channel: Select the type of traffic that accesses this endpoint. Select Web Traffic, Mobile Traffic or Web and Mobile Traffic. If you select Web and Mobile Traffic, you must provide a header to distinguish mobile request from web requests. You can use a wildcard (*) in the header value to match a substring.

   • Bot Traffic Mitigation: Specify what action to take when a bot is detected.

     • Block: The endpoint returns a status code and message. You can enter a status code and edit the message here.
     • Redirect: The endpoint forwards the browser to the URI that you specify. You can only select Redirect for web endpoints.
     • Flag: Allows requests to continue to the origin. Select No headers to create a log record only or select Append Headers to create custom headers for inference and automation type.

   • Good Bot Detection Settings: Specify whether the mitigation actions you selected above apply to both bad bots and good bots. You can choose to flag good bots but allow them to continue to origin, or you can apply the mitigation actions to all automation. By default, mitigation actions are applied to all automation.

   Important: Good bots, also called benign bots, are bots that perform specific, helpful tasks, such as search engine bots, social media crawlers and aggregator bots. Many of these bots can be useful to your business and therefore you might decide to allow them to continue to origin.

6. Click Apply.

7. Click Add Item to add another endpoint or click Apply when you finish adding endpoints.

Next Steps

Configure how Bot Defense injects JavaScript into your application pages.

Configure JavaScript Injection

To protect web-based endpoints, Bot Defense injects JavaScript tags. The Bot Defense JavaScript collects telemetry data about requests to your endpoint. If you configure web-based endpoints, you must configure how the Bot Defense JavaScript tags are injected into the pages that you want to protect.

In the JavaScript Insertion section:

1. In the JavaScript Download Path field, enter the path from where the HTTP load balancer can download the Bot Defense JavaScript to serve to the client browser.

   F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. Enter a simple path that starts with / or a complete URL such as https://example.com/customer1.js. The URL or path you choose cannot conflict with your existing JavaScript files.

2. From the Web Client JavaScript Mode drop-down menu, determine how the protection JavaScript is loaded into the entry page. The JavaScript is loaded in two parts. The larger part can be loaded in two possible ways:

   • Asynchronous: The JavaScript runs as soon as it is loaded and does not block the page from loading.
   • Synchronous: The page does not continue loading until the JavaScript has been loaded and executed.

   You can also choose to cache the larger part of the JavaScript, so it does not have to be downloaded each time it is loaded into a new page.

   Choose one of the following options:

   • Async JS with no Caching
   • Async JS with Caching
   • Sync JS with no Caching
   • Sync JS with Caching

3. From the JavaScript Insertion Settings drop-down menu, specify if the HTTP load balancer should insert JavaScript into all pages, or if some pages should be excluded.

   Important: When you choose the JavaScript location, F5 recommends that you select After <head> so that the Bot Defense JavaScript is executed early. This allows time for the Bot Defense JavaScript to be fetched and executed while the rest of page is rendered. If you select After </title>, be sure your application pages have the <title> tag.

   If you select Insert JavaScript in All Pages, choose where you want to insert the JavaScript:

   • After <head> tag
   • After </title> tag
   • Before <script> tag
   

   Figure: Configure JavaScript Injection

   If you select Insert JavaScript in All Pages with the Exceptions:

   • Choose where you want to insert the JavaScript:

     • After <head> tag
     • After </title> tab
     • Before <script> tag

   • Create a list of pages where Bot Defense should not insert JavaScript tags:

     1. In the Exclude Pages section, click Configure and then click Add Item.

     2. Enter the following information for each page in your application where you want to insert the Bot Defense JavaScript.

        • Name: The name of the message. Must follow DNS-1035 format.
        • Description: A human-readable description of the endpoint.
        • Domain Matcher: Specify domains you want to exclude. Enter an exact value, a suffix value, or a regex value.
        • Path: Specify protected paths here. Enter a prefix, exact path, or regex value.

     3. Click Apply. Click Add Item to add additional JavaScript insertion paths.

4. When you finish configuring JavaScript insertion settings, click Apply.

   

   Figure: Configure JavaScript Injection with Exceptions

Insert JavaScript Tags in specific pages

You can optionally configure Bot Defense to only insert JavaScript tags in specific pages. Be sure to select paths to HTML pages that end users are likely to visit before they browse to any protected endpoint. In Bot Defense, these are called “entry pages.”

Note: F5 recommends that you use wildcards to select JavaScript insertion paths for HTML pages to which end users are likely to go, such as /index.htm and /login/*.

1. Click Show Advanced Fields.
2. From the JavaScript Insertion Settings drop-down menu, select Custom JavaScript Insertion Rules.
3. Use the descriptions above to configure the JavaScript Insertions and Exclude Paths sections.

Disable JavaScript Insertion

If necessary, you can optionally disable JavaScript insertion.

1. Click Show Advanced Fields.
2. From the JavaScript Insertion Rules drop-down menu, select Disable JavaScript Insertion.
3. Click Apply and then click Apply again.

Note: When you select Disable JavaScript Insertion, you are required to have a value in the JavaScript Download Path and Web Client JavaScript Mode fields even though Bot Defense ignores the actual values in those fields.

Next Steps

If you configured mobile endpoints, you must you must configure F5 Mobile SDK settings for WAAP. The F5 mobile SDK must be integrated with your mobile application to route requests to Bot Defense for inspection.

If you did not configure mobile endpoints, you do not need to configure the F5 Mobile SDK settings and can test Bot Defense to make sure it is handling requests to your web endpoints correctly. For information, see Verify that Bot Defense is injecting JavaScript tags in your application pages.

Configure F5 Mobile SDK Settings for WAAP

Important: Before you configure mobile settings, see Protect Mobile Endpoints for important best practices, required configuration, and information about integrating the F5 Mobile SDK with your mobile endpoints.

If you added a mobile endpoint in the Protected App Endpoints section, you must enable the F5 Mobile SDK and specify a specific header for mobile requests. If you did not add any mobile endpoints, then you do not need to configure F5 Mobile SDK settings.

1. In the Mobile SDK Settings section, click Show Advanced Fields.

2. From the Mobile SDK Settings drop-down menu, select Mobile SDK Configuration.

   

   Figure: Configure Mobile SDK Settings

3. In the Mobile Traffic Identifier section, click Add Item.

4. Enter a Header Name to identify mobile requests. The header name is case sensitive.

5. From the Match Options drop-down menu, select one of the following options:

   • Present: Matches only if a header is present.
   • Not Present: Matches only if a header is not present.
   • Match Values: Click Add Item to enter an exact value or a regex value. You can enter multiple values. When you finish adding values to match, click Apply.

6. If you selected Match Values, click Show Advanced Fields. From the Transformers drop-down menu, optionally select any transformers, such as converting the path to lower case or removing blank spaces, that you want to apply to your paths before matching. Transformers are applied in the order you add them.

   

   Figure: Configure Mobile Header

7. When you finish configuring SDK settings, click Apply.

Next Steps

Make sure you have configured Bot Defense correctly. For information, see Test your Bot Defense configuration.

---

Enable Bot Defense on BIG-IP v14-16 (iApp Connector)

Prerequisites

Before you deploy or upgrade an iApp in the F5 BIG-IP system, you must meet the following requirements:

• You have access to the F5 Distributed Cloud Console to download the latest iApp template.
• You have BIG-IP versions 14.1 or later.

  Note: The Distributed Cloud Bot Defense iApp template is required for BIG-IP versions 14 to 16. For BIG-IP version 17.0 or later, Bot Defense is integrated natively with BIG-IP and provides improved performance. For information, see https://techdocs.f5.com/en-us/bigip-17-1-0/big-ip-saas-bot-defense.html.

• You have backed up your BIG-IP configuration. For information, see “Back up your BIG-IP system configuration”: https://support.f5.com/csp/article/K13132#BackingUp.
• The virtual server that you want to protect with Bot Defense must have an HTTP profile and default pool attached to it.
• To protect mobile endpoints, you must create your Mobile Base Configuration. See your mobile SDK documentation for information.
• F5 BIG-IP Application Services Templates (FAST) are the next-generation successor to now deprecated iApp templates. F5 strongly recommends that you do not use both FAST and iApp templates together. They are not compatible with each other.

Download the iApp Connector Template v3.0.4 from the Distributed Cloud Console

1. Log on to the Distributed Cloud Console. From the Dashboard page, select Bot Defense.
2. Verify that you are in the correct namespace. For information about namespaces, see https://docs.cloud.f5.com/docs/ves-concepts/core-concepts.
3. Select Add Application. If you have not already added any protected applications, you are instructed to add one.
4. Add a Name and Description for the application.
5. Select the region: US, EU, Asia.
6. From the Connector Type drop-down list, select F5 BIG-IP iApp.
7. Select Save and Exit.
8. From the Actions column in the list of applications, click the Action Menu … and then click Download template. Save the template in a location you can access later.

Next Steps

After you download iApp Connector Template v3.0.4, perform one of the following steps:

• To configure a new application, see Create a New Application from iApp Template v3.0.4.
• To upgrade an existing application, see Upgrade an application from iApp Template v3.0.3 to iApp Template v3.0.4.

Create a New Application from iApp Template v3.0.4

Import the iApp Template to BIG-IP for a New Application

The following steps explain how to import iApp Connector Template v3.0.4 into BIG-IP to create a new application.

Note: To upgrade an existing application from the v3.0.3 template to v3.0.4, see Upgrade an application from iApp Template v3.0.3 to iApp Template v3.0.4

1. Log on to the BIG-IP where you want to add your application.
2. Select iApps > Templates > Import.
3. Select Choose File and navigate to the location where you saved the v3.0.4 template.
4. Select the template you want to import and click Open.
5. Then select Upload and OK to confirm.

Required Initial Configuration of a New Applications from iApp Templates 3.0.4

When you use the F5 XC Bot Defense Template v3.0.4 to create a new XC Bot Defense Standard Application instance, you must perform the following required initial configuration steps in BIG-IP before you configure any additional settings.

1. In BIG-IP, click iApps, Application Services > Applications and then click Create.
2. Enter a Name for the new application. The name cannot contain any spaces or special characters.
3. From the Template drop down, select f5.ibd.cs.
4. In the One-Time Install/Upgrade Setup section, make sure No, I will click the FINISHED button now is selected and then review the information in the Important section. Then scroll to the bottom of the page and click Finished.

Important: Do not make any other configuration changes before you click Finished. You can make only configuration changes after you click Finished.

Next Steps

After you click Finished, you can safely make changes to the application configuration. See Configure an application that uses iApp Connector Template v3.0.4.

Upgrade an application from iApp Template v3.0.3 to iApp Template v3.0.4

The following sections explain how to upgrade an existing XC Bot Defense Standard Application on a BIG-IP from Template v3.0.3 to v3.0.4.

Important: You can only upgrade to template version 3.0.4 from v3.0.3. To upgrade from a template version older than 3.0.3 and maintain your existing configuration settings, you must first upgrade your existing iApp template to v3.0.3.

Important: To upgrade a group of XC Bot Defense Standard Applications (more than one application on the same BIG-IP with the same F5 Security API hostname) contact F5 Customer Support for upgrade assistance.

Import the v3.0.4 Template for an Existing Application

1. Log on to BIG-IP where your application is protected and hosted.
2. Click iApps > Templates > Import.
3. Click Overwrite Existing Templates.
4. Click Choose File and navigate to the location where you saved the template you downloaded from the Distributed Cloud Console.
5. Select the template you want to import and click Open.
6. Click Upload and OK to confirm.

Upgrade the Template for an Existing Application

1. Click Application Services > Applications and then click the name of the application you want to upgrade.

2. Click the Reconfigure tab.

3. In the Template section, click Change.

4. From the Template drop down menu, select f5.ibd.cs.

5. In the One-Time Install/Upgrade Setup section, make sure No, I will click the FINISHED button now is selected and then review the information in the Important section. Then scroll to the bottom of the page and click Finished.

   Important: Do not make any other configuration changes before you click Finished. You can only make configuration changes after you click Finished.

   

   Figure: iApp Connector One-Time Install/Upgrade screen

Next Steps

After you click Finished, you can safely make changes to the application configuration. See “Configure an application that uses iApp Connector Template v3.0.4.”

Configure an application that uses iApp Connector Template v3.0.4

The following instructions explain how to configure a new application that uses iApp Connector Template v3.0.4 or an existing application that has been upgraded from v3.0.3 to v3.0.4.

1. In the BIG-IP that hosts your applications, click iApps > Application Services > Applications.
2. From the list of applications, click the application you want to configure.
3. Select the Reconfigure tab.

The following sections explain how to configure each option in your application.

General Settings

1. Decide if you want to Activate Bypass Mode, which allows all HTTP traffic to bypass the Bot Defense processing engine. Only select Yes if you want to temporarily disable the Bot Defense service. For example, enable bypass mode if you suspect there is an issue with Bot Defense, such as too many false positive results.

2. Decide if you want to send all web form contents to the F5 XC Defense Engine API for analysis or if you want to send only telemetry data. You might decide to send only telemetry data (the default selection) if you must adhere to strict regulatory compliance rules, such as GDPR.

3. To see information about pattern and regular expression wildcard matching displayed in the user interface, select Yes from the drop-down menu. This information can be useful when you configure which client requests should be inspected by F5 XC Bot Defense.

   

   Figure: iApp Connector General Configuration screen

Mobile SDK Options

1. If you have mobile endpoints, in the Do you want to enable F5 XC Bot Defense Mobile SDK support, select Yes (supports F5 XC Mobile SDK for mobile apps).

2. Decide how you want Bot Defense to identify requests from your Mobile SDK Clients and to help distinguish between mobile and web traffic through the same virtual server. Choose either headers or body keywords:

   • Enter the header Name and Value and click Add. For example, for the header name, you might enter sample-mobile-app, and for the value you might enter true. You can specify multiple headers.
   • Enter keywords that appear in request bodies. To enter multiple keywords, use the following format, “keyword1|keyword2|keyword3”.

3. In the Mobile SDK Reload Header Name field, enter the Reload Header Name from the Distributed Cloud Console. This value you enter is included in the response message when Bot Defense blocks a request. To find the Reload Header Name:

   1. Log on to the Distributed Cloud Console. From the Dashboard page, click Mobile Base Configurations.
   2. Copy the Reload Header Name for the appropriate mobile base configuration.
   3. Enter the value in the Mobile SDK Reload Header Name field in the iApp template.
   

   Figure: iApp Connector Mobile SDK Options screen

JavaScript Injection Configuration

To protect web-based endpoints, decide if you want your BIG-IP to automatically insert the Bot Defense protection JavaScript into your application pages or if you want to add the JavaScript manually.

• If you want BIG-IP to insert the JavaScript, perform the following steps:

  1. From the BIG-IP Handles F5 Client JavaScript Injections drop-down menu, select Yes.

  2. Enter the path or URL where clients can access the F5 Client JavaScript to insert in your application.

     F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. Enter a simple path that starts with / or a complete URL such as https://example.com/customer1.js. The URL or path you choose cannot conflict with your existing JavaScript files.

  3. Select the location in the application pages where you want BIG-IP to insert the protection JavaScript. F5 recommends that you select After <head> so that the JavaScript is executed early. This helps to avoid conflicts with other scripts and allows time to for the protection JavaScript to be executed while the rest of page is rendered.

     Note: If you select After </title>, be sure your application pages have the title tag.

  4. To inject JavaScript into Telemetry data, in the Telemetry JavaScript Injection drop-down menu, select Enable. Otherwise, select Disable.

  5. If you enabled Telemetry JavaScript Injection, decide if you want to inject the JavaScript in the <Body> tag. If you select No, the JavaScript is inserted in the same location as the protection JavaScript.

  6. Specify whether want to inject the protection JavaScript only in specific webpages:

     • To inject JavaScript in specific webpages, in the Do you want to choose which pages are injected with protection Javascript drop-down menu, select Yes. Then enter the path for the pages where you want to inject the JavaScript and click Add.

       Note: Not all pages require JavaScript, but JavaScript must be inserted at all entry points, such as login forms.

     • To inject JavaScript in all pages, select No.

  7. To exclude the protection JavaScript injection from specific webpages, in the Do you want to avoid injecting F5 Client Javascript into certain pages drop-down menu, select Yes. Then enter the path for the page you want to exclude and click Add.

     

     Figure: iApp Connector JavaScript Injection Configuration screen

• To manually insert the JavaScript in your application, perform the following steps:

  Note: Not all webpages require JavaScript, but JavaScript must be inserted at all entry points, such as login forms.

  1. From the BIG-IP Handles F5 Client JavaScript Injections drop-down menu, select No.

  2. Enter the path or URL where clients can access the F5 Client JavaScript to insert in your application.

     F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. Enter a simple path that starts with / or a complete URL such as https://example.com/customer1.js. The URL or path you choose cannot conflict with your existing JavaScript files.

  3. If you require Manual JavaScript Insertion, add the following tags to one of the recommended locations:

     • Immediately after <head>
     • Immediately after </title>
     • Before <script> (first script tag on the page).

     Matcher Config JavaScript:

     <script type='text/javascript' src='INJECTION_PATH?matcher'></script>​

     I/O Hook JavaScript​:

     <script type='text/javascript' src='INJECTION_PATH?cache'></script>​

     Async Telemetry JavaScript​:

     <script type='text/javascript' src='INJECTION_PATH?async' async></script>​

Replace INJECTION PATH with the value you specified for Web Client JavaScript Path.

F5 XC Bot Defense Protected Endpoints Configuration

Specify pages and sources on the website that should be protected by Bot Defense.

1. The Mitigation Handler field is informational only. You do not need to make any changes to this field.

2. If you previously enabled F5 XC Bot Defense Mobile SDK support, select the type of client requests that should be inspected and then mitigated by F5 XC Bot Defense: Web, MSDK (Mobile Client), or Both (Web and Mobile).

   Note: If you select Both, you must provide a header which distinguishes Mobile requests from Web. For example:

   • User-Agent: Android 10; MyApp/1.0
   • User-Agent: Android 9; MyApp/2.0
   • X-App-Version: 4.1
   • X-App-Version: 4.3

   The specified header value can use a wildcard (*) to match a substring.

3. In the Host field, enter the host domain of the protected endpoint. For example, enter identity. <your domain>.com.

4. In the Path field, enter the path to the endpoint. The path must meet the following requirements:

   • Only uses lowercase letters.
   • Starts with ‘/’. For example, enter /login/.
   • Can use glob patterns: * ? [ ].
   • Closes any open bracket [ with ].
   • Brackets must include only valid URL characters.
   • Does not specify /* as a protected URL.
   • Uses / to protect the root.

   For example:

   • Example 1: /application/version[0-9]/login
   • Example 2: /myapp/service/*
   • Example 3: /*/login.aspx
   • Example 4: /api/*/connection/*/*
   • Example 5: /api/connection/[a-zA-Z0-9_]*/set*

5. (Optional) In the Query field, if you want to protect specific sections of a page, enter the criteria for the section you want to protect.

   For example, if the query string of a URI you want to protect is <yourdomain>/account.do/issue? account=moneytransfer, enter the parameter name and parameter value ‘account=moneytransfer’ to protect the “moneytransfer” function.

   When you enter a Query parameter, the Bot Defense service looks at the Path and Query values. The Query field is regex matched.

6. Choose the HTTP Methods are monitored on this endpoint. You must set at least one of the options to Yes. HTTP requests are not routed if no methods are set to Yes.

   Select Yes or No for each of the following methods:

   • ANY: Select Yes to protect the path with any type of method. Select No to limit protection to only certain methods.

   • GET: Select Yes to protect the path when it has a GET method.

   • POST: Select Yes to protect the path when it has a POST method.

   • PUT: Select Yes to protect the path when it has a PUT method.

   Important: If you choose to protect all pages and endpoints (/*), F5 recommends that you select specific HTTP methods to monitor and that you do not select the ANY option. Protecting all HTTP methods for all pages can adversely impact performance.

7. In the Action drop-down menu, select the mitigation action you want to take for this endpoint if Bot Defense detects automation:

   • Continue (request continues to origin). For reporting purposes, you can optionally add a header to capture traffic that is going to the origin. You provide the header name in the Define Mitigation Actions section.

     Important: When you initially deploy the iApp connector, F5 recommends that you set mitigation action to Continue for the first 24-48 hours and then monitor the system to confirm that it is functioning properly.

   • Redirect. The Bot is sent to a different page. You provide the URL where the Bot is redirected later in the Define Mitigation Actions section. The redirect must go to:
     • An absolute URL, for example, https://acme.com/redirect.html
     • A domain that you own.
   • Block. The Bot is presented with a message that it has been blocked. You provide the Response Code and Body of the response message later in the Define Mitigation Actions section.
   • Drop. This is not a valid selection. If you select Drop, Bot Defense defaults to Block.

   When you select mitigation actions, you must be aware of the following important information:

   Client Type	Valid Actions	Additional Information
   MSDK (mobile)	Continue, Block	-- Redirect and Drop are visible but are not valid actions. If you select an invalid action, the system defaults to Block.
   		-- You must specify a header, otherwise the endpoint is treated as a web endpoint. For information, see “Define Mitigation Actions.”
   Web Client	Continue, Block, Redirect	Drop is visible but is not a valid action. If you select Drop, Bot Defense defaults to Block.
   Both (mobile and web)		If you select Both (web and mobile clients):
   		-- Drop is not a valid action. If you select Drop, Bot Defense defaults to Block.
   		-- You can select mitigation actions for each client type.
   		-- In the MSDK Req ID drop-down menu (see below), you must select either Hdrs or Body. Otherwise, Bot Defense treats the endpoint as a web endpoint.
   		-- You must specify a header, otherwise Bot Defense treats the endpoint as a web endpoint. For information, see Define Mitigation Actions.

8. In the MSDK Req ID drop-down menu, specify how you want Bot Defense to identity mobile endpoints.

   • If your endpoint type is MSDK (mobile), select Hdrs or Body. Otherwise, Bot Defense treats the endpoint as a web endpoint by default.
   • If your endpoint type is Both (web and mobile), select Hdrs or Body. Otherwise, Bot Defense treats the endpoints as a web endpoint by default.
   • If your endpoint type is Web, then you do not need to choose a setting. This field is ignored for web endpoints.

9. Specify whether you want to ignore letter case while matching request paths. If you select Yes, letter case is ignored when matching the path of a request URL. If you select No then matching is case sensitive.

   

   Figure: iApp Connector Protected Endpoint Configuration screen

   Select Add to add additional protected endpoints.

   After you finish adding endpoints, all protected endpoints are displayed in a table. You can modify or delete endpoints.

Web-Scraping Protection Endpoints

Configure web scraping protection for documents and pages on a web site that is accessible by GET requests without visiting the main page, for example, from a link on social media, from an email or from a saved bookmark. This direct access to resources prevents Bot Defense from inserting the protection JavaScript. When you configure an endpoint for web scraping, Bot Defense displays an interstitial page that is transparent to the user but that allows it to collect telemetry data about the requests.

1. The Mitigation Handler field is informational only. You do not need to make any changes to this field.

2. In the Host field, enter the host domain of the protected endpoint.

3. In the Path field, enter the path to the endpoint. The path must meet the following requirements:

   • Only uses lowercase letters.
   • Starts with ‘/’. For example, enter /login/.
   • Can use glob patterns: * ? [ ].
   • Closes any open bracket [ with ].
   • Brackets must include only valid URL characters.
   • Does not specify /* as a protected URL.
   • Uses / to protect the root.

   For example:

   • Example 1: /application/version[0-9]/login
   • Example 2: /myapp/service/*
   • Example 3: /*/login.aspx
   • Example 4: /api/*/connection/*/*
   • Example 5: /api/connection/[a-zA-Z0-9_]*/set*

4. (Optional) In the Query field, if you want to protect specific sections of a page, enter the criteria for the section you want to protect.

   For example, if the query string of a URI you want to protect is <yourdomain>/account.do/issue? account=moneytransfer, enter the parameter name and parameter value account=moneytransfer to protect the moneytransfer function.

   When you enter a Query parameter, the Bot Defense service looks at the Path and Query values. The Query field is regex matched.

5. In the Action drop-down menu, select the mitigation action you want to take for this endpoint if Bot Defense detects automation:

   • Continue (request continues to origin). For reporting purposes, you can optionally add a header to capture traffic that is going to the origin. You provide the header name in the Define Mitigation Actions section.

     Important: When you initially deploy the iApp connector, F5 recommends that you set mitigation action to Continue for the first 24-48 hours and then monitor the system to confirm that it is functioning properly.

   • Redirect. The Bot is sent to a different page. You provide URL where the Bot is redirected later in the Define Mitigation Actions section. The redirect must go to:
     • An absolute URL, for example, “https://acme.com/redirect.html”.
     • A domain that you own.
   • Block. The Bot is presented with a message that it has been blocked. You provide the Response Code and Body of the response message later in the Define Mitigation Actions section.
   • Drop. This is not a valid selection. If you select Drop, Bot Defense defaults to Block.

6. Specify whether you want to ignore letter case while matching request paths. If you select Yes, letter case is ignored when matching the path of a request URL. If you select No then matching is case sensitive.

   

   Figure: iApp Connector Web Scraping Configuration screen

Define Mitigation Actions

1. In the Specify redirect path field, enter the URL to which you want to redirect Bots when you select Redirect as a mitigation action.

2. In the Specify ‘Block’ response fields, enter a Response Code and then enter the body of the response message that you want to send to malicious traffic if you specify Block as a mitigation action. You must include the correct HTML tags in the body of the response.

3. When you select Continue as a mitigation response, specify whether you want to add a header to requests that provides F5 XC Bot Defense information. If you select Yes, add an F5 XC Bot Defense info header to requests sent to origin, then specify the header.

   

   Figure: iApp Connector Define Mitigation Actions screen

Allow-listed Entities

Optionally, create an Allow List that allows requests to reach the origin destination without being evaluated by Bot Defense. You are not charged for request that are not evaluated by the Bot Defense Engine. You can create a list by IP Address or by request headers.

1. To specify an IP Address Allowlist, in the IP field, enter the IP addresses you want to allow. Click Add after you enter each IP address.

2. Specify if you want to Use advanced header matching.

   • If you select Yes, Bot Defense uses regex to match the header name and value.
   • If you select No, then header names are matched exactly as you specify and header values are matches using simple * and ? wildcards.

   Header name matching is always case insensitive.

3. To specify an HTTP Header Allowlist, enter a Name and Value for each header you want to allow. Click Add after you enter each name and value.

   

   Figure: iApp Connector Allow List screen

Application Virtual Servers

In the Application Virtual Servers section, select the application virtual servers that you want to assign to your iApp. You iApp does not run if it is not assigned to at least one virtual server.

Note: You create virtual servers in BIG-IP. For information, see your BIG-IP documentation.

Know the following about selecting a virtual server:

• The virtual server you select must have an HTTP profile attached to it.
• The virtual server you select must have a default pool attached to it.
• F5 recommends that each protected server have a Client SSL profile and SNAT profile, but these are not required.

Note: If you have deployed an application on an iApp using a virtual server, you cannot deploy Bot Defense on an iApp using the same virtual server. You must choose a different virtual server.

F5 XC Defense Engine API Service Settings.

Define the API settings that allow you to route traffic to the Bot Defense engine and define pools.

1. The Application ID is automatically populated in the template.

2. Enter a Timeout value for API response. The default is 700 milliseconds. If the API response exceeds the configured value, then the request is allowed to continue without being checked for automation.

3. Enter the hostname of the F5 XC Web Defense Engine API service.

4. Enter the hostname of the F5 XC Mobile SDK Defense Engine API service.

5. Enter the route domain that is used to reach the F5 XD Defense Engine API servers. The default is route domain 0. For information about route domains, see: https://techdocs.f5.com/en-us/bigip-14-1-0/big-ip-tmos-routing-administration-14-1-0/route-domains.html.

6. Specify when F5 XC Defense Engine API server pools are forcibly refreshed.

7. Specify the source addresses that outbound connections to F5 XC Defense Engine API servers must use:

   • The default selection is Use SNAT Automap.
   • If you select, Create a SNAT pool, enter the list of APIs in the pool. After you enter each IP address, click Add.
   • If you select, Use an existing SNAT pool, select the Existing SNAT Pool from the drop-down menu.

   For information about SNAT Automap and SNAT pools, see: https://support.f5.com/csp/article/K7820.

8. Specify the Server SSL Profile that you want to use for outbound connections to F5 XD Defense Engine API servers.

9. To require that F5 XC Defense Engine API requests are routed through a proxy, select Yes, use an (explicit) HTTP proxy to connect to API servers, then do the following:

   • If the HTTP proxy requires basic authorization credentials, select Yes, send username and password in Proxy-Authentication header and then enter the Username and Password.
   • Select the HTTP proxy pool that you want to use. Perform one of the following tasks:
     • Select Create a new pool using a single proxy hostname and then enter the fully-qualified domain name (FQDN) and Port number of the new pool.
     • Select Create a new pool from one or more proxy IP addresses and then enter the proxy IP addresses and Port numbers you want to use. Click Add after each IP and Port number.
     • Select Choose an existing proxy pool and then select a proxy pool from the drop-down menu.
   

   Figure: iApp connector F5 XC Defense Engine API Service Settings screen

F5 XC Defense Engine API Service(s) Health Monitor

If you do not require F5 XC Defense Engine API requests to go through a proxy, you can configure a health monitor to monitor the availability of your API service on both web and mobile clusters.

Health monitors display one of the following statuses for each cluster:

• Available: The monitor is successfully monitoring the pool member.
• Unknown: The monitor is unable to determine if the pool member is up or down.
• Down: The monitor has determined that the pool member is currently down.

For detailed status information, see your BIG-IP Local Traffic Manager documentation.

To configure the health monitor, decide if you want to use the HTTP monitor or default monitor. The default monitor is not as sensitive as the HTTP monitor. The HTTP monitor is more sensitive but does not use TLS.

If you select Prefer HTTP monitor, review the following settings. You should not need to change the default settings.

1. Review which TCP port the HTTP monitor should query.

2. Review which HTTP path the HTTP monitor should query.

3. Review what HTTP status code means that the service is unavailable.

   

   Figure: iApp connector health monitor screen

Advanced Features

1. Enter the IP address that the F5 XC Connector should use to contact internal virtual servers.

2. In the field, Do you want to update the HTTP X-Forwarded-For header, decide if you want BIG-IP to replace X-Forwarded-For IP address at the security perimeter.

3. Specify how you want to handle client requests with Expect: 100 header. Select Send prompt 100-Continue if you want BIG-IP to wait for larger requests to complete rather than time out.

4. Decide if you want to use an HSL log publisher or use the BIG-IP syslogd. If you choose to use the HSL log publisher, from the HSL log publisher drop-down menu, select the publisher you want to use.

5. Select a logging level to determine the verbosity of the logging data this is collected:

   • Error – Includes connection and network errors. Does not include transaction errors.
   • Warning – Includes information about malicious transactions. The Warning level also includes all Error-level log data.
   • Info – Includes information about both human and malicious transactions. The Info level also includes all Warning-level log data.
   • Debug – Full transaction logs that include all available log data, including all data from Error, Warning and Info levels.

     Note: Under normal circumstances, you can set a lower logging level, such as Error or Warning. If you suspect that an incident is occurring, you can change logging levels to Info or Debug to help your investigation and defense, and then change it back later.

6. In the field, Which syslog ‘facility’ do you want to send log messages to, decide where you want the syslog file to be written.

7. In the field, Use what log-message format, enter the log format you want to use for syslog.

8. In the field, What request headers (if any) should request log messages include, enter a Header name. The header name can be exact or regex.

   

   Figure: iApp connector advanced features screen

Save the application

When you finish making configuration changes, double-check your configuration settings and click Finished.

Delete an iApp Application

Deleting an iApp application is two-step process. First you must run a cleanup process. Then you can safely delete the iApp application. Note that deleting an iApp application removes all configuration information for the application.

1. In the BIG-IP that hosts your applications, click iApps > Application Services > Applications.
2. From the list of applications, click the application you want to delete.
3. Select the Reconfigure tab.
4. In the General section, select Yes to Clean Before Deletion. This removes or restores all the BIG-IP configuration components which were added/modified by the Bot Defense iApp template that are not automatically restored when you delete the iApp Application
5. Then scroll to the bottom of the page and click Finished.
6. When the cleanup process finishes, from the list of applications, click the application you want to delete.
7. Click Delete.

---

Enable Bot Defense on BIG-IP v17.0 or later

To enable Bot Defense on BIG-IP v17.0 or later you must first add BIG-IP as a protected application in Bot Defense and then configure BIG-IP to send requests to be evaluated by Bot Defense.

Prerequisites

• You must have an active F5 Distributed Cloud account. If you do not have an account, see: Create a Distributed Cloud Console Account.
• You must enable Bot Defense in the Distributed Cloud Console. See: Enable Bot Defense.
• You must have BIG-IP v17.0 or later installed and configured. If you have BIG-IP v14.0-16.0, see: Enable Bot Defense on BIG-IP v14-16 (iApp Connector).

Add BIG-IP v17.0 to Bot Defense

The following task explains how to add BIG-IP v17.0 or later as a protected application in Bot Defense.

1. Log on to the Distributed Cloud Console. From the Dashboard page, click Bot Defense.
2. Verify that you are in the correct namespace. For information about namespaces, see https://flatrender.tora.reviews/docs/ves-concepts/core-concepts#namespaces.
3. Click Manage > Applications and then click Add Application.
4. Add a Name and Description for the protected application.
5. Select the Application Region where the origin server for the new protected application resides: US, EU, Asia.
6. From the Connector Type drop-down list, select F5 BIG-IP (v17.0 or greater).
7. Click Save and Exit.

Next Steps

Copy information from the protected application you just added in the Distributed Cloud Console. You use this information to configure Bot Defense on BIG-IP v17.0 or later. For information, see Copy required information from your protected application.

Copy required information from your protected application

The following task explains how to copy information from your new protected application that you need to configure Bot Defense on BIG-IP v17.0 or later.

1. In the Distributed Cloud Console, from the Bot Defense page, click Manage > Applications.
2. From the Actions column, click the Action menu (…) next to the protected application you just added for BIG-IP.
3. From the Action menu (…), click the following options and save the copied information in a location you can access later:
   • Copy App ID
   • Copy Tenant ID
   • Copy API Key
   • Copy Web API Hostname
   • Copy Mobile API Hostname
   • Copy Telemetry Header Prefix
   • Copy Dashboard Link

Next Steps

Log on to your BIG-IP v17.0 or later to continue configuring Bot Defense. For information, see one of the following topics:

• BIG-IP v17.0: https://techdocs.f5.com/en-us/bigip-17-0-0/big-ip-saas-bot-defense.html.
• BIG-IP v17.1 and later: https://techdocs.f5.com/en-us/bigip-17-1-0/big-ip-saas-bot-defense.html.

---

Enable Bot Defense on Cloudflare

To enable F5 Bot Defense on Cloudflare, you must complete the following high-level tasks:

1. Configure Bot Defense Cloudflare connector settings.
2. Download a configuration file and template from the Distributed Cloud Console.
3. Create a Cloudflare Worker and deploy the connector in Cloudflare.

Prerequisites

• You must have a functioning Cloudflare environment.
• You must know how to configure and maintain your Cloudflare environment, including how to create and configure Cloudflare Workers. See your Cloudflare documentation for information.

Configure Bot Defense Cloudflare Connector Settings.

To enable Bot Defense on Cloudflare, you must first configure the Cloudflare connector in the Distributed Cloud Console.

1. On the Distributed Cloud Console Dashboard, click Bot Defense.

2. Click Manage > Applications > Add Application. If no applications exist, you are prompted to add a protected application.

3. Add a Name and Description for the new application.

   The name must be unique in the namespace and must follow DNS-1035 format.

4. Select an Application Region (US, EU, or Asia). This is the region where the origin server for the application is located.

5. From the Connector Type drop-down list, select Cloudflare and then select Configure.

   

   Figure: Connector Type

Protected Endpoints

Configure the endpoints you want to protect with Bot Defense.

1. In the Protected Endpoints section, click Configure and then click Add Item.

2. Enter a Name and Description for the new endpoint.

3. Specify the Domain Matcher. The same Cloudflare website can be served from multiple domains. You can choose any domain or specify a specific host value. Enter an exact value, a suffix value, or a regex value.

4. Specify the Path to the endpoint. For example, enter /login. The path can include the wildcards, * and ?.

5. If you want Bot Defense to ignore capitalization when searching paths, select Case insensitive.

   

   Figure: Case Sensitivity Setting

6. (Optional) In the Query field, if you want to protect specific sections of a page, enter the criteria for the section you want to protect.

   For example, if the query string of a URI you want to protect is:

   <yourdomain>/account.do/issue? account=moneytransfer, enter the parameter name and parameter value account=moneytransfer to protect the moneytransfer function.

   When you enter criteria in the Query field, Bot Defense looks at the Query parameters in addition to the Path. The Query field is regex matched.

7. Choose the HTTP Methods that are monitored on this endpoint by Bot Defense:

   • GET (XHR/Fetch)
   • POST
   • PUT

   You can select multiple methods.

8. Select the type of client that accesses this endpoint (Web Client, Mobile Client, or Web and Mobile Client).

   Note: For endpoints that receive requests from both web and mobile clients, F5 recommends that you add a single endpoint and select Web and Mobile Client, rather than two separate endpoints for Web Client and Mobile Client.

9. Select the mitigation action for this endpoint when automation is detected. If you selected the Web and Mobile Client type, select a mitigation action for each type:

   • Continue. This allows traffic to continue to the origin. You can choose to add a header that enables you to monitor traffic in reporting and analytics dashboards. You can change the header name in the Header Name for Continue Mitigation Action field in the More Options section.

   • Redirect. This redirects automated traffic to a different page. You provide the appropriate Status Code and URI where you want to redirect the bot. Use this option to deceive bots into thinking their request successfully went through. You can also redirect to a page with more information for human users that may have been incorrectly redirected.

   • Block. This blocks automated traffic from proceeding to the origin. You can customize the Status Code, Content Type, and Body of the response message.

     Note: Mobile clients only allow Continue and Block. If you select Web and Mobile Client, you can select mitigation actions for each client type.

     

     Figure: Client Type

   Note: If you select Web and Mobile Client, you must enter a Mobile Request Identifier Header when you enable Mobile SDK Settings. For instructions, see Mobile Settings.

10. When you finish configuring the endpoint, click Apply.

11. To add an additional endpoint, click Add Item and repeat steps 2-10.

12. When you finish adding endpoints, click Apply.

Web Client JavaScript Settings

After you add web-protected endpoints, you must configure how the Bot Defense JavaScript is injected into the web pages you want to protect.

Note: If you only protect mobile endpoints, then select Disable JavaScript Insertion and go to Mobile Settings.

Note: To manually insert the Bot Defense Javascript, see Manual JavaScript Insertion

1. From the Web Client JavaScript Insertion Settings drop-down list, select Specify JavaScript Insertion Rules and click Configure.
2. Add the Web Client JavaScript Path. The web client fetches the Bot Defense JavaScript from this path.

F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. Enter a simple path that starts with / or a complete URL such as https://example.com/customer1.js. The URL or path you choose cannot conflict with your existing JavaScript files.

1. From the JavaScript Location drop-down menu, choose the location where you want to insert the Bot Defense JavaScript in the application pages:

   • After <head> tag
   • After </title> tag
   • Before <script> tag

   F5 recommends that you select After <head> so that the Bot Defense JavaScript is executed early. This allows time for the Bot Defense JavaScript to be fetched and executed while the rest of page is rendered.

   Note: If you select After </title>, be sure your application pages have the <title> tag.

2. In the JavaScript Insertion Paths section, click Add Item.

   • Enter a Name, Description, Domain Matcher, and Path for each page in your application where you want to insert the Bot Defense JavaScript.

     Note: Be sure to select paths to HTML pages that end users are likely to visit before they browse to any protected endpoint. In Bot Defense, these are called “entry pages.”

     Note: F5 recommends that you use wildcards to select JavaScript insertion paths for HTML pages to which end users are likely to go, such as /index.htm and /login/*.

     JavaScript insertion path examples:

     • /login/*
     • /catalog

   • Click Apply. The JavaScript Insertion Path is added to the table. Click Add Item to add additional JavaScript Insertion Paths.

3. (Optional) To exclude the Bot Defense JavaScript from specific web pages, in the JavaScript Exclude Paths section, click Add Item.

   • Enter a Name, Description, Domain Matcher, and Path to exclude.
   • Click Apply. This adds an item to the table. Click Add Item to add additional exclusion paths.

   Note: F5 recommends that you carefully add JavaScript insertion paths to minimize the number of false positive results.

   JavaScript exclusion path examples:

   • /login/images
   • /catalog/soldout/*

4. When you finish configuring JavaScript Insertion Rules, click Apply.

Manual JavaScript Insertion

Important: F5 recommends that you allow Bot Defense to automatically insert the Bot Defense JavaScript in your application pages. Only use manual insertion if it is required for Bot Defense to work in your IT environment.

To manually insert the Bot Defense JavaScript in your application pages:

1. In the Web Client JavaScript Settings section, from the Web Client JavaScript Insertions drop-down menu, select Disable JavaScript Insertion.

2. Manually add the JavaScript tags below to one of the following recommended locations:

   • Immediately After <Head>
   • Immediately After </title>
   • Before <script> (first script tag on the page).

   Endpoint Matcher JavaScript:

   <script type='text/javascript' src='INJECTION_PATH?matcher'></script>​

   I/O Hook JavaScript​:

   <script type='text/javascript' src='INJECTION_PATH?cache'></script>​

   Telemetry JavaScript​:

   <script type='text/javascript' src='INJECTION_PATH?async' async></script>​

   Replace INJECTION PATH with the value you specified for Web Client JavaScript Path.

   

   Figure: Manual Javascript insertion

Mobile Settings

Important: Before you configure mobile settings, see Protect Mobile Endpoints for important best practices, required configuration, and information about integrating the F5 Mobile SDK with your mobile endpoints.

1. If you added mobile endpoints to your configuration, select Enable Mobile SDK.

2. If you selected Web and Mobile Client as your client type during endpoint configuration, add a mobile header to distinguish the endpoints. This is not required if you selected only Web Client or Mobile Client.

   1. Enable Show Advanced Fields.
   2. In the Mobile Request Identifier Headers section, click Add Item.
      

      Figure: Mobile Settings

3. Enter a Name and the corresponding Value. Specify if the value must be exact or if it can be regex.

   

   Figure: Header Configuration

4. Click Apply.

More Options

Important: Enable Show Advanced Fields to see all options.

Trusted Client Rules (Allow List)

Trusted Client Rules add headers and IPv4 addresses to an Allow List. Incoming HTTP requests from the allowed IPs or requests that contain allowed header name/value pairs bypass Bot Defense engine for evaluation and proceed directly to the origin. There is no logging for pages on the Allow List.

1. In the Trusted Client Rules section, click Configure and then click Add Item.

2. Enter a Name and specify the Client Identifier. Choose either IP Prefix or HTTP Headers.

   • For IP Prefix, enter a string.
   • For HTTP Header, click Add Item, enter a Name and Value and then click Apply.

   Note: You can add multiple headers to the table at the same time. You must add IP addresses individually.

   

   Figure: Trusted Client Rules

3. Click Apply when you finish adding Trusted Client Rules and then click Apply again to configure More Options.

Set Logging Level

1. In the More Options section, click Show Advanced Fields.
2. Select one of the following logging levels to determine the verbosity of the logging data collected by the system:
   • Error – Includes connection and network errors. Does not include transaction errors.
   • Warning – Includes information about malicious transactions. The Warning level also includes all Error-level log information.
   • Informational – Includes information about both human and malicious transactions. The Informational level also includes all Warning-level log information.
   • Debug – Full transaction logs that include all available log data, including all data from Error, Warning and Informational levels.

Define Continue Mitigation Header

In the More Options section, click Show Advanced Fields. The Header Name for Continue Mitigation Action field is the header that is added to a request when automation is detected and you have set the mitigation action to Continue. You made this selection when you configured your protected endpoints. For information, see Protected Endpoints.

Timeout and Body Sample Size Limit

1. In the More Options section, click Show Advanced Fields.
2. Specify the Timeout value. This value defines the maximum wait time for the Bot Defense engine to run the analysis and return the inference. If the timeout is exceeded, the request continues to the origin. By default, the field is set to 700 ms based on performance efficiency.

Download the Cloudflare Connector Configuration and Worker Files

When you finish configuring the Cloudflare connector in the Distributed Cloud Console, you must download Worker and configuration files that you use to deploy the connector in Cloudflare.

1. In the Bot Defense dashboard, click Manage > Applications.

2. From the Actions column in the list of applications, next to the application you just added, click the Action Menu … .

   

   Figure: Action Menu

3. Click Download Config File and save the <app_name>.json file in a location you can access later.

4. Click Download Worker File and save the <app_name>.js file in a location you can access later.

Note: <app_name> is the name of the application you added to Bot Defense earlier. You can decide to save the .js and .json files with different names.

Configure the Connector in Cloudflare

Important: In Cloudflare, DNS must be in proxy mode.

Important: In Cloudflare, check your worker rate-limiting settings. Depending on your traffic volume, you might need to disable rate limiting. To disable rate limiting, contact Cloudflare support.

To deploy the Bot Defense Connector in Cloudflare, you must create a new Cloudflare Worker and then insert the connector code in the Worker.

1. In Cloudflare, create a new Worker to deploy the Bot Defense connector.
2. Navigate to the Worker you created.
3. Edit the Worker so you can replace the default Worker code with the code from the configuration files that you downloaded from the Distributed Cloud Console.
4. On the Worker edit page, clear the default Worker code and enter the entire contents of the <app_name>.js file you downloaded.
5. After you enter the code from the .js file, on the line const CONFIG = “__Config__”, replace “__Config__” (including the quotes) with the entire contents of the .json file that you downloaded from the Distributed Cloud Console.
6. Assign a route to the Worker you created for the Bot Defense service. Enter a wildcard or /* so the route matches all HTML pages and endpoints.
7. Save and deploy your changes in Cloudflare.

Confirm that Bot Defense is Functioning Properly

Perform the following steps to help ensure that Bot Defense is properly configured and evaluating traffic correctly.

• F5 recommends that you enable stream logging in Cloudflare to confirm that requests are being evaluated by Bot Defense correctly.
• On your website, inspect a protected endpoint to confirm that Bot Defense inserted the Bot Defense JavaScript.
• Review the Bot Defense dashboard to see the types of traffic identified by Bot Defense

---

Enable Bot Defense on Adobe Commerce Cloud (Magento)

Prerequisites

• You must have an active F5 Distributed Cloud account. If you do not have an account, see: Create a Distributed Cloud Console Account.
• You must enable Bot Defense in the Distributed Cloud Console. See: Enable Bot Defense.
• You must have Adobe Commerce Cloud (Magento) configured.
• You must have sufficient privileges in Adobe Commerce Cloud to configure Bot Defense.

Add Adobe Commerce Cloud to Bot Defense

The following task explains how to add Adobe Commerce Cloud as a protected application in Bot Defense.

1. Log on to the Distributed Cloud Console. From the Dashboard page, click Bot Defense.
2. Verify that you are in the correct namespace. For information about namespaces, see: https://flatrender.tora.reviews/docs/ves-concepts/core-concepts#namespaces.
3. Click Manage > Applications and then click Add Application.
4. Add a Name and Description for the protected application.
5. Select the Application Region where the origin server for the new protected application resides: US, EU or Asia.
6. From the Connector Type drop-down menu, select Adobe Commerce.
7. Click Save and Exit.

Next Steps

Copy information from your protected application in the Distributed Cloud Console that you need to configure the F5_DistributedCloudConnector extension in Adobe Commerce Cloud. For information, see Copy required information from your protected application.

Copy required information from your protected application

The following task explains how to copy information from your new protected application that you need to configure the F5_DistributedCloudConnector extension.

1. In the Distributed Cloud Console, from the Bot Defense page, click Manage > Applications.
2. From the Actions column, click the Action menu (…) next to the protected application you just added for Adobe Commerce Cloud.
3. From the drop-down menu, click the following options and save the copied information in a location you can access later:
   • Copy App ID
   • Copy Tenant ID
   • Copy API Key
   • Copy API Hostname
   • Copy Telemetry Header Prefix

Next Steps

Download the F5_DistributedCloudConnector extension from the Magento Marketplace and install it. For information, see: Install the F5_DistributedCloudConnector extension.

Install the F5_DistributedCloudConnector extension

1. To download the F5_DistributedCloudConnector extension from the Magento Marketplace, go to https://marketplace.magento.com/f5-distributed-cloud-connector.html. Or, from the Magento Marketplace, search for "F5 Distributed Cloud Services."
2. Run composer require f5/distributed_cloud_connector:VERSION (for example, f5/distributed_cloud_connector:1.0.2). You can find the extension version in the composer.json file.
3. Run php bin/magento set:up.
4. Run php bin/magento s:d:c.
5. Run php bin/magento setup:static-content:deploy. If Magento is in developer mode, add an -f argument. Developer mode is not officially supported in the extension.

Next Steps

Use the information you just copied to configure the F5_DistributedCloudConnector extension. See: Configure the F5_DistributedCloudConnector extension.

Configure the F5_DistributedCloudConnector extension

To configure the F5_DistributedCloudConnector extension, in Adobe Commerce Cloud, go to Admin Panel > Stores > Configuration > F5® DISTRIBUTED CLOUD SERVICES.

Configuration modules include:

• Bot Defense
• Account Protection
• Authentication Intelligence

To enable the Bot Defense module, configure the following sections:

• General
• JS Insertion
• Login Protection
• Protected Endpoints
• Web Scraping
• Allow List

General

Note: To configure some of the options in this section, you need information that you copied from your protected application. If you have not yet copied that information, see Copy required information from your protected application.

Configure the following options:

• Enable Service: Enable/disable the module.
• Mode: Select one of the following options:
  • Enterprise: The dedicated mode of usage where the “Application ID” and “Tenant ID” fields are not required. If you purchased the Advanced edition of Bot Defense, select Enterprise.
  • Standard: The multi-tenant mode of operation. If you purchased the Standard edition of Bot Defense, select Standard.

Choose the mode based on the F5 Distributed Cloud plan that you have.

• API Hostname: Enter the API Hostname value that you copied from the protected application you added in the Distributed Cloud Console.
• Backend API path: The path to the Bot Defense script on the website backend. F5 recommends that you enter api/v1/decision for this value.
• API Key: The key used for authentication of the API calls to the F5 system. Enter the API Key value that you copied from the protected application you added in the Distributed Cloud Console.
• Telemetry Header Prefix: Enter the Telemetry Header Prefix value that you copied from the protected application you added in the Distributed Cloud Console.
• Application ID: Enter the App ID value that you copied from the protected application you added in the Distributed Cloud Console. Note that this field is only available when you select Standard mode.
• Tenant ID: Enter the Tenant ID value that you copied from the protected application you added in the Distributed Cloud Console. Note that this field is only available when you select Standard mode.
• Timeout API response: The time (in milliseconds) that the module waits for a response from the F5 server. After that, the request is processed by the Adobe Commerce backend. The default is 700.
• Source for Client IP address: Decide how Bot Defense gathers your client IP address:
  • Connecting IP: From your connection information.
  • X-forwarded-For: From the X-forwarded-For header.
  • Custom: From a custom header name that you define.
    • Custom Ip address source: The custom header name for getting your IP address. In the configured header, the first character of each word must be upper case.
• Enable Debug: Enable this to record requests and responses to/from the F5 service in the log file on the website server.

JS Insertion

Configure the following options to determine how Bot Defense inserts JavaScript tags in your application.

• JS Path: Enter an absolute path or a relative path to the JavaScript tags:

  • Absolute example: https://<FQDN+JS_location>, such as https://www.foo.com/abc.js.

    If you enter an absolute path, verify that the JavaScript requests are routed to the F5 Bot Defense service.

  • Relative example: </JS_location>, such as /abc.js.

• Insert JS option: Specify where in the page to add the JavaScript tags:

  • Before <script>
  • After </title>
  • After <head>

  F5 recommends that you select After <head> so that the Bot Defense JavaScript is executed early. This allows time to fetch and execute the Bot Defense JavaScript while the rest of page is rendered.

Note: If you select After </title>, be sure your application pages have the <title> tag.

• JavaScript load mode: Select the load mode of the JavaScript on the page:

  • Async with caching
  • Async with no caching
  • Sync with caching
  • Async with caching and defer XHR

• Insert JS to specific web pages: Displays the Specific pages list, which lists the pages in which Bot Defense should insert JavaScript tags.

  • If you select Yes, the Specific pages list displays.
    • Enter only the path to the page, such as /about-us.
    • Enter each page on a new line.
    • You can use wildcards used for page path definitions, such as *, and so on.
    • To insert JavaScript tags on all pages, enter only an asterisk (*).

  If this field is empty, Bot Defense does not insert JavaScript tags in any pages.

  • If you select No, the Specific page list field is hidden and JavaScript tags are inserted in all available pages that are not defined in the Excluded pages list field.

• Exclude JS from specific web pages: Displays the Excluded pages list, which lists all the pages in which Bot Defense must not insert JavaScript tags.

  • If you select Yes, the Excluded pages list displays.
    • Enter the path to the page, such as /about-us.
    • Enter each page on a new line.
    • You can use wildcards for page path definitions, such as *, and so on.
  • If you select No, the Excluded pages list field is hidden and JavaScript tags are inserted according to the configuration in Insert JS to specific web pages.

Login Protection

Configure the following options to protect your login pages.

• Protection type: Select one of the following protection types:
  • Disable: Disables login protection.
  • Collect txn: Customer verification is performed after sending the login request to the origin destination.
  • Ignore txn: Customer verification is performed right after clicking the Login button on the storefront, but before the Login request is performed to the origin destination.
• Login Url: Defines the login action URL that should be protected by Bot Defense. By default, this is set to /customer/account/loginpost*, which is used by the Adobe Commerce Cloud platform. You only need to update this field if you use a non-default login URL on your website.
• Mitigation: Choose one of the following actions when Bot Defense detects automated traffic:
  • Continue: The bot is allowed to visit the destination page but is flagged by the header defined in the Mitigation Continue header field.
  • Block: The bot is blocked from reaching the destination page. It is routed to a blank page with the content defined in the Blocked Response Body field and the response code defined in the Blocked Response Code field.
  • Redirect: The bot is redirected to the path defined in the Mitigation Redirect path field.

Protected Endpoints

Configure the following options in the Protected Endpoints section to define pages and sources on the website that you want to protect with Bot Defense.

• URL endpoint: Enter the path to the page or action that should be protected by Bot Defense. Use wildcards to define complex URLs.
• Method: Enter the type of HTTP methods that Bot Defense monitors on this endpoint:
  • GET XHR
  • POST
  • PUT
• Mitigation: Select the mitigation action you want to take for this endpoint if Bot Defense detects automation:
  • Continue: The bot is allowed to visit the destination page but is flagged by the header defined in the Flag Header name field.
  • Block: The bot is blocked from reaching the destination page. It is routed to a blank page with the content defined in the Block Response Body field and the response code defined in the Block Response Code field.
  • Redirect: The bot is redirected to the path defined in Redirect location.

Web Scraping

Configure web scraping protection for documents and pages on a web site that is accessible by GET requests without visiting the main page, for example, from a link on social media, from an email or from a saved bookmark. This direct access to resources prevents Bot Defense from inserting the protection JavaScript tags. When you configure an endpoint for web scraping, Bot Defense displays an interstitial page that is transparent to the user but that allows it to collect telemetry data about the requests.

• URL endpoint: Enter the path to the page or action you want to protect. Use wildcards to define complex URLs.
• Mitigation: Select the mitigation action you want to take for this endpoint if Bot Defense detects automation:
  • Continue: The bot is allowed to visit the destination page but is flagged by the header defined in the Flag Header name field.
  • Block: The bot is blocked from reaching the destination page. It is routed to a blank page with the content defined in the Block Response Body field and the response code defined in the Block Response Code field.
  • Redirect: The bot is redirected to the path defined in Redirect location.

Allow List

Configure the Allow List to let requests get to the origin destination without being verified by Bot Defense. Create your Allow List using either IP addresses or request headers.

• Allowed IP Addresses: Requests sent from IP addresses defined in the Allowed IP addresses field are delivered to the endpoint without being verified by Bot Defense. You must enter each IP address on a new line.
• Allow Header: Requests that contain the [header]:[value] pair are delivered to the endpoint without being verified by Bot Defense. You must enter each [header]:[value] pair on a new line. Bot Defense supports wildcards for both header name and header value.

Account Protection

F5 Distributed Cloud Account Protection provides a converged solution for application security and fraud protection powered by a real-time, closed-loop engine and large-scale unified telemetry to reduce customer friction and stop fraud before it happens.

The Account Protection module contains these sections:

• General
• Protected Endpoints
• Action

General

The General section contains options to enable and configure the connection of the Account Protection` module with the F5 Service. The path to the module is:

Admin panel */} Stores */} Configuration */} F5® DISTRIBUTED CLOUD SERVICES */} Account Protection

The configuration options are:

• Enable Service - Enables or disables the module.
• API Hostname - The host name of the Account Protection service.
• Script Tag - Path to the F5 Account Protection script
• JS Path - Path to the JavaScript file.
• Customer ID - The customer identifier, can be obtained from the F5 Service.
• Cookie name - The name of the cookie from the Account Protection service that should be decrypted and processed.
• Decryption key - The key that decrypts the fr value in the cookie received from the Account Protection service.

Protected Endpoints

Configure the following options to define the endpoints that you want to protect with Account Protection.

• URL endpoint - The path to the page or action that should be protected. You can use wildcards to define complex URLs.

• Mitigation - The mitigation action options:

  • Continue - The bot is allowed to visit the destination page, but is flagged by the header defined in the Mitigation Continue header field.
  • Block - The bot is blocked from reaching the destination page and is routed to a blank page that displays the content you defined in the Blocked response Body field and the response code you defined in the Blocked response Code field.
  • Redirect - The bot is redirected to the path defined in Mitigation Redirect path.

• Method - The type of request being performed on the defined page. These types of request methods are supported:

  • GET
  • POST
  • PUT

• Blocked Response Body - The message to display on the blank page when the Block mitigation action is performed.

• Blocked Response Code - The status code to deliver when the Block mitigation action is performed.

• Redirect location - The path the user is redirected to when the Redirect mitigation action is performed.

Action

The Action section contains the mitigation actions settings, such as:

• Missing Cookie - Allows you to select the mitigation action for cases when the Account Protection cookie is missing. There are three options:
  • Continue
  • Block
  • Redirect
• Invalid Cookie - Allows you to select the mitigation action for cases when the Account Protection cookie is invalid. There are three options:
  • Continue
  • Block
  • Redirect

Authentication Intelligence

Authentication Intelligence extends the login session lifetime for non-malicious users, after they are verified by F5.

General

The General section contains the following configuration options to enable and configure the connection of the Authentication Intelligence module with the F5 Service.

• Enable Service - Enables or disables the module.
• API Hostname - The host name of the Authentication Intelligence service.
• Script Tag - Path to the F5 Authentication Intelligence script.
• JS Path - Path to the JavaScript file.
• Customer ID - The customer identifier, can be obtained from the F5 Service.
• Cookie name - The name of the cookie from the Authentication Intelligence service that should be decrypted and processed.
• Decryption key - The key that decrypts the c value in the cookie received from the Authentication Intelligence service.

---

Enable Bot Defense on Amazon CloudFront

Create a new Bot Defense application for Amazon CloudFront

1. On the Distributed Cloud Console Dashboard, click Bot Defense.
2. Click Manage > Applications > Add Application. If no applications exist, you are prompted to add a protected application.
3. Add a Name and Description for the Application.
4. Select the Application Region where the origin server for the new protected application resides:US, EU, or Asia. Note that selecting the wrong region can increase latency.
5. From the Connector Type drop-down list, select Amazon CloudFront and click Configure. Options appear to enter Amazon Reference Information.

Add AWS Reference Information

1. From the AWS Configuration drop-down list, select how you want to associate your protected application with your AWS distribution. Choose Select AWS CloudFront Distribution ID or Select AWS CloudFront Distribution by tag matching.
2. Click Configure and then depending on how you chose to associate your application with your distribution, enter a Distribution ID from your CloudFront console or enter a Distribution Tag.
3. Click Add Item to add another distribution or click Apply.
   

   Figure: Associate a protected application with your AWS distribution

Note: You can choose to manually associate your distributions after you download the integration package. For information, contact support@cloud.f5.com.

Add Protected Endpoints

1. In the Protected Endpoints section, click Configure and then click Add Item.

2. Enter a Name and Description for the new endpoint.

3. Specify the Domain Matcher. You can choose any domain or specify a specific host value.

4. Specify the Path to the endpoint. For example, enter /login.

5. Specify a Query parameter, if needed. If a Query value is defined, the Bot Defense service looks at the Path and Query values.

6. Choose the HTTP Methods that are monitored on this endpoint by Bot Defense. You can select multiple methods.

7. Enter Endpoint Labels to allow more granular attack intent identification and reporting when Bot Defense detects automation. For example, to identify a multi-factor authentication flow on an endpoint, select Specify Endpoint label category > Authentication > Login MFA. F5 strongly recommends that you select endpoint labels.

   For a full list of available endpoint labels, see Endpoint Labels.

   Note: For web scraping labels, select Specify endpoint label category > Search and select an available flow label.

8. Select the type of client that accesses this endpoint (Web Client, Mobile Client, or Web and Mobile Client).

9. Select the mitigation action for this endpoint when automation is detected:

   • Continue (request continues to origin)​. For reporting purposes, you can optionally add a header to capture traffic that is going to the origin. Provide the header name in the Define Continue Mitigation Header section.

   • Redirect​. Provide the appropriate Status Code and URI​.

   • Block. Enter the Status Code, Content Type, and Body of the response message​.

   Note: Mobile clients only allow Continue and Block. If you select Web and Mobile Client, you can select mitigation actions for each client type.

   Note: If you select Web and Mobile Client, you must enter a Mobile Request Identifier Header when you enable Mobile SDK Settings. For instructions, see Define Mobile SDK Settings.

10. When you finish configuring the endpoint, click Apply.

    Your protected endpoint is added to the table. To modify the endpoint, click Actions > Edit. To add additional endpoints, click the Add Item button.

11. When you finish adding endpoints, click Apply.

Define Web Client JavaScript Settings

Note: You only configure Web Client JavaScript Settings if you have web-protected endpoints. If you only protect mobile endpoints, then select Disable JavaScript Insertion and skip to Define Mobile SDK Settings.

Note: To manually insert the protection JavaScript in your application, enable Show Advanced Fields, select Insert JavaScript Manually, and enter a Web Client JavaScript Path. Then see Manual JS Insertion for information.

1. From the Web Client JavaScript Insertion Settings drop-down list, select Specify JavaScript Insertion Rules and click Configure.

2. Add the Web Client JavaScript Path. The web client fetches the F5 Client JavaScript from this path.

   F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. Enter a simple path that starts with / or a complete URL such as https://example.com/customer1.js. The URL or path you choose cannot conflict with your existing JavaScript files.

   

   Figure: Web Client JavaScript Settings

3. From the Web Client JavaScript Mode drop-down menu, determine how the protection JavaScript is loaded into the entry page. The JavaScript is loaded in two parts. The larger part can be loaded in two possible ways:

   • Asynchronous: The JavaScript runs as soon as it is loaded and does not block the page from loading.
   • Synchronous: The page does not continue loading until the JavaScript has been loaded and executed.

   You can also choose to cache the larger part of the JavaScript so it does not have to be downloaded each time it is loaded into a new page.

   Choose one of the following options:

   • Async JS with no Caching
   • Async JS with Caching
   • Sync JS with no Caching
   • Sync JS with Caching

4. From the JavaScript Location drop-down list, choose the location where you want to insert the JavaScript in the code:

   • After <head> tag
   • After </title> tag
   • Before <script> tag

5. In the JavaScript Insertion Paths section, click Add Item.

   1. Enter a Name, Description, Domain Matcher, and Path for each page in your application where you want to insert the protection JavaScript.

      Note: Be sure to select paths to HTML pages that end users are likely to visit before they browse to any protected endpoint.

      Note F5 recommends that you use wildcards to select JavaScript insertion paths for HTML pages to which end users are likely to go, such as /index.htm and /login/*.

   2. Click Apply. The JavaScript Insertion Path is added to the table. Click Add Item to add additional JavaScript Insertion Paths.

6. To exclude the protection JavaScript from specific web pages, in the JavaScript Exclude Paths section, click Add Item.

   1. Enter a Name, Description, Domain Matcher, and Path to exclude.

   2. Click Apply. This adds an item to the table. Click Add Item to add additional exclusion paths.

   Note F5 recommends that you carefully add JavaScript Insertions and that you do not add a long list of exclusions. A small cost is incurred for each inclusion request for AWS lambda to check for exclusions.

   • JavaScript insertion path examples​:
     • /login/*
     • /catalog
   • JavaScript exclusion path examples​:
     • /login/images
     • /catalog/soldout/*

7. When you finish configuring JavaScript Insertion Rules, click Apply.

Define Mobile SDK Settings

Important: Before you configure mobile settings, see Protect Mobile Endpoints for important best practices, required configuration, and information about integrating the F5 Mobile SDK with your mobile endpoints.

1. If you added mobile endpoints to your configuration, select Enable Mobile SDK.
2. If you selected Web and Mobile Client as your client type during endpoint configuration, add a mobile header to distinguish the endpoints. This is not required if you selected only Web Client or Mobile Client.
   1. Enable Show Advanced Fields.
   2. In the Mobile Request Identifier Headers section, Click Add Item.
      

      Figure: Show Advanced Fields

   3. Enter a Name and the corresponding Value. Specify if the value must be exact or if it can be regex.
   4. Click Apply.

Configure More Options

Enable Show Advanced Fields to see all options.

Trusted Client Rules (Allow List)

Trusted Client Rules add headers and IP addresses to an Allow List. Pages that have a specific IP address or that contain specific headers are allowed to proceed to the origin and are not sent to the Bot Defense engine for evaluation. There is no logging for pages on the Allow List.

1. In the Trusted Client Rules section, click Configure and then click Add Item.
2. Enter a Name and specify the Client Identifier. Choose either IP Prefix or HTTP Headers.
   • For IP Prefix, enter a string​.
   • For HTTP Header, click Add Item, enter a Name and Value and then click Apply.

   Note: You can add multiple headers to the table at the same time. You must add IP addresses individually.

3. Click Apply when you finish adding Trusted Client Rules and then click Apply again to configure More Options.

Set Logging Level

Note: Enable Show Advanced Fields to see the following options.

Select a logging level to determine the verbosity of logs that are written to AWS storage:

• Error – Includes connection and network errors. Does not include transaction errors.
• Warning – Includes information about malicious transactions that show they were from bots. The Warning level also includes all Error-level log information.
• Info – More verbose than Warning. The Info level also includes all Warning-level log information.
• Debug – Full transaction logs that include all available log data.

Define Continue Mitigation Header

Note: Enable Show Advanced Fields to see the following option.

The Header Name for Continue Mitigation Action field is the header that is added to a request when automation is detected and you have set the mitigation action to Continue and Add Header for the endpoint. You made these selections when you configured your protected endpoints. For information, see Add Protected Endpoints.

Timeout and Body Sample Size Limit

Note: Enable Show Advanced Fields to see the following options.

• Timeout – This defines the maximum time to send the requests to the Bot Defense Engine for analysis. If the timeout is exceeded, the request continues to the origin (this is tracked in AWS CloudWatch). By default, the field is set to 700 ms based on performance efficiency.
• Body Sample Size - This allows additional request body data (other than F5 telemetry) to be sent for analysis. By default, this is set to 0 MB. Max size limit is 1 MB. If you exceed the size limit, the load balancer responds with a 413 error, "Payload Too Large."

Manual JS Insertion

If you require Manual JavaScript Insertion, add the following tags to one of the recommended locations:

• Immediately After <Head>
• Immediately After </title>
• Before <script> (first script tag on the page).

Matcher Config JavaScript:

<script type='text/javascript' src='INJECTION_PATH?matcher'></script>​

I/O Hook JavaScript​:

<script type='text/javascript' src='INJECTION_PATH?cache'></script>​

Async Telemetry JavaScript​:

<script type='text/javascript' src='INJECTION_PATH?async'async></script>​

Replace INJECTION PATH with the value you specified for Web Client JavaScript Path.

Download Config File and AWS Installer Tool

1. In the Actions column of the Applications table, click the Action menu (…) for your application.
2. Click Download Config File.
3. Click Download AWS Installer.

Deploy the F5 Connector Using Amazon CloudFront

Note: The CloudFront Connector does not support legacy cache policies in “Cache key and origin requests.” You must configure “Cache policy and origin request policy” as recommended by Amazon CloudFront for Bot Defense. For information, see your Amazon CloudFront documentation.

1. Log in to AWS Console home page.

2. Select AWS Region Northern Virginia (US-EAST-1).

3. Use the search to find Serverless Application Repository and click it.

4. Click Available Applications.

5. Click Public Applications.

   

   Figure: Public Application Tab

6. Click the F5BotDefense tile to install the F5 XC Connector for Amazon CloudFront code module.

   Important: Be sure to download the latest version of F5BotDefense in the Serverless Application Repository.

   • If there are too many tiles here, search for f5.
   • If the F5 connector tile does not appear, validate the AWS Account number you provided to F5.

7. Click Deploy to install the F5 Connector for CloudFront.

Deploying the F5 Connector creates a new Lambda Application in your AWS Account.​ AWS sets the name of the new Lambda Application to start with serverlessrepo-.

The deployment can take a few minutes to complete. It is complete when you see the F5BotDefense of type Lambda Function.

Click the name F5BotDefense to review contents of the installed Lambda Function.

Important: The available rate limit for Lambda functions is shared by all functions in your AWS account. If you reach the Lambda rate limit, an error displays in AWS. The rate limit for Bot Defense is 1000 per second. If you reach the Bot Defense rate limit, user traffic is allowed to continue to the origin with no mitigation from Bot Defense. F5 recommends that you increase the rate limit so that it accommodates all of the Lambda functions in your AWS account. For instructions, see your AWS documentation.

Configure the F5 Bot Defense Connector in AWS

F5 recommends that you use the F5 CLI tool to configure the F5 Bot Defense Connector in AWS. For best results, F5 recommends that you use the AWS CloudShell.

1. After you start AWS CloudShell, click Actions and Upload file.
2. Upload config.json and *f5tool, which you downloaded from the F5 Distributed Cloud Console.
3. When the upload is finished, run ls to confirm that the files were uploaded.
4. Run bash f5tool -–install config.json. Installation can take up to 5 minutes.

The installation tool saves the previous configuration of each CloudFront Distribution in a file. You can use the F5 tool to restore a saved Distribution config (thus removing F5 Bot Defense).

Note: Your Bot Defense configuration is sensitive security information and is stored in AWS Secrets Manager. You should delete config.json after CLI installation.

AWS CloudWatch

AWS CloudWatch contains logs for Lambda function deployed by f5ConnectorCloudFront serverless application.

​The Log group name starts with /aws/lambda/us-east-1.serverlessrepo-f5ConnectorCl-f5ConnectorCloudFront-.

The logs of lambda function can be found in the region closest to the location where the function executed.

For troubleshooting, look for error messages contained in the links under Log steams.

View Traffic

After your configuration is added, navigate to Monitor to view all traffic that the F5 XC Defense Engine has recorded for valid and invalid requests.​ This tool can help analyze thousands or millions of requests.

---

Enable Bot Defense on Salesforce Commerce Cloud

To enable Bot Defense on Salesforce Commerce Cloud, you must first add Salesforce as a protected application in Bot Defense and then configure Salesforce to send requests to be evaluated by Bot Defense.

Prerequisites

• You must have an active F5 Distributed Cloud account. If you do not have an account, see: Create a Distributed Cloud Console Account.
• You must enable Bot Defense in the Distributed Cloud Console. See: Enable Bot Defense.
• You must have Salesforce Commerce Cloud configured and have an account with sufficient permission to configure Bot Defense.

Add Salesforce Commerce Cloud to Bot Defense

The following task explains how to add Salesforce Commerce Cloud as a protected application in Bot Defense.

1. Log on to the Distributed Cloud Console. From the Dashboard page, click Bot Defense.
2. Verify that you are in the correct namespace. For information about namespaces, see https://flatrender.tora.reviews/docs/ves-concepts/core-concepts#namespaces.
3. Click Manage > Applications and then click Add Application.
4. Add a Name and Description for the protected application.
5. Select the Application Region where the origin server for the new protected application resides: US, EU or Asia.
6. From the Connector Type drop-down menu, select Salesforce Commerce.
7. Click Save and Exit.

Next Steps

Copy information from the protected application that you just added in the Distributed Cloud Console. You need this information to configure Bot Defense on Salesforce Commerce Cloud. For information, see Copy required information from your protected application.

Copy required information from your protected application

The following task explains how to copy information from your new protected application that you need to configure Bot Defense on Salesforce Commerce Cloud.

1. In the Distributed Cloud Console, from the Bot Defense page, click Manage > Applications.
2. From the Actions column, click the Action menu (…) next to the protected application you just added for Salesforce Commerce Cloud.
3. From the drop-down menu, click the following options and save the copied information in a location you can access later:
   • Copy App ID
   • Copy Tenant ID
   • Copy API Key
   • Copy API Hostname
   • Copy Telemetry Header Prefix

Next Steps

Download the F5 XC Bot Defense Cartridge from the Salesforce AppExchange. For information, see: Download the F5 XC Bot Defense Cartridge for Salesforce Commerce Cloud.

Download the F5 XC Bot Defense Cartridge for Salesforce Commerce Cloud

To use Bot Defense with Salesforce Commerce Cloud, you must download the “F5 Distributed Cloud Bot Defense Cartridge for B2C Commerce” from the Salesforce AppExchange. The download includes the files you need to use Bot Defense with Salesforce Commerce Cloud as well as documentation that explains how to install and configure the Bot Defense cartridge.

To download the Bot Defense cartridge, do one of the following:

• Use the following link to go directly to the F5 Distributed Cloud Bot Defense Cartridge for B2C Commerce page in the Salesforce AppExchange and click Get It Now: https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000R8FxIEAV&tab=d
• Go to the Salesforce AppExchange at https://appexchange.salesforce.com/ and search for “F5 Bot Defense”. From the search results, click F5 Distributed Cloud Bot Defense Cartridge and then click Get It Now.

Next Steps

After you download the Bot Defense cartridge, review the following information:

• Follow the instructions provided in the documentation included with the Bot Defense cartridge download to install and configure the cartridge.**
• Review the following section, Supplemental Bot Defense configuration information for information to help you correctly configure the cartridge.**

Supplemental Bot Defense configuration information

This section provides additional information about many of the fields that you use when you configure Bot Defense. For fields that are not listed below, follow the information provided in the documentation you downloaded with the Bot Defense cartridge.

Important: Page titles and field names may be slightly different from the titles and names included below.

Custom Site Preferences

To see the following fields, log into Salesforce Commerce Cloud and go to Custom Site Preferences Groups in BM Merchant Tools > Site Preferences > Custom Preferences.

Field Name	Information
Tenant ID	Enter the Tenant ID value that you copied from the protected application you added in the Distributed Cloud Console.
Telemetry Header Prefix	Enter the Telemetry Header Prefix value that you copied from the protected application you added in the Distributed Cloud Console.
F5 Shape API hostname	Enter the API Hostname value that you copied from the protected application you added in the Distributed Cloud Console.
API Key	The key used for authentication of the API calls to the F5 system. Enter the API Key value that you copied from the protected application you added in the Distributed Cloud Console.
Application (App) ID	Enter the App ID value that you copied from the protected application you added in the Distributed Cloud Console.
Specify F5 Shape JS URL or Path	Specify the path or URL from where clients can load the F5 client JavaScript to insert in your application. F5 recommends that you choose a URL or path that is similar to your existing JavaScript files, but that does not include “F5,” “Bot Defense” or other indications that it is used for security purposes. If you enter an absolute path, verify that the JavaScript requests are routed to the F5 Bot Defense service.
Select location for JS tags	Select the location where JavaScript tags are inserted in application pages. F5 recommends that you select After <head> so that the Bot Defense JavaScript is executed early. This allows time for the Bot Defense JavaScript to be fetched and executed while the rest of page is rendered. If you select After </title>, be sure your application pages have the <title> tag.

Manage Custom Objects

To see the following fields, log into Salesforce Commerce Cloud and go to Custom Objects in BM Merchant Tools > Custom Objects > Manage Custom Objects.

Field Name	Information
Method	The HTTP methods that Bot Defense monitors on this application.
Mitigation Action	The action Bot Defense takes on the endpoint when automated traffic is detected: - Continue: This allows traffic to continue to the origin. You can choose to add a header that enables you to monitor traffic in reporting and analytics dashboards. Block: The Bot is presented with a message that it has been blocked. - Redirect: The Bot is sent to a different page.
Block Response Body	Text that is displayed to automated traffic when Bot Defense performs the Block mitigation action.
Block Response Code	The status code that is displayed to automated traffic when Bot Defense performs the Block mitigation action.
Block Response Content Type	The type of content that is displayed when Bot Defense performs the Block mitigation action. For example, plain text or HTML.
Redirect location	The path where automated traffic is redirected when the Redirect mitigation action is performed by Bot Defense.

---

Enable Bot Defense with custom applications

Add a custom application when you want to protect an application for which Bot Defense does not have a preconfigured connector type. When you configure a connection to a custom application, you add the protected application in Bot Defense and copy a set of parameters that you need to complete the configuration process. You then complete configuration in the application you want to protect.

Prerequisites

• You must have an active F5 Distributed Cloud account. If you do not have an account, see: Create a Distributed Cloud Console Account.
• You must enable Bot Defense in the Distributed Cloud Console. See: Enable Bot Defense.
• You must have sufficient permissions in the application you want to protect to configure it with Bot Defense.

Add a custom application to Bot Defense

1. From the Distributed Cloud Console Home page, click Bot Defense.
2. Click Manage > Applications and then click Add Application.
3. On the Protected Application page, enter a Name and Description for the application.
4. From the Application Region drop-down menu, select the region where the origin server for the application resides.
5. From the Connector Type drop-down menu, select Custom.
6. Select Save and Exit.
7. On the Applications page, from the Actions column, click the Action menu (…) next to the protected application you just added.
8. From the drop-down list, click the following options and save the copied parameters in a location you can access later:
   • Copy App ID
   • Copy Tenant ID
   • Copy API Key
   • Copy Web API Hostname
   • Copy Mobile API Hostname
   • Copy Telemetry Header Prefix

Next Steps

When you finish adding the protected application to Bot Defense, use the parameters you copied from the Distributed Cloud Console to complete configuration in the application you want to protect.

---

References

• Firewall or Proxy Reference for Distributed Cloud
• System Overview
• Proxy & Load Balancer

---

Best Practices - Path Syntax

Pattern-match syntax:

• An asterisk * matches any sequence of zero or more characters.
• A question-mark ? matches any single character.

For example, to find the word 'food' in the middle of a string, you must put asterisks before and after it. For example:

• '*food*' matches both 'bird food' and 'food for birds'.
• 'food*' (single asterisk) only matches 'food for birds'.
• 'food' (no asterisks) does not match either one.

If a pattern expression does not match all of the characters in a target string (either exactly or by * or ?), the pattern reports no match.

Example query URL:

/catalog/socks?color=red&region=emea&n=20

Example URL path match:

All pages that start with /catalog/ (note each / matters)

/catalog/*

Example URL query parameter matches:

Query-string must include region=emea

(^|[^w])region=emea([^w]|$)

Query-string must include region=emea OR region=latam

(^|[^w])region=(emea|latam)([^w]|$)

Query-string must include region=emea OR region=latam in any mix of UPPER- and lower-case letters, like region=LatAm

(?i)(^|[^w])region=(emea|latam)([^w]|$)

Query-string must either be empty or include region=emea

(^$|(^|[^w])region=emea([^w]|$))

Incorrect Usage (Would match unwanted text)

Query-string must include region=emea

(DO NOT USE THIS--) region=emea (OOPS! MATCHES testregion=emea)

---

Match URL Query Parameters (and other regular-expression matches)

Basic regular-expression (regex) syntax:

• A period . matches any single character.
• A period followed by an asterisk .* matches any sequence of zero or more characters.
• [abc] and [pqr] match respectively any character in or not-in the list.
• [0-7] matches digits 0-7 inclusive.
• By default, regex reports partial matches. For example, the regex 'food' matches both 'bird food' and 'food for birds'. To prevent a partial match, use a caret ^ at the left and/or dollar-sign $ at the right to force matches at the start or end of the target string. For example, ^food matches 'food for birds' and food$ matches 'bird food', while ^food$ only matches 'food' by itself with nothing preceding or following those four letters.
• To match multiple distinct words separate them by pipe symbols | and surround the set with parentheses (). For example, enter ^(food|drink|toothp.*)$ to match any string which contains exactly 'food' or 'drink' or anything that starts with 'toothp', such as 'toothpick' or 'toothpaste'.
• Regular expressions have many additional powerful features, such as a? to match zero-or-one letter 'a'.

This system supports most RE2 or TCL ARE regular expression syntax. For a full description of features, use a search engine to search for 'RE2 syntax'.

Javascript (ECMAScript) uses very similar syntax, but differs in a few ways. For comparison information, use a search engine to search for 'cmcdragonkai regular expression comparison'.

For endpoint matches, use regex syntax common to RE2 and Javascript. The exception is (?i), which is specially handled for you.

When you look for several different words, for best performance, use a single regex like (red|blue|green) rather than searching for each word separately.

When you use regex, be aware of partial matching. For example, to match a URL path starting with /mobile you must enter ^/mobile, otherwise paths such as '/docs/mobile-info.htm' (/mobile in the middle) also match.

For regex endpoint matching:

• To ignore letter-case, prepend (?i) to your expression. For example, enter '(?i)^food'.
• Use only regex syntax common between RE2, TCL ARE, and Javascript. The exception is (?i), which Bot Defense handles specially.
• Be aware of matching at word boundaries. The syntax [\w] works in all cases. For example, to find the word 'head' by itself, possibly surrounded by punctuation as with '<head>' but NOT embedded in a longer word like 'sleepyhead' or 'headlamp', enter (^|[\w])head([\w]|$). To match the word 'head' or the empty string, which is often useful with URL query strings, use (^$|(^|[\w])head([\w]|$)).

---

Endpoint Labels

Use endpoint labels to allow more granular attack intent identification and reporting when Bot Defense detects automation.

Category	Label	Description
Authentication	Login	When credentials are provided to gain access to a saved account.
Authentication	Login MFA	When multi-factor authentication is used to gain access to a saved account.
Authentication	Login for Channel Partner	Login to a saved account occurs through a partner via a different channel.
Authentication	Logout	When a session ends or saved account is exited.
Authentication	Token Refresh	Session remains valid; login is not requested again to access a saved account.
Account Management	Account Creation	When an account is created (for example, at a department store, a restaurant, or with a ride-share service).
Account Management	Password Reset	When a password is reset.
Profile Management	Profile Creation	When a new user profile has been created; some accounts allow for multiple profiles to be added (for example, health insurance with dependents).
Profile Management	Profile Update	When profile information (may contain personal or sensitive information, such as password, email, or payment info.) is updated.
Profile Management	Profile View	When profile information (may contain personal or sensitive information, such as password, email, payment info) is viewed.
Shopping & Gift Cards	Add to Cart	When an item has been added to the shopping cart.
Shopping & Gift Cards	Promo Code Validation	When a promotional code is validated.
Shopping & Gift Cards	Checkout	When payment is submitted for items in the cart.
Shopping & Gift Cards	Payment / Billing	When payment/billing information is added.
Shopping & Gift Cards	Order Submit	When an order is submitted to the vendor to be fulfilled.
Shopping & Gift Cards	Price Inquiry	When a price inquiry is submitted for a product, insurance, quote, and so on.
Shopping & Gift Cards	Purchase a Gift Card	When a gift card is purchased for a specified amount.
Shopping & Gift Cards	Update Quantity	When the cart quantity for an item has been updated.
Shopping & Gift Cards	Select Seat(s)	When a seat (for a flight, concert, movie hall, sporting event) has been selected.
Shopping & Gift Cards	Enter Drawing Submission	Used to submit entry for a drawing or lottery.
Shopping & Gift Cards	Gift Card Validation	Used when validating a gift card value.
Shopping & Gift Cards	Purchase with Gift Card	When a gift card number is entered as a payment option during checkout. This is also another way that can be used to validate the value on a gift card.
Financial Services	Apply for a Financial Service Account	When an application for a new credit card account, retirement account, bank account has been submitted.
Financial Services	Money Transfer	When a money transfer from one account to another has occurred.
Search	Flight Search	Used to search for open seats on a flight.
Search	Product Search	Used to search for a specific product.
Search	Room Search	Used to search for room availability.
Search	Reservation Search	Used to search to book a sports reservation, concert, and so on.
Flight	Check into Flight	Used for online flight check-ins.

---