Wade Hilmo

Dynamic IP Restriction Proxy Mode

wadeh — Wed, 01 Aug 2012 20:26:14 GMT

Last week, we released the final version of our Dynamic IP Restrictions module for IIS 7.x. The feature is also built into IIS 8.0, which is included with Windows 8 and Windows Server 2012.

At the highest level, Dynamic IP Restrictions works by looking at incoming client IP addresses and allowing the server administrator to restrict either the maximum number of concurrent connections, or throttle the rate of incoming requests.

For information on how to configure and use Dynamic IP Restrictions, we have published a help topic here with screen shots that show all of the settings.

Requests behind a proxy

We’ve been showing this feature for some time now at various events, like Tech Ed, and one question invariably comes up: What about clients behind a proxy?

To handle that situation, Dynamic IP has a checkbox near the bottom of the page in Internet Services Manager entitled “Enable Proxy Mode”. But what does this setting actually do?

Proxy Mode allows Dynamic IP Restrictions to work with the client request header X-Forwarded-For to determine the IP address of the original client. Wikipedia has a pretty good description of the header here.

The way it works in general is that, when a proxy server gets a request from a client, it adds the client’s IP address to the end of a comma separated list of client IPs. Assuming that a request goes though multiple proxies, you would get an X-Forwarded-For header that looks something like this (where you’d see IP addresses in place of the names below):

X-Forwarded-For: original-client, first-proxy, second-proxy

Dynamic IP Restrictions can therefore determine the IP address of the original client.

But how can you trust data from the client?

Right after we explain support for the X-Forwarded-For header, the immediate next question is: How can you trust data from the client?

This is actually a pretty insightful question, and I really enjoy hearing questions that demonstrate the knowledge of our users. The ultimate answer to this question is that we can’t trust data from the client request without help from the server administrator. And this is where the behavior of Proxy Mode is not as intuitive as it could be. In order for it to be useful (or even functional), there is another configuration setting that needs to be made.

Specifically, we look at the X-Forwarded-For header only if Proxy Mode is enabled *and* we recognize the IP address of the client as a known safe proxy. A proxy server is considered safe only if its IP address is registered in the Allowed IP Address list. The logic works like this:

1) A new request arrives at the server. We get the IP address of the client from the network stack. This address is trusted, since it came from the local machine’s network software and not from the HTTP request.

2) If that IP address is on the Allowed list, we then know that it was the last entity to touch the X-Forwarded-For header and we consider the last entry on X-Forwarded-For to be a valid client IP address. If the network stack IP address is not on the Allowed list, then we consider the client IP address to be the value from the network stack and will use it. Otherwise, we go on to step 3.

3) We know that the last entry on X-Forwarded-For is valid, so we then check to see if it is on the Allowed list. If it is, then we know that the next-to-last entry on X-Forwarded-For was put there by a trusted proxy and we consider it valid. If the last entry is not on the Allowed list, then we consider it to be the IP address and use it.

We keep working our way from the end of X-Forwarded-For, towards the beginning until we reach an IP address that is not on the Allowed list. In this way, we know which entries to trust because of the proxy servers listed in the Allowed IP List.

Some examples

Now let’s look at an example. Consider the following value for X-Forwarded-For:

X-Forwarded-For: 23.34.45.56

Further, let’s assume that this request came through a load balancing proxy with the IP address 1.1.1.1, which is included on the Allowed list.

When the request arrives at our server, we can see that it came from the proxy with the IP address 1.1.1.1. Since this address is on the Allowed list, we look at the last entry in X-Forwarded-For and get 23.34.45.56. Since this address is not on the allowed list, we will use 23.34.45.56 as the IP address for applying dynamic IP restrictions.

----------

Let’s look at another example. In this case, let’s assume that the client is trying to bypass dynamic IP restrictions by forging an X-Forwarded-For header. Finally, let’s say that Proxy Mode was enabled, but the request didn’t come through any proxy.

X-Forwarded-For: 9.9.9.9

When the request arrives at our server, we’ll get the client’s actual IP address; let’s say it’s 23.34.45.56. Since 23.34.45.56 is not in the Allowed IP Addresses list, we don’t even look at the X-Forwarded-For header. We use the client’s actual IP address for dynamic IP restriction processing.

----------

Finally, let’s look at a more complicated scenario, with a malicious client that is using your internet facing IP address in a fraudulent X-Forwarded-For header. This is a clever thing to do because it assumes that your internet facing server is a proxy. And let’s say that this assumption is correct. To complete the scenario, let’s say that they are going through 2 proxies, both of which are trusted by inclusion on then Allowed IP Address list and have the addresses 2.2.2.2 and 1.1.1.1. The X-Forwarded-For header now looks like this:

X-Forwarded-For: 2.2.2.2, 23.34.45.56, 2.2.2.2

When the request arrives at our server, we can see that it came directly from the proxy with the IP address 1.1.1.1. Since that IP address is on the Allowed list, we know that the last entry appended to X-Forwarded-For was put there by our trusted proxy.

So now we know that the last entry on X-Forwarded-For can be trusted. This entry is 2.2.2.2. We look up this value in the Allowed IP Address list and find it there.

We now know that the entry just before the previous one can be considered valid. This entry is 23.34.45.56. When we look it up on the Allowed IP Address list, we do not find it. We Therefore use 23.34.45.56 as the IP address for dynamic IP restrictions.

----------

As you can see from these examples, we will never look at an entry in X-Forwarded-For unless we can validate its legitimacy by using the Allowed IP Address list.

How do I find the IP address of trusted proxies?

In our research on this topic, we’ve found that the majority of trusted proxies are going to be load balancers and reverse proxies that are owned by the same owner as the IIS server. In these cases, the IP addresses will be well known.

Finding the IP addresses of forward proxies out on the internet is a bit tougher question. I’ve spoken with a number of people concerned that many of their web site visitors are coming from within corporations or other places where a large number of users are behind such a proxy. This is. admittedly, a harder problem to solve.

My suggestion to address this would be to use the IIS logs to find cases where Dynamic IP Restriction has been triggered. This is easy to do by searching to logs for specific substatus codes. In particular, Dynamic IP Restrictions uses the following substatus codes:

501: Dynamic IP Restrictions rejected the request due to too many concurrent requests

502: Dynamic IP Restrictions rejected the request due to too many requests over time

Of course, these substatus codes may appear in combination with other HTTP status codes. This is because Dynamic IP Restrictions allows you to customize the HTTP response in the case of rejection.

Another very handy feature of Dynamic IP Restrictions is that you can use Logging Only Mode. In Logging Only Mode, Dynamic IP Restrictions runs its normal logic but does not reject any requests. Instead of rejecting requests, it will return the normal response and include one of the above substatus codes in the log to indicated that what it would have done in normal mode. With this feature, you can test out settings without actually interrupting your traffic.

The good news on this topic is that the anecdotal evidence we are seeing from early adopters is that this is not a common issue. What we are hearing is that traffic volumes subject to this issue are generally not high enough to trigger errant rejections. Of course, your specific situation may vary and you will need to tune your settings to find the proper balance.

Conclusion

The key takeaway here is that checking the “Enable Proxy Mode” box is only part of the process of supporting proxy server with Dynamic IP Restrictions. You also need to specify the IP addresses of proxies that you wish to trust. Also, you can be confident that when properly configured, Dynamic IP Restrictions works well with the X-Forwarded-For header and that clients cannot escape your restrictions by forging a bogus header.

Application Initialization Part 2

wadeh — Tue, 01 May 2012 16:38:00 GMT

In my last post, I gave a bit of background on the Application Warm-Up module, now called Application Initialization. This week, I would like to go into more detail as to what the Application Initialization module does, and how you should think about using it.

As I mentioned earlier, the idea behind Application Initialization is that we want to provide a way that IIS can prepare an application to serve requests without having to wait for an actual client to make a request. With Application Initialization, we break the problem down into 3 parts:

How can I start the worker process that hosts my application without waiting for a request?
How can I get the worker process to load my application without waiting for a request?
How can my application send some kind of response so that clients don't see the browser hang until the application is ready?

I would like to address the first two questions here. The third question is a bit more complex and I will save it for my next post.

Starting a worker process without waiting for a request

This is something that's not strictly speaking a part of Application Initialization in that we added this capability as a built-in feature of IIS, starting with IIS 7.5. I will go over it here because it works hand in hand with Application Initialization to make the application available as soon as possible after starting IIS.

This feature is controlled by a the startMode property for the application pool, described (along with other application pool properties) here. The default value for startMode is OnDemand, which means that IIS will not spin up any worker processes until needed to satisfy a client request. If you set it to alwaysRunning, IIS will ensure that a worker process is always running for the application pool. This means that IIS will spin up a worker process when the World Wide Web Service is started, and it will start a new worker process if the existing one is terminated.

Note that this property should not be confused with the autoStart property. Understanding autoStart requires a bit of background knowledge. Both application pools and worker processes can be started and stopped. If an application pool is started, it means that IIS will accept requests for URLs within the pool, but it does not necessarily mean that there are any worker processes started. If an application pool is stopped, IIS will return a "503 Service Unavailable" for any requests to the application pool and it will not start any worker processes. The autoStart property is essentially a flag that IIS uses to know which application pools should be started when the World Wide Web Service is started. When you stop an application pool in IIS Manager, autoStart is set to false. When you start an application pool, autoStart is set to true. In this way, IIS ensures that the same set of application pools are running after the World Wide Web Service is started and stopped (or through a machine reboot.)

Now let's take a quick look at the configuration for an application pool that is set to be always available. This application pool will start when the World Wide Web Service starts and it will immediately spin up a worker process.

<system.applicationHost> 
  <applicationPools> 
    <add name="DefaultAppPool" autoStart="true" startMode="alwaysRunning" /> 
  </applicationPools> 
</system.applicationHost>

With this configuration, the Default Application Pool will immediately spin up a worker process when IIS is started, and it will spin up a new worker process when the existing one exits.

With IIS 7.5, this property was not exposed in IIS Manager. It can be set by editing the applicationhost.config file directly or by one of IIS's scripting or programming APIs, or by the Configuration Editor UI tool. In IIS 8, we have added the startMode property to the advanced properties page for the application pools UI.

How can I get the worker process to load my application without waiting for a request?

Now that you can see how to get IIS to spin up a worker process without waiting for a request, the next thing to address is how to get an application loaded within that worker process without waiting for a request. The Application Initialization module provides a solution here, and as above, it is controlled by a single configuration property.

The Application Initialization module extends the IIS configuration by adding a new property to the application settings called preloadEnabled (in IIS 8, this property is built-in.) Let's take a look at what this looks like in the configuration where I've added a new application to the default web site and enabled it for preload:

<system.applicationHost> 
  <sites> 
    <site name="Default Web Site" id="1"> 
      <application path="/"> 
        <virtualDirectory path="/" physicalPath="%SystemDrive%\inetpub\wwwroot" /> 
      </application> 
      <application name="AppInit" applicationPool="DefaultAppPool" preloadEnabled="true"> 
        <virtualDirectory path="/AppInit" physicalPath="c:\inetpub\wwwroot\appinit" /> 
      </application> 
    </site> 
  </sites> 
</system.applicationHost>

Here's how Application Initialization uses this property. When a new worker process spins up, Application Initialization will enumerate all of the applications that it will host and checks for this property. For any application where preloadEnabled="true", it will build a URL corresponding to the default page for the application and run it through the pipeline. This request does not go through the network, and there is no client listening for a response (IIS discards any data that would have gone to the client.)

This "fake" request accomplishes a few key things. First, it goes through the IIS pipeline and kicks off an application start event. This initializes a number of parts inside of IIS, and if the request is for ASP.NET, it will cause global.asax to run. It also reaches the application, which will see it is the first request after starting. Typically, I expect that applications will just handle this request just like any other request from a real client, but we do set some server variables into our "fake" request, so an application with awareness of this feature could implement special processing if it chose to do so.

There is another important aspect to this process. When IIS spins up a new worker process, there is two way communication between WAS and the new process. This allows WAS to know precisely when the worker process is ready to accept new requests. It also allows the worker process to get information from WAS as to whether it is going to be a new process to start taking requests, or whether it's a replacement process to take over for an older process that's being recycled.

This is an important distinction. In the case of a new worker process, we want to start taking client requests as soon as possible, which is the way that things work outside of Application Initialization. In the case of a replacement process, though, Application Initialization will prevent the new process from reporting itself ready for new requests, until all of the preload requests (and any warumup requests, which I will discuss later) have completed. This means that no client will ever have to wait for a process recycle to complete - because the old process will continue to take requests until the new one has completed all application initialization.

In my experience, many applications with a slow startup will do their work even for a simple request to the default page. For such applications, you can take advantage of improved application recycling simply by setting preloadEnabled="true" for that application. Similar to the startMode property above, IIS 7.5 requires you to make this setting via direct edits or applicationhost.config, or via scripting or one of our config APIs, or via the Configuration Editor UI tool. In IIS 8, we have added "Enable Preload" as a checkbox in the UI for application settings.

Next time...

The two topics that I've covered here should get you started with Application Initialization. The ability to handle worker process recycles has been a highly requested feature.

In my next post, I'll tackle the topic of what it means to initialize an application and what things an application developer can do to make things responsive during the time everything is warming up. This is where we've made major changes and added a lot of stuff since the original beta release.

(Re)introducing Application Initialization

wadeh — Mon, 16 Apr 2012 20:25:51 GMT

“IIS is a demand-driven web server, i.e. IIS does things only when asked for…”

This was the start of a blog post back in late 2009 announcing the beta for the IIS 7.5 Application Warm-Up module. The idea behind this module is to address a common customer need. Specifically, the demand driven nature of IIS is such that it doesn’t load application code until it’s needed to handle a request.

Many applications do a significant amount of work when they first start. And in many cases, the framework needed to run the application is loaded in the same way. Finally, it may be necessary for the application framework to compile some or all of the application code before it can handle that first request. All of this leads to an all too common situation where the unlucky client that makes the first request the application has to endure a long wait before they see the first response.

So back before IIS 7.5 was released, we asked ourselves what functionality would be needed to help to address this problem. The results of that thinking were two new features in IIS 7.5, one of them an administrative feature, and one of them a new interface in the IIS pipeline.

I’d like to talk about the pipeline change first.

The IIS pipeline is the heart of the IIS runtime – the part that determines how an IIS worker process responds to events, like the arrival of a request that needs to be served. The pipeline is a collection of event notifications and application programming interfaces (APIs) that modules can plug into and do work when things happen. The IIS product team uses these events an APIs to implement all of the interesting parts of what people think of as IIS in the form of modules. For example, IIS uses a module called StaticFileModule to be able to serve plain files. It uses a module called DefaultDocumentModule to know how to serve the default document for virtual directory or application. Modules are also used for things other than serving request. The WindowsAuthenticationModule implements Windows authentication, and the UriCacheModule implements certain caching that you don’t see, but improved the performance of the pipeline. If you are a programmer interested in the pipeline, one of the coolest decisions that we made for IIS 7.0 was to make the same interfaces that we use on the product team available to anyone. You can get started taking a look at it here.

So what does all of this have to do with warming up applications?

IIS 7.5 introduced a new event to the pipeline called GL_APPLICATION_PRELOAD. This event fires when the worker process is first starting up. A module plugged in here can register for the event to do work before the worker process notifies WAS that it is ready to handle requests. At the same time, we added a new pipeline interface that allows a module to create requests and drop them into the pipeline. These requests work just like requests from a client, except that there is no client, no network connection etc. Unless they specifically look for it, modules don’t see a difference between these “fake” requests and requests with a live client on the other end. Data that would normally be sent back to the client is discarded.

These two things together create the opportunity to solve part of the problem that I mentioned at the start of this post. When a worker process starts up, it can create a bunch of “fake” requests and send them through the pipeline. These requests will run through their respective applications without having to wait for a live client to create the demand to start.

So this looks good, but there is still a catch. IIS worker processes (which each host there own pipeline) are themselves demand started. Prior to IIS 7.5, the only way to start the worker process was for a client to make a request.

Start Mode

The second new IIS 7.5 feature makes it possible to automatically start an IIS worker process without waiting for a requests. This feature is pretty straightforward. To enable it, just go to the advanced properties for the application pool in Internet Information Services Manager, and set “Start Automatically” to “True”. Once you do this, worker processes for the application pool will be started up as soon as the IIS service starts. You can do the same thing by setting the startMode property in applicationhost.config to alwaysRunning.

So now, if you have a module that can send a list of requests through the pipeline, and you have the application pool set to auto start, all of the applications represented by the list of requests will be touched as soon as IIS starts.

The Application Warm-Up Module

The Application Warm-Up module that I first mentioned at the top of this post was to be the module to send the warmup requests. Why do I say this in the past tense? Back in March last year, we pulled the beta release and pointed the download page to a notice explaining that it was temporarily removed.

There were a couple of things that happened leading up to the removal. The first thing is that the functionality that I’ve listed above only solves a part of the problem. The remaining puzzle piece is that, even under the best of circumstances, there is still a period of time after starting the application where it cannot respond to client requests. If you need to restart the IIS service for any reason, even enabling Start Automatically does not help requests that arrive at the moment that the service starts. To address that, there needs to be a way for IIS to actually send a response during the warmup period. And there needs to be a way that an application can participate in what that response looks like. If we wanted to solve that problem, we needed to make a deeper investment in the module. And since we were fully engaged in the development of IIS 8, we were able to do just that as a part of the next major IIS release.

The other factor is that, when we looked at how the beta module worked, we realized that we would need to make some changes to the new pipeline functionality that we introduced in IIS7.5. Normally, when we introduce new APIs to IIS, we do so only when we are either going to use them ourselves or when we have a partner that is committed to using them before release. The pipeline changes for warmup were an exception to this because we didn’t have time to do the module before IIS 7.5 released. As sometimes happens when there is no code that depends on a new interface, we discovered that there were some things that would need to be fixed before Application Warm-Up could be made ship ready. This meant that, over and above the new functionality in the module, we would need to ship a QFE for IIS 7.5 (which is included in the setup package for Application Initialization).

Where are we now?

Finally, after almost a year after we pulled the beta, we were able to release the Release Candidate version of Application Initialization.

So that is the history up to this point for the Application Warm-Up/Initialization module. There are still questions that I’d like to answer:

- What is new in the RC?
- What’s the easiest way to start using it?
- What about advanced usage and troubleshooting?
- Why did the name change?

I am going to address these questions and more in my next few blog posts.

How IIS blocks characters in URLs

wadeh — Wed, 20 Apr 2011 12:53:41 GMT

Recently, the question came up about why it is not possible for IIS to handle a URL that contains a ‘%’ character that is not part of an escape sequence. The resulting discussion produced some informative references to the relevant RFC documents and also included some anecdotes on URL canonicalization.

I would like to share my response to the question. I hope that you find it informative.

Disclaimers and Assumptions

Discussing how URLs is processed can be somewhat confusing because common usage of the term “URL” does not reflect the fact that there are different parts in the string that are processed differently. Consider the following URL:

http://www.myserver.com/somefolder/somepage.aspx?morestuff

It can be though of as 4 distinct parts that are each subject to their own rules and processing. The first part is the protocol specification: “http://”. This information is used by the client to know what protocol to use when contacting a server to handle the request. The second part is the hostname: “www.myserver.com”. This information is used by the client to resolve the IP address of the client and connect. It may optionally include IP port information by using a colon to delimit the port ID: “www.myserver.com:80”. Notably, neither of these two parts of the URL are typically sent to the server. They are consumed directly by the client and never put on the wire. The exception to this is when your browser is configured to use a proxy server. In that case, the client will sent them because the proxy server will need the information to know how to connect to the downstream server.

The third and fourth parts of the URL are the path: “/somefolder/somepage.aspx” and the query string: “morestuff”. This is the information that a web server deals with. The URL canonicalization rules discussed in this post are applied to the path only. The query string is generally considered opaque by the web server and left to the application that handles the request to process (ie. somepage.aspx in this example.)

Next, I would like to note that there are many different components involved in processing a typical HTTP request that may apply their own rules regarding what is allowed in a URL and what is not. In the case of IIS, the first component to see the request is http.sys. This is the driver component that picks up the raw request from the wire and parses the HTTP protocol. Next, the request goes to user mode and the IIS core server which sends the request through our pipeline. In the pipeline, the request may be handled by any number of modules that can each get a look at the request. In the case of this conversation, the module of interest is the RequestFilteringModule. The request is then dispatched to a handler, which is a special module that is responsible for the heavy lifting work of processing the request and producing a response. Some common handlers in IIS are the static file handler, which serves plain old static pages; ASP.NET which provides its own development platform and gives access to the .NET framework; and FastCGI, which provides a platform to support things like PHP.

My expertise lies in IIS and the modules that ship with it. Some of the common handlers, like ASP.NET and PHP can and do implement their own checks for URL validity, but I am not going to try and explain them because I don’t know their internals well enough. I also would not consider myself an expert on http.sys, but I do know some things about how it validates URLs which I will explain here.

HTTP.SYS

Http.sys is the first component that looks at the incoming URL. One of its jobs is to parse the HTTP request according to a well defined set of rules. Strictness is important here as http.sys needs to protect itself from malformed requests. For the URL, http.sys applies RFC 2396. Http.sys also has a documented registry setting called AllowRestrictedCharacters, which opens things up a bit. In the case of the original question that started this discussion, even this setting will not allow requests through with an ‘%’ character that is not part of an escape sequence. The reason comes directly from RFC 2396, which as this to say in section 2.4.4 entitled “When to escape and unescape”:

Because the percent "%" character always has the reserved purpose of being the escape indicator, it must be escaped as "%25" in order to be used as data within a URI. Implementers should be careful not to escape or unescape the same string more than once, since unescaping an already unescaped string might lead to misinterpreting a percent data character as another escaped character, or vice versa in the case of escaping an already escaped string.

Request Filtering

Once a request moves from http.sys to the IIS core server, the RequestFilteringModule will get a look at it. This happens in the RQ_BEGIN_REQUEST notification. The behavior of the request filter is pretty clearly called out by its schematized configuration, where we’ve tried to name the properties as clearly as possible. I won’t go over all of the details here, but I do want to call out one property that generates some confusion: allowDoubleEscaping.

The allowDoubleEscaping feature maps to an old UrlScan feature called VerifyNormalization. The original intent of VerifyNormalization was to ensure that any URLs passed to applications were reduced to their canonical form (see the caution above in the quote from RFC 2396 about misinterpretation of a ‘%’ character.) Guaranteeing that a URL is in canonical form protects against the case where an application naively does its own unescape on a URL that has already been unescaped. Strictly speaking, there is nothing in any RFC that disallows URLs that produce different results when decoded more than once, but proper process mandates that the application handling the request does the right thing. As such, this check is a defense in depth measure. We turn it on by default because misinterpreting non-canonical URLs is probably the most common type of bug that leads to security problems.

So allowDoubleEscaping/VerifyNormalization seems pretty straightforward. Why did I say that it causes confusion? The issue is when a ‘+’ character appears in a URL. The ‘+’ character doesn’t appear to be escaped, since it does not involve a ‘%’. Also, RFC 2396 notes it as a reserved character that can be included in a URL when it’s in escaped form (%2b). But with allowDoubleEscaping set to its default value of false, we will block it even in escaped form. The reason for this is historical: Way back in the early days of HTTP, a ‘+’ character was considered shorthand for a space character. Some canonicalizers, when given a URL that contains a ‘+’ will convert it to a space. For this reason, we consider a ‘+’ to be non-canonical in a URL. I was not able to find any reference to a RFC that calls out this ‘+’ treatment, but there are many references on the web that talk about it as a historical behavior.

The IIS Core Server

Ok, so getting back to the components that might be checking for URLs, I would like to say just a bit about the IIS core server itself.

In general, the IIS core server does not enforce any restrictions on URLs - but there are a couple of things it does with the physical file mappings that are produced from URL mappings. The core pipeline API exposes the IHttpFileInfo interface that allows modules to work with files in the IIS file cache. The static file handler, for example, uses this interface. Also, when you configure a handler to verify the existence of a file, the core itself uses this. The file cache API will not work with file paths that contain a ‘:’ character. The reason for this is that the colon is used by NTFS to specify alternate data streams. It is possible to use alternate data stream syntax as a non-canonical way to get file data. The most infamous case of this was the ancient ::$Data bug.

The other notable thing that the IIS core does in any cases where it works with physical file names is that it uses a special syntax. Specifically, we prepend “\\?\” to any local filenames, or “\\?\UNC\” to UNC filenames. This special syntax tells Win32 file APIs that they should not attempt to do their own canonicalization on the filename and should instead pass it directly to the file system layers below. This ensures that when we open a file, we are using its canonical name. If a filename gets past our canonicalization checks and is still non-canonical, this will cause the file operation to fail. The downside to this is that the CLR (at least the last time I checked) does not support this syntax. So if you are writing a .NET application that uses IIS server variables, you may need to strip out the above prepends.

Conclusion

So there you have it. This covers the things that a URL must pass through in order to be processed by IIS. I hope that you find it informative and useful.

-Wade

Understanding Versions of the IIS FTP Server

wadeh — Fri, 04 Sep 2009 04:04:00 GMT

It’s been a busy few days on the IIS Security Team.

Earlier this week, a vulnerability was found in the IIS FTP server. We have been working with security teams across Microsoft to research the issue and formulate a response to best protect our customers.

Unfortunately, this finder chose to release the details of the vulnerability directly to the public instead of bringing it to our attention first. When this happens, we have competing priorities: We want to research the issue as thoroughly as we can. And at the same time, we want to get information out to our customers as soon as possible so that they can protect themselves.

In response to this issue, Microsoft issued Microsoft Security Advisory (975191) on Tuesday.

Earlier today, this same finder released information for a second vulnerability in the IIS FTP server. Again, the finder chose to release his information directly to the public. While this new finding is a different issue, the impact, migitations and workarounds are very similar to the first issue; similar enough that both issues are now addressed in the above advisory.

One significant difference is that different versions of FTP are affected in different ways. This has resulted in some confusion about determining whether a particular server is vulnerable or not. I will now attempt to clear up some of that confusion. Note that the primary source of information on the details is the security advisory. I will not discuss those details here.

I will cover the most straightforward cases first:

Windows 2000 includes IIS 5.0, which includes FTP 5.0. All of the issues in the security apply to this version of the FTP server.
Windows XP includes IIS 5.1, which includes FTP 5.1. All of the issues in the security advisory apply to this version of the FTP server.
Windows 7 and Windows 2008 R2 both include IIS 7.5, which includes FTP 7.5. None of the issues in the security advisory apply to this version of the FTP server. It is unaffected by both these vulnerabilities.

The confusion arises with Windows 2003, Vista and Windows 2008. Windows 2003 contains IIS 6.0; Vista and Windows 2008 contain IIS 7.0. All of these platforms contain a version of FTP that we call FTP 6.0.

Only it’s not quite that simple.

We did some maintenance to FTP 6.0 between Windows 2003 and Vista. As a result of this work, the first of this week’s two findings applies only to the older flavor that ships with IIS 6. The second of this week’s findings apply to FTP 6.0 on all 3 Windows versions.

The version story is even more confusing because we released FTP 7.0 as an add-on component to Vista and Windows 2008 and has also made FTP 7.5 available for these operating system versions. Both FTP 7.0 and FTP 7.5 are unaffected by this week’s findings described in the above security advisory. If you are running the FTP server with Vista or Windows 2008 and have not yet upgraded the FTP server, we strongly recommend that you consider upgrading to FTP 7.5. We offer this upgrade for free. You can find details here.

If you are running the IIS FTP server on Windows 2003 or earlier, or if you choose to run FTP 6.0 on Vista or Windows 2008, please see the security advisory for the most current information on mitigations and workarounds.

I would like to touch on one other topic on the subject of IIS versions.

The IIS FTP server is hosted in the same process as the IIS Admin Service. In IIS 6.0 and earlier, all of the IIS services are dependent on this service. Because both vulnerabilities have the potential to terminate this process, a successful denial of service attack to FTP will also shut down all IIS services, including the web server.

IIS 7.0 has a different architecture and the IIS 7.0 web server is not dependent on the IIS Admin Service. For this reason, a successful denial of service attack against FTP 6.0 will not affect the IIS 7.0 web server.

Running Perl on IIS 7

wadeh — Tue, 14 Apr 2009 00:53:04 GMT

We've had a few people on our forums asking about running Perl on IIS 7. This led to some discussion on the team about getting it to work with FastCGI.

The team has been doing a lot of great work with the Web Platform Installer and Windows Web App Gallery that feature popular PHP applications. Since PHP runs best on IIS with FastCGI, I suppose it was logical to turn to FastCGI for Perl as well.

Sometimes, though, the right tool for the job is not the newest and flashiest thing. It turns out that this is the case for Perl. For many years, ActiveState has provided a free version of ActivePerl that runs great on IIS using ISAPI instead of FastCGI.

It's been a while since I've looked at ActivePerl, so I did some research last week to see the state of things and discovered that there are a few things you need to know in order to get it to work on IIS 7:

ActivePerl is available as an ISAPI for 32 bits only. This does not prevent it from running on a 64 bit install of Windows. It just means that any application pool that contains Perl content must be configured to run as 32 bit.

As of this writing, ActivePerl runs well on IIS 7, but its installer does not properly configure IIS 7 for running Perl scripts. After completing the ActivePerl installation, you will need to create handler mappings to associate requests for Perl scripts to the correct ISAPI based Perl interpreter.

There are at least two different ISAPI extensions with ActivePerl. You should make sure that you use PerlEx30.dll with IIS 7. If you use perlis.dll, you may find that response headers sent from your Perl script are added to your response page instead of going back to the client as headers.

Given the above information, here are the steps to get ActivePerl running on IIS 7:

1. Install ActivePerl from http://www.activestate.com/activeperl/. At this time, there is a link to version 5.10 for Windows (x86) on this page. This link downloads an MSI installer to your machine which you can run.

2. If you are running the 64 bit version of Windows 2008, ensure that your application pool is configured to run as 32 bit. Assuming that you will be using ActivePerl in the default application pool, these steps will do it:

From the Windows 'Start' menu, pick run and type "inetmgr" (without the quotes). Click on 'OK".

In the left hand pane of IIS Manager, open up the settings for your server. Click on "Application Pools".

In the Application Pools page, select "DefaultAppPool".

In the right hand pane, under "Edit Application Pool", click on "Advance Settings..."

In the Advanced Settings dialog, ensure that "Enable 32-bit Applications" is set to "True".

3. Create a handler mapping that associates "*.pl" requests with ActiveState's perlex30.dll extension using the following steps:

4. In the left hand pane of IIS Manager, select your server. This will apply the following handler mappings on the entire server. If you would like to do this for just a specific site or application, you can open up the server and select any site or application. In the center pane, double click on the Handler Mappings icon.

5. When the Handler Mappings pane is displayed, click on the "Add Module Mapping..." item in the Actions pane on the right.

6. Fill out the Add Module Mapping dialog as follows:

For Request Path, enter "*.pl".

For Module, select "IsapiModule" from the dropdown list. Note that the ISAPI module is a prerequisite. If it does not show up on this list, it will need to be installed an an IIS optional component.

For Executable, enter "c:\perl\bin\PerlEx30.dll" (without the quotes.) Note that this assumes that you've installed ActiveState Perl using its default location. If you installed it in another location, you will need to look there for perlex30.dll.

For Name, enter "ActiveState Perl for .pl". Note that this name is just a label and does not affect functionality. It does need to be unique, though. If you are going to be associating other file extensions with ActiveState Perl, the names for those mappings will need to be different.

You do not need to do anything with the "Request Restrictions..." button. If you wish to limit this mapping to specific HTTP verbs, etc., it can be done there.

7. Repeat the above steps for any additional file extensions you wish to be associated with Perl. On IIS 6, ActiveState Perl creates mappings for "*.pl", "*.plx" and "*.plex". Additionally, some applications are known to map "*.cgi" with Perl.

That's it. After doing this, ActiveState Perl should run on IIS 7.

How IIS can help with SQL Injection

wadeh — Thu, 18 Dec 2008 23:48:00 GMT

2008 has been a busy year for attackers exploiting SQL Injection vulnerabilities in web applications. Once again, I am finding questions about this subject in my inbox.

Earlier today, I found myself reviewing the material that's been published by Microsoft and others. I was searching for a single, concise link that I could send out to describe what IIS's various filtering tools can do and how to set them up for the job.

It turns out that there are so many articles out there, that the core "what can I do about it" message has been lost in the deluge. For someone new to the issue, who just wants to know what to do, there is no good starting place.

This post is my attempt to provide that starting place.

Before getting into the details, no discussion about SQL Injection filtering is complete without the following caveat: Filtering for SQL Injection is nothing more than a tool to help mitigate the issue. It is not the final solution and it is not foolproof. The only complete solution to prevent SQL Injection over the web is to fix vulnerable web applications on the server. For lots of in-depth information about the root cause of SQL Injection vulnerabilities and strategies for fixing them, here are some suggested links:

Definition of SQL Injection
SQL Server Injection Protection
Preventing SQL Injections in ASP
How To: Protect from SQL Injection in ASP.NET
Coding Techniques for protecting against SQL Injection in ASP.NET
Filtering SQL Injection from Classic ASP
Security Vulnerability Research & Defense Blog on SQL Injection Attack

What that caveat out of the way, here is how IIS can help to mitigate against SQL Injection attacks:

It is possible to filter input to IIS so that HTTP requests containing information deemed dangerous by the server administrator can be blocked before a web application is allowed to process them. In the context of SQL Injection, this means that IIS can look for SQL statements in various parts of the request and shut them down before they become a problem.

The actual tools and methods for doing this are different for different IIS versions. Starting with IIS 7, request filtering is included as a core feature and is installed by default on all IIS 7 servers. Prior to IIS 7, IIS did not have this feature built in, but it is available as an add-on component. So for IIS 6 and earlier, request filtering is accomplished via the UrlScan tool available as a free download.

I have prepared posts describing step-by-step instructions for setting up filtering for SQL Injection attempts at the following links:

To set up SQL Injection filtering for IIS 7 and later, go here.
To set up SQL Injection filtering for IIS 6 and earlier, go here.

Finally, it has become very clear to me today that the state of the art changes pretty rapidly. I've seen many articles that talk about betas and other versions that were current at the time they were written - but are no longer current today. I fully expect that the blog posts I'm writing today are going to fall victim to that same trend.

To address that issue, I am going to see if we can set up an area on iis.net for security articles that are always kept current. Once we have that, we can put a SQL Injection article there and let that be the canonical location for guidance from the IIS team on that topic. With the holidays approaching, it will likely be well into January before I can make this happen, but it's now on my agenda.

Thanks,
-Wade

Filtering for SQL Injection on IIS 6 and earlier

wadeh — Thu, 18 Dec 2008 23:47:00 GMT

This article is specific to IIS 6 and earlier. If you are using IIS 7.0 or later, please see this article.

The IIS team has created an add-on tool for IIS called UrlScan that is able to filter HTTP requests. If a request is found to have contents deemed unacceptable to the administrator, it will be blocked before it is processed by a web application. This feature is useful as a mitigation tool in defense of SQL Injection vulnerabilities.

Note that any scheme that filters SQL Injection attempts is only a mitigation. The complete solution to the problem requires fixing vulnerable web applications. For more information about SQL Injection vulnerabilities and strategies for fixing them, here are some suggested links:

Definition of SQL Injection
SQL Server Injection Protection
Preventing SQL Injections in ASP
How To: Protect from SQL Injection in ASP.NET
Coding Techniques for protecting against SQL Injection in ASP.NET
Filtering SQL Injection from Classic ASP
Security Vulnerability Research & Defense Blog on SQL Injection Attack

Prerequisite

Before getting started, you will need the current version of UrlScan. As of the date of this writing, it is version 3.1. Most of the information here will also work with UrlScan 3.0, but there are a number of bug fixes in 3.1 and it is strongly encouraged that you upgrade if you are running an earlier version. A free download of UrlScan 3.1 can be found here.

Configuring UrlScan

UrlScan is configured via the urlscan.ini file.

Open the urlscan.ini file in the following path:

%systemroot%\system32\inetsrv\urlscan\urlscan.ini

Search the urlscan.ini file for "RuleList=" (without the quotes.)
Add "SQLInjection" (without the quotes) to the end of the RuleList line. If there is already an item or items in the RuleList, use a comma to separate them.
Create the following new sections at the end of the urlscan.ini file:

[SQLInjection]
AppliesTo=.asp,.aspx
DenyDataSection=SQLInjectionStrings
ScanURL=0
ScanAllRaw=0
ScanQueryString=1
ScanHeaders=

[SQLInjectionStrings]
--
%3b ; a semicolon
/*
@ ; also catches @@
char ; also catches nchar and varchar
alter
begin
cast
create
cursor
declare
delete
drop
end
exec ; also catches execute
fetch
insert
kill
open
select
sys ; also catches sysobjects and syscolumns
table
update

Save the changes to urlscan.ini.

What effect does this have on my server?

With the above configuration in place, IIS will look at each incoming request for pages with .asp or .aspx extensions to search for specific strings in the request's query string. If found, IIS will block the request and return a 404 Not Found page to the client. If you want to change the file extensions, you can add or remove file extensions on the AppliesTo line. The specific strings in the search are controlled by the entries in the [SQLInjectionStrings] section. If you want to change the strings, you can do so by adding or removing entries here.

It is worth noting that the above rule is fairly aggressive about blocking requests. If this is an issue for your content, it is possible to make specific URLs exempt from UrlScan filtering. To do this, search the urlscan.ini file for the [AlwaysAllowedUrls] section and add the exempt URLs (one per line.) Note that URLs here should not include "http://hostname.com" or "https://hostname.com". Follow the example in the urlscan.ini comments for this section. Also note that the behavior of this section has changed with UrlScan 3.1. If you are using UrlScan 3.0, you cannot bypass query string filtering in this manner.

Note that it is very important that you thoroughly check any URLs for SQL Injection vulnerabilities before adding them to the [AlwaysAllowedUrls] section!

How can I check my logs for SQL Injection attempts?

UrlScan logs all of the requests that it blocks in UrlScan log files. The default location for these files is %systemroot%\system32\inetsrv\urlscan\logs. Beginning with UrlScan version 3.1, these logs are in W3C compliant format. Rejections triggered by the above SQL Injection rule will have "rule+SQLInjection+triggered" in the x-reason field.

You can check these logs periodically to see if you've been getting requests with SQL Injection attempts and also to see if your rule may be blocking legitimate requests.

In Conclusion

This should be everything you need to know to get a quick start in filtering SQL Injection attempts with UrlScan on your server. For more information about things UrlScan can do, check out the articles here.

Happy UrlScan filtering,
-Wade

Filtering for SQL Injection on IIS 7 and later

wadeh — Thu, 18 Dec 2008 23:47:00 GMT

This article is specific to IIS 7 and later. If you are using IIS 6.0 or earlier, please see this article.

Starting with version 7.0, IIS has a built-in feature that is able to filter HTTP requests. If a request is found to have contents deemed unacceptable to the administrator, it will be blocked before it is processed by a web application. This feature is useful as a mitigation tool in defense of SQL Injection vulnerabilities.

Definition of SQL Injection
SQL Server Injection Protection
Preventing SQL Injections in ASP
How To: Protect from SQL Injection in ASP.NET
Coding Techniques for protecting against SQL Injection in ASP.NET
Filtering SQL Injection from Classic ASP
Security Vulnerability Research & Defense Blog on SQL Injection Attack

Prerequisite

Before getting started, you should verify the specific version of IIS that you are using. If you are using SP1 or earlier with IIS 7.0, you will need to install this update to the request filtering component before applying the following configuration. If you are using IIS 7.0 with SP2, or any later version of IIS, you do not need to install any updates.

Configuring the Request Filter

To create a global filtering rule for SQL Injection:

Open the applicationhost.config file in the following path:

%systemroot%\system32\inetsrv\config\applicationhost.config

Search the applicationhost.config file for "<requestFiltering>" (without the quotes.)
Immediately under the <requestFiltering> tag, paste the following settings:

<filteringRules>
    <filteringRule name="SQLInjection" scanQueryString="true">
        <appliesTo>
            <add fileExtension=".asp" />
            <add fileExtension=".aspx" />
        </appliesTo>
        <denyStrings>
            <add string="--" />
            <add string=";" />
            <add string="/*" />
            <add string="@" />
            <add string="char" />
            <add string="alter" />
            <add string="begin" />
            <add string="cast" />
            <add string="create" />
            <add string="cursor" />
            <add string="declare" />
            <add string="delete" />
            <add string="drop" />
            <add string="end" />
            <add string="exec" />
            <add string="fetch" />
            <add string="insert" />
            <add string="kill" />
            <add string="open" />
            <add string="select" />
            <add string="sys" />
            <add string="table" />
            <add string="update" />
        </denyStrings>
    </filteringRule>
</filteringRules>

Save the changes to applicationhost.config.

What effect does this have on my server?

With the above configuration in place, IIS will look at each incoming request for pages with .asp or .aspx extensions to search for specific strings in the request's query string. If found, IIS will block the request and return a 404 Not Found page to the client. If you want to change the file extensions, you can add or remove fileExtension tags in the <appliesTo> section. The specific strings in the search are controlled by the <denyStrings> section. If you want to change the strings, you can do so by adding or remove entries here.

It is worth noting that the above rule is fairly aggressive about blocking requests. It is possible that this rule will block legitimate requests. If this is an issue for your content, it is possible to use a web.config file to create a rule that applies only to content under that web.config. Do do this, remove any overly restrictive strings from the above applicationhost.config rule. Then, in the web.config file, include the following configuration with the more restrictive settings in the <system.webServer> section. For example, if you have content on the server that requires "end" in the query string, remove the <add string="end" /> entry from applicationhost.config and then add the following into the web.config file where you want to restrict "end":

<security>
    <requestFiltering>
        <filteringRules>
            <filteringRule name="SQLInjection2" scanQueryString="true">
                <appliesTo>
                    <add fileExtension=".asp" />
                    <add fileExtension=".aspx" />
                </appliesTo>
                <denyStrings>
                    <add string="end" />
                </denyStrings>
            </filteringRule>
        </filteringRules>
    </requestFiltering>
</security>

Note that the name of the filteringRule tag must be unique and cannot conflict with a name in applicationhost.config or any other web.config files in the path.

Also note that if you want to skip request filtering for all but a specific directory or directories, it is possible to omit the filtering rules in applicationhost.config entirely and just use web.config files to constrain the paths to which filtering applies.

It is also possible to constrain the scope of filtering rules through the use of location tags.

How can I check my logs for SQL Injection attempts?

The request filter logs all of the requests that it blocks in the regular IIS W3SVC logs. Rejections triggered by a filteringRule will have a status of 404 with a substatus 19.

You can check these logs periodically to see if you've been getting requests with SQL Injection attempts and also to see if your rule may be blocking legitimate requests.

In conclusion

This should be everything that you need to know to get a quick start in filtering SQL Injection attempts on your web server. For more information about things the request filter can do, check out articles here and here.

Happy request filtering,
-Wade

UrlScan 3.1

wadeh — Fri, 31 Oct 2008 20:06:00 GMT

Earlier this year, it came to our attention that our customers were being subjected to a SQL Injection attack. In response to that, we updated the venerable UrlScan filter and released version 3.0 with new features that provide tools to provide some mitigation and allow users to address issues in their affected applications.

This effort has been largely successful, but it has driven attackers to come up with new techniques. Very recently, our internal security team brought it to our attention that they'd seen a new variation on the attacks. This new variation is trying to exploit a behavior in ASP's parsing of the query string for the Request.QueryString function. Note that ASP.NET's behavior in this area is different and ASP.NET applications are not vulnerable to this specific new technique.

The specific behavior in ASP results when the query string contains a name/value pair where the value contains a '%' sign that has not been escape encoded. Consider the following examples:

If the client sends "page.asp?abc=xyz", calling Request.QueryString("abc") will return "xyz".
If the client sends "page.asp?abc=x%79z", ASP will decode the value and Request.QueryString("abc") will also return "xyz".

But if you wanted the value to contain a percent, Request.QueryString requires the '%' sign to be encoded at %25. If you do not encode the '%' sign, Request.QueryString will drop it from the returned value. For example:

If the client sends "page.asp?abc=x%25yz", Request.QueryString("abc") will return "x%yz".
If the client sends "page.asp?abc=x%yz", Request.QueryString("abc") will drop the unescaped '%' and return "xyz".

It is the final example above that is problematic. If you have a filtering rule that is attempting to prevent "xyz" from reaching an ASP application, an attacker could try to get around the filter by sending it in a name value pair with an unescaped '%' in the value.

It is possible for UrlScan 3.0 to block the problematic request above, but to do so it is necessary to block any instance of a '%' sign in the query string. This would be effective, but it would also be subject to many false positives because it would also block '%' sign instances that are part of a valid escape sequence.

Enter UrlScan 3.1

It became clear pretty quickly that UrlScan needed a new tool to address this new attack in an efficient way. To do that, we've added the ability to deny unescaped '%' signs in a request. This new feature can be applied to unescaped '%' signs in the query string, in specific named headers, or anywhere in any header name or value.

To block any requests attempting to use an unescaped '%' to get around the query string filter, you can add a single rule to the urlscan.ini file. The following rule says that, for any ASP page, search the query string for an unescaped percent and, if found, block the request. To activate the rule, be sure to add to the RuleList property in the [Options] section of urlscan.ini:

[UnescapedPercentRule]
AppliesTo=.asp
DenyUnescapedPercent=1
ScanQueryString=1

And while we were adding this new feature, we were able to make a couple other fixes in UrlScan. The following changes have been made:

It was possible for certain escape sequences to get past filtering rules. This has been fixed.
Certain query string rules did not work properly on IIS 5.1. This has been fixed.
The behavior of the [AlwaysAllowedUrls] section has been changed. In UrlScan 3.0, any URLs listed in that section were not subject to filtering of anything that applied specifically to the URL. Effective with UrlScan 3.1, any URLs in that section are not subject to any UrlScan rules. This means that adding a URL to this section will prevent query string or other rules from blocking the URL.

The UrlScan team highly recommends that you update to UrlScan 3.1 today at one of the below links. If you are using UrlScan 3.0 to apply SQL injection filtering to Classic ASP pages, this is particularly important, along with adding the above rule to block unescaped '%' signs.

Also, any discussion of filtering for SQL injection or other injection attacks, it is important to remember that filtering is only a stopgap mitigation. It is essential to fix the vulnerabilities in the underlying code. Information on SQL injection vulnerabilities in applications can be found here and general information on security web applications can be found here.

UrlScan 3.1 can be downloaded from the following locations:

For 32 bit: http://www.iis.net/go/1697
For 64 bit: http://www.iis.net/go/1698

-Wade

UrlScan v3.0 Beta Release

wadeh — Tue, 24 Jun 2008 19:50:33 GMT

The IIS team has some street smarts when it comes to security.

We learned quite a few lessons the hard way back in 2001 with the outbreak of the CodeRed worm. One of the lesser known facts about the Code Red worm is that the vulnerability it exploited was not actually in IIS itself. It was an application that ran on top of IIS. Since that application was distributed with IIS and was installed by default, this distinction did not matter to our customers. IIS and CodeRed became associated with each other.

When we designed IIS 6, we took on the challenge of creating an environment to protect the server from vulnerabilities in applications we host. Our steps to address this issue ranged from not installing any applications (or even IIS itself) by default on a server, to providing a low privileged environment to minimize damage should a vulnerability be found. We also took a hard look at our engineering practices and changed the way we did things to minimize the chances for serious bugs in the IIS core code.

Our application of these lessons has withstood the test of time, with IIS 6 being recognized as one of the most secure server products ever released. We've applied the same principles to IIS 7 - and even extended them.

But back in 2001, IIS 5 was the current version of the web server and we needed to address the issues without waiting for the next IIS release. To do this, we released a set of tools with The IIS Lockdown Tool. This package included tools to go over configuration settings across IIS and set them to secure values appropriate to the applications running on the web server. It also included a runtime tool called UrlScan.

UrlScan installs as a filter on IIS and looks at incoming requests in real time. It can then screen requests based on a set of general request properties. For example, it can block overly long URLs or headers. It can block requests with unexpected HTTP verbs or strings in the URL.

Because CodeRed depended on a long URL and requests to a particular component, UrlScan was able to stop it in its tracks. While this was no substitute for an actual patch to the affected component, it did buy customers time and protected their servers until they could get patches installed. Over time, UrlScan was so effective at its job that we built most of its features into IIS 7 in the form of the request filter module.

Today, in 2008, we find ourselves in a similar situation. We are seeing a particularly nasty automated SQL Injection attack that is targeting our customers. This attack defaces web servers and sends their clients off to malicious servers that attempt to install malware. As before, the vulnerability does not exist in IIS - or any software from Microsoft. In this case, the attack is exploiting vulnerabilities in customer developed applications. And as before, the real fixes will need to come from the myriad developers of those applications.

Unfortunately, neither UrlScan nor the IIS 7 request filter have been able to mitigate these attacks. The reason for this is that the payload is delivered in the query string. For historical and some obscure RFC reasons, UrlScan never looked at the query string. And since the request filter is based on UrlScan, it has the same limitation.

As an initial measure to help our customers, we have released some sample ASP and ASP.NET code that can be used with existing applications to filter out these attacks. But both of these measures still require every affected page to be located and edited.

As our next measure, we are today releasing a beta for a new version of UrlScan - version 3.0 - that can reach these requests and block them. This release includes a GoLive license, so you can deploy it on your production servers. UrlScan version 3 is compatible with the configuration files for the existing UrlScan version 2.5, so you if you are already running UrlScan, everything will still work as it did - except you'll have new options. Also, since its been just over 5 years since UrlScan 2.5 shipped, we've taken the opportunity to add some frequently requested features. The new set of features in version 3 are:

Support for query string scanning, including an option to scan an unescaped version of the query string.
Change notification for configuration (no more restarts for most settings.)
UrlScan can be installed as a site filter. Different sites can have their own copy, with their own configuration.
Escape sequences can be used in the configuration file to express CRLF, a semicolon (normally a comment delimiter) or unprintable characters in rules.
Custom rules can be created to scan the URL, query string, a particular header, all headers or combination of these. The rules can be applied based on the type of file requested.
Support for 64 bit IIS worker processes.

We also have plans to update the IIS 7 request filter to add these features. In the interim, UrlScan 3 is fully supported on IIS 7.

Please feel free to download the UrlScan version 3 beta for 32 bit or 64 bit and discuss it in the Security Forum here on iis.net.

Finally, it cannot be overstated that these tools are just an interim measure to buy time to fix the affected applications. While they are effective against the current wave of automated attacks, they cannot protect against more directed attacks against a specific server. The category of SQL Injection vulnerabilites is so broad that there are no known filter strategies that can block a determined hacker against application vulnerabilities. There are many resources available for learning about SQL Injection attacks and prevention strategies. One of the nicest collections of links I've seen has been published in MVP Harry Waldron on his blog here.

Understanding FastCGI Settings for IIS 5.1 & 6

wadeh — Fri, 02 Mar 2007 05:02:00 GMT

So here it is, my first ever blog post.

I am not new to posting about IIS on the internet. A quick newsgroup search reminds me that I've posted to around 900 threads related to IIS. The first time was on June 10, 1997, where I helped someone to get "server push" to work from a CGI on IIS.

It strikes me as a bit ironic that my first usenet post for IIS was on CGI, and my first blog post for IIS will be on FastCGI. In the interim 10 years, I've worked far more with ISAPI than CGI. In fact, it's my expertise with ISAPI that's drawn me to doing FastCGI support for IIS 5.1 and 6.

So what does ISAPI have to do with FastCGI? To answer the question, let's start by looking at plain old CGI.

CGI, which stands for "Common Gateway Interface" is a way for application developers to interact with a web server. And it is a very old specification. Every version of IIS that has ever shipped has supported CGI. It's a simple specification: Basically, when a web server receives a request, it creates a new process to handle a request. For the new process, the stdin handle is remapped so that it receives request entity from the client, the stdout handle is remapped so that it writes response data to the client, and the command line and environment variables are set to provide other server and request information to the CGI process. There is some magic that happens in the response that allows the CGI to specify custom response status and headers, but there's not much more to it than that.

The problem with CGI, from IIS's perspective, is that IIS is somewhat at a disadvantage to its competition in handling requests. The issue is that every single request will result in a new process spinning up, doing work, and shutting down. If you are on an operating system that has very light weight process creation, the performance is bound by the "doing work" part of the equation. Unfortunately, if you are on an operating system where process creation is an expensive operation, the "doing work" part of the equation can be overwhelmed by the "process creation" part. This is the reason that CGI flourishes on our main competition running on a Unix-based platform, but is not recommended on IIS.

This is most definitely not to say that IIS has a performance disadvantage. To the contrary, IIS is quite capable of keeping up with - and often surpassing - the performance of other web servers. The reason for this is ISAPI.

ISAPI, which stands for Internet Server Application Programming Interface, is completely internal to the web server process. When a new request comes in for an ISAPI, no new process is created. Instead, the web server calls an entry point in a dll that is loaded into the web server process. If the ISAPI is written with an understanding of how the operating system threading model works, it can be blindingly fast.

So what is FastCGI, and why do we need it? Basically, we need FastCGI due to the existence of popular CGI-based development platforms, not the least of which is PHP.

PHP has run on IIS for years, with both CGI and ISAPI implementations. Unfortunately, both implementations are a compromise when running on IIS. The CGI implementation is a compromise due to the performance characteristics of process creation on Windows. So why is the ISAPI implementation a compromise? Remember what I said above about "threading model"? When PHP runs as an ISAPI, it runs inside the web server process in a highly multithreaded process. As it turns out, the PHP implementation itself is thread safe - but lots of folks use extensions to PHP that may or may not be thread safe. If you end up using a non-thread-safe extension to PHP with the ISAPI, the result is an unstable server. For this reason, some people are able to run the ISAPI version of PHP, and some are not.

FastCGI offers a compromise solution that can deliver both performance and stability. To do this, FastCGI preserves almost all of the original CGI specification, including a non-multithreaded environment - but it allows the host CGI process to remain alive after the request finishes, so that it's ready to be reused for another request. Since the process can be used over and over, the cost of process creation drops out of the equation. The difference between a regular CGI and a FastCGI is that a FastCGI has a layer in the process that maps the FastCGI protocol into the stdin, stdout and such that CGI uses. There are available libraries (from outside of Microsoft) that can be simply linked into existing CGI source code with very minor modifications.

So what does my ISAPI background have to do with FastCGI?

Well, for the IIS 7 version of the PHP handler, it has nothing to do with it. In fact, the main parts of the FastCGI handler, and all of the IIS 7 module code were written by Rick James (who has written lots of FastCGI stuff in his blog, and is very active on the FastCGI forums.) This is because IIS 7 has an all new, and very powerful API, that works well for hosting many different platforms.

Earlier versions of IIS, on the other hand, don't have this rich new API. Because of that, it's necessary that the FastCGI handler for these versions of IIS to run on top of ISAPI. My day-to-day responsibilities don't give me much time to write code any more, so when I saw a need to port FastCGI to ISAPI, I jumped at the chance to keep the project for myself.

With the history lesson over, let's talk a bit about what the FastCGI handler has to do in IIS, which will lead to understanding what all of the configuration options do.

The FastCGI handler is broken into a few parts: Applications, the Application Manager, and various code to support the FastCGI protocol.

Because you probably want to be able to handle multiple, concurrent requests, it is necessary to have a pool of processes available and ready to handle a request. In the FastCGI handler, this pool of processes is called an application (and since the term "application" is already so overused in the web world, I often just go ahead and use the term "process pool".) There are a number of properties of a process pool that you might want to manage. For example, you probably want to specify the number of processes in the pool, or the number of requests a process is allowed to accept before it's shut down and recycled, etc.

The FastCGI handler can support multiple process pools. The reason for this is that you may want to run more than one kind of FastCGI on one server - for example, both PHP and Ruby. You may also have multiple sites on your server, and you may not want requests for those sites to share the same processes, especially if you want the site processes to run as different users. The piece that handles multiple process pools is called the application manager.

Finally, you need to wire the FastCGI handler into IIS, so that requests can be routed to it. As it turns out, IIS 7 does this in a different way than IIS 5.1 and 6. In this blog entry, I am only going to discuss IIS 5.1 and 6. This is done with an IIS configuration setting called "script maps", which basically associates a file extension with the ISAPI that should handle it. In addition, the script mapping has an optional setting that will only allow requests to be processed where the physical file associated with the request exists. This is the default setting for security reasons (which may be another good blog topic), but there are times when you may want to allow a URL which has no physical file behind it. The ISAPI extension that contains the FastCGI handler is called fcgiext.dll. So if you want the FastCGI handler to accept PHP requests, you would set up a script mapping that associates ".php" with fcgiext.dll; for Ruby, you would map ".rb" to fcgiext.dll, etc. In IIS 6 (but not 5.1), it is also possible to set up a "wildcard script map" where all requests can be routed to an ISAPI dll. If you create a wildcard script map for fcgiext.dll, all requests would go to FastCGI, regardless of file extension.

So now that we know how the FastCGI handler works, let's talk about the specific things that you can put in the fcgiext.ini file.

There is one section in fcgiext.ini file that is required, no matter what FastCGI you are trying to run. That is the types section. The purpose of the types section is to associate a file extension with a specific process pool. Note that this is different than the script mapping described above. If you set up script mappings, for example, for both .php and .rb, the FastCGI handler needs to know how they are different from each other, and the types section does this work.

To see what is possible, let me show the types section from the fcgiext.ini file on my test machine. This is the actual file that I used while writing and testing the FastCGI ISAPI:

[Types]
echo=c:\echo\echo.exe
php=c:\php\php-cgi.exe
fooby=c:\echo\echo.exe
php:123154536=PHP Site 2
php:123154537=PHP Site 3
*=Wildcard Mapping

The format of the file is pretty simple at first glance. It is basically "file-extension:process-pool". You can tell from the first three entries in this ini file that I probably have script maps set up that associate ".echo", ".php" and ".fooby" with fcgiext.dll, and you can see each of those is associated with a FastCGI compliant exe file. And in the first technical preview, this would have been it.

The next three entries are demonstrate new capabilites that were added in the second technical preview. There are two more ".php" associations, but they have some long number behind them, and they don't have exe files associated with them. The numbers behind them are site instance IDs. These numbers tell the FastCGI handler that the association should only apply to a specific site with that ID. And, starting with the second technical preview, the process name is no longer associated with the file extension in the types section. Now, the association is made between a file extension (which is optionally site specifc) and a section name that must appear later in the fcgiext.ini file. The reason for the latter change is that we need to be able to support declaring arguments for the process, and since we might want different pools running the same process with different arguments (a likely scenario for Ruby), we can't depend on the process name to define all of the process pool settings. For compatibility with the first technical preview, we will still use the section name as the exe path if it's not otherwise specified in the section.

Let's look at the section for the ".echo" association:

[c:\echo\echo.exe]
QueueLength=999
MaxInstances=20
InstanceMaxRequests=500

This section was created during development of the first technical preview. Since it doesn't have an ExePath setting, which is how the second tech preview declares the exe, the FastCGI handler will just use the section name for the path to the exe.

Now, lets look at the section for PHP Site 2, which only applies to the site with 123154536 as its ID:

[PHP Site 2]
ExePath=c:\php\php-cgi.exe
Arguments=site2
QueueLength=1001
MaxInstances=20
IdleTimeout=200
ActivityTimeout=20
RequestTimeout=60
InstanceMaxRequests=1000

In this section, you can see that we are associating ".php" requests on that site with c:\php\php-cgi.exe. Also, you can see that we are passing "site2" as an argument to the process when we start it. This is different from PHP Site 3, which looks like:

[PHP Site 3]
ExePath=c:\php\php-cgi.exe
Arguments=site3
QueueLength=1001
MaxInstances=20
IdleTimeout=400
ActivityTimeout=40
RequestTimeout=120
InstanceMaxRequests=1000

In this case, we are passing "site3" as the argument when we start c:\php\php-cgi.exe. Note that the Arguments setting is optional, and you can pass multiple arguments using a space delimiter just like you would on the console command line. If you need spaces within the arguments, instead of as a delimiter, you should be able to use quotes - again, just line the command line.

Before talking about the Wildcard Mapping, let's take this opportunity to look at the other settings that can be used in each process pool:

ExePath - The path to the process to use in the pool

Arguments - Arguments to pass to each process in the pool at start time. This setting is optional

QueueLength - What happens if you get more simultaneous requests than you have processes to handle them? Why, we queue them, of course. This setting controls the number of requests for the process pool that we will queue before they start failing. The default value is 1000 requests.

MaxInstances - This is the highest number of processes we will allow in the pool. The default is 10. Note that this number is a maximum. We won't create the processes until we need them. If you never have more than two concurrent requests, we will only start two processes.

InstanceMaxRequests - This is the number of requests that we will send to a process in the pool before we shut it down and recycle it. The default value is 1000.

IdleTimeout - This is the number of seconds that a process can site idle, without working on a request, before we will shut it down. The default is 300 seconds.

ActivityTimeout - The is the number of seconds that the FastCGI handler will wait for I/O activity from a process before we terminate it. The default is 30 seconds. Note that, internally, we double that number on the first I/O from a newly started process. This allows a process to take some extra time to start up without incurring the wrath of the timeout period.

RequestTimeout - The is the maximum amount of time that we'll allow for a FastCGI process to handle a request before we terminate it. The default is 90 seconds.

Now let's take a look at that '*' association with Wildcard Mapping. This is something that applies only to IIS 6. IIS 6 allows a special kind of script map that applies to all requests. If you set up fcgiext.dll as a "Wildcard Scriptmap", this assocation will catch any requests that don't have a more specific association. For example, with the types section above, if you request a "/foo.bar", the ".bar" file extension doesn't have a specific association, so it will be caught by this '*' association and go to the process pool called "Wildcard Mapping". Let's take a look at that section:

[Wildcard Mapping]
ExePath=c:\echo\echo.exe
QueueLength=1000
MaxInstances=20
InstanceMaxRequests=100
IgnoreExistingFiles=1
;IgnoreDirectories=1

Most of it looks just like the other process pool sections, but it has two new settings that are only used for wildcard script maps (and thus, only IIS 6): IgnoreExistingFiles and IgnoreDirectories. Remember way back in my discussion above about script mappings where I said that you might want to handle requests that don't map to a script file? If you do this, it would be very convenient if you could have the FastCGI handler handle these non-file requests, but still get IIS to handle other files in the directory normally - and that's exactly what these two settings provide:

IgnoreExistingFiles - If this is set to 1, the FastCGI handler will check to see if the requested URL exists as a file. If so, the FastCGI handler will defer processing of the URL so that it will be processed without FastCGI. The default value is 0.

IgnoreDirectories - If this is set to 1, the FastCGI handler will check to see if the requested URL exists as a directory. If so, the FastCGI handler will defer processing of the URL so that it will be processed without FastCGI. This effectively allows default documents and directory listings to be served. The default value is 0.

It is possible to set a site-specific wildcard mapping using the same site ID syntax that file extensions use (ie. "*:12345678=Section Name". The search order for file extensions is significant. When a request reaches the FastCGI handler, the associations in the types section are checked in the following order:

- A specific file extension association specific to the site ID

- A '*' association specific to the site ID

- A specific file extension association with no side ID specified

- A '*' association with no site ID specified

There is one other process pool setting that is pretty esoteric:

FlushNamedPipe - There are some cases where a FastCGI might not read all of the data from the named pipe that communicates with the web server. If this happens, the web server will wait for a read that isn't coming, effectively deadlocking that member of the process pool. This most often happens in the case where the FastCGI process exits when we don't expect, due to its having an internal notion of the max number of request is will handle that is lower than our InstanceMaxRequests setting. Setting FlushNamedPipe=1 causes FastCGI to flush data that might lead to this condition. The default is 0.

----------

So that is my first blog entry - whew! It turned out to be a whole lot longer than I expected, but I wanted to be thorough about how the FastCGI handler works on IIS 6 and how it is affected by each of the available configuration options.

If you have specific feedback about the content of the material or the presentation style, I would love to hear it. I promise that they won't all be this long...