0
# DoS Protection and Rate Limiting
1

2
Comprehensive denial of service protection with rate limiting, request throttling, IP whitelisting, and extensive management capabilities. The DoS filters provide configurable protection against request flooding attacks and resource abuse.
3

4
## Capabilities
5

6
### DoSFilter
7

8
Primary DoS protection filter with rate limiting, throttling, and management features.
9

10
```java { .api }
11
/**
12
 * Denial of Service filter for limiting exposure to request flooding attacks.
13
 * Tracks requests per connection per second and applies rate limiting actions.
14
 */
15
public class DoSFilter implements Filter {
16
    // Filter lifecycle methods
17
    public void init(FilterConfig filterConfig) throws ServletException;
18
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain) 
19
        throws IOException, ServletException;
20
    public void destroy();
21
    
22
    // Configuration properties
23
    public void setMaxRequestsPerSec(int value);
24
    public int getMaxRequestsPerSec();
25
    public void setDelayMs(long value);
26
    public long getDelayMs();
27
    public void setMaxWaitMs(long value);
28
    public long getMaxWaitMs();
29
    public void setThrottledRequests(int value);
30
    public int getThrottledRequests();
31
    public void setThrottleMs(long value);
32
    public long getThrottleMs();
33
    public void setMaxRequestMs(long value);
34
    public long getMaxRequestMs();
35
    public void setMaxIdleTrackerMs(long value);
36
    public long getMaxIdleTrackerMs();
37
    public void setInsertHeaders(boolean value);
38
    public boolean isInsertHeaders();
39
    public void setRemotePort(boolean value);
40
    public boolean isRemotePort();
41
    public void setEnabled(boolean enabled);
42
    public boolean isEnabled();
43
    
44
    // Whitelist management
45
    public void setWhitelist(String commaSeparatedList);
46
    public String getWhitelist();
47
    public void clearWhitelist();
48
    public boolean addWhitelistAddress(String address);
49
    public boolean removeWhitelistAddress(String address);
50
    
51
    // Management operations
52
    public void setTooManyCode(int tooManyCode);
53
    public int getTooManyCode();
54
    public void setName(String name);
55
    public String getName();
56
    public void setListener(DoSFilter.Listener listener);
57
    public DoSFilter.Listener getListener();
58
    public void removeFromRateTracker(String id);
59
}
60
```
61

62
**Configuration Parameters:**
63

64
- **maxRequestsPerSec**: Maximum requests per connection per second (default: 25)
65
- **delayMs**: Delay in milliseconds for over-limit requests (default: 100, -1 to reject immediately)
66
- **throttledRequests**: Number of requests that can be throttled simultaneously (default: 5)
67
- **maxWaitMs**: Maximum wait time for throttle semaphore in milliseconds (default: 50)
68
- **throttleMs**: Asynchronous wait time for semaphore in milliseconds (default: 30000)
69
- **maxRequestMs**: Maximum request processing time in milliseconds (default: 30000)
70
- **maxIdleTrackerMs**: Time to track connection rates before cleanup in milliseconds (default: 30000)
71
- **insertHeaders**: Whether to insert DoS-related headers in responses (default: true)
72
- **remotePort**: Whether to include remote port in tracking (default: false)
73
- **ipWhitelist**: Comma-separated list of whitelisted IP addresses or CIDR blocks
74
- **managedAttr**: Whether to register filter as ServletContext managed attribute (default: false)
75
- **tooManyCode**: HTTP status code for rate limit exceeded responses (default: 429)
76

77
**Usage Examples:**
78

79
```java
80
// Web.xml configuration
81
/*
82
<filter>
83
    <filter-name>DoSFilter</filter-name>
84
    <filter-class>org.eclipse.jetty.ee10.servlets.DoSFilter</filter-class>
85
    <init-param>
86
        <param-name>maxRequestsPerSec</param-name>
87
        <param-value>10</param-value>
88
    </init-param>
89
    <init-param>
90
        <param-name>delayMs</param-name>
91
        <param-value>1000</param-value>
92
    </init-param>
93
    <init-param>
94
        <param-name>throttledRequests</param-name>
95
        <param-value>3</param-value>
96
    </init-param>
97
    <init-param>
98
        <param-name>ipWhitelist</param-name>
99
        <param-value>127.0.0.1,192.168.1.0/24</param-value>
100
    </init-param>
101
</filter>
102
*/
103

104
// Programmatic configuration
105
DoSFilter dosFilter = new DoSFilter();
106
dosFilter.setMaxRequestsPerSec(10);
107
dosFilter.setDelayMs(1000);
108
dosFilter.setThrottledRequests(3);
109
dosFilter.setWhitelist("127.0.0.1,192.168.1.0/24");
110
dosFilter.setTooManyCode(429);
111

112
// Custom listener for rate limit events
113
dosFilter.setListener(new DoSFilter.Listener() {
114
    @Override
115
    public DoSFilter.Action onRequestOverLimit(HttpServletRequest request, 
116
                                              DoSFilter.OverLimit overlimit, 
117
                                              DoSFilter dosFilter) {
118
        // Log the rate limit violation
119
        logger.warn("Rate limit exceeded for {}: {} requests in {}", 
120
                   overlimit.getRateId(), overlimit.getCount(), overlimit.getDuration());
121
        
122
        // Return custom action based on severity
123
        return overlimit.getCount() > 50 ? DoSFilter.Action.REJECT : DoSFilter.Action.DELAY;
124
    }
125
});
126
```
127

128
### CloseableDoSFilter
129

130
Extended DoS filter that forcibly closes connections on timeout.
131

132
```java { .api }
133
/**
134
 * Extension of DoSFilter that abruptly closes connections when requests timeout.
135
 * More aggressive than standard DoSFilter for handling persistent attackers.
136
 */
137
public class CloseableDoSFilter extends DoSFilter {
138
    // Inherits all DoSFilter functionality
139
    // Overrides timeout behavior to close connections
140
}
141
```
142

143
**Usage Example:**
144

145
```java
146
// Use when you need aggressive connection termination
147
CloseableDoSFilter closeableFilter = new CloseableDoSFilter();
148
closeableFilter.setMaxRequestsPerSec(5);
149
closeableFilter.setMaxRequestMs(10000); // Connections closed after 10 seconds
150
```
151

152
### Action Enum
153

154
Defines the actions that can be taken when rate limits are exceeded.
155

156
```java { .api }
157
/**
158
 * Actions that can be taken when request rate limits are exceeded
159
 */
160
public enum Action {
161
    /** Take no action, allow the request to proceed */
162
    NO_ACTION,
163
    /** Abort the request processing */
164
    ABORT,
165
    /** Reject the request with an error response */
166
    REJECT,
167
    /** Delay the request before processing */
168
    DELAY,
169
    /** Throttle the request using async processing */
170
    THROTTLE;
171
    
172
    /**
173
     * Convert delay time to appropriate action
174
     * @param delayMs Delay time in milliseconds
175
     * @return Corresponding Action enum value
176
     */
177
    public static Action fromDelay(long delayMs);
178
}
179
```
180

181
### OverLimit Interface
182

183
Provides information about rate limit violations.
184

185
```java { .api }
186
/**
187
 * Information about a rate limit violation
188
 */
189
public interface OverLimit {
190
    /** Get the rate tracking identifier */
191
    String getRateId();
192
    /** Get the duration over which the rate was measured */
193
    Duration getDuration();
194
    /** Get the number of requests in the measurement period */
195
    long getCount();
196
}
197
```
198

199
### Listener Interface
200

201
Callback interface for handling rate limit events.
202

203
```java { .api }
204
/**
205
 * Listener for rate limit events, allows custom handling of over-limit situations
206
 */
207
public static class Listener {
208
    /**
209
     * Called when a request exceeds the configured rate limit
210
     * @param request The HTTP request that exceeded the limit
211
     * @param overlimit Information about the rate limit violation
212
     * @param dosFilter The DoSFilter instance
213
     * @return Action to take for this request
214
     */
215
    public Action onRequestOverLimit(HttpServletRequest request, 
216
                                   OverLimit overlimit, 
217
                                   DoSFilter dosFilter);
218
}
219
```
220

221
### RateTracker
222

223
Internal class for tracking request rates (exposed for management).
224

225
```java { .api }
226
/**
227
 * Tracks request rates for a specific connection/user
228
 */
229
public static class RateTracker implements Runnable, Serializable {
230
    /** Check if the current rate exceeds configured limits */
231
    public OverLimit isRateExceeded(long now);
232
    /** Get the unique identifier for this rate tracker */
233
    public String getId();
234
    /** Set the servlet context for this tracker */
235
    public void setContext(ServletContext context);
236
    /** Cleanup method called periodically */
237
    public void run();
238
}
239
```
240

241
## Protected Extension Points
242

243
The DoSFilter provides several protected methods for customization:
244

245
```java { .api }
246
protected void doFilter(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) 
247
    throws IOException, ServletException;
248
protected void doFilterChain(FilterChain chain, HttpServletRequest request, HttpServletResponse response) 
249
    throws IOException, ServletException;
250
protected void onRequestTimeout(HttpServletRequest request, HttpServletResponse response, Thread handlingThread);
251
protected boolean checkWhitelist(String candidate);
252
protected boolean subnetMatch(String subnetAddress, String address);
253
protected Scheduler startScheduler() throws ServletException;
254
protected void stopScheduler();
255
```
256

257
## Whitelist Management
258

259
The DoS filters support flexible IP whitelisting with CIDR notation support:
260

261
```java
262
// Single IP addresses
263
dosFilter.addWhitelistAddress("192.168.1.100");
264

265
// CIDR blocks
266
dosFilter.addWhitelistAddress("192.168.1.0/24");
267
dosFilter.addWhitelistAddress("10.0.0.0/8");
268

269
// Remove addresses
270
dosFilter.removeWhitelistAddress("192.168.1.100");
271

272
// Clear all whitelist entries
273
dosFilter.clearWhitelist();
274

275
// Set entire whitelist at once
276
dosFilter.setWhitelist("127.0.0.1,192.168.1.0/24,10.0.0.0/16");
277
```