Manual Chapter :
Securing Applications That Use WebSocket
Applies To:
Show Versions
BIG-IP ASM
- 17.1.2, 17.1.1, 17.1.0, 17.0.0
Securing Applications That Use WebSocket
Overview: Securing applications that use WebSocket connections
WebSocket
is an HTML5 protocol that simplifies and speeds up communication between
clients and servers. Once a connection is established through a handshake, messages can be passed
back and forth while keeping the connection open.For example, WebSocket connections are used for bi-directional, real-time applications such as
support chats, news feeds, immediate quotes, or collaborative work. It is important to secure the
content that is exchanged, otherwise an attacker could potentially gain access to the application
server.
If your application uses WebSocket protocol, your security policy can protect WebSocket
connections from exploits related to the protocol. If the policy uses automatic learning, the
system handles much of the work for you. If you are using manual learning, you can add content
profiles and WebSocket URLs to the security policy to protect WebSocket traffic.
This use case presumes that you have already created the security policy for the web
application. It tells you what you need to do so that the system can recognize and secure
WebSocket traffic.
Task Summary
About WebSocket security
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.
Threat |
How WebSocket Security Prevents It |
---|---|
Server stack abuse |
Enforces mandatory headers in the request. |
Session riding or CSRF |
Denies access to requests coming from origins not in the configured whitelist. |
Information leakage |
Enforces login sessions for ws:// and wss://
URLs. |
XSS, SQL injection, command shell injection, and other threats that attack signatures
prevent |
Uses attack signatures to examine parameter content in each WebSocket text message. If
it finds them, closes the WebSocket connection and logs it in the Request log. |
Server exploits |
Examines text messages for RFC compliance, illegal meta characters, and null
characters. |
Cache poisoning |
Enforces message masking for client text messages to avoid caching false content. |
Buffer overflow |
Limits message size, frame size, and enforces correct frame format. If messages are in
JSON format, validates content. |
Exhausted server socket resources |
Limits the time for sending a message and time between messages. |
About WebSocket and login enforcement
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.About WebSocket and cross-domain request enforcement
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.Securing WebSocket
applications: The easy way
You can use Application Security Manager to secure
applications that use WebSocket connections. The easiest way to do this is to create a
security policy that uses automatic learning. That way, the system builds the policy for
you when you tell it how to recognize WebSocket traffic.
- On the Main tab, click.The Policies List screen opens.
- With no policy selected, clickCreate New Policy.
- Type a name for the policy.
- ForPolicy Template, selectComprehensive.
- ForVirtual Server, configure the local traffic settings for the virtual server.
- ClickCreate policy.
The system creates a security policy, but the policy does not yet support WebSocket. - Click, open the virtual server you created, select theAdvancedconfiguration settings, and from theWebSocket Profilelist, selectwebsocket, and when done, clickUpdateto save your changes.For details, seeRecognizing WebSocket Traffic.The system uses the default WebSocket profile for the application.
- Start sending traffic to the web application that uses WebSocket connections.
The system starts examining the application
traffic, and builds the security policy as usual. The system adds Allowed WebSocket URLs
to the security policy along with other policy elements when ASM sees enough traffic
from various users.
In Comprehensive policies, the system examines
and classifies request content of learned WebSocket URLs, and creates a JSON profile
if needed. The system stabilizes the security policy when sufficient sessions over a
period of time include the same elements.
In Fundamental
policies, the system learns URLs selectively, and classification is turned off, by
default. Most WebSocket traffic is treated as plain text, and URLs with binary
messages are learned (assuming they are the exception). The system does not learn
JSON automatically because JSON is seen as plain text, and no violation is issued.
Creating a WebSocket profile
If you want the BIG-IP system to recognize WebSocket traffic,
you need a WebSocket profile. For most purposes, you can use the default
websocket
profile included with the system and skip this task. If
you need to adjust the masking options, you can create a new WebSocket profile. - On the Main tab, click.
- ClickCreate.The New WebSocket Profile screen opens.
- In theNamefield, type a name for the WebSocket profile.
- Select theCustomcheck box at the right so you can edit the screen.
- From theMaskinglist, select an option:OptionWhen you want to do thisPreservePreserve the mask of the packet received, and make no change. ASM and other modules receive masked frames.UnmaskRemove the mask from the packet and remask it using the same mask when sending the traffic to the server. (Default value.)SelectivePreserve 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.RemaskRemove the mask received from the client. The system generates a new, random mask when sending the traffic to the server.
- ClickFinished.
Next, you can associate the WebSocket profile with the virtual server that handles
applications with WebSocket connections. For example, this could be the virtual server
associated with an Application Security Policy created for WebSocket applications.
Recognizing WebSocket traffic
If you want the system to recognize and handle WebSocket traffic, you need to
associate a WebSocket profile with the virtual server that handles the traffic. For
example, this could be the virtual server associated with a security policy that you
want to secure an application with WebSocket connections.
- On the Main tab, click.The Virtual Server List screen opens.
- Click the name of the virtual server associated with the security policy that you want to secure WebSocket traffic.
- From theConfigurationlist, selectAdvanced.
- Make sure thatHTTP Profileis set tohttp.
- From theWebSocket Profilelist, selectwebsocket, or the name of the profile you created.Thewebsocketprofile is a default profile included with the system.
- ClickUpdateto save the changes.
The WebSocket profile is associated with the virtual server. The system can now
recognize WebSocket traffic.
Creating a JSON profile
Before you can complete this task, you need to have already created a security
policy for your application.
This task describes how to create a JSON profile that defines the properties that
the security policy enforces for an application sending JSON payloads or WebSocket
payloads in JSON format.
The system supports JSON in UTF-8 and UTF-16
encoding. WebSocket allows only UTF-8.
- On the Main tab, click.
- ClickCreateto create a new JSON profile, or edit theDefaultJSON profile (by clicking it).The Create New JSON Profile screen opens.
- Type a name for the profile.
- Adjust the maximum values that define the JSON data for the AJAX application, or use the default values.
- If you want the system to tolerate and not report warnings about JSON content, select theTolerate JSON Parsing Warningscheck box.If the system cannot parse JSON content, it generates the violationMalformed JSON data, regardless of whether this setting is enabled or disabled.
- To parse parameters in a JSON payload as parameters (recommended), ensure thatParse Parametersis 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.
- If the signatures included in the security policy are not sufficient for this JSON profile, you can change them.
- On the Attack Signatures tab, in theGlobal Security Policy Settingslist, select any specific attack signatures that you want to enable or disable for this profile, and then move them into theOverridden Security Policy Settingslist.If no attack signatures are listed in theGlobal Security Policy Settingslist, create the profile, update the attack signatures, then edit the profile.
- After you have moved any applicable attack signatures to theOverridden Security Policy Settingslist, 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 violationAttack Signature Detectedwhen 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.
- 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 theCheck characterscheck box, if it is not already selected.
- Move any meta characters that you want allow or disallow from theGlobal Security Policy Settingslist into theOverridden Security Policy Settingslist.
- In theOverridden Security Policy Settingslist, change the meta character state toAlloworDisallow.
- To mask sensitive JSON data (replacing it with asterisks), click the Sensitive Data Configuration tab.
- In theElement Namefield, type the JSON element whose values you want the system to consider sensitive.
- ClickAdd.
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. - ClickCreate(orUpdateif editing the Default profile).The system creates the profile and displays it in the JSON Profiles list.
This creates a JSON profile that affects the security policy when you associate the
profile with a URL, WebSocket URL, or parameter.
Next, you need to associate the JSON profile with any URLs, WebSocket URLs, or
parameters that might include JSON data.
Creating a plain text content profile
Before you can complete this task, you need to have already created a security
policy for your application.
You can create a plain text content profile that defines the properties that a
security policy enforces for unstructured text content, such as those used in WebSocket
messages. Note that the system creates a default plain text profile in advance for *
wildcard URLs (unless this was an upgrade from a previous version). You can use the
default profile for other URLs, and also edit it if it applies to multiple URLs
including the *, instead of creating new ones.
- On the Main tab, click.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- ClickCreate.The Create New Plain Text Profile screen opens.
- ForProfile Name, type the name of the profile.
- Adjust the maximum values that define the length of the text messages, or use the default values.
- In the Attack Signatures tab, determine which patterns to look for in the text:
- If the text content does not need to be reviewed for potential threats, clear theCheck attack signaturescheck box. Otherwise, leave it selected and the system will use the attack signatures to look for threats.
- If checking signatures, in theGlobal Security Policy Settingslist, select any specific attack signatures that you want to enable or disable for this profile, and then move them into theOverridden Security Policy Settingslist.
- Once you have moved any applicable attack signatures to theOverridden Security Policy Settingslist, enable or disable each of them as needed.
EnabledEnforces the attack signature for this text profile, although the signature might be disabled for the policy in general. The system reports the violationAttack Signature Detectedwhen the text in a request matches the attack signature.DisabledDisables the attack signature for this text profile, although the signature might be enabled in general.If no attack signatures are listed in theGlobal Security Policy Settingslist, create the profile, update the attack signatures, then edit the profile. - To allow or disallow specific meta characters in the text (and thus override the global meta character settings), click the Value Meta Characters tab.
- Select theCheck characterscheck box, if it is not already selected.
- Move any meta characters that you want allow or disallow from theGlobal Security Policy Settingslist into theOverridden Security Policy Settingslist.
- In theOverridden Security Policy Settingslist, change the meta character state toAlloworDisallow.
- ClickCreate.The system creates the profile and displays it in the Plain Text Profiles list.
This creates a plain text content profile that affects the security policy when you
associate the profile with a URL, such as a WebSocket URL. Once associated, the security
policy checks the content of text being sent to the WebSocket URL.
Next, you need to associate the plain text content profile with the WebSocket URLs
so the system can verify the content of the messages being sent over the WebSocket
connection. You can create the WebSocket URLs manually if not using automatic
learning.
Creating allowed WebSocket URLs
You can manually create
allowed WebSocket URLs
, which are URLs from
which the security policy accepts messages over WebSocket connections. You do this if
you have a short list of WebSocket URLs to protect and you know their paths. If
you are using automatic learning, the security policy protects WebSocket URLs
automatically, and you do not have to add them. Learning settings for WebSocket URLs
are on the Learning and Blocking Settings screen.
- On the Main tab, click.The Allowed WebSocket URLs screen opens.
- ClickCreate.The New Allowed WebSocket URL screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- Next toCreate New Allowed WebSocket URL, selectAdvanced.
- ForWebSocket URL, choose a type and protocol, and then type the URL name or wildcard.TypeDescriptionExplicitSpecifies a specific WebSocket URL, such as/chat.room.com/websocket. SelectWS(for unencrypted text) orWSS(for encrypted text), and type the URL in the adjacent field.WildcardSpecifies 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/*. SelectWS(for unencrypted text) orWSS(for encrypted text), and type a wildcard expression in the adjacent field.
- Retain the default selectedPerform Stagingcheck box.Keep it selected so you can check for false positives before enforcing the new URL.
- For wildcard WebSocket URLs, leaveWildcard Match Includes Slashesselected.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.
- On the Message Handling tab, leaveCheck Message Payloadenabled.Based on the traffic and the selections in thePayload Enforcementsetting, theCheck Message Payloadsetting causes the system to validate the format of WebSocket messages.
- For theWebSocket Extensionslist, leave the default valueRemove Headersto 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 theSec-WebSocket-Extensionsheader from the message and allows the WebSocket to be established so messages can be exchanged.
- ForAllowed Message Payload Formats, select the format or formats that you want to enforce for WebSocket messages: clickJSONorBinary.At least one format must be selected. (Initially,Plain Textis always selected.) If you are using a different format and not verifying plain text in messages, you can clearPlain Text.
- ForPayload 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, forMaximum Binary Message Size, clickLengthand type the largest binary message (in bytes) to allow. The default value is10000bytes.
- ForMaximum Frame Size, adjust the frame size, if necessary.The default value is10000bytes.
- ForMaximum Frames per Fragmented Message, adjust the number, if necessary.The default value is100frames.
- 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.
- TheCheck characters on this URLsetting 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.)
- To specify which meta characters to allow or disallow, from theGlobal Security Policy Settingslist, select any meta characters that you want to specifically allow or disallow, and move them to theOverridden Security Policy Settingslist.
- For each meta character that you moved, set the state toAlloworDisallow.
The Overridden Security Policy Settings take precedence over the global settings for the web application character set. - If your web site uses CORS (Cross-Origin Resource Sharing), click the HTML5 Cross-Domain Request Enforcement tab.
- ForEnforcement Mode, selectEnforce on ASM.
- On the HTML5 Cross-Domain Request Enforcement tab, specify how to enforce CORS on this WebSocket URL. For details, seeSetting Up Cross-Domain Request Enforcement.
- ClickCreate.The Allowed WebSockets URLs screen opens and lists the new WebSocket URL.
- To put the security policy changes into effect immediately, clickApply Policy.
The security policy allows requests for the WebSocket URLs that you added. If the
WebSocket URL is in staging, the system informs you when learning suggestions are
available or when it is ready to be enforced.
Adjusting learning
settings for WebSocket URLs
You can adjust the policy building settings for
WebSocket URLs if you need to change how WebSocket URLs are learned, or how WebSocket
violations are handled.
- On the Main tab, click.The Learning and Blocking Settings screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- In the Policy Building Settings, expandURLsto view the settings.
- Specify how WebSocket URLs are added to the security policy inLearn New WebSocket URLs.OptionDescriptionNever (wildcard only)Do not add explicit WebSocket URLs; just use a wildcard and relax the settings if it causes false positives.SelectiveAdd explicit WebSocket URLs that do not match the attributes of the * wildcard.Add All EntitiesAdd all WebSocket URLs used on the website.
- Review theLearn,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.
- ForMaximum Learned WebSocket URLs, use the default value of10000.This option is available only if you are usingSelectiveorAdd All Entitiesfor learning.
- ClickSaveto save your settings.
- To put the security policy changes into effect immediately, clickApply Policy.
The WebSocket URL learning settings are changed.
Classifying the
content of requests to WebSocket URLs
You can instruct the system to automatically examine and classify
the content of requests to WebSocket URLs. If the system detects legitimate JSON,
plain text, or binary data in requests to URLs allowed in the security policy, the
system adds the content profiles to the security policy, and configures them using
the data found.
- On the Main tab, click.The Learning and Blocking Settings screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- In the General Settings, forLearning Mode, ensure that it is set toAutomatic.
- On the right side of the Learning and Blocking Settings screen, selectAdvanced.The screen displays the advanced configuration details for policy building.
- In the Policy Building Settings area, expandURLs.
- ForLearn New HTTP URLs, specify when the system should add explicit URLs to the security policy.
- ChooseSelectiveto add explicit URLs that do not match the * wildcard.
- ChooseAdd All Entriesto create a comprehensive whitelist of all the website URLs.
Using these options activates theClassify Client Message Payload Format of Learned WebSocket URLscheck box. - SelectClassify Client Message Payload Format of Learned WebSocket URLs.
- ClickSaveto save your settings.
- To put the security policy changes into effect immediately, clickApply Policy.
If JSON, binary, or plain text data is discovered in requests to WebSocket URLs, the
system classifies the data and makes learning suggestions regarding each format of data
(binary, JSON, and plain text). The policy suggests adding, then after examining
sufficient traffic, creates the appropriate content profiles, and adds them to the
policy.
It is useful to view the learning suggestions
regarding classification. The benefit of seeing the suggestions is being able to see
sample requests that lead the system to choose the respective payload formats.
Adding disallowed
WebSocket URLs
For some web applications, you might want to
deny requests for certain WebSocket URLs. In this case, you can create a set of
disallowed WebSocket
URLs. Disallowed
WebSocket URLs can
be explicit or a wildcard.
- On the Main tab, click.The Disallowed WebSocket URLs screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- ClickCreate.The New Disallowed WebSocket URL screen opens.
- For theWebSocket URL (Explicit only)setting, selectExplicitorWildcard. If you select Wildcard, select if to leaveWildcard Match Includes Slashesenabled (default) or to disable it.
- SelectWSorWSSas the protocol for the URL, and type the WebSocket URL that the security policy considers illegal; for example,/index.html.URLs are case-sensitive unless you cleared theSecurity Policy is case sensitiveoption when you created the policy.
- ClickCreate.The Disallowed WebSocket URLs screen opens and lists the URL.
- To put the security policy changes into effect immediately, clickApply Policy.
If a requested URL is on the disallowed WebSocket URLs list, the system ignores,
learns, logs, or blocks the request depending on the settings you configure for the
Illegal URL
violation on the Learning
and Blocking Settings screen. You can view learning suggestions for disallowed WebSocket
URLs on the Traffic Learning screen. Associating a
profile with a WebSocket URL
Before you can associate a text or JSON content profile with a WebSocket URL, you need
to have created a security policy with policy elements including WebSocket URLs, and a
text or JSON content profile.
You can associate a text or JSON content profile,
or both, with one or more existing explicit or wildcard WebSocket URLs. The associated
profiles specify the format you want to enforce for WebSocket payloads.
- On the Main tab, click.The Allowed WebSocket URLs screen opens.
- In theCurrent edited security policylist near the top of the screen, verify that the security policy shown is the one you want to work on.
- 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.
- In theAllowed Message Payload Formatssetting, selectPlain TextorJSONor both.
- For thePayload Enforcementsetting, from thePlain Text ProfileorJSON Profilelists, select the content profiles to enforce.
- ClickUpdate.
- To put the security policy changes into effect immediately, clickApply Policy.
The Plain Text and JSON profiles are associated with the WebSocket URL, and ASM
verifies the content of the messages being sent over the WebSocket connection.
Continue to associate Plain Text or JSON profiles
with any WebSocket URLs in the application that might contain unstructured text or JSON
data.
WebSocket violations
This table lists the violations that Application Security Manager
can detect in WebSocket traffic.
Violation |
Cause |
---|---|
Bad WebSocket handshake request |
A problem occurred while establishing a WebSocket connection. The request did not
comply with protocol. |
Failure in WebSocket framing protocol |
A framing protocol error occurred while parsing the message. |
Illegal cross-origin request |
The request did not come from the same origin as the traffic, and is not on the
list of allowed origins in the HTTP or WebSocket URL. |
Illegal number of frames per message |
The request contains more frames than the WebSocket URL allows. |
Illegal WebSocket binary message length |
The binary message is longer than the WebSocket URL allows. |
Illegal WebSocket extension |
The message has an extension that the WebSocket URL does not allow. |
Illegal WebSocket frame length |
The message exceeds the maximum frame size permitted by the WebSocket
URL. |
Mask not found in client frame |
The mask bit in the client frame is not set, and it needs to be. |
Null character found in WebSocket text message
|
The system found a null character in a text message having has a content
profile. |
Text content found in binary only WebSocket |
The WebSocket URL allows only binary content, but the message includes plain
text. |