Getting Started with LinkDeny

LinkDeny allows you to granularly control access to your Web site content and to protect your site from hotlinking, leeching or bandwidth theft of valued Web site content.



Installation and Activation

Major Components

LinkDeny consists of the following major program components:

  • An ISAPI filter (LinkDeny.dll) which is installed in %SystemRoot%\System32\inetsrv, and mapped to the service (W3SVC) node in the Internet Information Services (IIS) metabase. The component implements all LinkDeny functionality within IIS.
  • A graphical user interface called the LinkDeny Settings Manager (LinkDeny.exe), which is installed in the LinkDeny installation directory (by default C:\Program Files\Port80\LinkDeny). The LinkDeny Settings Manager is the primary way most users will interact with and configure LinkDeny.
  • An XML rules file (rules.ld). This file stores the underlying LinkDeny configuration. It is read and written to by the LinkDeny Settings Manager, and can also be edited manually. A master copy of the rules.ld file, having the default settings, is stored in the data sub-directory of the LinkDeny installation directory. In addition, when LinkDeny is enabled for a given site, a rules.ld file is created in the home directory of that site.
  • Templates.ld is an XML configuration file containing predefined LinkDeny rule templates which can be enabled at the user's discretion via the LinkDeny Settings Manager. The templates.ld file is found in the data sub-directory of the LinkDeny installation directory
  • GeoIP.dat is a binary database of geographical IP information, for use with LinkDeny rules that have Geographic IP tests. The GeoIP.dat file is found in the data sub-directory of the LinkDeny installation directory

Installing LinkDeny

LinkDeny uses a single installer for both 32-bit and 64-bit installations. The installer determines which type of operating system is in use before installing the appropriate files. In addition, the installer is capable of installing any runtime packages required by LinkDeny.

Depending on the current configuration of your IIS server(s), there are runtime prerequisites that might be missing or out of date when LinkDeny is installed. The two most common are:

  • .Net Framework 2.0 (or better)
  • Visual C++ 2005 SP1

When the LinkDeny installer detects that a runtime prerequisite is missing or out of date, it asks the user if an outbound Internet connection is available. (As a security best practice many production Web servers are not permitted to initiate HTTP connections.) If a connection is available, then the required files will be downloaded automatically. If a connection is not available, then the installer will provide instructions for downloading the necessary files from another computer. If it proves necessary to interrupt the installation in order to download files manually, the installer can either be left open in the meantime or else cancelled and rerun once the files are available locally.

Trial and Activation

When first installed LinkDeny will be in trial mode. The trial period lasts for 30 days, during which time all of LinkDeny's features are fully functional.

At the end of the trial period, LinkDeny will cease functioning. Your IIS server will continue to function normally, and LinkDeny rules added or modified during the trial period will be persisted in the various rules.ld files, but no LinkDeny rules will be enforced.

LinkDeny may be activated at any time during the trial period, or after that period has ended, thereby continuing (or, if the trial has ended, restoring) full functionality. Activation always requires the prior purchase of a LinkDeny license from www.port80software.com, or the purchase of an additional activation if you already own a LinkDeny license and are seeking to activate an additional server.

After purchasing a license (or a new activation for an existing license) there are two options for completing the activation: If your IIS server can initiate outbound SSL (HTTPS) connections, you can activate online. If your server lacks an outbound secure connection, you can use the email-based activation alternative. Both activation options are available on the activation dialog that comes up whenever the LinkDeny Settings Manager is launched in trial mode.

System Requirements

The System Requirements for LinkDeny are as follows:

  • A compatible version of IIS and Windows:
    • IIS 7.5 / Server 2008 R2 with Service Pack 1
    • IIS 7 / Server 2008 with Service Pack 2
    • IIS 6 / Server 2003 (all editions) with Service Pack 2
  • Compatible hardware:
    • x86 (32-bit)
    • x64 (64-bit)
  • Required runtimes:
    • .Net Framework 2.0 (or later)
    • Visual C++ 2005 SP1 Runtime

Notes:

  • For best results, IIS 6.0 should be in its default isolation mode (Worker Process Isolation Mode) not in IIS 5.0 isolation (backwards compatibility) mode.
  • For IIS 7.x / Server 2008 installations, the following IIS Role Services must be installed:
    • ISAPI Filters
    • IIS 6.0 Metabase Compatibility
back to top

Your Security Policies and LinkDeny Rules

LinkDeny is rules-based security software for protecting online resources. To use the software, employ the LinkDeny Settings Manager to create LinkDeny rules that reflect your desired security policies.

Thus, before jumping in and starting to create LinkDeny rules, it is a good idea to pause and think about what security policies you want LinkDeny to enforce.

To create a good security policy, you generally need to know three things:

  1. The resource(s) you want to protect.
  2. The type of threat(s) you want to protect against.
  3. What action to take once a threat is discovered.

Resources to protect, threats to protect against, and actions to take -- think of these as the three logical parts of a complete security policy.

A good way to come up with a list of the security policies you want LinkDeny to enforce would therefore be to create a simple document with three columns, one for each logical part of a given policy. After going through such an exercise, for instance, you might have come up with the following two policies:

Resource Threat Action
Policy 1 Proprietary images Linked to by other sites Replace with a warning image
Policy 2 Extranet directories Unauthorized users Restrict to known IPs

Your own list of security policies will probably be longer than this, but it should have a similar form, so that you can be clear about what you are trying to accomplish. Of course, it helps in building such a list to have an idea of the kinds of things LinkDeny can do. We will cover that in a preliminary way here, then in more detail in the next section:

  1. What resources can LinkDeny protect?
    The resources you want to protect are entirely up to you. Since LinkDeny can identify resources based on both their URL path and their MIME type, you should be able to create a policy for any resource or subset of resources you want to protect on any Web site or application.

  2. What kind of threats can LinkDeny protect against?
    LinkDeny protects resources by testing requests for those resources to make sure those requests are legitimate. LinkDeny can perform up to a half-dozen different tests against requests for any number of protected site resources. These tests can in turn be logically combined in a variety of ways to provide even tighter coverage. These tests are the heart of LinkDeny rules, and you will learn about them in more detail in the next section.

  3. What can LinkDeny do about threats it identifies?
    When it comes to handling the various threats, LinkDeny gives you several options, ranging in severity from merely logging them (for tracking and analysis purposes) to responding with a blunt, uninformative, yet secure server-side HTTP 404 message.

As you will see shortly, actual LinkDeny rules map very well onto security policies like the ones given in the example above. This is why, once you know the security policies you want enforced, it is quite easy to create the corresponding LinkDeny rules, so that LinkDeny can begin protecting your online resources.

Before you get started creating and enabling LinkDeny rules on your server, however, you will want to have a clear understanding of how a LinkDeny rule is put together. This will help you translate your desired security policies into the appropriate LinkDeny rules in the easiest and most efficient way.

back to top

The Grammar of a LinkDeny Rule

A single LinkDeny rule is a powerful security tool. It is also a logical unit, composed of the following parts:

  • Rule-Name
  • Selector
  • Rule-Type
  • Tests*
  • Action

Let's look at each of these parts in detail:

Rule-Name

This is just a friendly name for the rule. It can be anything, but you should always try to use something descriptive of what the rule is trying to do, to make it easy to manage your LinkDeny rules in the future. In test cases and templates, we tried to name our LinkDeny rules to match the desired intent of security policy for a specific LinkDeny rule.

Selector

This is the part of a LinkDeny rule that answers the question, "What resource(s) should this LinkDeny rule protect?" If the requested resource matches the Selector, the rule will be evaluated for that resource, otherwise not. This is what allows you to have different rules (and thus different policies) for different resources. LinkDeny Selectors are made up of three parts: A Selector-Type, a Match-Type and a Match-String. The Selector-Type lets you choose whether to compare the Selector against the request's URL path or its MIME type (To find out how to view all the MIME types registered in IIS, click here). The Match-Type gives you three options for how to do the comparison between the Selector and the request (you can choose an exact match, a wildcard match, or a Regular Expression match). And the Match-String is the actual string of characters that is compared against the request. As you can see, the complete Selector gives you a great deal of flexibility in deciding the rule's scope -- how widely or narrowly a given rule will apply.

For example, imagine six LinkDeny rules with the following six Selector match-strings:

  1. /images/*
  2. /images/foo.jpg
  3. /images/[^\/]*
  4. image/*
  5. image/png
  6. image/(png|gif)

In this example, the wildcard URL path Selector match-string /images/* would apply to all files in the directory called "images" located in the site's root directory (and all files in sub-directories of /images), while the exact match URL path Selector match-string /images/foo.jpg would apply only to the file "foo.jpg" in that same directory. If you wanted the rule to apply only to files in the /images/ directory and not any files in sub-directories of /images/, you would need to use a Regular Expression Selector match-string, such as /images/[^\/]*. This specifies only URL paths with no further slashes after "/images/", meaning only files. In the same vein, the wildcard MIME Selector match-string image/* would apply to all image content in the site, while the exact match MIME Selector match-string image/png would only apply to images of PNG type. However, if you wanted to protect only PNG and GIF files, but not other image content, you could use the Regular Expression Selector match-string image/(png|gif).

Putting all of these example Selectors together, suppose we had a request for a jpeg image called bar.jpg, living in the root directory of the site. Which of our Selectors (hence which of our rules) would apply to this request?:

  1. The rule with the /images/* Selector would not apply, because the URL path of the request does not point to the "images" directory.
  2. The rule with the /images/foo.jpg Selector would not apply, because it is not an exact match for the URL path of the request.
  3. The rule with the /images/[^\/]* Selector would not apply, again because the URL path of the request does not point to the "images" directory.
  4. The rule with the image/* Selector would apply, because the MIME type of the requested resource (image/jpeg) is one of the image sub-types.
  5. The rule with the image/png Selector would not apply, because the MIME type of the requested resource is a different image sub-type than the one given in the Selector.
  6. The rule with the image/(png|gif) Selector would not apply, because the Regular Expression Selector does not match the MIME type of the requested resource.

Rule-Type

Once we know (thanks to the Selector) that a requested resource should be protected by this rule, the next question a LinkDeny rule has to answer is, "What specific threats should this LinkDeny rule protect this particular resource against?" The first part of the answer comes from the Rule-Type. The Rule-Type has a specific question of its own to answer: "How will these threats be identified -- directly, or indirectly?"

A LinkDeny rule can be one of two general types: A Deny Rule or an Allow Rule. A Deny Rule directly identifies specific threats so that they can be handled by LinkDeny. An Allow Rule, on the other hand, identifies legitimate requests for a resource. This means that it identifies threats not directly but indirectly, by a process of elimination.

Deny rule logic is sometimes called "blacklisting" or "negative model" security, whereas Allow rule logic is sometimes known as "whitelisting" or "positive model" security. LinkDeny can use both security models, and you can even intermix rules of different types, to construct a blended security model.

As you will see below, each LinkDeny rule contains one or more Tests, and it is these tests which really make up the heart of a LinkDeny rule. When considering the different Rule-Types, therefore, it is important to keep in mind that the role or purpose of the rule's test(s) will be different, depending on the Rule-Type. In particular, the Rule-Type changes what it means for a request to "pass" a given test. This can be a little tricky to understand, so it's worth going over in some detail before we consider the different tests that are available to you:

When you choose a Deny Rule-Type, that rule's tests are used to single out requests that need to be acted on by LinkDeny. Think of medical tests that screen for a variety of diseases. In this case, since the tests are looking for something bad, a request can only "pass" if there is no match between the request and any of that rule's tests. The requests that "fail" -- that need to be acted on by LinkDeny -- are those that matched at least one of the rule's tests.

When an Allow Rule-Type is chosen, on the other hand, the tests are used to pick out requests that can safely be permitted access without any action by LinkDeny. Think of an academic exam, or a driver's license test. In this case, since the rule is looking for a set of desirable characteristics, a request can only "pass" if there is a match between it and the tests within the rule. Here, the requests that "fail" -- that need to be acted upon by LinkDeny -- are those that failed to match the rule's test(s).

(A minor point about Allow rules is that it is up to you to decide how restrictive to be when applying multiple tests: you can require matches on all of the tests in the rule, or accept a match on any one test. With Deny rules, by contrast, one match always results in the request being marked as disallowed.)

Tests

The second part of the answer to the question of what threats a LinkDeny rule should protect against is provided by one or more tests applied to all requests for a protected resource (a resource that matches the rule's Selector). These tests are the heart of a LinkDeny rule because they are how LinkDeny identifies certain requests as threats to the resources it is supposed to protect -- threats it must intercept and act upon. There are five kinds of tests to choose from, and we will look at each one in detail in a moment: Referer, User-Agent, IP Address, HTTP Request Conformance and Time Limit.

As you read these test descriptions, keep in mind that a LinkDeny rule can use just one single test, or a combination of several, and that the Rule-Type will affect how a test is interpreted, as well as how multiple tests are treated: A Deny Rule will identify a request as a threat if it matches any one of the tests that make up the rule, and only tests that have no matches are allowed to pass. In contrast, an Allow Rule will identify a request as a threat if it fails to match the test or tests that make up the rule, and you decide whether a "passing grade" requires matching just one test, or all of them.

Referrer Test

The referer test allows you to test for the presence of a specific URL or set of URLs in a request's HTTP Referer header. Since requests for the objects that are required by a page (e.g., images, JavaScript, CSS) will have that page's URL in the Referer header, the Referer test provides a convenient way to differentiate between requests local to the site and attempts to "leech" (make unauthorized use of) such objects from outside the site. A simple test, for example, might be to allow requests for your images only when the Referer URL starts with your own site's domain name -- thereby denying all requests for your images made from other sites that try linking directly to them. To implement this, you might use an Allow By type rule with a Referer test that checks the HTTP Referer header against a wildcard expression such as http://www.mysite.com/* (exact matches and Regular Expression matches are also available). The Referer test can also be a useful way to limit the "entry points" to your site, by allowing only a limited number of pages to be requested from other domains. Finally, using a Deny By Rule-Type, you could exclude certain referers that are known or suspected by you to be linking to your content in an unauthorized or illegitimate way.

User-Agent Test

The User-Agent test is similar to the Referer test in that it tests a request by looking at the value of a particular HTTP header. In this test, however, the header is User-Agent, and it customarily contains the user agent string that identifies the browser, proxy server, or other software that is making the request. User-Agent tests can be used to restrict certain content to certain browsers and even to direct certain browsers or bots to specialized content (a well-known Web development task called "browser detection"). As with the Referer test, the match can be exact, wildcard based or Regular Expression based. A simple example would be the wildcard expression *MSIE 7.* which would single out Internet Explorer version 7.0 (along with any subsequent minor version upgrades). A good list of user agent strings is available at http://en.wikipedia.org/wiki/User_agent.

IP Address Tests

There are really two types of IP Address test: Custom IP and Geographic IP. With the Custom IP version of the test, you can allow or deny any IP address or range of IP addresses. Obviously, this can be a very handy way to reinforce the security of an extranet application, among other uses. The Geographic IP version of the IP Address test lets you test not against hard-coded IPs, but rather all the IPs that are associated with a given country or group of countries. This feature of LinkDeny is preconfigured with numerous useful country and regional groups (e.g., Top Countries with High Risk for Phishing Attacks). Here again, these tests can used both to restrict access to certain users and also to direct specific users to specialized content.

HTTP Request Conformance Test

This test is primarily useful for the control of unfriendly bots, crawlers and scripts. It does this by allowing you to build a sort of profile of the types of requests you want to allow (if using an Allow Rule-Type) or deny (if using a Deny Rule-Type). This profile can be based on the values contained in the HTTP request line (i.e., the HTTP Method and/or the HTTP Version) and/or the presence of specific HTTP headers. For instance, you might use an Allow rule that requires the request to be either a GET, HEAD or POST, to use HTTP 1.1 exclusively, and to contain (non-empty) Accept, Accept-Encoding, Accept-Language, Connection, Host and User-Agent headers (or any custom HTTP header names associated with your particular Web application).

Time Limit Test

This test is designed to provide an additional layer of security when seeking to prevent things like leeching or unauthorized cross-linking. Referer and other headers and even client IPs can be spoofed, thereby disguising illegitimate requests as legitimate ones. To combat this, LinkDeny also allows you to protect resources by requiring them to be requested with a temporary, user-unique access key. Because the access key is time limited, it cannot be hijacked and later reused in unauthorized ways. Effectively, this forces legitimate users to establish a LinkDeny session in order to access the protected resources. This session requirement can only be fulfilled by receiving one of the user-unique, time-limited access keys from LinkDeny and then passing that same key back when requesting additional resources. When you set up a Time Limit test, you have the option of requiring that the temporary, user-unique access key be transmitted in a session cookie, or in the URL paths, or (for extra security) in both.

There are a number of special considerations to keep in mind when using the Time Limit test:

  • When the URL path Selector-Type is selected, the links to the protected resources in your source code must include a URL Flag and 20 character URL Mask (both configurable). This Flag/Mask sequence in the source code URLs allows LinkDeny to efficiently insert the temporary, user-specific access key each time a protected resource is served.
  • The Time Limit test is unique in being the only LinkDeny test that can be used only as an Allow By Rule-Type, never as a Deny By Rule-Type (since it makes no sense to Deny users who have a valid session).
  • Although you can have more than one rule per site that includes a Time Limit test, the Time Limit itself (that is, the expiration time for the temporary, user-specific access keys) is the same for all the Time Limit tests in all the rules on the site.

Action

The final part of a LinkDeny rule is the Action. When the Selector has identified a resource to protect, and when the Tests have identified a particular request as a threat to that resource, then the Action comes into play to answer the final question, "What should be done about this particular threat?" When a request for a protected resource has been identified as a threat to that resource, LinkDeny will execute one of the following four actions for that request:

Log Only

Threats to protected resources are logged, but no other action is taken against them. This mode is very useful when testing for vulnerabilities and/or testing the impact of new rules. By setting up a rule and monitoring the events logged by that rule, you can confirm (or disconfirm) the presence of suspected threats (e.g., are my images being leeched?) and avoid misidentifying legitimate requests as threats and thereby blocking desirable traffic (by weeding out false positives).

Redirect to URL

This option is useful when you want to send users who fall outside of the intended audience for a given resource to some alternative resource, or to a context-specific message informing them why they are not permitted to access the originally-requested resource. A note of caution: When using this option, take care not to create infinite loops by redirecting requests to an alternative resource that is protected by the same rule. This is normally an easy error to avoid, but it can crop up in unexpected ways, as when a request is bounced between several protected resources, covered by several different rules, only to wind up being redirected back to resources protected by the original rule. The safest policy is always to redirect to a resource that is not itself covered by any rules (i.e., to which no Selector applies). And of course you should always test your complete rule set fully before deploying it to production, or updating it once in production.

Replace with File

This action affords the option of replacing a protected resource with an alternative one, but without redirecting the user. Instead of a redirect (which depends on a browser or other user agent to fetch the target file -- and will mean performance penalty on the browser side to request the redirected URL), the Replace with File option simply transparently serves the target file in place of the requested one. This is especially useful for example if you want to serve alternative images in place of protected ones to preserve a page layout while denying access to some of its content -- or when you are concerned with the speed of the replacement (itself a "redirection") on the browser side. You can also use this option to deliver a customized error page in place of a protected one, without changing the URL the user sees in the browser.

Send 404 Error

Sometimes the most desirable action is to block a request in the most efficient manner possible, while disclosing the least information possible to whomever or whatever made that request. This is often the wisest policy for the most serious security threats, for example, because it prevents someone probing your defenses from learning anything useful about them. The Send 404 Error action accomplishes this by sending a terse, uninformative 404 error message in place of the protected resource. This message is designed to disclose the least information possible about the protected resource, and any related resources (especially to scripts and bots), and to do so at the lowest cost in bandwidth and server resources (itself a useful counter-measure to error-generating Denial of Service attacks). Think of it as your bare-bones, maximum-security choice among the Action options.

back to top

Combining Two or More Rules

To implement a complete set of security policies, you will probably need to use several LinkDeny rules in conjunction, including potentially some rules whose Selectors overlap (meaning that two or more rules could apply to the same request). This raises the question of how LinkDeny handles the evaluation of multiple rules.

When using multiple LinkDeny rules in conjunction, there are several things to keep in mind:

  1. Rules are evaluated in top-to-bottom order -- the order in which they appear in the list of rules for a site.
  2. LinkDeny automatically stops processing rules for a given request as soon as it takes the Action specified by a rule (since LinkDeny Actions are designed to protect your resources, the first reason to act is reason enough). This means that when a request matches any one of the tests in a Deny rule, rule evaluation for that request stops immediately. LinkDeny already knows what it needs to do with that request. The same thing happens when a request fails to match the required number of tests in an Allow rule (either one or all, depending on how the rule was set up). In all of the above cases, the fate of the request is sealed, so LinkDeny can stop interrogating rules and tests, and start acting on the request.
  3. By default, a request that "passes" a rule does not stop rule processing--there might be other rules, further down in the rule set, with other reasons to stop that request, and they normally are allowed their chance to do so. So when a rule's tests have been passed, it really only means that the request has been given a conditional pass--it will be allowed through, conditional on passing all subsequent tests. This default policy is designed to make sure that users do not accidentally "short circuit" LinkDeny rule evaluation and permit requests that they had intended to block.
  4. There are times, however, when you really do need an Allow rule to stop all further rule processing and immediately allow a given request to pass, even if there are rules further down the list that would have blocked that request. When that is the case, you can mark that Allow rule with a special flag that gives it the power to do just this. This makes your Allow rule unconditional. As long as you are aware of what you are doing, there is nothing wrong with stopping rule evaluation on the passage of an Allow rule.

Note: For performance reasons, you should arrange your rules such that you maximize the likelihood of terminating rule evaluation early. This is because the more rules LinkDeny has to evaluate before deciding to act on a request, the longer the individual decision will take, and the more server resources will be used to make that decision. This means that you will generally want to give priority to rules that are most often going to result in the rule Action being taken (or more generally in rule evaluation being terminated). You can accomplish this by following these general guidelines:

  • Deny rules should be positioned above Allow rules.
  • Allow rules with the "stop rule evaluation" flag should be positioned above Allow rules without that flag.
  • Allow rules that require all tests to have a match, for the request to be allowed, should be positioned above those that require only one test to have a match.
  • Deny rules that are more likely to generate matches should be positioned above Deny rules that are less likely to generate matches.
  • Allow rules that are less likely to generate matches should be positioned above Allow rules that are more likely to generate matches.
back to top

Using the Settings Manager

The Settings Manager can be launched from the Port80/LinkDeny program group in the Start menu, or directly by running LinkDeny.exe. The Settings Manager controls the operation of LinkDeny for any Web site (virtual server) provisioned on the computer. On the left side of the Settings Manager is a list of all the Web sites (virtual servers) that are available on the computer. Use this list to select the Web site whose settings you want to change.

Screenshot
  • To enable or disable LinkDeny for a given Web site: Select the site to enable (or disable) from the Web Sites list and check (or uncheck) the Enable LinkDeny checkbox located above the configuration settings tabs, on the right side of the interface.
  • To configure LinkDeny settings for a particular Web site: Select the site from the Web Sites list. The controls on the Settings Manager will reflect the current settings for that Web site. Any changes you make will take effect only for the site that is selected.
  • To configure LinkDeny settings for two or more Web sites: Select the sites from the Web Sites list (optionally including Default Settings) using the Shift key (for two or more contiguous Web sites) or the Control key (for two or more discontinuous Web sites). In this case, the controls on the Settings Manager will reflect the current settings for the first Web site selected -- which will also be the one pointed to by the arrow indicator. Any changes you make will take effect for all the sites that are selected.
  • To replicate settings from one site to another: To propagate the settings of one site (or the Default Settings) to one or more additional sites, select source site and right click and choose 'Copy Settings' (or type Ctrl+C). Select the site or sites in which you would like to propagate the copied settings and then right click and choose 'Paste Settings' (or type Ctrl+V).

After making any changes on the LinkDeny Settings Manager, you must press either the "Apply" or the "OK" button in order for the changes to take effect. OK dismisses the Settings Manager dialog, Apply does not. Click "Cancel" (or use the File/Exit menu option) to abandon any changes and exit the Settings Manager.

back to top

Configuration Options

The LinkDeny Settings Manager consists of a Web Sites list to select which sites to configure and a series of tabs where the configuration controls are located for various areas of LinkDeny functionality. These tabs are where LinkDeny is configured for each Web site. Changes made on a tab apply only to the highlighted Web sites. After making any changes on these tabs, you must press either the "Apply" or the "OK" button on the Settings Manager in order for the changes to take effect. The functional areas represented by the various tabs include:

1. Rules Tab

Rules Tab Screenshot

The Rules Tab displays the LinkDeny rules for the selected site(s). When creating LinkDeny rules, you can start to create a new rule by clicking on the "Add..." button, or you may add a rule from a template by clicking on the "Template..." button. To edit an existing rule, select the rule you would like to edit and click on the "Edit..." button. If you select multiple rules and click on the "Edit..." button, you will be prompted to edit each rule in succession. To remove a rule from the list, select the rule and click on the "Remove" button.

The order of the rules is important if there is any overlap of protected content between two or more rules with different actions taken, and more specific rules that overlap should be ordered above less specific/general rules on the Rules tab to avoid one rule negating the effect of another. You can change the order of the rules by selecting a rule and using the arrow buttons to move the rule up and down in the list.

Add/Edit Rule Dialog

When you add or edit a rule, the following dialog appears:

Add/Edit Rule Dialog Screenshot

Name is a way to easily describe or name the rule so that the user can easily identify the particular rule from the main rule list on the Rules tab.

Rule Selector

The Rule Selector section allows the administrator to select the content in the Web site that they would like to protect. The first drop down is the Selector-Type, the second drop down is the Match-Type, and the third drop down is the Match-String.

Selector-Type

The Selector-Type has two values: "By Path" or "By Mime". When "By Path" is selected, the Match-String is a URL path that describes the content this rule is protecting (e.g. /images/*). When the Selector-Type is "By Mime", the Match-String is a MIME type that describes the content this rule is protecting (e.g. images/*, text/css, or application/x-javascript -- for more information on MIME types, click here).

Match Type

The Match-Type describes what method LinkDeny will use to match the Match-String with incoming HTTP requests. When "Use Exact Match" is selected, the HTTP request must match exactly (ignoring case) the Match-String. For example, if the Match-String is going to be /images/logo.gif, then this rule will only be active for requests for logo.gif in the images directory off of the root of the site. When "Use Wildcard Match" is selected, the Match-String can contain two wildcard characters: * matches any 0 or more characters, and ? matches any one character.

For example, if the Selector-Type was "By Mime" and the Match-Type was "Use Wildcard Match" and the Match-String was image/*, the rule would be active for GIF images (image/gif), JPG images (image/jpeg), PNG images (images/png), etc.

When "Use Regular Expression Match" is selected, the Match-String is treated as a Regular Expression (for more information on regular expressions, click here).

Rule Type and Tests

The Rule Type (sometimes referred to as "Rule-Type") has three possible values:

  • Allow Requests If All Selected Tests Have A Match
    If the HTTP request satisfies all of the tests, then it is said to be "allowed". If any one of the configured tests fails to match the HTTP request, that request is said to be "denied".
  • Allow Requests If Any Selected Test Has A Match
    If the HTTP request satisfies any one of the configured tests, then it is said to be "allowed". If none of the configured tests matches the HTTP request, that request is said to be "denied".
  • Deny Requests If Any Selected Test Has A Match
    If the HTTP request matches any one of the configured tests, then it is said to be "denied". Otherwise (if it does not match any of the tests), the request is "allowed".

Rule Tests

There are 6 types of "tests" or criteria to help describe whether a HTTP request is allowed or denied:

  • Referer - Scans the Referer: header of the HTTP request.
  • User-Agent - Scans the User-Agent: header of the HTTP request.
  • Custom IP - Scans the IP address of the client.
  • Geographic IP - Scans the Geographic location of the client.
  • HTTP Request Conformance - Scans the format of the HTTP request.
  • Time Limit (Not Pictured) - Requires requests to have a time-limited access key to be allowed.

Referer Test

The Referer Test allows the administrator to maintain a list of allowed/denied Referer: HTTP header values. You can test a particular referer by entering it in the test text box, available on the Add/Edit dialog. It will test the entered value against the current list of Referer values above.

Referer Test Dialog Screenshot

User Agent Test

The User Agent Test allows the administrator to maintain a list of allowed/denied User-Agent: HTTP header values. You can test a particular User Agent by entering it in the test text box. It will test the entered value against the current list of User Agent values above (for more information on user agent strings, click here).

User Agent Test Dialog Screenshot

Custom IP Test

The Custom IP Test allows the administrator to maintain a list of allowed/denied IP Addresses or IP Address ranges. You can test a particular IP Address by entering it in the test box. It will test the entered IP Address against the current list of Custom IP Test values above.

Custom IP Test Dialog Screenshot

Geographic IP Test

The Geographic IP Test allows the administrator to maintain a list of allowed/denied countries or groups of countries and their associated IP addresses. You can add specific countries by clicking on the "Add..." button or you can add pre-defined groups by clicking on the "Add Group..." button. You can test a particular geographic location's IP address by entering it in the test box. It will test the entered value against the current list of geographic locations and their related IP addresses above.

Geographic  IP Test Dialog Screenshot

HTTP Request Conformance Test

The HTTP Request Conformance Test allows the administrator to allow or deny requests based on the content of an HTTP request. When selecting "Request must contain all of the values below", HTTP requests must satisfy all of the request parts specified in the list for the HTTP Request Conformance to have a match. When selecting "Request only needs to contain one of the values below", HTTP requests match the HTTP Request Conformance tests when the first request part is found.

When adding a HTTP header to the list, there is an additional option to allow empty header values. When specifying request verbs, use a comma delimited list (e.g. GET,HEAD,POST). When specifying an HTTP version, the administrator can use wildcard values (e.g. HTTP/1.*). You can test an HTTP request by entering it in the test box. It will test the entered request against the current list of request parts above.

Geographic  IP Test Dialog Screenshot

Time Limit Test

The Time Limit Test is a special type of test that only works with Deny rules. The Time Limit test allows the administrator to put time limited access keys on the selected content. There are two types of time limiting options available in LinkDeny: Cookie Time Limits and URL Time Limits.

When the Cookie Time Limit is enabled, LinkDeny will set a cookie on outbound HTTP responses for text/html, text/css, and application/x-javascript content. When the client subsequently sends HTTP requests the supporting objects, they will include the encrypted Access Key.

When the URL Time Limit is enabled, the administrator or site developer needs to modify source code URLs to include the LinkDeny-configured URL Flag, followed by the 20 character LinkDeny-configured URL Mask, and then the URL path for the file (see Time Limiting Tab).

For example, with a URL Flag with the value of "protected" and a URL Mask with the value of "P80-LINKDENY-URLMASK", any links to:

http://mysite.com/myimages/logo.jpg

should be changed in your source code to:

http://mysite.com/protected/P80-LINKDENY-URLMASK/myimages/logo.jpg

LinkDeny will then modify URLs that contain the URL Flag (in this case "/protected") during outbound HTTP responses and update them with the appropriate Access Key.

So, in your source code:

<img src="/protected/P80-LINKDENY-URLMASK/myimages/logo.jpg">

would be modified such that the client would then see something like this:

<img src="/protected/C1EBAA32DF321808A923/myimages/logo.jpg">

This URL would then be valid for the time specified in the Time Limiting Tab. After the Access Key expires, the URL will no longer access the resource, and any requests will be denied.

Time Limit Test Dialog Screenshot

Action Taken on Denial

Action Taken on Denial defines what LinkDeny does for requests that match the current rule.

There are 4 options:

  • No Action (Log Only)
    LinkDeny takes no action for the denied request and the client receives the requested resource. If logging is enabled, the denied request is logged.
  • Redirect to URL LinkDeny redirects the client to the specified URL.
  • Replace with file
    LinkDeny sends back the specified file. This may be any file type recognized by IIS.
  • Send 404 error page
    LinkDeny sends a custom 404 Not Found error page.
    Note: This is the recommended method for Action Taken on Denial if you are concerned about saving bandwidth.

2. Time Limiting Tab

The Time Limiting Tab allows the administrator to control the advanced settings for Time Limit feature of LinkDeny.

Time Limiting Tab Screenshot

Cookie Name

This is the name of the cookie that LinkDeny uses when Cookie Time Limiting is enabled.

URL Flag

This is what tells LinkDeny which URLs in outbound HTTP responses should be modified to include the encrypted Access Key.

URL Mask

This is the 20 character mask that is a place holder in the site content/source code's URLs to be protected for the encrypted Access Key.

Access Key Time Limit

This is the amount of time for which Access Keys are valid, whether the Access Key is included in a cookie or in a URL.

Private Key

The Private Key is used to compute the encrypted Access Key. In a server farm environment with mirrored content, all machines must have the same Private Key in order for the Access Keys to work on all of the servers.

Mime Type and URL

These settings allow administrators to restrict the pages where the Time Limiting Cookie will be placed. The restrictions can be both by file type (MIME or Content Type) as well as the URLs in the site that are authorized to place the Time Limiting cookie. By default only text/html requests will place the Time Limiting cookie, but there are no restrictions as to which URLs may place it.

3. Logging Tab (and Log Files)

The Logging Tab allows you to enable/disable LinkDeny-specific request logging for the selected sites. When logging is enabled, LinkDeny will log information about denied requests in a log file in the specified logging directory for a particular site/virtual server.

Logging Tab Screenshot

With LinkDeny logging enabled for a site, you will be able to retrieve log files for later analysis. As you can see from the screenshot above, you have control over where each log file for each site is stored. To review a log file for a site, open the appropriate directory and view the log files, .txt documents, within Notepad or another editor. The log file for a site is organized in tabs for each request made to the site. The codes for both LinkDeny Errors and Actions Taken that are logged will be displayed in a set of tabs as well -- please use the tables below to identify LinkDeny Errors and Actions Taken in a log file:

Log File Error Code Description
256 Referer Test
512 User-Agent
768 Custom IP Test
800 Geographic IP Test
832 No Tests Match (For Allow-If-Any rules only)
1024 HTTP Conformance Match
1025 No HTTP Conformance Match
1026 HTTP Version
1027 HTTP Request Verb
1028 HTTP Request Header
1029 HTTP Request Header Missing
1030 HTTP Request Header Empty
1280 Time Limit Cookie
1281 Time Limit Cookie Missing
1282 Time Limit Cookie Invalid
1283 Time Limit Cookie Expired
1344 Time Limit URL
1345 Time Limit URL Missing
1346 Time Limit URL Invalid
1347 Time Limit URL Expired

LinkDeny Log Files Action Taken Code Description
0 No Action (Log Only)
1 Redirect to URL
2 Replace with file
3 Send 404 error page

A future version of LinkDeny will provide a standalone Log Viewer GUI interface.

4. Test Tab

The Test Tab allows you to enter requests and test them against the current set of rules.

When the request you have entered matches a rule, the rule name will be displayed at the bottom of the tab.

If the request matches a rule, but does not match the criteria for that rule, the request status is "Allowed". If the request matches a rule and is denied, the request status will say "Denied" and the reason (e.g. which criteria) will be displayed.

Test Tab Screenshot

back to top

Configuration and Data Files

Rules.ld Files for Scripted LinkDeny Rule Management

LinkDeny allows admins and developers to script their own LinkDeny rules by relying on XML management files named rules.ld. An example of this file is located by default in C:\Program Files\Port80\LinkDeny\data, and each Web site/virtual server with LinkDeny enabled will also have a site-specific rules.ld file located in its Web site root directory. Changes made in the Settings Manager for rules will be stored here for each site, and any changes made to this file for a particular site will be reflected in the Settings Manager UI once saved. You can edit each XML file with Notepad, another editor, or with an XML parser to make programmatic changes to LinkDeny rules by site, then upload the revised XML files to the Web root for the particular site to apply changed settings to LinkDeny. As with all setting changes, it is recommended that you test new rules settings in a testing environment before deployment in production Web servers.

For security purposes, direct HTTP requests to the rules.ld file (http://[hostname]/rules.ld) will result in an automatic 404 response from LinkDeny to avoid public exposure of your LinkDeny rules settings.

Templates.ld File for Scripted LinkDeny Templates Management

LinkDeny allows admins and developers to script their own LinkDeny templates by relying on a single XML management file named templates.ld, located by default in C:\Program Files\Port80\LinkDeny\data. Within the Settings Manager's Rules tab, you can apply templates to a site or group sites, but you cannot add or delete new template entries from within the Settings Manager. To add or remove templates that will be available as options to every site/virtual server, you can edit the templates.ld file with Notepad, another editor, or with an XML parser. Save the revised templates.ld file to the same directory (by default C:\Program Files\Port80\LinkDeny\data) to apply changed templates settings to LinkDeny sites. As with all setting changes, it is recommended that you test new template settings in a testing environment before deployment in production Web servers.

GeoIP.dat File for IP Address and Geographic Data (For Included "GeoLite Country" Database)

LinkDeny provides an easy-to-update process for managing the data used for Custom IP Address and Geographic IP Address rule tests. We rely on the "GeoLite Country" database from Port80 Software partner MaxMind for the IP address and geographic/regional mapping data used in LinkDeny -- the data used for IP address identification is 97% accurate and will be updated every few months (see next section for details). The data is persisted within LinkDeny in a file named GeoIP.dat, located by default in C:\Program Files\Port80\LinkDeny\data. You will not be able to review the IP address and geographic region data within this file directly, but this file is required so that LinkDeny can create IP address associations for anti-leeching and access control rules.

Updates to the GeoIP.dat File (For Included "GeoLite Country" Database)

To load a new GeoIP.dat file, simply download the latest (binary format) GeoLite Country database from the MaxMind site, uncompress the .gz archive (using a tool such as WinRAR), and then replace the current GeoIP.dat file in the correct directory on your server (C:\Program Files\Port80\LinkDeny\data by default).

Upgrading to the "GeoIP Country" Database

While not required to use LinkDeny by default, there is an optional upgrade to the included, 97% accurate "GeoLite Country" IP address database that LinkDeny relies on for Custom IP Address and Geographic IP Address rule tests. Port80 Software partner MaxMind also offers the "GeoIP Country" database -- with this paid upgrade, the data used for IP address identification is 99% accurate, and updates are available every week. The "GeoIP Country" database is currently priced at $50 for a site license only (per MaxMind, all machines within organization) with an optional monthly $12 fee for the weekly, downloadable data updates.

To purchase the "GeoIP Country" database upgrade

Please visit Port80 Software partner MaxMind's site. When ordering the "GeoIP Country" database upgrade for LinkDeny from MaxMind's site, make sure to select either the "Downloadable Database" Site License (for a one-time upgrade) or the Site License with Updates product offerings on the "GeoIP Country" page. Proceed and complete your order at MaxMind's site.

To install "GeoIP Country" database upgrade within an installed version of LinkDeny

Download the new database from MaxMind's site after purchasing the database upgrade. You will want to download the latest in the GeoIP-106 series of files, which should end with a .dat file extension (for example, GeoIP-106_20070123.dat). Note: do not download the GeoIP-108 series of files, as these are in .csv format and are not compatible with LinkDeny. After downloading the file, navigate to the C:\Program Files\Port80\LinkDeny\data directory (by default) on the server with LinkDeny installed. Make a backup copy of your included "GeoLite Country" GeoIP.dat (just rename it to GeoIP.dat.BAK) to make sure you can roll back if there is an issue with the upgrade. Rename the new "GeoIP Country" file to GeoIP.dat and save it in the C:\Program Files\Port80\LinkDeny\data directory (by default). Close the LinkDeny Settings Manager (if open), restart IIS, and test any IP Address-related rules in LinkDeny. You will now be using the "GeoIP Country" database for LinkDeny anti-leeching and access control. If you subscribe to the weekly updates for the "GeoIP Country" database, repeat the process of downloading from MaxMind's site, renaming and saving the file in the correct directory, and then restarting IIS to apply your updates to the "GeoIP Country" database.

back to top