Module org.eclipse.jetty.servlets
Package org.eclipse.jetty.servlets

Class DoSFilter

java.lang.Object
org.eclipse.jetty.servlets.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 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 priority queue. Priority is given first to authenticated users and users with an HttpSession, then connections which can be identified by their IP addresses. Connections with no way to identify them are given lowest priority.

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.
trackSessions
if true, usage rate is tracked by session if a session exists. Defaults to true.
remotePort
if true and session tracking is not used, 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>.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    DoSFilter.Action
     
    static class 
    DoSFilter.Listener
    Listener for actions taken against specific requests.
    static interface 
    DoSFilter.OverLimit
     
    static enum 
    DoSFilter.RateType
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    DoSFilter()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    addWhitelistAddress(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(String candidate)
     
    void
    clearWhitelist()
    Clears the list of whitelisted IP addresses
    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 String
    extractUserId(javax.servlet.ServletRequest request)
    Returns the user id, used to track this connection.
    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()
     
    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.
    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.
    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) if session tracking is not used.
    boolean
    isTrackSessions()
    Get flag to have usage rate tracked by session if a session exists.
    protected void
    onRequestTimeout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, Thread handlingThread)
    Invoked when the request handling exceeds getMaxRequestMs().
    void
    removeFromRateTracker(String id)
     
    boolean
    removeWhitelistAddress(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(String name)
     
    void
    setRemotePort(boolean value)
    Set flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
    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)
    Set flag to have usage rate tracked by session if a session exists.
    void
    setWhitelist(String commaSeparatedList)
    Set a list of IP addresses that will not be rate limited.
    protected org.eclipse.jetty.util.thread.Scheduler
    startScheduler()
     
    protected void
    stopScheduler()
     
    protected boolean
    subnetMatch(String subnetAddress, String address)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • DoSFilter

      public DoSFilter()

  • Method Details

    • 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 org.eclipse.jetty.util.thread.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 IOException, javax.servlet.ServletException
      Specified by:
      doFilter in interface javax.servlet.Filter
      Throws:
      IOException
      javax.servlet.ServletException

    • doFilter

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

    • doFilterChain

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

    • onRequestTimeout

      protected void onRequestTimeout(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, 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

    • getMaxPriority

      protected DoSFilter.RateType getMaxPriority()
      Returns:
      the maximum priority that we can assign to a request

    • setListener

      public void setListener(DoSFilter.Listener listener)

    • getListener

      public DoSFilter.Listener getListener()

    • removeFromRateTracker

      public void removeFromRateTracker(String id)

    • checkWhitelist

      protected boolean checkWhitelist(String candidate)

    • subnetMatch

      protected boolean subnetMatch(String subnetAddress, String address)

    • destroy

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

    • stopScheduler

      protected void stopScheduler()

    • extractUserId

      protected String extractUserId(javax.servlet.ServletRequest request)
      Returns the user id, used to track this connection. This SHOULD be overridden by subclasses.
      Parameters:
      request - the current request
      Returns:
      a unique user id, if logged in; otherwise 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 String getName()
      The unique name of the filter when there is more than one DosFilter instance.
      Returns:
      the name

    • setName

      public void setName(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

      @ManagedAttribute("usage rate is tracked by session if one exists") public boolean isTrackSessions()
      Get flag to have usage rate tracked by session if a session exists.
      Returns:
      value of the flag

    • setTrackSessions

      public void setTrackSessions(boolean value)
      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) if session tracking is not used.
      Returns:
      value of the flag

    • setRemotePort

      public void setRemotePort(boolean value)
      Set flag to have usage rate tracked by IP+port (effectively connection) if session tracking is not used.
      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 String getWhitelist()
      Get a list of IP addresses that will not be rate limited.
      Returns:
      comma-separated whitelist

    • setWhitelist

      public void setWhitelist(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") 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

      @ManagedOperation("removes an IP address that will not be rate limited") public boolean removeWhitelistAddress(@Name("address") 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: