Client-Side Defense

Objective

This guide provides instructions on how to enable Client-Side Defense (CSD) and apply it on your web applications using F5® Distributed Cloud Console. For more information on CSD, see About Client-Side Defense.


Prerequisites

Note: If you do not have an account, see Create a Distributed Cloud Console Account.


Enable CSD

To enable CSD on Distributed Cloud Console, do the following:

Step 1: In the System namespace, go to Client-Side Defense->Overview in the navigation pane on the left.

csd nav new
Figure: Navigate to CSD

Step 2: In the Client-Side Defense screen that appears, click Enable Client-Side Defense.

enable csd
Figure: Enable CSD

CSD is now enabled and ready for use.


Add a Domain for CSD Protection

After you have enabled CSD on Distributed Cloud Console, you should add the domains on which you want to apply CSD protection according to the following steps:

Step 1: In the CSD dashboard, click the Configuration tab.

config tab
Figure: Select Configuration Tab

Step 2: Click Add domain to protect.

add domain
Figure: Add domain to protect

The Domain to protect screen appears.

domain to protect
Figure: Domain to protect

Step 3: In the Domain to protect screen, enter the root domain you want to protect and click Save and Exit.

The domain you added now appears in the list of domains to protect.

---

Injecting the CSD JS on Your Web Pages

After you have added the domains on which to apply CSD protection, you need to inject the CSD JavaScript (JS) on the web pages in the domain. F5 recommends injecting the CSD JS on all web pages in the domain to maximize CSD protection.

Inject the CSD JS on web pages as follows:

Step 1: In the CSD dashboard, click the Configuration tab.

config tab
Figure: Select Configuration Tab

Step 2: Click How to Inject JS.

inject js
Figure: Inject JS

The How to Inject JS screen appears.

how to inject js updated
Figure: How to Inject JS screen

Step 3: Follow the instructions for injecting the CSD JS in the How to Inject JS screen.

Verifying Your Email on the Alert Receiver

When you enable CSD, CSD automatically creates an Alert Receiver using the email address you entered for your account on Distributed Cloud Console. CSD also automatically creates an Alert Policy and adds a CSD alerts group to this policy. To ensure that you receive alerts when CSD detects suspicious activity, you need to verify your email on the Alert Receiver.

To verify your email on the Alert Receiver:
  • In the System namespace, go to Manage->Alerts Management->Alert Receivers in the navigation pane on the left.

select alert receivers
Figure: Navigate to Alert Receivers

  • In the Alert Receivers screen, go to the row of client-side-defense-receiver and in the Actions column on the far-right click the three dots.
  • In the pop-up menu, select Verify Email.
  • In the prompt “Do you want to send verification email for receiver client-side-defense-receiver?” select Send email.
  • Wait to receive the email and once you receive it return to the Alert Receivers screen.
  • Go to the row of client-side-defense-receiver and in the Actions column on the far-right click the three dots.
  • In the pop-up menu, select Enter verification code, then enter the verification from the email and click Verify receiver.

For more information on configuring Alert Receivers and Alert Policies, click here.


Testing the JS Injection on Your Web Pages

After you have added domains for CSD protection and injected the CSD JS on your web pages, you can test if the JS injection was successful on a web page. Testing for the CSD JS injection is not required, but F5 recommends performing this test to verify that your web pages are recieving CSD protection.

Perform testing for the CSD JS injection as follows:

Step 1: In the CSD dashboard, click the Configuration tab.

config tab
Figure: Select Configuration Tab

Step 2: Find the domain in the list that contains the web page that you want to test, and click the Test JS Injection button at the end of the row on the right.

The Test JS Injection screen appears.

test js injection
Figure: Test JS Injection

Step 3: In the Test JS Injection screen, paste the URL of the web page that you want to test and click Test JS Injection.

When the test is finished, a confirmation message is displayed indicating whether or not the CSD JS was detected on the web page.


Using the CSD Dashboard

The CSD Dashboard displays the following 5 main tabs that you use for displaying data, for deciding whether to mitigate or allow a suspicious domain, and for configuring your web application for CSD protection:

  • Suspicious Domains: When a web page with CSD protection is loaded on the end-user’s browser, scripts running on that web page interact with other domains. The Suspicious Domains list displays a list of the domains that those scripts interact with and which CSD detected to be potentially malicious.
  • Mitigate List: Displays a list of domains that the user has assigned for mitigation. When a domain is assigned for mitigation, CSD blocks that domain and it cannot be accessed by any script running on the end-user's browser when accessing a CSD protected web page.
  • Allow List: Displays a list of domains that the user has decided do not need mitigation and can be allowed free access.
  • All Domains: When a web page with CSD protection is loaded, scripts running on that web page interact with other domains. The All Domains list displays a list of the domains that those scripts interact with.
  • Configuration: Displays a list of all the customer's root domains configured for CSD protection, and also displays the following options:
    • Add domains for CSD protection
    • Display instructions for injecting the CSD JS on web pages in a domain
    • Schedule a CSD training session

Viewing Suspicious Domains

When CSD detects suspicious activity on a domain that has been configured for CSD protection, the user is alerted and that domain is added to the suspicious domains list. You can view that list by clicking on Suspicous Domains in the CSD dashboard, as shown below.

suspic domains
Figure: Viewing Suspicious Domains

Filtering Suspicious Domains by Location

You can filter the Suspicious Domains list according to a specific loction or locations where CSD detected suspicious activity.

To filter the Suspicious Domains list by location:
  • Click Select Page in the upper-right section of the screen.
  • In the pop-up list that appears, select one or more locations and then click Apply. The list will now display only those domains containing the location(s) you selected.

Adding a Domain to the Mitigate List or Allow List

To add a domain to the Mitigate List or Allow List:

  • Go to the Suspicious Domains list or All Domains list.

  • Go to the row of the relevant domain, and in the Actions column on the far right click the three dots.

    select three dots new .

  • In the pop-up menu, select Add to Allow List/Add to Mitigate List.

Alternatively, you can add a domain directly from the Mitigation List or Allow List as follows:

  • In the Mitigation List or Allow List, click Add domain.

    add domain to mitigate .

  • In the screen that opens, enter the domain name and click Save and Exit.

After a domain has been added to the Mitigate List or Allow List, you can delete it from the list by clicking the three dots in the Actions column and then select Delete.


Viewing Domain Details

From the Suspicious Domains list or All Domains list, you can view valuable information on a domain by clicking on the domain in the list. A window then opens on the right side of the screen displaying the following domain details:

  • Reasons why this domain may be at risk
  • Risk score
  • Web pages on this domain with CSD protection
  • Scripts that are potentially networking with the domain

Modifying the CSD JS for Asynchronous Loading

By default, the CSD JS is configured to load synchronously and F5 highly recommends against changing this configuration. However, if there is a strong customer need, the CSD JS can be modified to load asynchronously. To modify the CSD JS for asynchronous loading, you just need to add async defer at the beginning of the script, as shown below:

Change: <script src="https://us.gimp.zeronaught.com/js/example.js"></script>

To: <script async defer src="https://us.gimp.zeronaught.com/js/example.js"></script>

The CSD JS should always be the first JS or script to load on the web page to ensure that the CSD JS can detect any malicious JS or scripts running on the web page.