How To: Use URLScan

Article
07/14/2010

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Improving Web Application Security: Threats and Countermeasures

J.D. Meier, Alex Mackman, Michael Dunner, Srinath Vasireddy, Ray Escamilla and Anandha Murukan

Microsoft Corporation

Published: June 2003

Last Revised: January 2006

Applies to:

Internet Information Services (IIS) version 5.0
Microsoft Windows® 2000 operating system

See the "patterns & practices Security Guidance for Applications Index" for links to additional security resources.

See the Landing Page for the starting point and a complete overview of Improving Web Application Security: Threats and Countermeasures.

Applies To

This information applies to server computers that run the following:

Microsoft® Windows® 2000 Server operating system

Summary: URLScan is an ISAPI filter that allows Web site administrators to restrict the kind of HTTP requests that the server will process. By blocking specific HTTP requests, the URLScan filter prevents potentially harmful requests from reaching the server and causing damage.

Note IIS 6.0 on Windows Server 2003 has functionality equivalent to URLScan built in. Your decision whether to install UrlScan should be based on your organization's specific requirements. For more information and guidance, see "Installing UrlScan 2.5" at https://technet.microsoft.com/en-us/security/cc242650.aspx.

This How To contains the following items:

Installing URLScan Log files Removing URLScan Configuring URLScan Throttling request sizes with URLScan Debugging Microsoft Visual Studio .NET with URLScan installed Masking content headers (banners) Pitfalls Additional Resources

Installing URLScan

At the time of writing (April 2003), URLScan 2.0 is installed when you run IISLockdown (IISLockd.exe,) or you can install it independently.

Installing URLScan 2.0 with IISLockdown: You can install URLScan 2.0 as part of the IIS Lockdown Wizard (IISLockd.exe). IISLockd.exe is available as an Internet download from Microsoft's Web site at: https://download.microsoft.com/download/iis50/Utility/2.1/NT45XP/EN-US/iislockd.exe.
Installing URLScan 2.0 without running IISLockdown: To install URLScan without running IISLockdown, you need to manually extract it from the IIS Lockdown Tool. First you need to save IISLockd.exe to a directory. Then to extract the URLScan setup files, run the following command at the command line from the directory where you installed IISLockd.exe:
```
iislockd.exe /q /c
```
This unpacks URLScan.exe which is the URLScan installation program.

For more information, refer to Microsoft Knowledge Base article 315522, "How To: Extract the URLScan Tool and Lockdown Template Files from the IIS Lockdown Tool."
Installing URLScan 2.5: URLScan 2.5 is currently the latest version of URLScan. If you want to install URLScan 2.5, you first need URLScan 1.0 or URLScan 2.0.

For more information, refer to Microsoft Knowledge Base article 307608, "INFO: Availability of URLScan Version 2.5 Security Tool."
Default installation directory: The URLScan files including Urlscan.dll, URLScan.ini and URLScan logs are stored in %windir%\system32\inetsrv\urlscan. URLScan.dll is the filter. You use URLScan.ini to configure the way it works.

Log Files

URLScan creates log files that record rejected requests. Log files are located in the following folder:

%windir%\system32\inetsrv\urlscan

Log files are named using the following convention: URLScan<date>.log.

Removing URLScan

You remove URLScan manually by using the ISAPI filters page of the Web server properties dialog in Internet Services Manager

Configuring URLScan

To configure URLScan to determine which requests should be rejected, you use URLScan.ini. This is located in the following folder:

%windir%\system32\inetsrv\urlscan

For more information on how to modify the various sections in URLScan.ini, refer to Microsoft Knowledge Base article 815155 "How To: Configure URLScan to Protect ASP.NET Web Applications."

Throttling Request Sizes with URLScan

You can use URLScan as another line of defense against denial of service attacks even before requests reach ASP.NET. You do this by setting limits on the MaxAllowedContentLength, MaxUrl and MaxQueryString attributes.

To throttle the request sizes, add the following configuration to URLScan.ini:

[RequestLimits]
; The entries in this section impose limits on the length
; of allowed parts of requests reaching the server.
;MaxAllowedContentLength=2000000000
;MaxUrl=16384
;MaxQueryString=4096

Debugging VS .NET with URLScan Installed

By default, URLScan does not allow the DEBUG verb. Therefore, when you use VS.NET to debug a Web application on a server where URLScan is installed, you may see the following error:

Microsoft Development Environment:
Error while trying to run project: Unable to start debugging on the web server. Could not start ASP.NET or ATL Server debugging.

Verify that ASP.NET or ATL Server is correctly installed on the server. Would you like to disable future attempts to debug ASP.NET pages for this project? Yes   No   Help

Your URLScan log file will also contain an entry similar to the following:

[01-18-2003 - 22:25:26] Client at 127.0.0.1: Sent verb 'DEBUG', which is not specifically allowed. Request will be rejected.

To support debugging, add DEBUG to the AllowVerbs section in URLScan.ini as shown below:

[AllowVerbs]
GET
HEAD
POST
DEBUG

Note You need to restart IIS for changes to take effect.

Masking Content Headers (Banners)

To prevent banner information that reveals the type and version of your Web server, locate the RemoveServerHeader attribute in URLScan.ini, and set its value to 1 as shown below.

RemoveServerHeader=1

For more information, see Microsoft Knowledge Base article, 317741, "How To: Mask IIS Version Information from Network Trace and Telnet."

Pitfalls

If you use URLScan, you might run into the following issues:

URLScan blocks the DEBUG verb which breaks application debugging. If you need to support debugging, add the DEBUG verb to the [AllowVerbs] section in URLScan.ini.
You need to recycle IIS for changes to take effect. URLScan is an ISAPI filter that runs inside the IIS process (Inetinfo.exe) and URLScan's options are loaded from URLScan.ini when IIS starts up. You can run the IISReset command from a command prompt to recycle IIS.
URLScan blocks requests that contain potentially harmful characters, for example, characters that have been used to exploit vulnerabilities in the past such as "." used for directory traversal. It is not recommended that project paths contain the "." character. If you must allow this, you need to set AllowDotInPath=1 in URLScan.ini.

If your Web application directories include dots in the path, for example, a directory containing the name "Asp.Net", then URLScan will reject the request and a "404 not found" message will be returned to the client.

Other characters to avoid in project names because they will be rejected by URLScan include comma (,) and the pound sign (#).

Additional Resources

For additional information, refer to the following resources:

For more information about how to modify the various sections in Urlscan.ini, refer to Microsoft Knowledge Base article 815155 "How To: Configure URLScan to Protect ASP.NET Web Applications."
For more information about URLScan 2.5, refer to Microsoft Knowledge Base article 307608, "INFO: Availability of URLScan Version 2.5 Security Tool."

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.