UrlScan 2 Reference

By Robert McMurray

July 15, 2010

Note: UrlScan 2.x has been replaced by UrlScan 3.1. If you are using UrlScan 2.x, you should download and install the latest version. The information on this page is presented for reference purposes.

Microsoft released UrlScan 2.0 and UrlScan 2.1 as part of the IIS Lockdown Tool, which was a more comprehensive approach to reducing the surface attack area for Web servers that used IIS versions 4.0, 5.0, and 5.1. The IIS Lockdown Tool was a wizard that server administrators would use to customize the content types, script mapping, system permissions, and virtual directories that their Web servers will use. The IIS Lockdown included the option to install UrlScan as an additional security measure, and included several configuration templates for UrlScan that addressed several installation environments for IIS, such as installing IIS with Exchange Server, BizTalk Server, and SharePoint.

Microsoft later released UrlScan 2.5 as a separate download, which added request limits to the list of features. Request limits allow administrators to configure the maximum size for request elements, such as content length, URLs, and query strings.

On This Page

Installing UrlScan 2.x

Installing UrlScan 2.0 or UrlScan 2.1

UrlScan 2.0 and UrlScan 2.1 are installed as part of the IIS Lockdown Tool.

For more information about installing the IIS Lockdown Tool, see the IIS Lockdown Tool download pages at the following URL:

http://www.microsoft.com/downloads/details.aspx?FamilyID=dde9efc0-bb30-47eb-9a61-fd755d23cdec

Installing UrlScan 2.5

UrlScan 2.5 installs as a clean install on a computer running IIS 5.1 or later. Upgrade scenarios are also supported.

To Install UrlScan 2.5

  1. Download the Setup.exe file for UrlScan 2.5 from the following URL to your computer:
    http://www.microsoft.com/downloads/details.aspx?familyid=23d18937-dd7e-4613-9928-7f94ef1c902a
  2. Double-click the Setup.exe icon to begin the installation process.
  3. Review the agreement in the UrlScan Installer Package End User Agreement and then click Yes to accept the agreement and continue. If you click No, the installer will close.
  4. When the installer completes, the following message is displayed: "UrlScan has been successfully installed." Click OK to close the installer.

To Uninstall UrlScan

  1. In Control Panel, double-click Add or Remove Programs.
  2. Select UrlScan 2.5 and then click the Change/Remove button.
  3. When UrlScan 2.5 has been removed from your server, the following message is displayed: "UrlScan has been successfully uninstalled."
  4. Click OK to complete the uninstall process.

Understanding the UrlScan 2.5 Installer

When installing UrlScan 2.5, the UrlScan 2.5 installer does the following:

  • Installs the UrlScan.dll and UrlScan.ini files in the %windir%\system32\inetsrv\UrlScan directory. If UrlScan is already installed on the computer, the UrlScan.ini file is updated with any new settings that are not present in the current configuration file.
  • Adds UrlScan as a global filter to IIS.
  • Creates a %windir%\system32\inetsrv\UrlScan\Logs directory.

When installing UrlScan on a server running IIS 6.0, the UrlScan 2.5 installer makes some additional changes that enable UrlScan 2.5 to work with the new IIS 6.0 process model. These changes are as follows:

  • PerProcessLogging is set to 1 in the UrlScan.ini file. This ensures that two UrlScan processes do not write to the log file at the same time.
  • UrlScan is marked as cache-aware in the metabase. This ensures that two or more worker processes that are running UrlScan do not write to the log file at the same time.
  • The new log directory, which is a subdirectory located under the ..\inetsrv\UrlScan directory, ensures that the UrlScan directory does not get cluttered with all of the log files that the PerProcessLogging option will create.

When installing UrlScan 2.5 on IIS, the installer sets permissions for UrlScan.dll, UrlScan.ini, and the log file. When installing UrlScan 2.5 on IIS 6.0, the installer sets additional permissions on the same files to allow UrlScan 2.5 to work with IIS 6.0 worker process isolation mode. Table 2 lists the IIS permissions that are set when UrlScan 2.5 is installed.

Table 2: UrlScan 2.5 IIS 6.0 Permissions

File/Directory Permissions
..\inetsrv\UrlScan\UrlScan.dll Read and Execute (set on IIS 6.0 only): LocalService, IIS_WPG, and NetworkService
Full: Administrators, and LocalSystem
..\inetsrv\UrlScan\UrlScan.ini Read (set on IIS 6.0 only): IIS_WPG, LocalService, and NetworkService
Full: Administrators, and LocalSystem
..\inetsrv\UrlScan\logs Read and Write (set on IIS 6.0 only): IIS_WPG, LocalService, and NetworkService
Full: Administrators, and LocalSystem

If a version of UrlScan is detected on the computer, the installation will be considered an upgrade. In the upgrade scenario, the changes that the installer makes will be the same as for a clean installation unless you have configured a custom log directory. If you have defined a different location for the UrlScan logs, then the new logs directory will not be created.

Using UrlScan 2.x

You configure UrlScan's operation by setting options in the UrlScan.ini file. This file should reside in the same directory as UrlScan.dll, and it contains the sections and options that are listed below.

Note: For performance reasons, UrlScan only reads the UrlScan.ini file when IIS first loads the ISAPI filter. If you make changes to the UrlScan.ini file, you will need to stop and start the World-Wide-Web Publishing Service before your changes will be effective.

Warning: The default options built into UrlScan.dll will result in a configuration that will reject all requests to the server, therefore it is necessary to provide a UrlScan.ini file for IIS to serve HTTP requests when you are using UrlScan. A sample UrlScan.ini file is provided that contains the recommended settings to defend against known attacks against IIS servers at the time of writing.

UrlScan.ini Sections

[Options] Section

The [Options] section of a UrlScan.ini file contains a list of name/value pairs that define the general behavior for UrlScan. A few of the settings enable or disable other sections in the UrlScan.ini file.

Enabling or Disabling other UrlScan.ini Sections

UseAllowVerbs Allowed values are 0 or 1. The default value for UseAllowVerbs is 1.

If set to 1, UrlScan will read the [AllowVerbs] section of the UrlScan.ini file and reject any request containing an HTTP verb that is not explicitly listed.

If set to 0, UrlScan will read the [DenyVerbs] section of the UrlScan.ini file and reject any request containing an HTTP verb listed.

Note: The [AllowVerbs] section is case sensitive, but the [DenyVerbs] section is not case sensitive.
UseAllowExtensions Allowed values are 0 or 1. The default value for UseAllowExtensions is 1.

If set to 1, UrlScan will read the [AllowExtensions] section of the UrlScan.ini file and reject any request where the file name extension associated with the URL is not explicitly listed.

If set to 0, UrlScan will read the [DenyExtensions] section of the UrlScan.ini file and reject any request where the file name extension associated with the request is listed.

Note: The [AllowExtensions] and [DenyExtensions] sections are both case insensitive.

URL Scanning Options

NormalizeUrlBeforeScan Allowed values are 0 or 1. The default value for NormalizeUrlBeforeScan is 1.

If set to 1, UrlScan will do all of its analysis on the request URLs after IIS decodes and normalizes them.

If set to 0, UrlScan will do all of its analysis on the raw URLs as sent by the client.

Note: Only advanced administrators who are very knowledgeable about URL parsing should set this option to 0, as doing so will likely expose the IIS server to canonicalization attacks that bypass proper analysis of the URL extensions.
VerifyNormalization Allowed values are 0 or 1. The Default value for VerifyNormalization is 1.

If set to 1, UrlScan verifies normalization of the URL. This action will defend against canonicalization attacks, where a URL contains a double encoded string in the URL. For example, the string "%252e" is a double encoded dot '.' character because "%25" decodes to a '%' character, the first pass decoding of "%252e" results in "%2e", which can be decoded a second time into a single dot '.' string.

If set to 0, then UrlScan will not verify normalization of the URL.

Note: This option is dependent on the NormalizeUrlBeforeScan option.
AllowHighBitCharacters Allowed values are 0 or 1. The default value for AllowHighBitCharacters is 1.

If set to 1, then UrlScan will allow any byte to exist in the URL.

If set to 0, UrlScan will reject any request where the URL contains a character outside of the ASCII character set.

Note: This feature can defend against UNICODE or UTF-8 based attacks, but will also reject legitimate requests on IIS servers that use a non-ASCII code page.
AllowDotInPath Allowed values are 0 or 1. The default value for AllowDotInPath is 1.

If set to 1, UrlScan will allow requests that contain multiple instances of the dot (.) character in the URL.

If set to 0, UrlScan will reject requests that contain multiple instances of the dot (.) character in the URL.

Note: Because UrlScan operates at a level where IIS has not yet parsed the URL, it is not possible to determine in all cases whether a dot character denotes the extension or whether it is a part of the directory path or filename of the URL. For the purposes of extension analysis, UrlScan will always assume that an extension is the part of the URL beginning after the last dot in the string and ending at the first question mark or slash character after the dot or the end of the string. Setting AllowDotInPath to 0 defends against the case where an attacker uses path info to hide the true extension of the request (for example, something like "/path/TruePart.asp/FalsePart.htm"). Setting AllowDotInPath to 0 also causes UrlScan to deny any request that contains a dot in a directory or file name.
AllowLateScanning Allowed values are 0 or 1. The default value for AllowLateScanning is 0.

If set to 1, UrlScan will register itself as a low priority filter. This will allow other ISAPI filters to modify the URL before UrlScan performs any analysis.

If set to 0, UrlScan runs as a high priority filter.

Note: In addition to the value of AllowLateScanning, it may be necessary to ensure that UrlScan is listed lower on the list of ISAPI filters for the server. For example, the FrontPage Server Extensions require that AllowLateScanning is set to 1 and that UrlScan is lower on the filter load order list than the Fpexedll.dll ISAPI filter.

Note: This feature was introduced in UrlScan 2.0.
UseFastPathReject Allowed values are 0 or 1. The default value for UseFastPathReject is 0.

If set to 1, UrlScan will return a short 404 response to the client in cases where it rejects a request.

Note: Using UseFastPathReject is faster than using the RejectResponseUrl option, but IIS cannot return a custom 404 response or log many parts of the request into the IIS log, even though the UrlScan log file will contain complete information about the rejected request.

Note: This feature was introduced in UrlScan 2.0.
RejectResponseUrl Allowed value is a string. The default value for RejectResponseUrl is /<Rejected-By-UrlScan>.

The value for RejectResponseUrl is a URL in the form "/path/filename.ext". When UrlScan rejects a request, it will process the specified URL, which needs to be local to the Web site for the request that is being analyzed by UrlScan. The specified URL can have the same extension as the rejected URL; for example, ".asp".

Note: UrlScan creates the following server variables that can be used by the specified URL in determining the nature of the rejected request and to allow flexibility in returning the actual response to the client:
  • HTTP_UrlScan_STATUS_HEADER - Contains the reason the request is being rejected.
  • HTTP_UrlScan_ORIGINAL_VERB - Contains the original verb from the request that is being rejected.
  • HTTP_UrlScan_ORIGINAL_URL - Contains the original URL from the request that is being rejected.
UrlScan appends the URL of the request that is being rejected as a query string to the location specified by RejectReponseUrl. If IIS is configured to log request query strings, the URL of the rejected request can be found in the IIS log in addition to the UrlScan log.

There is a special value for RejectResponseUrl that can be used to put UrlScan into "Logging Only Mode." If you set the value of RejectResponseUrl to /~*, UrlScan performs all of the configured scanning and logs the results, however, it will allow IIS to serve the page even if it would normally be rejected. This mode is useful if you would like to test UrlScan.ini settings without actually rejecting any requests, and the log entries in the UrlScan log file will indicate that requests are not being rejected.

Note: This feature was introduced in UrlScan 2.0.

Logging Options

EnableLogging Allowed values are 0 or 1. The default value for EnableLogging is 1.

If set to 1, UrlScan will log its actions in a file called UrlScan.log that will be created in the same directory that contains UrlScan.dll.

If set to 0, UrlScan will not log any activity.
PerProcessLogging Allowed values are 0 or 1. The default value of PerProcessLogging is 0.

If set to 1, UrlScan will append the process ID of the IIS process that is hosting UrlScan.dll to the log file name; for example, UrlScan.1234.log. This feature is helpful for IIS versions that can host filters in more than 1 process concurrently, such as IIS 6.0 and later.

If set to 0, UrlScan will log all activity in UrlScan.log.
PerDayLogging Allowed values are 0 or 1. The default value of PerDayLogging is 1.

If set to 1, UrlScan creates a new log file each day and appends a date to the log file name; for example, UrlScan.101501.log.

If set to 0, UrlScan opens a single file called UrlScan.log, or UrlScan.nnnn.log, where nnnn is the process ID when PerProcessLogging is set to 1.

Note: When PerDayLogging is set to 1, a log file is created for the current day when the first log entry is written for that day. If no UrlScan activity occurs, a log file will not be created for that day. If both PerDayLogging and PerProcessLogging are set to 1, the log file name contains the date and a process ID in the name; for example, UrlScan.101501.123.log.

Note: This feature was introduced in UrlScan 2.0.
LogLongUrls Allowed values are 0 or 1. The default value of LogLongUrls is 0.

If set to 1, then URLs up to 128 KB per request can be logged.

If set to 0, then only URLs up to 1 KB is allowed per request.

Note: This feature was introduced in UrlScan 2.5.

LoggingDirectory Allowed value is a string. The default value for LoggingDirectory is C:\WINDOWS\system32\inetsrv\UrlScan\logs.

Use LoggingDirectory to specify the absolute path to the directory where the UrlScan log files will be created. If you do not specify a path, UrlScan will create log files in the same directory where the UrlScan.dll file is located.

Note: This feature was introduced in UrlScan 2.5.

HTTP Server Header Manipulation

RemoveServerHeader Allowed values are 0 or 1. The default value for RemoveServerHeader is 1.

If set to 1, UrlScan will remove the server header on all responses, and the value of AlternateServerName will be ignored.

If set to 0, IIS will return the default server header on all responses.

Note: This feature is only available if UrlScan is installed on IIS 4.0 or later.
AlternateServerName Allowed value is a string. The default value for AlternateServerName is an empty string.

If you specify a value for AlternateServerName and RemoveServerHeader is set to 0, then IIS will replace its default "Server:" header in all responses with the AlternateServerName value. If RemoveServerHeader is set to 1, the value of AlternateServerName will be ignored.

Note: This feature is only available if UrlScan is installed on IIS 4.0 or later.
Example [Options] Section

The following example [Options] section configures several recommended settings for UrlScan:

[Options]
UseAllowVerbs=1          ; Use the [AllowVerbs] section.
UseAllowExtensions=0     ; Use the [DenyExtensions] section.
NormalizeUrlBeforeScan=1 ; Normalize a URL before processing.
VerifyNormalization=1    ; Normalize a URL twice and reject request if a change occurs.
AllowHighBitCharacters=0 ; Deny high bit characters in URL.
AllowDotInPath=0         ; Deny dots that are not file name extensions.
RemoveServerHeader=0     ; Do not remove the "Server" header from response.
EnableLogging=1          ; Log UrlScan activity.
PerProcessLogging=0      ; Do not create log files for each process.
AllowLateScanning=0      ; Load UrlScan as a high priority filter.
PerDayLogging=1          ; UrlScan will create a new log file each day.
RejectResponseUrl=       ; Default is /<Rejected-by-UrlScan>
UseFastPathReject=0      ; Use the RejectResponseUrl or allow IIS to log the request.
LogLongUrls=1            ; Log URLs up to 128 KB per request.

[AllowVerbs] Section

The [AllowVerbs] section contains a list of HTTP verbs or methods. If UseAllowVerbs is set to 1 in the [Options] section, UrlScan will reject any request that contains an HTTP verb that is not explicitly listed in this section. The entries in this section are case sensitive.

Example [AllowVerbs] Section

The following example [AllowVerbs] section configures UrlScan to allow basic HTTP functionality:

[AllowVerbs]
HEAD      ; Allow HTTP feature discovery.
GET       ; Allow most HTTP requests.
POST      ; Allow posting data to applications.
OPTIONS   ; Allow HTTP feature discovery.

To use this example, you would need to set UseAllowVerbs to 1 in the [Options] section.

[DenyVerbs] Section

The [DenyVerbs] section contains a list of HTTP verbs or methods. If UseAllowVerbs is set to 0 in the [Options] section, UrlScan will reject any request that contains a a verb that is listed in this section. The entries in this section are not case sensitive.

Example [DenyVerbs] Section

The following example [DenyVerbs] section configures UrlScan to deny several of the HTTP methods that are not required for basic HTTP functionality, such as WebDAV methods:

[DenyVerbs]
TRACE     ; Deny HTTP tracing.
PUT       ; Deny uploading files.
DELETE    ; Deny deleting files.
MKCOL     ; Deny creating folders/collections.
COPY      ; Deny copying files.
MOVE      ; Deny moving files.
LOCK      ; Deny locking resources.
UNLOCK    ; Deny unlocking resources.
PROPFIND  ; Deny property queries.
PROPPATCH ; Deny setting properties.
SEARCH    ; Deny protocol-based searches.

To use this example, you would need to set UseAllowVerbs to 0 in the [Options] section.

[DenyHeaders] Section

The [DenyHeaders] section contains a list of request headers in the form "header-name:". Any request containing a request header listed in this section will be rejected. The entries in this section are not case sensitive.

Example [DenyHeaders] Section

The following example [DenyHeaders] section configures UrlScan to deny several HTTP headers that are used with WebDAV requests:

[DenyHeaders]
Translate:  ; Allow HTTP feature discovery.
If:         ; Allow most HTTP requests.
Lock-Token: ; Allow posting data to applications.

[AllowExtensions] Section

The [AllowExtensions] section contains a list of file name extensions in the form of ".ext". If UseAllowExtensions=1 is set in the [Options] section, then any request containing a URL with an extension not explicitly listed here is rejected. The entries in this section are not case sensitive.

Example [AllowExtensions] Section

The following example [AllowExtensions] section configures UrlScan to allow several static content types:

[AllowExtensions]
.htm    ; Allow HTML files.
.html   ; Allow HTML files.
.txt    ; Allow text files.
.jpg    ; Allow JPEG graphics.
.jpeg   ; Allow JPEG graphics.
.gif    ; Allow GIF graphics.

To use this example, you would need to set UseAllowExtensions to 1 in the [Options] section.

[DenyExtensions] Section

The [DenyExtensions] section contains a list of file name extensions in the form of ".ext". If UseAllowExtensions=0 is set in the [Options] section, then any request containing a URL with an extension listed here is rejected. The entries in this section are not case sensitive.

Example [DenyExtensions] Section

The following example [DenyExtensions] section configures UrlScan to allow several static content types:

[DenyExtensions]
.asp     ; Deny ASP requests.
.asa     ; Deny ASA requests.
.inc     ; Deny include files.
.cdx     ; Deny certificate requests.
.cer     ; Deny certificate requests.
.config  ; Deny configuration files.
.exe     ; Deny executable files.
.bat     ; Deny batch files.
.cmd     ; Deny batch files.
.com     ; Deny executable files.
.htw     ; Deny Index Server hit highlighting.
.ida     ; Deny HTTP-based Index Server administration.
.idq     ; Deny Index Server queries.
.htr     ; Deny legacy IIS password changing requests.
.idc     ; Deny legacy database access requests.
.shtm    ; Deny Server Side Includes.
.shtml   ; Deny Server Side Includes.
.stm     ; Deny Server Side Includes.
.printer ; Deny Internet-based printing.
.ini     ; Deny configuration files.
.log     ; Deny log files.
.pol     ; Deny policy files.
.dat     ; Deny configuration files.
.mdb     ; Deny Microsoft Access databases.
.ldb     ; Deny Microsoft Access lock files.
.mdf     ; Deny Microsoft SQL databases.
.ldf     ; Deny Microsoft SQL log files.

To use this example, you would need to set UseAllowExtensions to 0 in the [Options] section.

[DenyUrlSequences] Section

The [DenyUrlSequences] section contains a list of character sequences that UrlScan will deny if they appear in a URL. For example, two dots ".." indicate a parent path, which a hacker might try to use to gain access to files outside of a Web site's content area.

Example [DenyUrlSequences] Section

The following example [DenyUrlSequences] section configures UrlScan to deny several URL sequences that could be used to attack your server:

[DenyUrlSequences]
..    ; Deny directory traversals.
./    ; Deny trailing dot on a directory name.
\     ; Deny backslashes in URL.
:     ; Deny access to alternate streams.
%     ; Deny escaping after normalization.
&     ; Deny running multiple CGI processes on a single request.

[RequestLimits] Section

The [RequestLimits] section impose limits on the length of user-defined parts of HTTP requests, such as the maximum content length or maximum URL length for HTTP requests.

Note: This feature was introduced in UrlScan 2.5.

You can specify the maximum length of the value for a specific request header by adding "Max-" to the name of the header. For example, the following entry would impose a limit of 100 bytes to the value of the 'Content-Type' header:

Max-Content-Type=100

To list a header and not specify a maximum value, use 0. For example, "Max-User-Agent=0". Note: Any HTTP request headers that are not listed in this section will not be checked for length limits.

The [RequestLimits] section can contain the following three special-case limits:

MaxAllowedContentLength Specifies the maximum allowed numeric value, in bytes, of the Content-Length request header. For example, setting this to 1000 would cause any request with a content length that exceeds 1000 to be rejected.

The default value for MaxAllowedContentLength is 30000000.
MaxUrl Specifies the maximum length, in bytes, of the request URL, not including the query string.

The default value for MaxUrl is 260, which is equivalent to the MAX_PATH constant.
MaxQueryString Specifies the maximum length, in bytes, of the query string.

The default value for MaxQueryString is 4096.
Example [RequestLimits] Section

The following example [RequestLimits] section configures UrlScan to specify the maximum lengths for several HTTP headers and the maximum content length for a request:

[RequestLimits]
MaxAllowedContentLength=30000000
MaxUrl=1024
MaxQueryString=2048
Max-User-Agent=1024



Discuss in IIS Forums