mod_security - Security Audit and Trailing Functionality

This module serves as a filter for authenticated requests handled in mod_auth. It provides possibility to restrict users from access for a specified amount of time if they fail to authenticate several times. It logs failed authentication as well as blocking of users, and it also calls a configurable call-back module when the events occur.

There is also an API to manually block, unblock and list blocked users or users, who have been authenticated within a configurable amount of time.

This module understands the following configuration directives:

*

<Directory>

*

SecurityDataFile

*

SecurityMaxRetries

*

SecurityBlockTime

*

SecurityFailExpireTime

*

SecurityAuthTimeout

*

SecurityCallbackModule

Syntax: SecurityDataFile filename

Default: - None -

Module: mod_security(3)

Context: <Directory>

Related: SecurityMaxRetries, SecurityBlockTime, SecurityFailExpireTime, SecurityAuthTimeout, SecurityCallbackModule

SecurityDataFile sets the name of the security modules for a directory. The filename can be either absolute or relative to the ServerRoot. This file is used to store persistent data for the mod_security module.

Note:

Syntax: SecurityMaxRetries integer() | infinity

Default: 3

Module: mod_security(3)

Context: <Directory>

Related: SecurityDataFile, SecurityBlockTime, SecurityFailExpireTime, SecurityAuthTimeout, SecurityCallbackModule

SecurityMaxRetries specifies the maximum number of tries to authenticate a user has before he is blocked out. If a user successfully authenticates when he is blocked, he will receive a 403 (Forbidden) response from the server.

Note:

Syntax: SecurityBlockTime integer() | infinity

Default: 60

Module: mod_security(3)

Context: <Directory>

Related: SecurityDataFile, SecurityMaxRetries, SecurityFailExpireTime, SecurityAuthTimeout, SecurityCallbackModule

SecurityBlockTime specifies the number of minutes a user is blocked. After this amount of time, he automatically regains access.

Syntax: SecurityFailExpireTime integer() | infinity

Default: 30

Module: mod_security(3)

Context: <Directory>

Related: SecurityDataFile, SecurityMaxRetries, SecurityFailExpireTime, SecurityAuthTimeout, SecurityCallbackModule

SecurityFailExpireTime specifies the number of minutes a failed user authentication is remembered. If a user authenticates after this amount of time, his previous failed authentications are forgotten.

Syntax: SecurityAuthTimeout integer() | infinity

Default: 30

Module: mod_security(3)

Context: <Directory>

Related: SecurityDataFile, SecurityMaxRetries, SecurityFailExpireTime, SecurityFailExpireTime, SecurityCallbackModule

SecurityAuthTimeout specifies the number of seconds a successful user authentication is remembered. After this time has passed, the authentication will no longer be reported by the list_auth_users function.

Syntax: SecurityCallbackModule atom()

Default: - None -

Module: mod_security(3)

Context: <Directory>

Related: SecurityDataFile, SecurityMaxRetries, SecurityFailExpireTime, SecurityFailExpireTime, SecurityAuthTimeout

SecurityCallbackModule specifies the name of a callback module. This module only has one export, event/4, which is called whenever a security event occurs. Read the callback module documentation to find out more.

list_auth_users(Port) -> Users | []

list_auth_users(Address, Port) -> Users | []

list_auth_users(Port, Dir) -> Users | []

list_auth_users(Address, Port, Dir) -> Users | []

Types

Port = integer()

Address = {A, B, C, D} | string() | undefined

Dir = string()

Users = list() = [string()]

list_auth_users/1, list_auth_users/2 and list_auth_users/3 returns a list of users that are currently authenticated. Authentications are stored for SecurityAuthTimeout seconds, and are then discarded.

list_blocked_users(Port) -> Users | []

list_blocked_users(Address, Port) -> Users | []

list_blocked_users(Port, Dir) -> Users | []

list_blocked_users(Address, Port, Dir) -> Users | []

Types

Port = integer()

Address = {A, B, C, D} | string() | undefined

Dir = string()

Users = list() = [string()]

list_blocked_users/1, list_blocked_users/2 and list_blocked_users/3 returns a list of users that are currently blocked from access.

block_user(User, Port, Dir, Seconds) -> true | {error, Reason}

block_user(User, Address, Port, Dir, Seconds) -> true | {error, Reason}

Types

User = string()

Port = integer()

Address = {A, B, C, D} | string() | undefined

Dir = string()

Seconds = integer() | infinity

Reason = no_such_directory

block_user/4 and block_user/5 blocks the user User from the directory Dir for a specified amount of time.

unblock_user(User, Port) -> true | {error, Reason}

unblock_user(User, Address, Port) -> true | {error, Reason}

unblock_user(User, Port, Dir) -> true | {error, Reason}

unblock_user(User, Address, Port, Dir) -> true | {error, Reason}

Types

User = string()

Port = integer()

Address = {A, B, C, D} | string() | undefined

Dir = string()

Reason = term()

unblock_user/2, unblock_user/3 and unblock_user/4 removes the user User from the list of blocked users for the Port (and Dir) specified.

The SecurityCallbackModule is a user written module that can receive events from the mod_security EWSAPI module. This module only exports one function, event/4, which is described below.

event(What, Port, Dir, Data) -> ignored

event(What, Address, Port, Dir, Data) -> ignored

Types

What = atom()

Port = integer()

Address = {A, B, C, D} | string() <v>Dir = string()

What = [Info]

Info = {Name, Value}

event/4 or event/4 is called whenever an event occurs in the mod_security EWSAPI module (event/4 is called if Address is undefined and event/5 otherwise). The What argument specifies the type of event that has occurred, and should be one of the following reasons; auth_fail (a failed user authentication), user_block (a user is being blocked from access) or user_unblock (a user is being removed from the block list).

Note:

Mattias Nilsson  - support@erlang.ericsson.se