Class DoSFilter

  • All Implemented Interfaces:
    javax.servlet.Filter
    Direct Known Subclasses:
    CloseableDoSFilter

    @ManagedObject("limits exposure to abuse from request flooding, whether malicious, or as a result of a misconfigured client")
    public class DoSFilter
    extends java.lang.Object
    implements javax.servlet.Filter
    Denial of Service filter

    This filter is useful for limiting exposure to abuse from request flooding, whether malicious, or as a result of a misconfigured client.

    The filter keeps track of the number of requests from a connection per second. If a limit is exceeded, the request is either rejected, delayed, or throttled.

    When a request is throttled, it is placed in a queue and will only proceed when there is capacity.

    The extractUserId(ServletRequest request) function should be implemented, in order to uniquely identify authenticated users.

    The following init parameters control the behavior of the filter:

    maxRequestsPerSec
    the maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
    delayMs
    is the delay given to all requests over the rate limit, before they are considered at all. -1 means just reject request, 0 means no delay, otherwise it is the delay.
    maxWaitMs
    how long to blocking wait for the throttle semaphore.
    throttledRequests
    is the number of requests over the rate limit able to be considered at once.
    throttleMs
    how long to async wait for semaphore.
    maxRequestMs
    how long to allow this request to run.
    maxIdleTrackerMs
    how long to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it
    insertHeaders
    if true , insert the DoSFilter headers into the response. Defaults to true.
    remotePort
    if true then rate is tracked by IP+port (effectively connection). Defaults to false.
    ipWhitelist
    a comma-separated list of IP addresses that will not be rate limited
    managedAttr
    if set to true, then this servlet is set as a ServletContext attribute with the filter name as the attribute name. This allows context external mechanism (eg JMX via ContextHandler.MANAGED_ATTRIBUTES) to manage the configuration of the filter.
    tooManyCode
    The status code to send if there are too many requests. By default is 429 (too many requests), but 503 (Unavailable) is another option

    This filter should be configured for DispatcherType.REQUEST and DispatcherType.ASYNC and with <async-supported>true</async-supported>.

    • Constructor Summary

      Constructors 
      Constructor Description
      DoSFilter()  
    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean addWhitelistAddress​(java.lang.String address)
      Adds the given IP address, either in the form of a dotted decimal notation A.B.C.D or in the CIDR notation A.B.C.D/M, to the list of whitelisted IP addresses.
      protected boolean checkWhitelist​(java.lang.String candidate)  
      protected boolean checkWhitelist​(java.util.List<java.lang.String> whitelist, java.lang.String candidate)
      Deprecated.
      void clearWhitelist()
      Clears the list of whitelisted IP addresses
      protected void closeConnection​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Thread thread)
      void destroy()  
      protected void doFilter​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, javax.servlet.FilterChain filterChain)  
      void doFilter​(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, javax.servlet.FilterChain filterChain)  
      protected void doFilterChain​(javax.servlet.FilterChain chain, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)  
      protected java.lang.String extractUserId​(javax.servlet.ServletRequest request)
      Deprecated.
      User ID no longer supported
      long getDelayMs()
      Get delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
      DoSFilter.Listener getListener()  
      long getMaxIdleTrackerMs()
      Get maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
      protected DoSFilter.RateType getMaxPriority()
      Deprecated.
      Priority no longer supported
      long getMaxRequestMs()
      Get maximum amount of time (in milliseconds) to allow the request to process.
      int getMaxRequestsPerSec()
      Get maximum number of requests from a connection per second.
      long getMaxWaitMs()
      Get maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
      java.lang.String getName()
      The unique name of the filter when there is more than one DosFilter instance.
      int getThrottledRequests()
      Get number of requests over the rate limit able to be considered at once.
      long getThrottleMs()
      Get amount of time (in milliseconds) to async wait for semaphore.
      int getTooManyCode()
      Status code for Rejected for too many requests.
      java.lang.String getWhitelist()
      Get a list of IP addresses that will not be rate limited.
      void init​(javax.servlet.FilterConfig filterConfig)  
      boolean isEnabled()  
      boolean isInsertHeaders()
      Check flag to insert the DoSFilter headers into the response.
      boolean isRemotePort()
      Get flag to have usage rate tracked by IP+port (effectively connection)
      boolean isTrackSessions()
      Deprecated.
      Session tracking is no longer supported
      protected void onRequestTimeout​(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, java.lang.Thread handlingThread)
      Invoked when the request handling exceeds getMaxRequestMs().
      void removeFromRateTracker​(java.lang.String id)  
      boolean removeWhitelistAddress​(java.lang.String address)
      Removes the given address from the list of whitelisted IP addresses.
      void setDelayMs​(long value)
      Set delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
      void setEnabled​(boolean enabled)  
      void setInsertHeaders​(boolean value)
      Set flag to insert the DoSFilter headers into the response.
      void setListener​(DoSFilter.Listener listener)  
      void setMaxIdleTrackerMs​(long value)
      Set maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
      void setMaxRequestMs​(long value)
      Set maximum amount of time (in milliseconds) to allow the request to process.
      void setMaxRequestsPerSec​(int value)
      Get maximum number of requests from a connection per second.
      void setMaxWaitMs​(long value)
      Set maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
      void setName​(java.lang.String name)  
      void setRemotePort​(boolean value)
      Set flag to have usage rate tracked by IP+port (effectively connection)
      void setThrottledRequests​(int value)
      Set number of requests over the rate limit able to be considered at once.
      void setThrottleMs​(long value)
      Set amount of time (in milliseconds) to async wait for semaphore.
      void setTooManyCode​(int tooManyCode)  
      void setTrackSessions​(boolean value)
      Deprecated.
      Session tracking is no longer supported
      void setWhitelist​(java.lang.String commaSeparatedList)
      Set a list of IP addresses that will not be rate limited.
      protected Scheduler startScheduler()  
      protected void stopScheduler()  
      protected boolean subnetMatch​(java.lang.String subnetAddress, java.lang.String address)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • DoSFilter

        public DoSFilter()
    • Method Detail

      • init

        public void init​(javax.servlet.FilterConfig filterConfig)
                  throws javax.servlet.ServletException
        Specified by:
        init in interface javax.servlet.Filter
        Throws:
        javax.servlet.ServletException
      • startScheduler

        protected Scheduler startScheduler()
                                    throws javax.servlet.ServletException
        Throws:
        javax.servlet.ServletException
      • doFilter

        public void doFilter​(javax.servlet.ServletRequest request,
                             javax.servlet.ServletResponse response,
                             javax.servlet.FilterChain filterChain)
                      throws java.io.IOException,
                             javax.servlet.ServletException
        Specified by:
        doFilter in interface javax.servlet.Filter
        Throws:
        java.io.IOException
        javax.servlet.ServletException
      • doFilter

        protected void doFilter​(javax.servlet.http.HttpServletRequest request,
                                javax.servlet.http.HttpServletResponse response,
                                javax.servlet.FilterChain filterChain)
                         throws java.io.IOException,
                                javax.servlet.ServletException
        Throws:
        java.io.IOException
        javax.servlet.ServletException
      • doFilterChain

        protected void doFilterChain​(javax.servlet.FilterChain chain,
                                     javax.servlet.http.HttpServletRequest request,
                                     javax.servlet.http.HttpServletResponse response)
                              throws java.io.IOException,
                                     javax.servlet.ServletException
        Throws:
        java.io.IOException
        javax.servlet.ServletException
      • onRequestTimeout

        protected void onRequestTimeout​(javax.servlet.http.HttpServletRequest request,
                                        javax.servlet.http.HttpServletResponse response,
                                        java.lang.Thread handlingThread)
        Invoked when the request handling exceeds getMaxRequestMs().

        By default, an HTTP 503 response is returned and the handling thread is interrupted.

        Parameters:
        request - the current request
        response - the current response
        handlingThread - the handling thread
      • closeConnection

        @Deprecated
        protected void closeConnection​(javax.servlet.http.HttpServletRequest request,
                                       javax.servlet.http.HttpServletResponse response,
                                       java.lang.Thread thread)
        Parameters:
        request - the current request
        response - the current response
        thread - the handling thread
      • getMaxPriority

        @Deprecated
        protected DoSFilter.RateType getMaxPriority()
        Deprecated.
        Priority no longer supported
        Returns:
        null
      • removeFromRateTracker

        public void removeFromRateTracker​(java.lang.String id)
      • checkWhitelist

        protected boolean checkWhitelist​(java.lang.String candidate)
      • checkWhitelist

        @Deprecated
        protected boolean checkWhitelist​(java.util.List<java.lang.String> whitelist,
                                         java.lang.String candidate)
        Deprecated.
      • subnetMatch

        protected boolean subnetMatch​(java.lang.String subnetAddress,
                                      java.lang.String address)
      • destroy

        public void destroy()
        Specified by:
        destroy in interface javax.servlet.Filter
      • stopScheduler

        protected void stopScheduler()
      • extractUserId

        @Deprecated
        protected java.lang.String extractUserId​(javax.servlet.ServletRequest request)
        Deprecated.
        User ID no longer supported
        Parameters:
        request - ignored
        Returns:
        null
      • getMaxRequestsPerSec

        @ManagedAttribute("maximum number of requests allowed from a connection per second")
        public int getMaxRequestsPerSec()
        Get maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
        Returns:
        maximum number of requests
      • setMaxRequestsPerSec

        public void setMaxRequestsPerSec​(int value)
        Get maximum number of requests from a connection per second. Requests in excess of this are first delayed, then throttled.
        Parameters:
        value - maximum number of requests
      • getDelayMs

        @ManagedAttribute("delay applied to all requests over the rate limit (in ms)")
        public long getDelayMs()
        Get delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
        Returns:
        the delay in milliseconds
      • setDelayMs

        public void setDelayMs​(long value)
        Set delay (in milliseconds) that is applied to all requests over the rate limit, before they are considered at all.
        Parameters:
        value - delay (in milliseconds), 0 - no delay, -1 - reject request
      • getMaxWaitMs

        @ManagedAttribute("maximum time the filter will block waiting throttled connections, (0 for no delay, -1 to reject requests)")
        public long getMaxWaitMs()
        Get maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
        Returns:
        maximum wait time
      • setMaxWaitMs

        public void setMaxWaitMs​(long value)
        Set maximum amount of time (in milliseconds) the filter will blocking wait for the throttle semaphore.
        Parameters:
        value - maximum wait time
      • getThrottledRequests

        @ManagedAttribute("number of requests over rate limit")
        public int getThrottledRequests()
        Get number of requests over the rate limit able to be considered at once.
        Returns:
        number of requests
      • setThrottledRequests

        public void setThrottledRequests​(int value)
        Set number of requests over the rate limit able to be considered at once.
        Parameters:
        value - number of requests
      • getThrottleMs

        @ManagedAttribute("amount of time to async wait for semaphore")
        public long getThrottleMs()
        Get amount of time (in milliseconds) to async wait for semaphore.
        Returns:
        wait time
      • setThrottleMs

        public void setThrottleMs​(long value)
        Set amount of time (in milliseconds) to async wait for semaphore.
        Parameters:
        value - wait time
      • getMaxRequestMs

        @ManagedAttribute("maximum time to allow requests to process (in ms)")
        public long getMaxRequestMs()
        Get maximum amount of time (in milliseconds) to allow the request to process.
        Returns:
        maximum processing time
      • setMaxRequestMs

        public void setMaxRequestMs​(long value)
        Set maximum amount of time (in milliseconds) to allow the request to process.
        Parameters:
        value - maximum processing time
      • getMaxIdleTrackerMs

        @ManagedAttribute("maximum time to track of request rates for connection before discarding")
        public long getMaxIdleTrackerMs()
        Get maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
        Returns:
        maximum tracking time
      • setMaxIdleTrackerMs

        public void setMaxIdleTrackerMs​(long value)
        Set maximum amount of time (in milliseconds) to keep track of request rates for a connection, before deciding that the user has gone away, and discarding it.
        Parameters:
        value - maximum tracking time
      • getName

        public java.lang.String getName()
        The unique name of the filter when there is more than one DosFilter instance.
        Returns:
        the name
      • setName

        public void setName​(java.lang.String name)
        Parameters:
        name - the name to set
      • isInsertHeaders

        @ManagedAttribute("inser DoSFilter headers in response")
        public boolean isInsertHeaders()
        Check flag to insert the DoSFilter headers into the response.
        Returns:
        value of the flag
      • setInsertHeaders

        public void setInsertHeaders​(boolean value)
        Set flag to insert the DoSFilter headers into the response.
        Parameters:
        value - value of the flag
      • isTrackSessions

        @Deprecated
        public boolean isTrackSessions()
        Deprecated.
        Session tracking is no longer supported
        Get flag to have usage rate tracked by session if a session exists.
        Returns:
        value of the flag
      • setTrackSessions

        @Deprecated
        public void setTrackSessions​(boolean value)
        Deprecated.
        Session tracking is no longer supported
        Set flag to have usage rate tracked by session if a session exists.
        Parameters:
        value - value of the flag
      • isRemotePort

        @ManagedAttribute("usage rate is tracked by IP+port is session tracking not used")
        public boolean isRemotePort()
        Get flag to have usage rate tracked by IP+port (effectively connection)
        Returns:
        value of the flag
      • setRemotePort

        public void setRemotePort​(boolean value)
        Set flag to have usage rate tracked by IP+port (effectively connection)
        Parameters:
        value - value of the flag
      • isEnabled

        @ManagedAttribute("whether this filter is enabled")
        public boolean isEnabled()
        Returns:
        whether this filter is enabled
      • setEnabled

        public void setEnabled​(boolean enabled)
        Parameters:
        enabled - whether this filter is enabled
      • getTooManyCode

        public int getTooManyCode()
        Status code for Rejected for too many requests.
        Returns:
        the configured status code (default: 429 - Too Many Requests)
      • setTooManyCode

        public void setTooManyCode​(int tooManyCode)
      • getWhitelist

        @ManagedAttribute("list of IPs that will not be rate limited")
        public java.lang.String getWhitelist()
        Get a list of IP addresses that will not be rate limited.
        Returns:
        comma-separated whitelist
      • setWhitelist

        public void setWhitelist​(java.lang.String commaSeparatedList)
        Set a list of IP addresses that will not be rate limited.
        Parameters:
        commaSeparatedList - comma-separated whitelist
      • clearWhitelist

        @ManagedOperation("clears the list of IP addresses that will not be rate limited")
        public void clearWhitelist()
        Clears the list of whitelisted IP addresses
      • addWhitelistAddress

        @ManagedOperation("adds an IP address that will not be rate limited")
        public boolean addWhitelistAddress​(@Name("address")
                                           java.lang.String address)
        Adds the given IP address, either in the form of a dotted decimal notation A.B.C.D or in the CIDR notation A.B.C.D/M, to the list of whitelisted IP addresses.
        Parameters:
        address - the address to add
        Returns:
        whether the address was added to the list
        See Also:
        removeWhitelistAddress(String)
      • removeWhitelistAddress

        @ManagedOperation("removes an IP address that will not be rate limited")
        public boolean removeWhitelistAddress​(@Name("address")
                                              java.lang.String address)
        Removes the given address from the list of whitelisted IP addresses.
        Parameters:
        address - the address to remove
        Returns:
        whether the address was removed from the list
        See Also:
        addWhitelistAddress(String)