FuseGuard ColdFusion Web Application Firewall Documentation

The FuseGuard Web Application Firewall for ColdFusion is a set of code designed to run inside your existing CFML web applications to block, filter, or log potentially malicious requests.

Installation is as simple as adding a few lines of code to your Application.cfm or Application.cfc file, and optionally creating a database (see the install.txt file for details). Configuration, and all of the actual filtering, is done with ColdFusion so you don't need to learn a new XML language or complicated user interfaces. The Foundeo WAF (Web Application Firewall) is designed for easy implementation and extension.

How it works:

  1. A request comes in and is sent to the firewall via your Application.cfm or Application.cfc file.
  2. The firewall runs each filter that you have configured, and the filter returns a threat level of 0-10 (10 being the most dangerous).
  3. If a filter returns a threat level greater than or equal to your configured block level, the request is blocked, and remaining filters are not executed.
  4. If a filter returns a threat level greater than or equal to your configured log level, the request is logged.
    • You can write your own custom logger or use one of the loggers included with the product.
  5. If the request makes it through all filters successfully the request is allowed to continue to your Application.

Basic Configuration

Several Example Configuration Objects (called Configurators) are included with FuseGuard. You can fully configure FuseGuard in CFML by creating or extending a configurator CFC. However starting with version 3 you can also configure FuseGuard using FuseGuard Manager (the web based interface to FuseGuard)

The Example Configuration Objects included are:

We recommend using the DBConfigurator or extending it because it will be the easiest to configure (using the FuseGuard web manager).

A good way to start FuseGuard is to enable LogOnlyMode in the core settings.

When you make a change to your configuration it will not be picked up until the application or server restarts.
You can manually reinitilize FuseGuard by logging into FuseGuard manager and clicking on the Reinitialize & Reconfigure button.

Setting up Loggers

Logging is an optional, but highly recommended feature in the FuseGuard Web Application Firewall.

Each filter returns a threat level of 0-10, with 10 meaning a strong indication of a threat and 0 meaning no indication of a threat was found. Each filter has a configurable log level that determines if messages are sent to the loggers.

You can configure multiple loggers, each logger may do something different with the event (for example send an email, write to a file or database, etc). The loggers that are included with FuseGuard are:

You may write your own custom logger by extending the fuseguard.components.loggers.BaseLogger component. You can create loggers to send an Email, IM, Text Messages, etc.

Configuring Filters

A Filter is a CFC Component that responds to a request with a threat level value from 0 to 10, with 10 being the most dangerous. The firewall includes several prebuilt filters, but you can really harness its power when you begin writing your own custom filters.

Common Filter Configuration Methods

Every filter has a common set of methods that you can use to customize filtering. The methods are:

setScopes("form,url,cookie,cgi")

By default filters may check variables in the scopes form, url, cookie, cgi. However, if you know your application doesn't make use of cookies or the cgi scope, then you can instruct the filter to only check certain variable scopes. For example, to run on form and url scoped variables you would call filter.setScopes("form,url") in your Configurator code.

ignoreVariable("scope", "variableName")

You can tell a filter to ignore a given variable using the ignoreVariable function on the filter.

For example if your site advertises with Google Adwords, they automatically append ?gclid=some_id_string to the url when users click on the ad. If you have configured the IDValidationFilter to only allow integer id's, you would block everyone who clicked on the ad (by default however the IDValidationFilter allows simple string id's and the request would not be blocked). This is a good example where you might use the ignoreVariable function as follows:

filter.ignoreVariable("url", "gclid")

The scope and variableName are not case sensitive. If you find that you are ignoring alot of variable, it might be a good idea to write a custom filter to ensure that the ignored variables are still safe.

denyURI("/ignored/folder/")

By calling denyURI() you can tell the filter to ignore any files matching that URI. The URI is obtained from the CGI.SCRIPT_NAME variable for the running request. The URI is not case sensitive, and will match any URI that has the same prefix as given.

allowURI("/ignored/folder/allow_file.cfm")

The allowURI() method explicitly allows a URI for execution through the firewall.

setAllowDenyOrder("deny,allow")

By using the setAllowDenyOrder() method you can set the allow / deny order used for ignoring URI's with denyURI() and allowURI() methods.

If you invoke setAllowDenyOrder("deny,allow") it will run through the deny list first allowing you to ignore all URIs, unless those explicitly specified.

The default order is allow,deny meaning all URIs are allowed to run through the filter, unless explicitly denied.

Built In Filters

Several filters are included with FuseGuard. Please see the FuseGuard CFC Reference for details.

Writing your Own Custom Filter

To create your own custom filter you must extend the fuseguard.components.filters.BaseFilter CFC.

<cfcomponent extends="BaseFilter" name="LocalHostFilter" displayname="LocalHost Filter">
	
	<cffunction name="inspectRequest" returntype="numeric" output="false">
		<cfif CGI.REMOTE_ADDR IS "127.0.0.1">
			<cfreturn 0>
		<cfelse>
			<cfreturn 10>
		</cfif>
	</cffunction>
	
	<cffunction name="getName" returntype="string"><cfreturn "Localhost Filter"></cffunction>
	
</cfcomponent>

As you can see there are only two methods or functions that you need to implement. Those are inspectRequest and getName.

The inspectRequest method must return a threat level for the request.

The getName method returns the name of this filter.

That's it. Only 10 lines of code, and you have written your first Web Application Firewall Filter in ColdFusion.

Blocked Requests

When a request is blocked by the firewall, a HTTP 403 Forbidden status code is returned to the client along with a generic blocked request message.

You can customize the blocked request message by editing fuseguard/views/blocked-request.cfm.

It is recommended that you avoid using too much CFML in this file, stick to a HTML response.

Authenticators

An Authenticator must be specified in order to login to the Web Manager GUI. Authenticators can be found in the fuseguard/components/authenticators/ folder. All authenticators should extend the BaseAuthenticator component located within that folder.

If you want to use an existing authentication method for accessing the Web Manager you can do so by creating your own authenticator. You remove the user edit forms from the Web Manager by implementing the canEditUsers method, and returning false.

When the firewall is configured you can specify the authenticator instance by calling firewall.setAuthenticator(authenticatorInstance) you may only call this method once.

Web Manager

The web manager allows you to view log entries, reinitialize configuration, and manage users.

The manager folder which is located under the root fuseguard folder by default can be moved anywhere on your server. It is a good idea to limit access to this folder by IP address, and require a SSL connection.

To use the Web Manager you must have specified an authenticator (see above), and also called firewall.setWebManagerEnabled(true) in your Configurator.

foundeo logo