About URLScan.ini

  • Article
Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The URLScan Web filter screens all incoming Web requests, in accordance with the settings configured in the URLScan.ini configuration file. This page details the sections in the URLScan.ini file.

The URLScan.ini file contains the following sections:

  • [Options]. This section describes general URLScan options.

  • [AllowExtensions] and [DenyExtensions]. This section defines the file name extensions that URLScan permits.

  • [AllowVerbs] and [DenyVerbs]. This section defines the verbs (also known as HTTP methods) that URLScan permits.

  • [DenyHeaders]. This section lists HTTP headers that are not permitted in an HTTP request. If an HTTP request contains one of the HTTP headers that are listed in this section, URLScan rejects the request.

  • [DenyURLSequences]. This section lists strings that are not permitted in an HTTP request. URLScan rejects HTTP requests that contain a string that appears in this section.

  • [RequestLimits] section. This section enforces limits on the size, in bytes, of separate parts of requests reaching the server.

Caution

Incorrectly editing the URLScan.ini file may severely damage your ISA Server configuration. Before making changes to this file, back up the original version.

[Options] section

In the [Options] section, you can configure a number of URLScan options. Each line in this section has the following format:

OptionName=OptionValue

Note that if the NormalizeUrlBeforeScan option is enabled, then the URL is always normalized, and scanning is performed on the normalized URL. See below in for more information on the NormalizeUrlBeforeScan option.

The available options and their default values are as follows:

  • AllowDotInPath=0
    By default, this option is set to 0. If this option is set to 0, URLScan rejects any request that contains multiple periods (.). This prevents attempts to disguise requests for dangerous file name extensions by putting a safe file name extension in the path information or query string portion of the URL. For example, if this option is set to 1, URLScan might permit a request for https://servername/BadFile.exe/SafeFile.htm because it interprets it as a request for an HTML page, when it is actually a request for an executable (.exe) file with the name of an HTML page in the PATH_INFO area. When this option is set to 0, URLScan may also deny requests for directories that contain periods.

  • AllowHighBitCharacters=0
    By default, this option is set to 0. If this option is set to 0, URLScan rejects any requests that contain non-ASCII characters. This can prevent certain types of attacks, but it may also block requests for certain legitimate files, such as files with non-English names.

  • AllowLateScanning=0
    On IIS Server, this option determines the priority of the URLScan Web filter. On ISA Server, the URLScan Web filter is installed with high priority. ISA Server processes all high-priority filters first, in the order specified in ISA Management.

  • AlternateServerName=(not specified by default)
    You can specify a string in the AlternateServerName option to specify what will be passed back in the Server header — for example, when returning an 403 - Access Denied error page.
    This option is applicable only if ISA Server generates the response.

  • EnableLogging=1
    By default, this option is set to 1. If this option is set to 1, URLScan keeps a complete log of all blocked requests in the ISA Server installation folder. You can set EnableLogging to 0 if you do not want to keep this log.

  • LoggingDirectory=(not specified by default)
    The LoggingDirectory option is used to specify the folder where the log file is stored. This value must be the absolute path (for example, c:\directory_path). By default, the log is created in the same folder where UrlScan.dll is located.
    This option is not included in the configuration files installed with the URLScan Web filter.

  • LogLongURLs=0
    The LogLongUrls option specifies the length of URLs that are logged. Allowed values are 0 or 1. The default value is 0. If you set the value to 1, up to 128 kilobytes per request are logged. If you set the value to 0, log entries contain only the first 1024 bytes of the request.

  • NormalizeUrlBeforeScan=1
    ISA Server receives requests that are URL encoded. This means that certain characters may be replaced with a percent sign (%) followed by a particular number. For example, %20 corresponds to a space, so a request for https://myserver/My%20Dir/My%20File.htm is the same as a request for https://myserver/My Dir/My File.htm. Normalization is the process of decoding URL-encoded requests. By default, this option is set to 1. If the NormalizeUrlBeforeScan option is set to 1, URLScan analyzes the decoded request. If it is set to 0, URLScan analyzes the undecoded request instead. Setting this option to 0 hinders the ability of URLScan to block certain kinds of attacks.

  • PerDayLogging=1
    By default, this option is set to 1. If this option is set to 1, URLScan creates a new log file each day. Each log file is named Urlscan.MMDDYY.log, where MMDDYY is the date of the log file. If this value is set to 0, all logging is saved in the same file, regardless of the date.

  • PerProcessLogging=0
    By default, this option is set to 0. If this option is set to 0, all processes log to the same file. If this option is set to 1, URLScan creates a separate log for each process that hosts URLScan.dll.
    A new log is created each time the Web Proxy service is restarted.

  • RejectResponseUrl=(not specified by default)
    This option specifies an alternate URL used when URLScan blocks a request. This permits you to customize the response that is sent to the client for blocked requests. You must specify RejectResponseUrl as a virtual path to the appropriate file, such as /Path/To/RejectResponseHandler.asp. You can specify a file that URLScan typically blocks, such as an Active Server Pages (ASP) page.
    The ASP page can contain references to the following server variables:

    • HTTP_URLSCAN_STATUS_HEADER: This specifies why the request has been blocked.

    • HTTP_URLSCAN_ORIGINAL_VERB: This specifies the original verb from the blocked request (for example, GET, POST, HEAD, or DEBUG).

    • HTTP_URLSCAN_ORIGINAL_URL: This specifies the original URL from the blocked request.

    If you set RejectResponseUrl to the special value of /~*, URLScan uses logging-only mode. This permits the requests to be passed on to the published server, while also adding an entry to the URLScan log for any requests that are typically blocked. This is useful if you want to test your URLScan.ini file.
    If you do not specify a value for RejectResponseUrl, URLScan uses the default value of /<Rejected-By-UrlScan>.

  • UseAllowVerbs=1
    By default, this option is set to 1. If this option is set to 1, URLScan only permits HTTP requests that use the verbs that are listed in the [AllowVerbs] section. URLScan blocks any requests that do not use these verbs. If this option is set to 0, URLScan ignores the [AllowVerbs] section, and instead blocks only requests that use verbs that are listed in the [DenyVerbs] section.

  • UseAllowExtensions=0
    By default, this option is set to 0. If this option is set to 0, URLScan blocks requests for file name extensions that are listed in the [DenyExtensions] section, but permits requests for any other file name extensions. If this option is set to 1, URLScan only permits requests for files with extensions that are listed in the [AllowExtensions] section, and it blocks requests for any other files.

  • UseFastPathReject=1
    By default, this option is set to 1. If this option is set to 1, URLScan ignores the RejectResponseUrl setting and immediately returns a 500 error message to the browser. This is faster than processing RejectResponseUrl, but it does not permit as many logging options. The Web Proxy log includes the original request, while the URLScan log includes the reason for the rejection. When this option is set to 1, for requests that are blocked, AlternateServerName causes the "Server:" header in the 500 error response to be removed or replaced with the string entered for AlternateServerName, as appropriate. For requests that are not blocked by the URLScan Web filter, the "Server:" header is not affected.
    If this option is set to 0, then a URL is set to the published Web server, as determined by the Web publishing rule. By default, the following URL is sent: "/<Rejected-By-UrlScan> ~/", along with the original URL. The IIS server then replies with an HTTP error code of 404 (file not found). In this case, the Web Proxy service logs the following entry: https://<isaserver>//<Rejected-By-UrlScan> ~/ original URL error 404.
    It is recommended to set UseFastPathReject to 1. When UseFastPathReject is set to 1, the Web Proxy log file generated by ISA Server will log the original request that was blocked, along with the external IP address of the offending client. ISA Server will also prevent that invalid request from generating any additional network traffic on the internal network.

  • VerifyNormalization=1
    Because the percent sign (%) itself can be URL encoded, an attacker can submit a request to a server that is, for example, multiple-encoded. If this occurs, ISA Server may accept a request that it would otherwise reject as not valid. By default, this option is set to 1. If the VerifyNormalization option is set to 1, URLScan normalizes the URL twice. If the URL after the first normalization is different from the URL after the second normalization, URLScan rejects the request. This prevents attacks that rely on multiple-encoded requests.

[AllowExtensions] and [DenyExtensions] sections

Most files have a file name extension that identifies the type of file. For example, file names for Word documents typically end in .doc, HTML file names typically end in .htm or .html, and plain text file names typically end in .txt. The [AllowExtensions] and [DenyExtensions] sections permit you to define extensions that URLScan will block. For example, you can configure URLScan to reject requests for .exe files to prevent Web users from executing applications on your system.

Both the [AllowExtensions] and the [DenyExtensions] sections have the same syntax. They consist of a list of file name extensions, and each extension appears on its own line. The extension starts with a period (.) — for example, .ext.

URLScan determines which section to use based on the value of UseAllowExtensions in the [Options] section. By default, this option is set to 0. If UseAllowExtensions is set to 0, URLScan only denies requests for file name extensions that are listed in the [DenyExtensions] section. Any file name extensions that are not listed in this section are permitted. The [AllowExtensions] section is ignored.

If UseAllowExtensions is set to 1, URLScan denies requests for any file name extensions that are not explicitly listed in the [AllowExtensions] section. Only requests for a file name extension that is listed in that section are permitted. The [DenyExtensions] section is ignored.

[AllowVerbs] and [DenyVerbs] sections

The [AllowVerbs] and [DenyVerbs] sections define the HTTP verbs (also known as methods) that URLScan permits. Common HTTP verbs include GET, POST, HEAD, and PUT. Other applications, such as FPSE and Web Distributed Authoring and Versioning (WebDAV), use additional verbs.

Both the [AllowVerbs] and the [DenyVerbs] sections have the same syntax. They consist of a list of HTTP verbs, and each verb appears on its own line.

URLScan determines which section to use based on the value of the UseAllowVerbs option in the [Options] section. By default, this option is set to 1. If UseAllowVerbs is set to 1, URLScan only permits requests that use the verbs that are listed in the [AllowVerbs] section. A request that does not use one of these verbs is rejected. In this case, the [DenyVerbs] section is ignored.

If UseAllowVerbs is set to 0, URLScan denies requests that use verbs that are explicitly listed in the [DenyVerbs] section. Any requests that use verbs that do not appear in this section are permitted. In this case, URLScan ignores the [AllowVerbs] section.

[DenyHeaders] section

When a client requests a page from a Web server, it typically sends HTTP headers that contain additional information about the request. Common HTTP headers include the following:

  • Host
    This header contains the name of the Web server.

  • Accept
    This header defines the file types that the client can handle.

  • User-Agent
    This header contains the name of the browser that requests the page.

  • Authorization
    This header defines the authentication methods that the client supports.

Clients may send other headers to the server to specify additional information.

In the [DenyHeaders] section, you define HTTP headers that URLScan will reject. If URLScan receives a request that contains any header that is listed in this section, it rejects the request. This section consists of a list of HTTP headers, with each header appearing on its own line. Header names must be followed by a colon (:) — for example, Header-Name:.

[DenyUrlSequences] section

You can configure URLScan to block requests that contain certain sequences of characters in the URL. For example, you can block requests that contain two consecutive periods (..), which are frequently used with exploits that take advantage of directory traversal vulnerabilities. To specify a character sequence to block, put the sequence on a line by itself in the [DenyUrlSequences] section.

Note that adding character sequences may adversely affect Microsoft® Exchange Outlook® Web Access (OWA) server publishing. When you open a message from Outlook Web Access, the subject line of the message is contained in the URL that is requested from the server. Because the URLScan.ini file blocks any requests that contain the percent sign (%) and the ampersand sign (&), users receive a 500 error message when they try to open a message with a subject line such as "Sales increase by 100%" or "Bob & Sue are coming to town." To resolve this, you can remove these sequences from the [DenyUrlSequences] section. Note that this reduces security because it potentially permits damaging requests to reach the server.

[RequestLimits] section

The RequestLimits section enforces limits on the size, in bytes, of separate parts of requests reaching the server. The RequestLimits section includes the following entries:

  • MaxAllowedContentLength=30000000
    The MaxAllowedContentLength enforces a maximum value, in bytes, on the content length. It does not actually prevent the server from reading more data than what this value is set to. For example, if a client makes a chunk transfer encoded POST, this option does not track the size of the entity in the request. The default value is 30000000.

  • MaxUrl=260
    MaxUrl restricts the length of the request URL, in bytes, but does not restrict the length of the query string. The default value is 260 bytes.

  • MaxQueryString=4
    MaxQueryString restricts the length of the query string, in bytes. The default value is 4 KB.

In addition, you can impose a byte limit on the size of a specific request header by prepending Max– to the name of any header. For example, the following entry imposes a limit of 100 bytes on the Content-Type header:
Max-Content-Type=100
To list a header and not specify a maximum value, set the entry to 0. For example, type:
Max-User-Agent=0
Headers that are not listed in this section are not checked for length limits.