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
Basic Configuration
Setting up Loggers
Configuring Filters
Blocked Requests
Authenticators
Web Manager

How it works:

A request comes in and is sent to the firewall via your Application.cfm or Application.cfc file.
The firewall runs each filter that you have configured, and the filter returns a threat level of 0-10 (10 being the most dangerous).
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.
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.
If a filter returns a threat level greater than or equal to your configured filter level the request is filtered, meaning we attempt to escape or strip malicious characters. Not all filters support this operation.
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 the Firewall. We recommend that you create a seperate Configurator for each Web Application that uses the firewall. Since no two applications are the same, you will be able to maximize the potential of the firewall if you understand how configuration works.

The Example Configuration Objects included are:

fuseguard.components.configuration.LogOnlyConfiguration - This configuration does not block any requests, it will log any request that has even a minor threat.
fuseguard.components.configuration.StrictConfiguration - This configuration will block and log any request that has even minor threat.
fuseguard.components.configuration.DefaultConfiguration - This configuration will block only request with the highest threat level (10) and logs all threats.
fuseguard.components.configuration.BaseConfiguration - Base object.

One good way to start configuring is to use StrictConfiguration and then test your application. If your application works with the StrictConfiguration, then you can simply create a your custom configuration object by creating a CFC that extends StrictConfigration.

Another way to start configuring is to use the LogOnlyConfiguration this will let your application run uninterrupted, and you can see which filters need to be configured further or removed.

All of the example configurators have a line:

<cfset variables.email = "you@example.com">

You should set variables.email to be equal to your email address to enable the SMTP Logger.

When you make a change to your configurator it will not be picked up until the application or server restarts.
You can manually reconfigure the firewall by writing code that calls application.fuseguard.reconfigure("YourConfiguratorName")

Setting up Loggers

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

The logger enabled by default is called the CFLogLogger because it logs using the cflog tag. You may view the log entries by using the log viewer in the CF Adminstrator, or by reading the file foundeo_firewall.log in your ColdFusion server's logs directory.

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.

As we mentioned logging is optional. You can disable logging by commenting out any statement your configurator that calls firewall.addLogger().

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 the Foundeo WAF for ColdFusion. Please see the list below.

Filter Name	Component Name	Description
Content Length Filter	ContentLengthFilter	The content length filter allows you to block or log requests which have a content length greater than a specified value. See the CFC reference for configurable settings.
CRLF Injection Filter	CRLFInjectionFilter	This filter blocks against CRLF injection attacks. By injecting a CRLF into a HTTP response header a malicious user may be able to execute a Cross Site Scripting attack.
XSS Filter	CrossSiteScriptingFilter	The XSS Filter blocks several cross site scripting attack vectors. This filter returns multiple threat levels based on the possible presence of a cross site scripting request.
Dictionary Attack Filter	DictionaryAttackFilter	Detects multiple requests from the same client which contain passwords. Once a specified number of password guesses is reached the filter will block or log subsequent requests from that client. See the CFC reference for configurable settings.
Dot Dot Slash Filter	DotDotSlashFilter	This filter blocks requests with variables containing `../` or `..\` found in Path Traversal Attacks.
Foreign POST Filter	ForeignPostFilter	This filter will block HTTP POST operations which have referrers that differ from the current template. You may not want to enable this filter if other web sites submit HTTP form posts cross domain to your application. This filter can help mitigate the effects of some Cross Site Scripting and Cross Site Request Forgery attacks.
ID Validation Filter	IDValidationFilter	The ID Validation Filter has a simple concept but can be very effective in blocking many attacks. This filter inspects the value of variables whose name ends with `id` and ensures that they are a valid id. By default it allows any string containing alphanumeric characters, underscore, and dash. You can configure this filter to only allow integer id values, or UUID values created with `CreateUUID`. Consult the CFC reference for details.
LocalHost Filter	LocalHostFilter	This filter blocks any request that comes from an IP other than 127.0.0.1
Query String Length Filter	QueryStringLengthFilter	Allows you to specify a maximum length for the url query string. The default value is `2083` characters which is the maximum length of a url in Internet Explorer. You will want to set it to a lower value to force attackers to have brevity. Most Applications do not requre a lengthy query string, inspect your web server logs to determine the appropriate length.
Repeat Offender Filter	RepeatOffenderFilter	This filter will block IP that have had more than a specified number of prior requests blocked. The blocked IP list is not persisted, it is reset when the server restarts or the firewall is reconfigured or reinitialized.
Session Hijacking Filter	SessionHijackingFilter	This filter is used when session variables are turned on in your application. It can detect if a session suddenly changes user agents, and will block the request.
IP Blocking Filter	SimpleIPBlockingFilter	This filter allows you to block a specific IP by invoking the `blockIP(ipAddress)` method. Interesting uses for this filter would be to create a logger that blocks IPs after a certain number of hack attempts.
SQL Injection Filter	SQLInjectionFilter	The SQL Injection Filter blocks against several SQL injection attack vectors.
URL Session ID Filter	URLSessionIDFilter	This filter blocks requests that pass session id in the URL (such as cfid, cftoken, or jsessionid) as this may allow for session hijacking. An authenticated user may unknowingly email, im, or otherwise make public a url granting anyone who visits the url their authentication rights. It is recommended that you don't place session identifiers in the url, this is done automatically with `cflocation` unless you specify the attribute `addtoken="false"` If your application requres support for disabled cookies we recommend that you encrypt an expiring token containing the session id's, the user's ip, user agent, and a secret token.
File Upload Filter	FileUploadFilter	This filter allows you to block or log requests in which a file upload takes place based on the file extension passed by the client. You can either provide a whitelist or blacklist of extensions.
Null Byte Filter	NullByteFilter	This filter allows you to block or log requestscontain a url encoded null byte %00.

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.