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.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
- Web Manager
- A request comes in and is sent to the firewall via your
- 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.
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
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 = "email@example.com">
You should set
variables.email to be equal to your email address to enable the SMTP Logger.
You can manually reconfigure the firewall by writing code that calls
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
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
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.
Every filter has a common set of methods that you can use to customize filtering. The methods are:
By default filters may check variables in the scopes
url scoped variables you would call
filter.setScopes("form,url") in your Configurator code.
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:
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() 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() method explicitly allows a URI for execution through the firewall.
By using the
setAllowDenyOrder() method you can set the allow / deny order used for ignoring URI's with
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.
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
|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
|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
|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
|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
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.|
To create your own custom filter you must extend the
<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 method must return a threat level for the request.
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.
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
It is recommended that you avoid using too much CFML in this file, stick to a HTML response.
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
When the firewall is configured you can specify the authenticator instance by calling
firewall.setAuthenticator(authenticatorInstance) you may only call this method once.
The web manager allows you to view log entries, reinitialize configuration, and manage users.
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.