ModSecurity configuration directives

Reviewed by Atomicorp WAF Research Team

Adapted ModSecurity documentationThis page has been reorganized, rewritten, and supplemented by Atomicorp from upstream ModSecurity reference material. Source, license, and attribution details.

Directives configure the engine around your rules: what ModSecurity inspects, how much data it buffers, where it logs, and how loaded rules are changed. Support and scope differ between ModSecurity 2.x and libmodsecurity 3, so verify a directive against your installed engine and connector.

Engine and rule loading

Directive	Purpose
`SecRuleEngine`	Selects `On`, `Off`, or `DetectionOnly` processing.
`SecRule`	Evaluates variables with an operator and actions.
`SecAction`	Runs actions without evaluating a variable/operator pair.
`SecDefaultAction`	Supplies inherited phase, logging, and disruptive defaults.
`SecMarker`	Creates a named destination for `skipAfter`.
`SecComponentSignature`	Adds a component identifier to ModSecurity’s signature.
`SecRemoteRules`	Loads rules from an HTTPS endpoint using a key.
`SecRemoteRulesFailAction`	Chooses `Abort` or `Warn` if remote rules cannot load.

Request inspection and limits

Directive	Purpose
`SecRequestBodyAccess`	Enables or disables request-body inspection.
`SecRequestBodyLimit`	Caps the total buffered request body.
`SecRequestBodyNoFilesLimit`	Caps non-file request-body data.
`SecRequestBodyInMemoryLimit`	Sets how much request data is retained in memory.
`SecRequestBodyLimitAction`	Chooses how an over-limit body is handled.
`SecArgumentsLimit`	Limits the number of parsed request arguments.
`SecArgumentSeparator`	Defines the application argument separator.
`SecCookieFormat`	Selects the expected cookie parsing format.
`SecUnicodeMapFile`	Supplies Unicode mapping used by `urlDecodeUni`.

Limits are security and availability controls. Do not raise them globally to accommodate one upload route without considering memory, concurrency, and application-specific scoping.

Response inspection

Directive	Purpose
`SecResponseBodyAccess`	Enables response-body buffering and inspection.
`SecResponseBodyMimeType`	Selects response MIME types to inspect.
`SecResponseBodyLimit`	Caps the response body retained for inspection.
`SecResponseBodyLimitAction`	Chooses what happens when a response exceeds the limit.

Response inspection supports data-loss and malicious-output controls but adds cost. Enable only the MIME types and sizes your policy needs.

Audit and debug logging

Directive	Purpose
`SecAuditEngine`	Selects `On`, `Off`, or `RelevantOnly` audit logging.
`SecAuditLog`	Sets the serial audit-log file or concurrent index.
`SecAuditLogType`	Selects serial or concurrent audit logging.
`SecAuditLogStorageDir`	Sets the transaction directory for concurrent logs.
`SecAuditLogParts`	Selects transaction sections to record.
`SecAuditLogRelevantStatus`	Defines relevant response statuses.
`SecAuditLogFormat`	Selects the supported audit format.
`SecDebugLog`	Sets the diagnostic log file.
`SecDebugLogLevel`	Controls diagnostic verbosity.

Debug logging can be extremely verbose. Raise the level temporarily for a focused investigation, then return it to an operational setting.

File handling and storage

Directive	Purpose
`SecTmpDir`	Sets a directory for temporary files.
`SecDataDir`	Sets persistent storage used by collections and other features.
`SecUploadDir`	Sets the intercepted-upload directory.
`SecUploadKeepFiles`	Controls whether uploaded files are retained.
`SecUploadFileMode`	Sets retained-upload permissions.
`SecUploadFileLimit`	Limits the number of files processed in one request.

These directories must be writable by the web-server account and must not be web-accessible. Treat retained uploads as untrusted data.

Changing loaded rules

Directive	Purpose
`SecRuleRemoveById`	Removes rules by ID or ID range.
`SecRuleRemoveByMsg`	Removes rules matching message text.
`SecRuleRemoveByTag`	Removes rules matching a tag.
`SecRuleUpdateActionById`	Changes actions on a loaded rule.
`SecRuleUpdateTargetById`	Adds or removes inspected targets for a rule ID.
`SecRuleUpdateTargetByTag`	Changes targets for rules selected by tag.

Prefer ID- and target-based changes over message matching. Keep exclusions in a separate local file so vendor updates do not overwrite them.

Source and version note

This operational summary is adapted from the ModSecurity reference material. Consult the exhaustive upstream 2.x directive reference and 3.x reference for syntax, defaults, scope, version introduction, and connector support. The upstream manuals are copyright Trustwave Holdings, Inc.; ModSecurity is licensed under Apache License 2.0.