1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
|
<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Configuration Directives</title><link href="modsecurity-reference.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="ModSecurity® Reference
Manual"><link rel="up" href="index.html" title="ModSecurity® Reference
Manual"><link rel="prev" href="installation.html" title="Installation"><link rel="next" href="processing-phases.html" title="Processing Phases"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background:#F5F5F5;width:100%;border-top:1px solid #DDDDDD;border-bottom:1px solid #DDDDDD"><table width="100%" cellspacing="0" cellpadding="0"><tr><td><a href="http://www.modsecurity.org"><img style="margin:4px" src="modsecurity.gif" width="120" height="36" alt="ModSecurity" border="0"></a></td><td align="right"><a href="http://www.breach.com"><img style="margin:6px" src="breach-logo-small.gif" height="36" width="100" border="0"></a></td></tr></table></div><div id="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Configuration Directives</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="installation.html">Prev</a> </td><td align="center" width="60%"> <a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%"> <a accesskey="n" href="processing-phases.html">Next</a></td></tr></table><hr size="1"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuration-directives"></a>Configuration Directives</h2></div></div><div></div></div><p>The following section outlines all of the ModSecurity directives.
Most of the ModSecurity directives can be used inside the various Apache
Scope Directives such as <code class="literal">VirtualHost</code>,
<code class="literal">Location</code>, <code class="literal">LocationMatch</code>,
<code class="literal">Directory</code>, etc... There are others, however, that can
only be used once in the main configuration file. This information is
specified in the Scope sections below. The first version to use a given
directive is given in the Version sections below.</p><p>These rules, along with the Core rules files, should be contained is
files outside of the httpd.conf file and called up with Apache "Include"
directives. This allows for easier updating/migration of the rules. If you
create your own custom rules that you would like to use with the Core
rules, you should create a file called -
<code class="filename">modsecurity_crs_15_customrules.conf</code> and place it in
the same directory as the Core rules files. By using this file name, your
custom rules will be called up after the standard ModSecurity Core rules
configuration file but before the other Core rules. This allows your rules
to be evaluated first which can be useful if you need to implement
specific "allow" rules or to correct any false positives in the Core rules
as they are applied to your site.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is highly encouraged that you do not edit the Core rules files
themselves but rather place all changes (such as
<code class="literal">SecRuleRemoveByID</code>, etc...) in your custom rules file.
This will allow for easier upgrading as newer Core rules are released by
Breach Security on the ModSecurity website.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101B0"></a><code class="literal">SecAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Unconditionally processes the
action list it receives as the first and only parameter. It accepts one
parameter, the syntax of which is identical to the third parameter
of<code class="literal"> SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAction
action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAction
nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME}</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>SecAction is best used when you unconditionally execute an action.
This is explicit triggering whereas the normal Actions are conditional
based on data inspection of the request/response. This is a useful
directive when you want to run certain actions such as
<code class="literal">initcol</code> to initialize collections.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101E1"></a><code class="literal">SecArgumentSeparator</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies which character to use
as separator for<code class="literal">
application/x-www-form-urlencoded</code> content. Defaults to
<code class="literal">&</code>. Applications are sometimes
(very rarely) written to use a semicolon (<code class="literal">;</code>).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecArgumentSeparator character</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecArgumentSeparator ;</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>This directive is needed if a backend web application is using a
non-standard argument separator. If this directive is not set properly
for each web application, then ModSecurity will not be able to parse the
arguments appropriately and the effectiveness of the rule matching will
be significantly decreased.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10216"></a><code class="literal">SecAuditEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the audit logging
engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditEngine On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Can be set/changed with
the "<code class="literal">ctl</code>" action for the current transaction.</p><p>Example: The following example shows the various audit directives
used together.</p><pre class="programlisting"><span class="emphasis"><em>SecAuditEngine RelevantOnly</em></span>
SecAuditLog logs/audit/audit.log
SecAuditLogParts ABCFHZ
SecAuditLogType concurrent
SecAuditLogStorageDir logs/audit
<span class="emphasis"><em>SecAuditLogRelevantStatus ^(?:5|4\d[^4])</em></span></pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - log all transactions
by default.</p></li><li><p><code class="literal">Off</code> - do not log
transactions by default.</p></li><li><p><code class="literal">RelevantOnly</code> - by default
only log transactions that have triggered a warning or an error, or
have a status code that is considered to be relevant (see<code class="literal"> SecAuditLogRelevantStatus</code>).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10263"></a><code class="literal">SecAuditLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the main
audit log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog
/path/to/auditlog</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog
/usr/local/apache/logs/audit.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This file is open on
startup when the server typically still runs as<span class="emphasis"><em>
root</em></span>. You should not allow non-root users to have write
privileges for this file or for the directory it is stored in..</p><p>This file will be used to store the audit log entries if serial
audit logging format is used. If concurrent audit logging format is used
this file will be used as an index, and contain a record of all audit
log files created. If you are planning to use Concurrent audit logging
and sending your audit log data off to a remote Console host or
commercial ModSecurity Management Appliance, then you will need to
configure and use the ModSecurity Log Collector (mlogc) and use the
following format for the audit log:</p><p><pre class="programlisting">SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"</pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10293"></a><code class="literal">SecAuditLog2</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
secondary audit log index file when concurrent logging is enabled. See
<code class="literal">SecAuditLog2</code> for more details.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog2
/path/to/auditlog2</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog2
/usr/local/apache/logs/audit2.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.2</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> A main audit log must be
defined via <code class="literal">SecAuditLog</code> before this
directive may be used. Additionally, this log is only used for
replicating the main audit log index file when concurrent audit logging
is used. It will <span class="emphasis"><em>not</em></span> be used for non-concurrent
audit logging.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102C5"></a><code class="literal">SecAuditLogDirMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
(permissions) of any directories created for concurrent audit logs using
an octal mode (as used in chmod). See <code class="literal">SecAuditLogFileMode</code> for controlling the mode
of audit log files.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogDirMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogDirMode 02750</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
available on operating systems not supporting octal file modes. The
default mode (0600) only grants read/write access to the account writing
the file. If access from another account is needed (using mpm-itk is a
good example), then this directive may be required. However, use this
directive with caution to avoid exposing potentially sensitive data to
unauthorized users. Using the value "default" will revert back to the
default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102F3"></a><code class="literal">SecAuditLogFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
(permissions) of any files created for concurrent audit logs using an
octal mode (as used in chmod). See <code class="literal">SecAuditLogDirMode</code> for controlling the mode of
created audit log directories.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogFileMode
octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogFileMode 00640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
available on operating systems not supporting octal file modes. The
default mode (0600) only grants read/write access to the account writing
the file. If access from another account is needed (using mpm-itk is a
good example), then this directive may be required. However, use this
directive with caution to avoid exposing potentially sensitive data to
unauthorized users. Using the value "default" will revert back to the
default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10321"></a><code class="literal">SecAuditLogParts</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines which part of each
transaction are going to be recorded in audit log. Each part is assigned
a single letter. If a letter appears in the list then the equivalent
part of each transactions will be recorded. See below for the list of
all parts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogParts PARTS</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogParts ABCFHZ</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> At this time ModSecurity
does not log response bodies of stock Apache responses (e.g. <code class="literal">404</code>), or the <code class="literal">Server</code> and <code class="literal">Date</code> response headers.</p><p>Default:<code class="literal"> ABCFHZ</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please refer to the ModSecurity Data Formats document for a
detailed description of every available part.</p></div><p>Available audit log parts:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">A</code> - audit log header
(mandatory)</p></li><li><p><code class="literal">B</code> - request headers</p></li><li><p><code class="literal">C</code> - request body (present
only if the request body exists and ModSecurity is configured to
intercept it)</p></li><li><p><code class="literal">D</code> - RESERVED for
intermediary response headers, not implemented yet.</p></li><li><p><code class="literal">E</code> - intermediary response
body (present only if ModSecurity is configured to intercept
response bodies, and if the audit log engine is configured to record
it). Intermediary response body is the same as the actual response
body unless ModSecurity intercepts the intermediary response body,
in which case the actual response body will contain the error
message (either the Apache default error message, or the
ErrorDocument page).</p></li><li><p><code class="literal">F</code> - final response headers
(excluding the Date and Server headers, which are always added by
Apache in the late stage of content delivery).</p></li><li><p><code class="literal">G</code> - RESERVED for the actual
response body, not implemented yet.</p></li><li><p><code class="literal">H</code> - audit log
trailer</p></li><li><p><code class="literal">I</code> - This part is a
replacement for part C. It will log the same data as C in all cases
except when <code class="literal">multipart/form-data</code>
encoding in used. In this case it will log a fake <code class="literal">application/x-www-form-urlencoded</code> body
that contains the information about parameters but not about the
files. This is handy if you don't want to have (often large) files
stored in your audit logs.</p></li><li><p><code class="literal">J</code> - RESERVED. This part,
when implemented, will contain information about the files uploaded
using <code class="literal">multipart/form-data</code> encoding.</p></li><li><p><code class="literal">K</code> - This part contains a
full list of every rule that matched (one per line) in the order
they were matched. The rules are fully qualified and will thus show
inherited actions and default operators. Supported as of
v2.5.0</p></li><li><p><code class="literal">Z</code> - final boundary,
signifies the end of the entry (mandatory)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103B4"></a><code class="literal">SecAuditLogRelevantStatus</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which response status
code is to be considered relevant for the purpose of audit
logging.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogRelevantStatus REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogRelevantStatus
^(?:5|4\d[^4])</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must have the
<code class="literal">SecAuditEngine</code> set to
<code class="literal">RelevantOnly</code>. The parameter is a regular
expression.</p><p>The main purpose of this directive is to allow you to configure
audit logging for only transactions that generate the specified HTTP
Response Status Code. This directive is often used to the decrease the
total size of the audit log file. Keep in mind that if this parameter is
used, then successful attacks that result in a 200 OK status code will
not be logged.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103E5"></a><code class="literal">SecAuditLogStorageDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the storage directory
where concurrent audit log entries are to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogStorageDir
/path/to/storage/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogStorageDir
/usr/local/apache/logs/audit</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> SecAuditLogType must be
set to Concurrent. The directory must already be created before starting
Apache and it must be writable by the web server user as new files are
generated at runtime.</p><p>As with all logging mechanisms, ensure that you specify a file
system location that has adequate disk space and is not on the root
partition.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1040E"></a><code class="literal">SecAuditLogType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the type of audit
logging mechanism to be used.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogType Serial|Concurrent</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogType Serial</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must specify
<code class="literal">SecAuditLogStorageDir</code> if you use concurrent
logging.</p><p>Possible values are:</p><div class="orderedlist"><ol type="1"><li><p><code class="literal">Serial</code> - all audit log
entries will be stored in the main audit logging file. This is more
convenient for casual use but it is slower as only one audit log
entry can be written to the file at any one file.</p></li><li><p><code class="literal">Concurrent</code> - audit log
entries will be stored in separate files, one for each transaction.
Concurrent logging is the mode to use if you are going to send the
audit log data off to a remote ModSecurity Console host.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1044A"></a><code class="literal">SecCacheTransformations</code>
(Deprecated/Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Controls caching of
transformations. Caching is off by default starting with 2.5.6, when it
was deprecated and downgraded back to experimental.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCacheTransformations On|Off
[options]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCacheTransformations On
"minlen:64,maxlen:0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p><p>First parameter:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - cache transformations
(per transaction, per phase) allowing identical transformations to
be performed only once. (default)</p></li><li><p><code class="literal">Off</code> - do not cache any
transformations, forcing all transformations to be performed for
each rule executed.</p></li></ul></div><p>The following options are allowed (comma separated):</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">incremental:on|off</code> -
enabling this option will cache every transformation instead of just
the final transformation. (default: off)</p></li><li><p><code class="literal">maxitems:N</code> - do not allow
more than N transformations to be cached. The cache will then be
disabled. A zero value is interpreted as "unlimited". This option
may be useful to limit caching for a form with a large number of
ARGS. (default: 512)</p></li><li><p><code class="literal">minlen:N</code> - do not cache the
transformation if the value's length is less than N bytes. (default:
32)</p></li><li><p><code class="literal">maxlen:N</code> - do not cache the
transformation if the value's length is more than N bytes. A zero
value is interpreted as "unlimited". (default: 1024)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1049C"></a><code class="literal">SecChrootDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory path
that will be used to jail the web server process.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecChrootDir
/path/to/chroot/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecChrootDir /chroot</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
available on Windows builds. The internal chroot functionality provided
by ModSecurity works great for simple setups. One example of a simple
setup is Apache serving static files only, or running scripts using
modules.builds. Some problems you might encounter with more complex
setups:</p><div class="orderedlist"><ol type="1"><li><p>DNS lookups do not work (this is because this feature requires
a shared library that is loaded on demand, after chroot takes
place).</p></li><li><p>You cannot send email from PHP because it uses sendmail and
sendmail is outside the jail.</p></li><li><p>In some cases Apache graceful (reload) no longer works.</p></li></ol></div><p>You should be aware that the internal chroot feature might not be
100% reliable. Due to the large number of default and third-party
modules available for the Apache web server, it is not possible to
verify the internal chroot works reliably with all of them. A module,
working from within Apache, can do things that make it easy to break out
of the jail. In particular, if you are using any of the modules that
fork in the module initialisation phase (e.g.
<code class="literal">mod_fastcgi</code>, <code class="literal">mod_fcgid</code>,
<code class="literal">mod_cgid</code>), you are advised to examine each Apache
process and observe its current working directory, process root, and the
list of open files. Consider what your options are and make your own
decision.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N104DD"></a><code class="literal">SecComponentSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Appends component signature to
the ModSecurity signature.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecComponentSignature
"COMPONENT_NAME/X.Y.Z (COMMENT)"</code></p><p><span class="emphasis"><em>Example usage</em></span>: <code class="literal">SecComponentSignature
"Core Rules/1.2.3"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Main</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes</em></span>: This directive should be
used to make the presence of significant ModSecurity components known.
The entire signature will be recorded in transaction audit log. It
should be used by ModSecurity module and rule set writers to make
debugging easier.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10504"></a><code class="literal">SecContentInjection</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables content injection using
actions <code class="literal">append</code> and <code class="literal">prepend</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecContentInjection
(On|Off)</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecContentInjection
On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10533"></a><code class="literal">SecCookieFormat</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Selects the cookie format that
will be used in the current configuration context.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCookieFormat 0|1</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCookieFormat 0</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - use version 0
(Netscape) cookies. This is what most applications use. It is the
default value.</p></li><li><p><code class="literal">1</code> - use version 1
cookies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10569"></a><code class="literal">SecDataDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path where persistent data (e.g.
IP address data, session data, etc) is to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDataDir
/path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDataDir /usr/local/apache/logs/data</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Dependencies/Notes: </em></span> This directive is needed
when initcol, setsid an setuid are used. Must be writable by the web
server user.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1058C"></a><code class="literal">SecDebugLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path to the ModSecurity debug
log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLog
/path/to/modsec-debug.log</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLog
/usr/local/apache/logs/modsec-debug.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N105B3"></a><code class="literal">SecDebugLogLevel</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the verboseness of
the debug log data.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLogLevel 0|1|2|3|4|5|6|7|8|9</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLogLevel 4</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Levels <code class="literal">1 - 3</code> are always sent to the Apache error log.
Therefore you can always use level <code class="literal">0</code>
as the default logging level in production. Level <code class="literal">5</code> is useful when debugging. It is not
advisable to use higher logging levels in production as excessive
logging can slow down server significantly.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - no logging.</p></li><li><p><code class="literal">1</code> - errors (intercepted
requests) only.</p></li><li><p><code class="literal">2</code> - warnings.</p></li><li><p><code class="literal">3</code> - notices.</p></li><li><p><code class="literal">4</code> - details of how
transactions are handled.</p></li><li><p><code class="literal">5</code> - as above, but including
information about each piece of information handled.</p></li><li><p><code class="literal">9</code> - log everything,
including very detailed debugging information.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10613"></a><code class="literal">SecDefaultAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the default action to
take on a rule match.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDefaultAction
action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDefaultAction
log,auditlog,deny,status:403,phase:2</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Rules following a
<code class="literal">SecDefaultAction</code> directive will inherit this setting
unless a specific action is specified for an individual rule or until
another <code class="literal">SecDefaultAction</code> is specified. Take special
note that in the logging disruptive actions are not allowed, but this
can inadvertently be inherited using a disruptive action in
<code class="literal">SecDefaultAction</code>.</p><p>The default value is minimal (differing from previous
versions):</p><pre class="programlisting">SecDefaultAction phase:2,log,auditlog,pass</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><code class="literal">SecDefaultAction</code> must specify a disruptive
action and a processing phase and cannot contain metadata
actions.</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><code class="literal">SecDefaultAction</code> is <span class="emphasis"><em>not</em></span>
inherited across configuration contexts. (For an example of why this
may be a problem for you, read the following ModSecurity Blog entry
<a href="http://blog.modsecurity.org/2008/07/modsecurity-tri.html" target="_top">http://blog.modsecurity.org/2008/07/modsecurity-tri.html</a>).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1065E"></a><code class="literal">SecGeoLookupDb</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
geographical database file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGeoLookupDb /path/to/db</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGeoLookupDb
/usr/local/geo/data/GeoLiteCity.dat</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Check out
<code class="literal">maxmind.com</code> for free database files.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10689"></a><code class="literal">SecGuardianLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configuration directive to use
the httpd-guardian script to monitor for Denial of Service (DoS)
attacks.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGuardianLog |/path/to/httpd-guardian</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGuardianLog
|/usr/local/apache/bin/httpd-guardian</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> By default httpd-guardian
will defend against clients that send more than 120 requests in a
minute, or more than 360 requests in five minutes.</p><p>Since 1.9, ModSecurity supports a new directive, SecGuardianLog,
that is designed to send all access data to another program using the
piped logging feature. Since Apache is typically deployed in a
multi-process fashion, making information sharing difficult, the idea is
to deploy a single external process to observe all requests in a
stateful manner, providing additional protection.</p><p>Development of a state of the art external protection tool will be
a focus of subsequent ModSecurity releases. However, a fully functional
tool is already available as part of the <a href="http://www.apachesecurity.net/tools/" target="_top">Apache httpd tools
project</a>. The tool is called httpd-guardian and can be used to
defend against Denial of Service attacks. It uses the blacklist tool
(from the same project) to interact with an iptables-based (Linux) or
pf-based (*BSD) firewall, dynamically blacklisting the offending IP
addresses. It can also interact with SnortSam (http://www.snortsam.net).
Assuming httpd-guardian is already configured (look into the source code
for the detailed instructions) you only need to add one line to your
Apache configuration to deploy it:</p><pre class="programlisting">SecGuardianLog |/path/to/httpd-guardian</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106BC"></a><code class="literal">SecMarker</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Adds a fixed rule marker in the
ruleset to be used as a target in a <code class="literal">skipAfter</code> action.
A <code class="literal">SecMarker</code> directive essentially creates a rule that
does nothing and whose only purpose it to carry the given ID.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecMarker
ID</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecMarker 9999</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><pre class="programlisting">SecRule REQUEST_URI "^/$" \
"chain,t:none,t:urlDecode,t:lowercase,t:normalisePath,<span class="emphasis"><em>skipAfter:99</em></span>"
SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
SecRule REQUEST_HEADERS:User-Agent \
"^Apache \(internal dummy connection\)$" "t:none"
SecRule &REQUEST_HEADERS:Host "@eq 0" \
"deny,log,status:400,id:08,severity:4,msg:'Missing a Host Header'"
SecRule &REQUEST_HEADERS:Accept "@eq 0" \
"log,deny,log,status:400,id:15,msg:'Request Missing an Accept Header'"
<span class="emphasis"><em>
SecMarker 99</em></span></pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106F4"></a><code class="literal">SecPcreMatchLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span>Sets the the match limit in the
PCRE library. See the pcre_extra field in the pcreapi man page.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPcreMatchLimit value</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPcreMatchLimit 1500</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Global</p><p><span class="emphasis"><em>Version:</em></span> 2.5.12</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Default is set at compile
(1500 by default)</p><p>The <code class="literal">--enable-pcre-match-limit=val</code> configure
option will set a custom default and the
<code class="literal">--disable-pcre-match-limit</code> option will resort to the
compiled PCRE library default.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10725"></a><code class="literal">SecPcreMatchLimitRecursion</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span>Sets the the match limit
recursion in the PCRE library. See the pcre_extra field in the pcreapi
man page.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPcreMatchLimitRecursion value</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPcreMatchLimitRecursion 1500</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Global</p><p><span class="emphasis"><em>Version:</em></span> 2.5.12</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Default is set at compile
(1500 by default)</p><p>The <code class="literal">--enable-pcre-match-limit-recursion=val</code>
configure option will set a custom default and the
<code class="literal">--disable-pcre-match-limit-recursion</code> option will
resort to the compiled PCRE library default.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10756"></a><code class="literal">SecPdfProtect</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables the PDF XSS protection
functionality. Once enabled access to PDF files is tracked. Direct
access attempts are redirected to links that contain one-time tokens.
Requests with valid tokens are allowed through unmodified. Requests with
invalid tokens are also allowed through but with forced download of the
PDF files. This implementation uses response headers to detect PDF files
and thus can be used with dynamically generated PDF files that do not
have the <code class="filename">.pdf</code> extension in the request URI.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtect On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtect On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10781"></a><code class="literal">SecPdfProtectMethod</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configure desired protection
method to be used when requests for PDF files are detected. Possible
values are <code class="literal">TokenRedirection</code> and
<code class="literal">ForcedDownload</code>. The token redirection approach will
attempt to redirect with tokens where possible. This allows PDF files to
continue to be opened inline but only works for GET requests. Forced
download always causes PDF files to be delivered as opaque binaries and
attachments. The latter will always be used for non-GET requests. Forced
download is considered to be more secure but may cause usability
problems for users ("This PDF won't open anymore!").</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectMethod method</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectMethod TokenRedirection</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span>
<code class="literal">TokenRedirection</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107B7"></a><code class="literal">SecPdfProtectSecret</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the secret that will be
used to construct one-time tokens. You should use a reasonably long
value for the secret (e.g. 16 characters is good). Once selected the
secret should not be changed as it will break the tokens that were sent
prior to change. But it's not a big deal even if you change it. It will
just force download of PDF files with tokens that were issued in the
last few seconds.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectSecret secret</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectSecret
MyRandomSecretString</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107DE"></a><code class="literal">SecPdfProtectTimeout</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the token timeout. After
token expires it can no longer be used to allow access to PDF file.
Request will be allowed through but the PDF will be delivered as
attachment.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTimeout timeout</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTimeout 10</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">10</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1080C"></a><code class="literal">SecPdfProtectTokenName</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the name of the token.
The only reason you would want to change the name of the token is if you
wanted to hide the fact you are running ModSecurity. It's a good reason
but it won't really help as the adversary can look into the algorithm
used for PDF protection and figure it out anyway. It does raise the bar
slightly so go ahead if you want to.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTokenName name</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTokenName PDFTOKEN</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">PDFTOKEN</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1083A"></a><code class="literal">SecRequestBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether request
bodies will be buffered and processed by ModSecurity by default.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
required if you plan to inspect <code class="literal">POST_PAYLOAD</code>. This
directive must be used along with the "phase:2" processing phase action
and <code class="literal">REQUEST_BODY</code> variable/location. If any of these 3
parts are not configured, you will not be able to inspect the request
bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access request
bodies.</p></li><li><p><code class="literal">Off</code> - do not attempt to
access request bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10878"></a><code class="literal">SecRequestBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
body size ModSecurity will accept for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 134217728</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 131072 KB (134217728
bytes) is the default setting. Anything over this limit will be rejected
with status code 413 Request Entity Too Large. There is a hard limit of
1 GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1089B"></a><code class="literal">SecRequestBodyNoFilesLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
body size ModSecurity will accept for buffering, excluding the size of
files being transported in the request. This directive comes handy to
further reduce susceptibility to DoS attacks when someone is sending
request bodies of very large sizes. Web applications that require file
uploads must configure <code class="literal">SecRequestBodyLimit</code> to a high
value. Since large files are streamed to disk file uploads will not
increase memory consumption. However, it's still possible for someone to
take advantage of a large request body limit and send non-upload
requests with large body sizes. This directive eliminates that
loophole.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyNoFilesLimit
NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 131072</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 1 MB (1048576 bytes) is
the default setting. This value is very conservative. For most
applications you should be able to reduce it down to 128 KB or lower.
Anything over the limit will be rejected with status code <code class="literal">413
Request Entity Too Large</code>. There is a hard limit of 1
GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108C6"></a><code class="literal">SecRequestBodyInMemoryLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
body size ModSecurity will store in memory.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyInMemoryLimit
NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyInMemoryLimit 131072</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>By default the limit is 128 KB:</p><pre class="programlisting"># Store up to 128 KB in memory
SecRequestBodyInMemoryLimit 131072</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108F2"></a><code class="literal">SecResponseBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum response
body size that will be accepted for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyLimit 524228</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Anything over this limit
will be rejected with status code 500 Internal Server Error. This
setting will not affect the responses with MIME types that are not
marked for buffering. There is a hard limit of 1 GB.</p><p>By default this limit is configured to 512 KB:</p><pre class="programlisting"># Buffer response bodies of up to 512 KB in length
SecResponseBodyLimit 524288</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1091E"></a><code class="literal">SecResponseBodyLimitAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Controls what happens once a
response body limit, configured with
<code class="literal">SecResponseBodyLimit</code>, is encountered. By default
ModSecurity will reject a response body that is longer than specified.
Some web sites, however, will produce very long responses making it
difficult to come up with a reasonable limit. Such sites would have to
raise the limit significantly to function properly defying the purpose
of having the limit in the first place (to control memory consumption).
With the ability to choose what happens once a limit is reached site
administrators can choose to inspect only the first part of the
response, the part that can fit into the desired limit, and let the rest
through. Some could argue that allowing parts of responses to go
uninspected is a weakness. This is true in theory but only applies to
cases where the attacker controls the output (e.g. can make it arbitrary
long). In such cases, however, it is not possible to prevent leakage
anyway. The attacker could compress, obfuscate, or even encrypt data
before it is sent back, and therefore bypass any monitoring
device.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecResponseBodyLimitAction
Reject|ProcessPartial</code></p><p><span class="emphasis"><em>Example Usage</em></span>:
<code class="literal">SecResponseBodyLimitAction ProcessPartial</code></p><p><span class="emphasis"><em>Processing Phase</em></span>: N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10949"></a><code class="literal">SecResponseBodyMimeType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which<code class="literal"> MIME</code> types are to be considered for response
body buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeType mime/type</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeType text/plain
text/html</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Multiple<code class="literal"> SecResponseBodyMimeType</code> directives can be
used to add<code class="literal"> MIME</code> types.</p><p>The default value is <code class="literal">text/plaintext/html</code>:</p><pre class="programlisting">SecResponseBodyMimeType text/plain text/html</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10985"></a><code class="literal">SecResponseBodyMimeTypesClear</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Clears the list of <code class="literal">MIME</code> types considered for response body
buffering, allowing you to start populating the list from
scratch.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N109B0"></a><code class="literal">SecResponseBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether response
bodies are to be buffer and analysed or not.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
required if you plan to inspect HTML responses. This directive must be
used along with the "phase:4" processing phase action and RESPONSE_BODY
variable/location. If any of these 3 parts are not configured, you will
not be able to inspect the response bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access response bodies
(but only if the MIME type matches, see above).</p></li><li><p><code class="literal">Off</code> - do not attempt to
access response bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N109E6"></a><code class="literal">SecRule</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> <code class="literal">SecRule</code> is the main ModSecurity directive. It
is used to analyse data and perform actions based on the results.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRule
VARIABLES OPERATOR [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRule REQUEST_URI "attack" \</code></p><p><code class="literal">
"phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>In general, the format of this rule is as follows:</p><pre class="programlisting">SecRule VARIABLES OPERATOR [ACTIONS]</pre><p>The second part, <code class="literal">OPERATOR</code>,
specifies how they are going to be checked. The third (optional) part,
<code class="literal">ACTIONS</code>, specifies what to do
whenever the operator used performs a successful match against a
variable.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A24"></a>Variables in rules</h4></div></div><div></div></div><p>The first part,<code class="literal"> VARIABLES</code>,
specifies which variables are to be checked. For example, the
following rule will reject a transaction that has the word<span class="emphasis"><em>
dirty</em></span> in the URI:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>Each rule can specify one or more variables:</p><pre class="programlisting">SecRule ARGS|REQUEST_HEADERS:User-Agent dirty</pre><p>There is a third format supported by the selection operator -
XPath expression. XPath expressions can only used against the special
variable XML, which is available only of the request body was
processed as XML.</p><pre class="programlisting">SecRule XML:/xPath/Expression dirty</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Not all collections support all selection operator format
types. You should refer to the documentation of each collection to
determine what is and isn't supported.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A40"></a>Collections</h4></div></div><div></div></div><p>A variable can contain one or many pieces of data, depending on
the nature of the variable and the way it is used. We've seen examples
of both approaches in the previous section. When a variable can
contain more than one value we refer to it as a
<span class="emphasis"><em>collection</em></span>.</p><p>Collections are always expanded before a rule is run. For
example, the following rule:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>will be expanded to:</p><pre class="programlisting">SecRule ARGS:p dirty
SecRule ARGS:q dirty</pre><p>in a requests that has only two parameters, named
<code class="literal">p</code> and <code class="literal">q</code>.</p><p>Collections come in several flavours:</p><div class="variablelist"><dl><dt><span class="term">Read-only</span></dt><dd><p>Created at runtime using transaction data. For example:
<code class="literal">ARGS</code> (contains a list of all request
parameter values) and <code class="literal">REQUEST_HEADERS</code>
(contains a list of all request header values).</p></dd><dt><span class="term">Transient Read/Write</span></dt><dd><p>The <code class="literal">TX</code> collection is created (empty)
for every transaction. Rules can read from it and write to it
(using the <code class="literal">setvar</code> action, for example), but
the information stored in this collection will not survive the
end of transaction.</p></dd><dt><span class="term">Persistent Read/Write</span></dt><dd><p>There are several collections that can be written to, but
which are persisted to the storage backend. These collections
are used to track clients across transactions. Examples of
collections that fall into this type are <code class="literal">IP</code>,
<code class="literal">SESSION</code> and <code class="literal">USER</code>.</p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A8D"></a>Operators in rules</h4></div></div><div></div></div><p>In the simplest possible case you will use a regular expression
pattern as the second rule parameter. This is what we've done in the
examples above. If you do this ModSecurity assumes you want to use the
<code class="literal">rx</code> (regular expression) operator.
You can also explicitly specify the operator you want to use by using
<code class="literal">@</code>, followed by the name of an
operator, at the beginning of the second <code class="literal">SecRule</code>
parameter:</p><pre class="programlisting">SecRule ARGS "@rx dirty"</pre><p>Note how we had to use double quotes to delimit the second rule
parameter. This is because the second parameter now has whitespace in
it. Any number of whitespace characters can follow the name of the
operator. If there are any non-whitespace characters there, they will
all be treated as a special parameter to the operator. In the case of
the regular expression operator the special parameter is the pattern
that will be used for comparison.</p><p>The @ can be the second character if you are using negation to
negate the result returned by the operator:</p><pre class="programlisting">SecRule &ARGS "!@rx ^0$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10AA8"></a>Operator negation</h4></div></div><div></div></div><p>Operator results can be negated by using an exclamation mark at
the beginning of the second parameter. The following rule matches if
the word <code class="literal">dirty</code> does <span class="emphasis"><em>not</em></span> appear
in the <code class="literal">User-Agent</code> request header:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent !dirty</pre><p>You can use the exclamation mark in combination with any
parameter. If you do, the exclamation mark needs to go first, followed
by the explicit operator reference. The following rule has the same
effect as the previous example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "!@rx dirty"</pre><p>If you need to use negation in a rule that is going to be
applied to several variables then it may not be immediately clear what
will happen. Consider the following example:</p><pre class="programlisting">SecRule ARGS:p|ARGS:q !dirty</pre><p>The above rule is identical to:</p><pre class="programlisting">SecRule ARGS:p !dirty
SecRule ARGS:q !dirty</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Negation is applied to operations against individual
operations, not agains the entire variable list.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10ACD"></a>Actions in rules</h4></div></div><div></div></div><p>The third parameter, <code class="literal">ACTIONS</code>,
can be omitted only because there is a helper feature that specifies
the default action list. If the parameter isn't omitted the actions
specified in the parameter will be merged with the default action list
to create the actual list of actions that will be processed on a rule
match.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10AD6"></a><code class="literal">SecRuleInheritance</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether the current
context will inherit rules from the parent context (configuration
options are inherited in most cases - you should look up the
documentation for every directive to determine if it is inherited or
not).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleInheritance On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleInheritance Off</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Resource-specific
contexts (e.g.<code class="literal"> Location</code>, <code class="literal">Directory</code>, etc) cannot override
<span class="emphasis"><em>phase1</em></span> rules configured in the main server or in
the virtual server. This is because phase 1 is run early in the request
processing process, before Apache maps request to resource. Virtual host
context can override phase 1 rules configured in the main server.</p><p>Example: The following example shows where ModSecurity may be
enabled in the main Apache configuration scope, however you might want
to configure your VirtualHosts differently. In the first example, the
first VirtualHost is not inheriting the ModSecurity main config
directives and in the second one it is.</p><pre class="programlisting">SecRuleEngine On
SecDefaultAction log,pass,phase:2
...
<VirtualHost *:80>
ServerName app1.com
ServerAlias www.app1.com<span class="emphasis"><em>
SecRuleInheritance Off</em></span>
SecDefaultAction log,deny,phase:1,redirect:http://www.site2.com
...
</VirtualHost>
<VirtualHost *:80>
ServerName app2.com
ServerAlias www.app2.com
<span class="emphasis"><em>SecRuleInheritance On</em></span> SecRule ARGS "attack"
...
</VirtualHost></pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - inherit rules from the
parent context.</p></li><li><p><code class="literal">Off</code> - do not inherit rules
from the parent context.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Configuration contexts are an Apache concept. Directives
<code class="literal"><Directory></code>,
<code class="literal"><Files></code>,
<code class="literal"><Location></code> and
<code class="literal"><VirtualHost></code> are all used to create
configuration contexts. For more information please go to the
Apache documentation section <a href="http://httpd.apache.org/docs/2.0/sections.html" target="_top">Configuration
Sections</a>.</p></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B39"></a><code class="literal">SecRuleEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the rules
engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleEngine On|Off|DetectionOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive can also
be controlled by the ctl action (ctl:ruleEngine=off) for per rule
processing.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - process rules.</p></li><li><p><code class="literal">Off</code> - do not process
rules.</p></li><li><p><code class="literal">DetectionOnly</code> - process
rules but never intercept transactions, even when rules are
configured to do so.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B75"></a><code class="literal">SecRuleRemoveById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleUpdateActionById RULEID
ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByID 1 2 "9000-9010"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
multiple parameters, where each parameter can either be a rule ID, or a
range. Parameters that contain spaces must be delimited using double
quotes.</p><pre class="programlisting">SecRuleRemoveById 1 2 5 10-20 "400-556" 673</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B9F"></a><code class="literal">SecRuleRemoveByMsg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveByMsg REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByMsg "FAIL"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
multiple parameters. Each parameter is a regular expression that will be
applied to the message (specified using the <code class="literal">msg</code> action).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10BCA"></a><code class="literal">SecRuleScript</code> (Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This directive creates a special
rule that executes a Lua script to decide whether to match or not. The
main difference from <code class="literal">SecRule</code> is that there are no
targets nor operators. The script can fetch any variable from the
ModSecurity context and use any (Lua) operator to test them. The second
optional parameter is the list of actions whose meaning is identical to
that of <code class="literal">SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleScript
/path/to/script.lua [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleScript "/path/to/file.lua"
"block"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All Lua scripts are compiled at configuration time and cached in
memory. To reload scripts you must reload the entire ModSecurity
configuration by restarting Apache.</p></div><p>Example script:</p><pre class="programlisting">-- Your script must define the <span class="emphasis"><em>main</em></span> entry
-- point, as below.
function main()
-- Log something at level 1. Normally you shouldn't be
-- logging anything, especially not at level 1, but this is
-- just to show you can. Useful for debugging.
m.log(1, "Hello world!");
-- Retrieve one variable.
local var1 = m.getvar("REMOTE_ADDR");
-- Retrieve one variable, applying one transformation function.
-- The second parameter is a string.
local var2 = m.getvar("ARGS", "lowercase");
-- Retrieve one variable, applying several transformation functions.
-- The second parameter is now a list. You should note that m.getvar()
-- requires the use of comma to separate collection names from
-- variable names. This is because only one variable is returned.
local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );
-- If you want this rule to match return a string
-- containing the error message. The message <span class="emphasis"><em>must</em></span> contain the name
-- of the variable where the problem is located.
-- return "Variable ARGS:p looks suspicious!"
-- Otherwise, simply return nil.
return nil;
end</pre><p>In this first example we were only retrieving one variable at the
time. In this case the name of the variable is known to you. In many
cases, however, you will want to examine variables whose names you won't
know in advance, for example script parameters.</p><p>Example showing use of <code class="literal">m.getvars()</code> to retrieve
many variables at once:</p><pre class="programlisting">function main()
-- Retrieve script parameters.
local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );
-- Loop through the paramters.
for i = 1, #d do
-- Examine parameter value.
if (string.find(d[i].value, "<script")) then
-- Always specify the name of the variable where the
-- problem is located in the error message.
return ("Suspected XSS in variable " .. d[i].name .. ".");
end
end
-- Nothing wrong found.
return nil;
end</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Go to <a href="http://www.lua.org/" target="_top">http://www.lua.org/</a> to find more
about the Lua programming language. The reference manual too is
available online, at <a href="http://www.lua.org/manual/5.1/" target="_top">http://www.lua.org/manual/5.1/</a>.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Lua support is marked as <span class="emphasis"><em>experimental</em></span> as
the way the progamming interface may continue to evolve while we are
working for the best implementation style. Any user input into the
programming interface is appreciated.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C24"></a><code class="literal">SecRuleUpdateActionById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Updates the action list of the
specified rule.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveById RULEID ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleUpdateActionById 12345
deny,status:403</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive merges the
specified action list with the rule's action list. There are two
limitations. The rule ID cannot be changed, nor can the phase. Further
note that actions that may be specified multiple times are appended to
the original.</p><pre class="programlisting">SecAction \
"t:lowercase,phase:2,id:12345,pass,msg:'The Message',log,auditlog"
SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new message'</pre><p>The example above will cause the rule to be executed as if it was
specified as follows:</p><pre class="programlisting">SecAction \
"t:lowercase,phase:2,id:12345,log,auditlog,t:compressWhitespace,deny,status:403,msg:'A new message'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C53"></a><code class="literal">SecServerSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Instructs ModSecurity to change
the data presented in the "Server:" response header token.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecServerSignature "WEB SERVER
SOFTWARE"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecServerSignature
"Netscape-Enterprise/6.0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> In order for this
directive to work, you must set the Apache ServerTokens directive to
Full. ModSecurity will overwrite the server signature data held in this
memory space with the data set in this directive. If ServerTokens is not
set to Full, then the memory space is most likely not large enough to
hold the new data we are looking to insert.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C7A"></a><code class="literal">SecTmpDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
temporary files will be created.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecTmpDir
/path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecTmpDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Needs to be writable by
the Apache user process. This is the directory location where Apache
will swap data to disk if it runs out of memory (more data than what was
specified in the SecRequestBodyInMemoryLimit directive) during
inspection.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10CA1"></a><code class="literal">SecUploadDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
intercepted files will be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadDir
/path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directory must be on
the same filesystem as the temporary directory defined with <code class="literal">SecTmpDir</code>. This directive is used with
<code class="literal">SecUploadKeepFiles</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10CD0"></a><code class="literal">SecUploadFileLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum number of
file uploads processed in a multipart POST.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadFileLimit number</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadFileLimit 10</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.12</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> The default is set to 100
files, but you are encouraged to reduce this value. Any file over the
limit will not be extracted and the <code class="literal">MULTIPART_FILE_LIMIT_EXCEEDED</code> and <code class="literal">MULTIPART_STRICT_ERROR</code> flags will be set. To
prevent bypassing any file checks, you must check for one of these
flags.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If the limit is exceeded, the part name and file name will still
be recorded in <code class="literal">FILES_NAME</code> and
<code class="literal">FILES</code>, the file size will be
recorded in <code class="literal">FILES_SIZES</code>, but there
will be no record in <code class="literal">FILES_TMPNAMES</code>
as a temporary file was not created.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D12"></a><code class="literal">SecUploadFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
(permissions) of any uploaded files using an octal mode (as used in
chmod).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadFileMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadFileMode 0640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.6</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
available on operating systems not supporting octal file modes. The
default mode (0600) only grants read/write access to the account writing
the file. If access from another account is needed (using clamd is a
good example), then this directive may be required. However, use this
directive with caution to avoid exposing potentially sensitive data to
unauthorized users. Using the value "default" will revert back to the
default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D3C"></a><code class="literal">SecUploadKeepFiles</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether or not the
intercepted files will be kept after transaction is processed.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadKeepFiles On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadKeepFiles On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive requires
the storage directory to be defined (using <code class="literal">SecUploadDir</code>).</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - Keep uploaded
files.</p></li><li><p><code class="literal">Off</code> - Do not keep uploaded
files.</p></li><li><p><code class="literal">RelevantOnly</code> - This will
keep only those files that belong to requests that are deemed
relevant.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D7C"></a><code class="literal">SecWebAppId</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Creates a partition on the
server that belongs to one web application.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecWebAppId
"NAME"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecWebAppId "WebApp1"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Partitions are used to
avoid collisions between session IDs and user IDs. This directive must
be used if there are multiple applications deployed on the same server.
If it isn't used, a collision between session IDs might occur. The
default value is<code class="literal"> default</code>.
Example:</p><pre class="programlisting"><VirtualHost *:80>
ServerName app1.com
ServerAlias www.app1.com
<span class="emphasis"><em>SecWebAppId "App1"</em></span>
SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
...
</VirtualHost>
<VirtualHost *:80>
ServerName app2.com
ServerAlias www.app2.com<span class="emphasis"><em>
SecWebAppId "App2"</em></span>
SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
...
</VirtualHost></pre><p>In the two examples configurations shown, SecWebAppId is being
used in conjunction with the Apache VirtualHost directives. What this
achieves is to create more unique collection names when being hosted on
one server. Normally, when setsid is used, ModSecurity will create a
collection with the name "SESSION" and it will hold the value specified.
With using SecWebAppId as shown in the examples, however, the name of
the collection would become "App1_SESSION" and "App2_SESSION".</p><p>SecWebAppId is relevant in two cases:</p><div class="orderedlist"><ol type="1"><li><p>You are logging transactions/alerts to the ModSecurity Console
and you want to use the web application ID to search only the
transactions belonging to that application.</p></li><li><p>You are using the data persistence facility (collections
SESSION and USER) and you need to avoid collisions between sessions
and users belonging to different applications.</p></li></ol></div></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="installation.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="processing-phases.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Installation </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Processing Phases</td></tr></table></div><div align="center" class="copyright">Copyright (C) 2004-2010 <a href="http://www.breach.com">Breach Security</a></div></body></html>
|
