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
orApplication.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.
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 |
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.