Installing the Java Module as a Servlet Filter
Last updated 2023-09-05
IMPORTANT
This guide only applies to Next-Gen WAF customers with access to the Next-Gen WAF control panel. If you have access to the Next-Gen WAF product in the Fastly control panel, you can only deploy the Next-Gen WAF with the Edge WAF deployment method.
Requirements
- A Servlet 3.x compliant Java servlet container (e.g., Tomcat 7.0.x.+, Jetty 9+, GlassFish 3.0+).
Supported Application Types
The Next-Gen WAF Java servlet filter module can be deployed to a variety of Servlet 3.0+ Java application servers (e.g., Apache Tomcat, Jetty, Glassfish, Resin).
The module is compatible with application servers deployed on both Linux and Windows servers running the Next-Gen WAF agent.
Agent Configuration
Like other Next-Gen WAF modules, the servlet filter supports both Unix domain sockets and TCP sockets for communication with the Next-Gen WAF agent. By default, the agent uses Unix domain sockets with the address set to unix:/var/run/sigsci.sock
. It is possible to override this or specify a TCP socket instead by configuring the rpc-address
parameter in the Agent.
Additionally, ensure the agent is configured to use the default RPC version: rpc-version=0
. This can be done by verifying the parameter rpc-version
is not specified in the agent configuration or if it is specified, ensure that is specified with a value of 0
. Below is an example Agent configuration that overrides the default Unix domain socket value:
1accesskeyid = "YOUR AGENT ACCESSKEYID"2secretaccesskey = "YOUR AGENT SECRETACCESSKEY"3rpc-address = "127.0.0.1:9999"
Download
Download the Next-Gen WAF Java module manually or access it with Maven.
Access with Maven
For projects using Maven for build or deployment, the latest version of Next-Gen WAF Java modules can be installed by adding XML to the project pom.xml
file. For example:
1<repositories>2 <repository>3 <id>sigsci-stable</id>4 <url>https://packages.signalsciences.net/release/maven2</url>5 </repository>6</repositories>7
8<dependency>9 <groupId>com.signalsciences</groupId>10 <artifactId>sigsci-module-java</artifactId>11 <version>LATEST_MODULE_VERSION</version>12</dependency>
Be sure to replace LATEST_MODULE_VERSION
with the latest release of the Java module. You can find the latest version in our version file at https://dl.signalsciences.net/sigsci-module-java/VERSION.
Download manually
If you aren't using Maven to build or deploy your Java projects, follow these steps to manually download the Next-Gen WAF Java module:
Download the Java module archive from https://dl.signalsciences.net/sigsci-module-java/sigsci-module-java_latest.tar.gz.
Extract
sigsci-module-java_latest.tar.gz
.Deploy the jars using one of the following options:
- Copy
sigsci-module-java-{version}-shaded.jar
(an uber jar with all the dependencies bundled) to your application’s classpath (e.g.,%CATALINA_HOME%\webbapps\<APP_FOLDER>\WEB-INF\lib
). - Copy
sigsci-module-java-{version}.jar
and its dependencies in thelib
folder to your application’s classpath (e.g.,%CATALINA_HOME%\webbapps\<APP_FOLDER>\WEB-INF\lib
). If you already have any of the dependency jar files in your application classpath folder (i.e., for Tomcat in theWEB-INF\lib
) then it is not necessary to copy them, even if the version numbers are different. The logging jars are optional based on howslf4j
is configured.
NOTE
If you want coverage across all web applications in your Application Server instance, the jar files must be placed in the server classpath. For example, in Tomcat that would be
%CATALINA_HOME%/lib
.- Copy
Installation
Determine the appropriate
filter-class
for your installation:For systems using Jakarta EE (Servlet API 5+):
<filter-class>com.signalsciences.jakartafilter.SigSciFilter</filter-class>For Java EE:
<filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>
NOTE
Failure to specify the appropriate servlet API may result in errors such as
package javax.servlet.x does not exist
.Example minimal configuration using the Java EE servlet filter class:
1<web-app>2 <filter>3 <filter-name>SigSciFilter</filter-name>4 <filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>5 <async-supported>true</async-supported>6 <init-param>7 <param-name>rpcServerURI</param-name>8 <param-value>unix:/var/run/sigsci.sock</param-value>9 </init-param>10 <init-param>11 <param-name>expectedContentTypes</param-name>12 <param-value>application/x-java-serialized-object</param-value>13 </init-param>14 <init-param>15 <param-name>extendContentTypes</param-name>16 <param-value>true</param-value>17 </init-param>18 </filter>19 <filter-mapping>20 <filter-name>SigSciFilter</filter-name>21 <url-pattern>/*</url-pattern>22 </filter-mapping>23</web-app>NOTE
The filter supports the use of either Unix domain sockets or TCP sockets for the
rpcServerURI
parameter. Ensure that the value specified here matches the address specified in your Agent configuration to avoid communication failures. The module configuration below provides more details.Restart the Application Server.
Module Configuration
Option | Default | Description |
---|---|---|
rpcServerURI | Required, tcp://127.0.0.1:9999 | The Unix domain socket or TCP connection to communicate with the agent. Use the appropriate prefix to specify either Unix Domain Sockets or a TCP connection: unix:/<file path> or tcp://<host>:<port> |
rpcTimeout | Required, 300ms | The timeout in milliseconds that the RPC client waits for a response back from the agent. |
maxResponseTime | Optional, no default | The maximum time in seconds that the server response time will be evaluated against (i.e. to see if it exceeds this value) to determine if the module should send a post request to the agent. |
maxResponseSize | Optional, no default | The maximum size in bytes that the server response size will be evaluated against (i.e. to see if it exceeds this value) to determine if the module should send a post request to the agent. |
maxPost | Optional, no default | The maximum POST body size in bytes that can be sent to the Next-Gen WAF agent. For any POST body size exceeding this limit, the module will not send the request to the agent for detection. |
asyncStartFix | Optional, false | This can be set to true to workaround missing request body when handling requests asynchronously in servlets. |
altResponseCodes | Optional, no default | Space separated alternative agent response codes used to block the request in addition to 406. For example "403 429 503". |
excludeCidrBlock | Optional, no default | A comma-delimited list of CIDR blocks or specific IP addresses to be excluded from filter processing. |
excludeIpRange | Optional, no default | A comma-delimited list of IP ranges or specific IP addresses to be excluded from filter processing. |
excludePath | Optional, no default | A comma-delimited list of paths to be excluded from filter processing. If the URL starts with the specified value it will be excluded. Matching is case-insensitive. |
excludeHost | Optional, no default | A comma-delimited list of host names to be excluded from filter processing. Matching is case-insensitive. |
extendContentTypes | Optional, false | This can be set to true to enable extended content inspection. |
Example configuration
The configuration shown here provides an example using all the parameters noted earlier in this guide:
1<!-- Signal Sciences Filter -->2 <web-app>3 <filter>4 <filter-name>SigSciFilter</filter-name>5 <filter-class>com.signalsciences.servlet.filter.SigSciFilter</filter-class>6 <async-supported>true</async-supported>7 <init-param>8 <param-name>rpcServerURI</param-name>9 <param-value>unix:/var/run/sigsci.sock</param-value>10 </init-param>11 <init-param>12 <param-name>expectedContentTypes</param-name>13 <param-value>application/x-java-serialized-object</param-value>14 </init-param>15 <init-param>16 <param-name>excludeIpRange</param-name>17 <param-value>192.168.0.1-192.168.0.5,192.169.0.10-192.169.0.12,193.168.0.1,192.168.10.1-192.168.10.5,192.168.10.7</param-value>18 </init-param>19 <init-param>20 <param-name>excludeCidrBlock</param-name>21 <param-value>192.168.14.0/24,193.165.0.0/28,192.168.11.0/24</param-value>22 </init-param>23 <init-param>24 <param-name>excludePath</param-name>25 <param-value>/test/exit,/hello,/bonus</param-value>26 </init-param>27 <init-param>28 <param-name>excludeHost</param-name>29 <param-value>localhost,127.0.0.2</param-value>30 </init-param>31 <init-param>32 <param-name>extendContentTypes</param-name>33 <param-value>true</param-value>34 </init-param>35 </filter>36 <filter-mapping>37 <filter-name>SigSciFilter</filter-name>38 <url-pattern>/*</url-pattern>39 </filter-mapping>40 </web-app>41 <!-- end Signal Sciences Filter -->
Do not use this form to send sensitive information. If you need assistance, contact support. This form is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.