URL categories and filtering status

Topic 50100 / Updated: 30-Jul-2010

Applies To:

Websense Web Filter 7.5 Websense Web Security 7.5

A command-line utility called WebsensePing is included as part of your Websense software installation. This utility can be used to:

Check URL categorization, including Master Database categorization, custom recategorization, or dynamic recategorization based on Content Gateway scanning.

Verify URL or protocol filtering behavior for a specific user, or via the Default policy.

Review current Filtering Service status and subscription count information.

Because WebsensePing does not rely on data passed from other network applications or services, it can test internal Websense processes.

This document provides instructions to help you:

Run WebsensePing and understand its most-used functions.

Find the default category for a URL or all categories for an IP address.

See how a URL is filtered for a client (user or IP address).

Tip  Administrators who prefer a graphical interface can use the TRITON - Web Security Toolbox (in the right shortcut pane) to retrieve URL category information and see what action is applied to a URL request from a specific user or IP address.

Check Filtering Service status, responsiveness, and subscription count.

Run WebsensePing

Windows:

1.	Open a command prompt on the Filtering Service machine (go to Start > Run and enter cmd).

2.	Navigate to the Websense bin directory (by default, C:\Program Files\Websense\bin).

3.	Enter the WebsensePing command with one or more additional parameters. For example:

websenseping -m 1

This command returns basic Filtering Service status information.

Linux:

1.	Open a command shell on the Filtering Service machine.

2.	Navigate to the Websense installation directory (by default, /opt/Websense).

3.	Enter the WebsenseTools -p command with one or more additional parameters. For example:

./WebsenseTools -p -m 1

This command returns basic Filtering Service status information.

The "-m" parameter, followed by a number, sends one of (currently) 15 request types to Filtering Service. In addition:

-h shows a full list of supported parameters.

-defaults lists the default values used when no other values are specified

-s, followed by an IP address or host name, sends the WebsensePing query to a Filtering Service instance on another machine. For example:

websenseping -s 10.201.67.1 -m 1

The table below describes the 3 most common WebsensePing request types with a brief overview of the information returned by each. Detailed instructions for using HTTP lookup requests and server status requests are provided in the sections that follow.

#	Request Type	Returns...
1	SERVER_STATUS_REQUEST	Filtering Service status, current subscription count, and responsiveness.
8	HTTP_LOOKUP_REQUEST (5.0+)	The destination IP address, disposition (action applied to the request), and category for a specified URL, as well as several other details, including where the block message originates, and whether: Scanning is performed for the category. The category is logged. The URL is cached Include a user or group name or a source IP address to see how the URL is categorized and filtered for the specified client.
14	DYNAMIC_HTTP_LOOKUP_ REQUEST (7.0+)	Used in Websense Web Security Gateway and Web Security Gateway Anywhere environments to retrieve HTTP lookup information (option 8), plus Content Gateway scanning information, for a selected URL.

Important  In Websense Web Security Gateway and Gateway Anywhere deployments, WebsensePing results for scanned sites may not always match the results experienced by a user. Due to the constantly changing content of some Web 2.0 sites, dynamic categorization based on content scanning can change rapidly.

Find the default category for a URL

Use the following command see how a specified URL or destination IP address is categorized, and what action is applied to site in the Default policy (shown in the Disposition line of the WebsensePing results). You can also use both the URL and destination IP address parameters in the same request.

Windows:

websenseping -m 8 -url <URL>
websenseping -m 8 -d <destinationIP>

Linux:

./WebsenseTools -p -m 8 -url <URL>
./WebsenseTools -p -m 8 -d <destinationIP>

Substitute the site that you want to test (domain name or IP address) for <URL>. For example:

./WebsenseTools -p -m 8 -url google.com

The URL is analyzed by Filtering Service, which returns a result like this:

------------------------------------------
Sending HTTP_LOOKUP_REQUEST...
------------------------------------------

URL = http://google.com
User Name =
Source IP = 0.0.0.0
Destination IP = 72.14.234.104

Disposition = CATEGORY_NOT_BLOCKED
Lookup Code = WISP_URL_OK
Category = Search Engines and Portals
Lookup Type = 0
Protocol ID = 1
Run Analytics = False
Logging Code = 1
Protocol Cache TTL = 0
URL Cache Cmd = 0
URL Cache Type = 0
URL Cache TTL = 0

Block Message =

Elapsed Time = 12 ms

AVG TIME PER REQUEST = 12 ms

See how a URL is filtered for a client

Supply a URL and a user name or IP address to see how that URL is filtered for a given client. You can also provide both the user name and client IP address parameters in the same request (for example, to help determine whether a user-based or IP address-based policy is being applied).

If your organization uses time-based policies, results may be different at different times of day.

Windows:

websenseping -m 8 -user <username> -url <URL>

websenseping -m 8 -uip <IPaddress> -url <URL>

Linux:

./WebsenseTools -p -m 8 -user <username> -url <URL>

./WebsenseTools -p -m 8 -uip <IPaddress> -url <URL>

In the following example, the user name appears in Windows NT format:

websenseping -m 8 -user winNT://Test/jdoe -url playboy.com

------------------------------------------
Sending HTTP_LOOKUP_REQUEST...
------------------------------------------

URL = http://playboy.com
User Name = winNT://Test/jdoe
Source IP = 0.0.0.0
Destination IP = 216.163.137.68

Disposition = CATEGORY_BLOCKED
Lookup Code = WISP_URL_BLOCKED
Category = Adult Content

Lookup Type = 0
Protocol ID = 1
Run Analytics = False
Logging Code = 1
Protocol Cache TTL = 0
URL Cache Cmd = 0
URL Cache Type = 0
URL Cache TTL = 0

 

Block Message = HTTP/1.0 302 Moved Location: http://10.201.67.72:15871/cgi-bin/blockpage.cgi?ws-session=687866717
Pragma: no-cache
Cache-Control: no-cache

 

Elapsed Time = 1 ms

 

AVG TIME PER REQUEST = 1 ms

In the following example, the user name appears in LDAP format, and a source IP address is also included. Providing both user name and source IP address helps to make sure that information for the correct policy is used to show how the request is filtered for the client.

The quotes around the LDAP string are required.

./WebsenseTools -p -m 8 -user "LDAP://GC OU=Technical Support,OU=US Technical Services,DC=Test,DC=com/John Doe" -uip 10.201.136.14 -url privacymania.info

------------------------------------------
Sending HTTP_LOOKUP_REQUEST...
------------------------------------------

URL = http://privacymania.info
User Name = LDAP://GC OU=Technical Support,OU=US Technical
Services,DC=Test,DC=com/John Doe
Source IP = 10.201.136.14
Destination IP = 87.118.64.84

Disposition = CATEGORY_BLOCKED
Lookup Code = WISP_URL_BLOCKED
Category = Proxy Avoidance
Lookup Type = 0
Protocol ID = 1
Run Analytics = True
Logging Code = 1
Protocol Cache TTL = 0
URL Cache Cmd = 0
URL Cache Type = 0
URL Cache TTL = 0

Block Message = HTTP/1.0 302 Moved

Location: http://10.201.67.72:15871/cgi-bin/blockpage.cgi?ws-session=687866718
Pragma: no-cache
Cache-Control: no-cache

 

Elapsed Time = 16 ms

AVG TIME PER REQUEST = 16 ms

The following example uses an IP address instead of a user name, and shows results for a URL that has been recategorized. Both URL and destination IP address information are included in the request, to improve categorization results:

websenseping -m 8 -url en.wikipedia.org -d 208.80.152.2
-uip 10.201.136.1

------------------------------------------
Sending HTTP_LOOKUP_REQUEST...
------------------------------------------

URL = http://en.wikipedia.org
User Name =
Source IP = 10.201.136.1
Destination IP = 208.80.152.2

Disposition = CATEGORY_BLOCKED_CUSTOM_DENY
Lookup Code = WISP_URL_BLOCKED
Category = Info-tainment
Lookup Type = 0
Protocol ID = 1
Run Analytics = False
Logging Code = 1
Protocol Cache TTL = 0
URL Cache Cmd = 0
URL Cache Type = 0
URL Cache TTL = 0

Block Message = HTTP/1.0 302 Moved
Location: http://10.201.67.72:15871/cgi-bin/blockpage.cgi?ws-session=687866719
Pragma: no-cache

 

Elapsed Time = 0 ms

AVG TIME PER REQUEST = 0 ms

Check Filtering Service status

Use the following command to verify that Filtering Service is able to respond to URL lookup requests. If Filtering Service does not respond, it can neither filter nor log Internet traffic.

Windows:

websenseping -m 1

Linux:

./WebsenseTools -p -m 1

The utility sends a server status request to Filtering Service. If Filtering Service is active, you receive a response like the following:

------------------------------------------
Sending SERVER_STATUS_REQUEST...
------------------------------------------
Status Code = 0
Subscription Count = 50
Elapsed Time = 3 ms
AVG TIME PER REQUEST = 3 ms

The final line (average time per requests) shows the URL filtering lookup response time for this Filtering Service instance. If the response time is less than 100 ms, Filtering Service is functional.

An alternate command can be used to see current server status, Master Database download status, and user count (number of unique IP addresses from which Internet requests have been received by Filtering Service since midnight):

websenseping -m 6 -duc

./WebsenseTools -p -m 6 -duc

Extended information about Master Database download status for all Filtering Service instances is also available in TRITON - Web Security on the Status > Today > Database Download page.