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. |
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 .
-
Click Create.
The New WebSocket Profile screen opens.
-
In the Name field, type a name for the WebSocket
profile.
-
Select the Custom check box at the right so you can edit
the screen.
-
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. |
-
Click Finished.
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.
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.
Note: The system supports JSON in UTF-8 and UTF-16
encoding. WebSocket allows only UTF-8.
-
On the Main tab, click
.
-
Click Create.
The Create New JSON Profile screen opens.
-
Type the name of the profile.
-
Adjust the maximum values that define the JSON data for the AJAX application,
or use the default values.
-
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 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.
-
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.
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.
-
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.
-
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.
-
Click Create.
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 the Current edited policy list near the top of the screen,
verify that the edited security policy is the one you want to work on.
-
Click Create.
The Create New Plain Text Profile screen opens.
-
For Profile 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 the Check attack signatures check box.
Otherwise, leave it selected and the system will use the attack
signatures to look for threats.
-
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.
-
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.
-
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 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.
-
Click Create.
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.
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 the Current edited policy list near the top of the screen,
verify that the edited security policy is the one you want to work on.
-
In the General Settings, for Learning Mode, ensure that
it is set to Automatic.
-
On the right side of the Learning and Blocking Settings screen, select
Advanced.
The screen displays the advanced configuration details for policy
building.
-
In the Policy Building Settings area, expand URLs.
-
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.
-
Select Classify Client Message Payload Format of Learned WebSocket
URLs.
-
Click Save to save your settings.
-
To put the security policy changes into effect immediately, click Apply
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.
-
On the Main tab, click .
The Disallowed WebSocket URLs screen opens.
-
In the Current edited policy list near the top of the screen,
verify that the edited security policy is the one you want to work on.
-
Click Create.
The New Disallowed WebSocket URL screen opens.
-
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.
-
Click Create.
The Disallowed WebSocket URLs screen opens and lists the
URL.
-
To put the security policy changes into effect immediately, click Apply
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 the Current edited policy list near the top of the screen,
verify that the edited security policy 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 the Allowed Message Payload Formats setting, select
Plain Text or JSON or both.
-
For the Payload Enforcement setting, from the
Plain Text Profile or JSON
Profile lists, select the content profiles to enforce.
-
Click Update.
-
To put the security policy changes into effect immediately, click Apply
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.