Many web applications use two-way communication channels between the client and the server. The WebSocket Protocol, specified in RFC 6455, defines a way to speed up and simplify the communication.

Application Security Manager™ (ASM) provides security for WebSocket connections in security policies by adding WebSocket URLs (ws:// and wss://) and defining defense measures in a WebSocket profile. The WebSocket protocol allows extensions to add features to the basic framing protocol. The WebSocket URL informs ASM how to handle the extensions. The WebSocket URL also defines the allowed message format, size, and whether it is enforced.

You cannot associate parameters with WebSocket URLs. Therefore, any parameters in the request are handled at the global level.

WebSocket security can protect against many threats, including those listed in this table.

If your application uses login enforcement, you can specify authenticated WebSocket URLs that can only be accessed after login. To do this, the security policy needs to include at least one login page. You specify the WebSocket and WebSocket Secure (ws:// and wss://) URLs that must be authenticated on the login enforcement screen.

See Creating Login Pages for Secure Application Access for how to set up login enforcement for WebSocket URLs.

To prevent access to a WebSocket from an unauthorized origin, you can add more security to it. You can enable cross-domain request enforcement as part of the Allowed WebSocket URL properties within a security policy.

See Setting Up Cross-Domain Request Enforcement for how to set up cross-domain request enforcement for WebSocket URLs.

1. On the Main tab, click Security > Application Security > Security Policies > Policies List .
   The Policies List screen opens.
2. With no policy selected, click Create New Policy.
   1. Type a name for the policy.
   2. For Policy Template, select Comprehensive.
   3. For Virtual Server, configure the local traffic settings for the virtual server.
   4. Click Create policy.
   The system creates a security policy, but the policy does not yet support WebSocket.
3. Click Local Traffic > Virtual Servers , open the virtual server you created, select the Advanced configuration settings, and from the WebSocket Profile list, select websocket, and when done, click Update to save your changes.
   For details, see Recognizing WebSocket Traffic.
   The system uses the default WebSocket profile for the application.
4. Start sending traffic to the web application that uses WebSocket connections.

1. On the Main tab, click Local Traffic > Profiles > Services > WebSocket .
2. Click Create.
   The New WebSocket Profile screen opens.
3. In the Name field, type a name for the WebSocket profile.
4. Select the Custom check box at the right so you can edit the screen.
5. From the Masking list, select an option:

   Option	When you want to do this
   Preserve	Preserve the mask of the packet received, and make no change. ASM and other modules receive masked frames.
   Unmask	Remove the mask from the packet and remask it using the same mask when sending the traffic to the server. (Default value.)
   Selective	Preserve the mask of the packet received, and make no changes unless an Application Security Policy is associated with the virtual server. In that case, unmask the packet, allow ASM™ to examine the WebSocket payload, and remask it when sending the traffic to the server.
   Remask	Remove the mask received from the client. The system generates a new, random mask when sending the traffic to the server.

6. Click Finished.

1. On the Main tab, click Local Traffic > Virtual Servers .
   The Virtual Server List screen opens.
2. Click the name of the virtual server associated with the security policy that you want to secure WebSocket traffic.
3. From the Configuration list, select Advanced.
4. Make sure that HTTP Profile is set to http.
5. From the WebSocket Profile list, select websocket, or the name of the profile you created.
   The websocket profile is a default profile included with the system.
6. Click Update to save the changes.

1. On the Main tab, click Security > Application Security > Content Profiles > JSON Profiles .
2. Click Create to create a new JSON profile, or edit the Default JSON profile (by clicking it).
   The Create New JSON Profile screen opens.
3. Type a name for the profile.
4. Adjust the maximum values that define the JSON data for the AJAX application, or use the default values.
5. If you want the system to tolerate and not report warnings about JSON content, select the Tolerate JSON Parsing Warnings check box.
   If the system cannot parse JSON content, it generates the violation Malformed JSON data, regardless of whether this setting is enabled or disabled.
6. To parse parameters in a JSON payload as parameters (recommended), ensure that Parse Parameters is enabled.
   The system extracts parameters from JSON content whenever the JSON profile is used; for example, with URLs, WebSocket URLs, or parameters that use a JSON profile.
   The security policy parses parameters extracted from the JSON payload the same as other parameters. Also, the Attack Signatures, Value Metacharacters, and Sensitive Data Configuration tabs are removed from the screen, so you can skip to the last step.
7. If the signatures included in the security policy are not sufficient for this JSON profile, you can change them.
   1. On the Attack Signatures tab, in the Global Security Policy Settings list, select any specific attack signatures that you want to enable or disable for this profile, and then move them into the Overridden Security Policy Settings list.
      Tip: If no attack signatures are listed in the Global Security Policy Settings list, create the profile, update the attack signatures, then edit the profile.
   2. After you have moved any applicable attack signatures to the Overridden Security Policy Settings list, enable or disable each of them as needed:
      • Enabled - Enforces the attack signature for this JSON profile, although the signature might be disabled in general. The system reports the violation Attack Signature Detected when the JSON in a request matches the attack signature.
      • Disabled - Disables the attack signature for this JSON profile, although the signature might be enabled in general.
8. To allow or disallow specific meta characters in JSON data (and thus override the global meta character settings), click the Value Meta Characters tab.
   • Select the Check characters check box, if it is not already selected.
   • Move any meta characters that you want allow or disallow from the Global Security Policy Settings list into the Overridden Security Policy Settings list.
   • In the Overridden Security Policy Settings list, change the meta character state to Allow or Disallow.
9. To mask sensitive JSON data (replacing it with asterisks), click the Sensitive Data Configuration tab.
   • In the Element Name field, type the JSON element whose values you want the system to consider sensitive.
   • Click Add.
   Important: If the JSON data causes violations and the system stops parsing the data part way through a transaction, the system masks only the sensitive data that was fully parsed.
   Add any other elements that could contain sensitive data that you want to mask.
10. Click Create (or Update if editing the Default profile).
    The system creates the profile and displays it in the JSON Profiles list.

1. On the Main tab, click Security > Application Security > Content Profiles > Plain Text Profiles .
2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
3. Click Create.
   The Create New Plain Text Profile screen opens.
4. For Profile Name, type the name of the profile.
5. Adjust the maximum values that define the length of the text messages, or use the default values.
6. In the Attack Signatures tab, determine which patterns to look for in the text:
   1. If the text content does not need to be reviewed for potential threats, clear the Check attack signatures check box. Otherwise, leave it selected and the system will use the attack signatures to look for threats.
   2. If checking signatures, in the Global Security Policy Settings list, select any specific attack signatures that you want to enable or disable for this profile, and then move them into the Overridden Security Policy Settings list.
   3. Once you have moved any applicable attack signatures to the Overridden Security Policy Settings list, enable or disable each of them as needed.

   Option	Description
   Enabled	Enforces the attack signature for this text profile, although the signature might be disabled for the policy in general. The system reports the violation Attack Signature Detected when the text in a request matches the attack signature.
   Disabled	Disables the attack signature for this text profile, although the signature might be enabled in general.

   Tip: If no attack signatures are listed in the Global Security Policy Settings list, create the profile, update the attack signatures, then edit the profile.
7. To allow or disallow specific meta characters in the text (and thus override the global meta character settings), click the Value Meta Characters tab.
   1. Select the Check characters check box, if it is not already selected.
   2. Move any meta characters that you want allow or disallow from the Global Security Policy Settings list into the Overridden Security Policy Settings list.
   3. In the Overridden Security Policy Settings list, change the meta character state to Allow or Disallow.
8. Click Create.
   The system creates the profile and displays it in the Plain Text Profiles list.

1. On the Main tab, click Security > Application Security > URLs > Allowed URLs > Allowed WebSocket URLs .
   The Allowed WebSocket URLs screen opens.
2. Click Create.
   The New Allowed WebSocket URL screen opens.
3. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
4. Next to Create New Allowed WebSocket URL, select Advanced.
5. For WebSocket URL, choose a type and protocol, and then type the URL name or wildcard.

   Type	Description
   Explicit	Specifies a specific WebSocket URL, such as /chat.room.com/websocket. Select WS (for unencrypted text) or WSS (for encrypted text), and type the URL in the adjacent field.
   Wildcard	Specifies a wildcard expression to represent a number of URLs. Any URL that matches the wildcard expression is considered legal. The pure wildcard (*) is automatically added to the security policy so you do not need to add it. But you can add other wildcards such as /main/*. Select WS (for unencrypted text) or WSS (for encrypted text), and type a wildcard expression in the adjacent field.

6. Retain the default selected Perform Staging check box.
   Keep it selected so you can check for false positives before enforcing the new URL.
7. For wildcard WebSocket URLs, leave Wildcard Match Includes Slashes selected.
   When this option is selected, an asterisk in a wildcard matches any number of path segments (separated by slashes); when cleared, an asterisk matches at most one segment.
8. On the Message Handling tab, leave Check Message Payload enabled.
   Based on the traffic and the selections in the Payload Enforcement setting, the Check Message Payload setting causes the system to validate the format of WebSocket messages.
9. For the WebSocket Extensions list, leave the default value Remove Headers to select what happens to messages that have WebSocket extensions.
   Other options to ignore extensions (Dangerous! Not recommended.) or block messages with extensions are available, but F5 recommends using the default.
   The system removes the Sec-WebSocket-Extensions header from the message and allows the WebSocket to be established so messages can be exchanged.
10. For Allowed Message Payload Formats, select the format or formats that you want to enforce for WebSocket messages: click JSON or Binary.
    At least one format must be selected. (Initially, Plain Text is always selected.) If you are using a different format and not verifying plain text in messages, you can clear Plain Text.
11. For Payload Enforcement, choose how to validate the message content.
    • To verify plain text or JSON formatting, select the previously created content profile, or create a new one.
    • To enforce binary messages, for Maximum Binary Message Size, click Length and type the largest binary message (in bytes) to allow. The default value is 10000 bytes.
12. For Maximum Frame Size, adjust the frame size, if necessary.
    The default value is 10000 bytes.
13. For Maximum Frames per Fragmented Message, adjust the number, if necessary.
    The default value is 100 frames.
14. For wildcard WebSocket URLs, on the Meta Characters tab, you can overwrite the global URL character set, and allow or disallow specific meta characters in the WebSocket URL if you need to.
    1. The Check characters on this URL setting is enabled by default so that the system verifies meta characters in the URL. (If you do not want to check for meta characters, clear the check box and skip to the next step.)
    2. To specify which meta characters to allow or disallow, from the Global Security Policy Settings list, select any meta characters that you want to specifically allow or disallow, and move them to the Overridden Security Policy Settings list.
    3. For each meta character that you moved, set the state to Allow or Disallow.
    Note: The Overridden Security Policy Settings take precedence over the global settings for the web application character set.
15. If your web site uses CORS (Cross-Origin Resource Sharing), click the HTML5 Cross-Domain Request Enforcement tab.
    1. For Enforcement Mode, select Enforce on ASM.
    2. On the HTML5 Cross-Domain Request Enforcement tab, specify how to enforce CORS on this WebSocket URL. For details, see Setting Up Cross-Domain Request Enforcement.
16. Click Create.
    The Allowed WebSockets URLs screen opens and lists the new WebSocket URL.
17. To put the security policy changes into effect immediately, click Apply Policy.

1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
   The Learning and Blocking Settings screen opens.
2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
3. In the Policy Building Settings, expand URLs to view the settings.
4. Specify how WebSocket URLs are added to the security policy in Learn New WebSocket URLs.

   Option	Description
   Never (wildcard only)	Do not add explicit WebSocket URLs; just use a wildcard and relax the settings if it causes false positives.
   Selective	Add explicit WebSocket URLs that do not match the attributes of the * wildcard.
   Add All Entities	Add all WebSocket URLs used on the website.

5. Review the Learn, Alarm, Block (if in blocking enforcement mode) settings of the WebSocket-related violations to see if they are set as you want them to be.
6. For Maximum Learned WebSocket URLs, use the default value of 10000.
   This option is available only if you are using Selective or Add All Entities for learning.
7. Click Save to save your settings.
8. To put the security policy changes into effect immediately, click Apply Policy.

1. On the Main tab, click Security > Application Security > Policy Building > Learning and Blocking Settings .
   The Learning and Blocking Settings screen opens.
2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
3. In the General Settings, for Learning Mode, ensure that it is set to Automatic.
4. On the right side of the Learning and Blocking Settings screen, select Advanced.
   The screen displays the advanced configuration details for policy building.
5. In the Policy Building Settings area, expand URLs.
6. For Learn New HTTP URLs, specify when the system should add explicit URLs to the security policy.
   • Choose Selective to add explicit URLs that do not match the * wildcard.
   • Choose Add All Entries to create a comprehensive whitelist of all the website URLs.
   Using these options activates the Classify Client Message Payload Format of Learned WebSocket URLs check box.
7. Select Classify Client Message Payload Format of Learned WebSocket URLs.
8. Click Save to save your settings.
9. To put the security policy changes into effect immediately, click Apply Policy.

1. On the Main tab, click Security > Application Security > URLs > Disallowed URLs > Disallowed WebSocket URLs .
   The Disallowed WebSocket URLs screen opens.
2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
3. Click Create.
   The New Disallowed WebSocket URL screen opens.
4. For the WebSocket URL (Explicit only) setting, select WS or WSS as the protocol for the URL, and type the WebSocket URL that the security policy considers illegal; for example, /index.html.
   Note: URLs are case-sensitive unless you cleared the Security Policy is case sensitive option when you created the policy.
5. Click Create.
   The Disallowed WebSocket URLs screen opens and lists the URL.
6. To put the security policy changes into effect immediately, click Apply Policy.

1. On the Main tab, click Security > Application Security > URLs > Allowed URLs > Allowed WebSocket URLs .
   The Allowed WebSocket URLs screen opens.
2. In the Current edited security policy list near the top of the screen, verify that the security policy shown is the one you want to work on.
3. From the Allowed WebSocket URLs List, click the name of a WebSocket URL that can contain unstructured text or JSON data.
   The Allowed WebSocket URL Properties screen opens.
4. In the Allowed Message Payload Formats setting, select Plain Text or JSON or both.
5. For the Payload Enforcement setting, from the Plain Text Profile or JSON Profile lists, select the content profiles to enforce.
6. Click Update.
7. To put the security policy changes into effect immediately, click Apply Policy.

This table lists the violations that Application Security Manager™ can detect in WebSocket traffic.