-
Notifications
You must be signed in to change notification settings - Fork 71
Configuration
Suhosin.'s features are all configured through the php.ini configuration file. Here you can find descriptions of all supported options.
For most users the Suhosin will work out of the box without any change to the default configuration needed.
When you only use the Suhosin-Patch only the logging features are supported. When you only use the Suhosin-Extension you cannot use the predefined constants for configuration. This is due to the way php.ini constant support is implemented in PHP.
Notes:
- This documentation refers to the Suhosin extension version 0.9.38.
- Some features are marked experimental and must be activated at compile time using configure --enable-suhosin-experimental.
- Type: Integer
- Default: S_ALL & ~S_SQL
Defines what classes of security alerts are logged to the syslog daemon. Logging of errors of the class S_MEMORY are always logged to syslog, no matter what this configuration says, because a corrupted heap could mean that the other logging options will malfunction during the logging process.
| Constant | Value | Description |
|---|---|---|
| S_MEMORY | > 1 | All canary violations and the safe unlink protection use this class |
| S_MISC | > 2 | All log messages (f.e. format string protection) that do not fit in other classes use this class |
| S_VARS | > 4 | All variable filters trigger this class |
| S_FILES | > 8 | All violations triggered by the uploaded files filter use this class |
| S_INCLUDE | > 16 | The protection against malicious include filenames use this class |
| S_SQL | > 32 | Failed SQL queries are logged with this class (not yet supported in Suhosin BETA) |
| S_EXECUTOR | > 64 | The execution depth protection uses this logging class |
| S_MAIL | 128 | The mail() header newline protection uses this logging class |
| S_SESSION | 256 | The transparent session protection uses this logging class |
| S_ALL | 511 | Combines all classes |
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value, e.g. [suhosin.log.syslog=511]{.title-ref}.
- Type: Integer
- Default: LOG_USER
Defines the syslog facility that is used when ALERTs are logged to syslog. Depending on your system type (syslogd) the following facilities are available. Please check your system's include header if the values are the same for your syslogd.
| Constant | Value |
|---|---|
| LOG_KERN | 8 |
| LOG_USER | 9 |
| LOG_MAIL | 10 |
| LOG_DAEMON | 11 |
| LOG_AUTH | 12 |
| LOG_SYSLOG | 13 |
| LOG_LPR | 14 |
| LOG_NEWS | 15 |
| LOG_UUCP | 16 |
| LOG_CRON | 17 |
| LOG_AUTHPRIV | 18 |
| LOG_LOCAL0 | 24 |
| LOG_LOCAL1 | 25 |
| LOG_LOCAL2 | 26 |
| LOG_LOCAL3 | 27 |
| LOG_LOCAL4 | 28 |
| LOG_LOCAL5 | 29 |
| LOG_LOCAL6 | 30 |
| LOG_LOCAL7 | 31 |
- Type: Integer
- Default: LOG_ALERT
Defines the syslog priority that is used when ALERTs are logged to syslog. Depending on your system type (syslogd) the following priorities are available. Please check your system's include header if the values are the same for your syslogd.
| Constant | Value |
|---|---|
| LOG_EMERG | 0 |
| LOG_ALERT | 1 |
| LOG_CRIT | 2 |
| LOG_WARNING | 3 |
| LOG_NOTICE | 4 |
| LOG_INFO | 5 |
| LOG_DEBUG | 6 |
| LOG_ERR | 7 |
Type: Integer
- Default: 0
Defines what classes of security alerts are logged through the SAPI error log. For a list of available classes see table 1.
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value.
- Type: Integer
- Default: 0
Defines what classes of security alerts are logged through STDOUT. For a list of available classes see table 1.
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value.
IMPORTANT NOTE: This option is meant for debugging purposes and unittests only and should not be used in production.
- Type: Integer
- Default: 0
Defines what classes of security alerts are logged to a separate Suhosin log file set by suhosin.log.file.name.
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value.
- Type: String
- Default:
Defines the full path to a dedicated Suhosin log file.
- Type: Boolean
- Default: On
Specifies if suhosin.log.file contains timestamp for each log entry.
IMPORTANT NOTE: This option is meant for debugging purposes and unittests only and should not be used in production.
- Type: Integer
- Default: 0
Defines what classes of security alerts are logged through the external logging script. For a list of available classes see table 1. An exception is the S_MEMORY class. It cannot be logged by a script, because S_MEMORY is triggered by buffer overflows etc... which means the process is in an unstable state.
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value.
- Type: String
- Default:
Defines the full path to an external logging script. The script is called with 2 parameters. The first one is the alert class in string notation and the second parameter is the log message. This can be used for example to mail failing MySQL queries to your email address, because on a production system these things should never happen (S_SQL not yet supported by Suhosin).
- Type: Integer
- Default: 0
Defines what classes of security alerts are logged through the defined PHP script. For a list of available classes see table 1. Please notice, that only those classes are allowed, that can be triggered during script execution. An exception is the S_MEMORY class. It cannot be logged by a PHP script, because S_MEMORY is triggered by buffer overflows etc... which means the process is in an unstable state.
Using constant names is only supported with the Suhosin-Patch. If in doubt, use the numeric value.
- Type: String
- Default:
Defines the full path to a PHP logging script. The script is called with 2 variables registered in the current scope: SUHOSIN_ERRORCLASS and
is the log message. This can be used for example to mail attempted remote URL include attacks to your email address.
- Type: Boolean
- Default: Off
Disables open_basedir (and safe_mode for older PHP versions < 5.4) when executing suhosin.log.phpscript.name.
- Type: Boolean
- Default: Off
When the Suhosin logs an error the log message also contains the IP of the attacker. Usually this IP is retrieved from the REMOTE_ADDR SAPI environment variable. With this switch it is possible to change this behavior to read the IP from the X-Forwarded-For HTTP header. This is for example necessary when your PHP server runs behind a reverse proxy.
- Type: Integer
- Default: 750
Defines the maximum stack depth allowed by the executor before it stops the script. Without this function an endless recursion in a PHP script could crash the PHP executor or trigger the configured memory_limit. A value of '0' disables this feature.
(Before 0.9.37, the default value was 0.)
- Type: Integer
- Default: 0
Defines how many '../' an include filename needs to contain to be considered an attack and stopped. A value of '2' will block '../../etc/passwd', while a value of '3' will allow it. Most PHP applications should work flawlessly with values '4' or '5'. A value of '0' disables this feature.
- Type: String
- Default:
Comma separated whitelist of URL schemes that are allowed to be included from include or require statements. Additionally to URL schemes it is possible to specify the beginning of allowed URLs. (f.e.: php://stdin) If no whitelist is specified, then the blacklist is evaluated.
Notes:
- This setting deactivates suhosin.executor.include.blacklist.
- If both suhosin.executor.include.whitelist and suhosin.executor.include.blacklist are unset or empty, all URLs will be blocked. This is the default.
- Type: String
- Default:
Comma separated blacklist of URL schemes that are not allowed to be included from include or require statements. Additionally to URL schemes it is possible to specify the beginning of allowed URLs. (f.e.: php://stdin) If no blacklist and no whitelist is specified all URL schemes are forbidden.
- Type: Boolean
- Default: On
Turn this flag off to prevent PHP from executing writable PHP files. This can prevent attackers from executing code that was uploaded before.
Note: Some software such as web-installers or web-based plugin installers won't work out of the box with this flag turned off.
- Type: String
- Default:
Comma separated whitelist of functions that are allowed to be called. If the whitelist is empty the blacklist is evaluated, otherwise calling a function not in the whitelist will terminate the script and get logged.
Note: This setting deactivates suhosin.executor.func.blacklist.
- Type: String
- Default:
Comma separated blacklist of functions that are not allowed to be called. If no whitelist is given, calling a function within the blacklist will terminate the script and get logged.
- Type: String
- Default:
Comma separated whitelist of functions that are allowed to be called from within eval(). If the whitelist is empty the blacklist is evaluated, otherwise calling a function not in the whitelist will terminate the script and get logged. Please read the instructions carefully.
Note: This setting deactivates suhosin.executor.eval.blacklist.
- Type: String
- Default:
Comma separated blacklist of functions that are not allowed to be called from within eval(). If no whitelist is given, calling a function within the blacklist will terminate the script and get logged. Please read the instructions carefully.
- Type: Boolean
- Default: Off
eval() is a very dangerous statement and therefore you might want to disable it completely. Deactivating it will however break lots of scripts. Because every violation is logged, this allows finding all places where eval() is used.
- Type: Boolean
- Default: Off
The /e modifier inside preg_replace() allows code execution. Often it is the cause for remote code execution exploits. It is wise to deactivate this feature and test where in the application it is used. The developer using the /e modifier should be made aware that he should use preg_replace_callback() instead.
- Type: Boolean
- Default: Off
This flag reactivates symlink() when open_basedir is used, which is disabled by default in Suhosin >= 0.9.6. Allowing symlink() while open_basedir is used is actually a security risk.
- Type: Boolean
- Default: Off
If you fear that Suhosin breaks your application, you can activate
simulation mode, violations are logged as usual, but nothing is blocked or removed from the request. (Transparent Encryptions are NOT deactivated in simulation mode.)
- Type: String
- Default: "0"
Allow certain categories of config directives to be changed by .htaccess for each directory individually. Possible values are "l" (log), "e" (exec), "g" (get), "c" (cookie), "p" (post), "r" (request), "s" (sql), "u" (upload), "m" (misc) or any combination, e.g. "legcprsum" to allow everything. Both "0" and no value disable this feature.
- Type: Boolean
- Default: On
Prevent Suhosin's secret key material (suhosin.cookie.cryptkey,
phpinfo().
- Type: Boolean
- Default: Off
Controls if suhosin coredumps when the optional suhosin patch detects a buffer overflow, memory corruption or double free. This is only for debugging purposes and should not be activated.
- Type: Boolean
- Default: On
controls if suhosin loads in stealth mode when it is not the only zend_extension (Required for full compatibility with certain encoders that consider open source untrusted. e.g. ionCube, Zend)
- Type: Boolean
- Default: Off
APC 3.0.12(p1/p2) uses reserved resources without requesting a resource slot first. It always uses resource slot 0. If Suhosin got this slot assigned APC will overwrite the information Suhosin stores in this slot. When this flag is set Suhosin will request 2 Slots and use the second one. This allows working correctly with these buggy APC versions.
- Type: String
- Default: 0
Prevent PHP from setting display_errors programmatically. "0" means off. Any one of "1", "on", "yes", "true" means on. "fail" or "2" (or greater values) will let PHP know that the value change failed.
- Type: Boolean
- Default: Off
This directive controls if multiple headers are allowed or not in a header() call. By default the Suhosin forbids this. (HTTP headers spanning multiple lines are still allowed).
- Type: Integer
- Default: 0
This directive controls if the mail() header protection is activated or not and to what degree it is activated. The appended table lists the possible activation levels.
Value Description
0 mail() header protection is disabled
1 Disallows newlines in Subject:, To: headers and double newlines in additional headers
Logging of this class of alerts is controlled by the new S_MAIL constant.
- Type: Integer
- Default: 0
As long scripts are not running within safe_mode they are free to change the memory_limit to whatever value they want. Suhosin changes this fact and disallows setting the memory_limit to a value greater than the one the script started with, when this option is left at 0. A value greater than 0 means that Suhosin will disallow scripts setting the memory_limit to a value above this configured hard limit. This is for example useful if you want to run the script normally with a limit of 16M but image processing scripts may raise it to 20M.
This class of features is experimental and still in development. As of suhosin version 0.9.36 only preliminary MySQL and Mysqli support was added.
- Type: Boolean
- Default: Off
(Planned feature. This is not yet supported.) When an SQL Query fails scripts often spit out a bunch of useful information for possible attackers. When this configuration directive is turned on, the script will silently terminate, after the problem has been logged.
- Type: String
- Default:
(introduced in 0.9.37) The SQL username must match this wildcard pattern or the connect function will fail and return FALSE. Example: [suhosin.sql.user_match = public_*]{.title-ref}
- Type: String
- Default:
This is an experimental feature for shared environments. With this configuration option it is possible to specify a prefix that is automatically prepended to the database username, whenever a database connection is made. (Unless the username starts with the prefix)
With this feature it is possible for shared hosters to disallow customers to connect with the usernames of other customers. This feature is experimental, because support for PDO and PostgreSQL are not yet implemented.
- Type: String
- Default:
This is an experimental feature for shared environments. With this configuration option it is possible to specify a postfix that is automatically appended to the database username, whenever a database connection is made. (Unless the username end with the postfix)
With this feature it is possible for shared hosters to disallow customers to connect with the usernames of other customers. This feature is experimental, because support for PDO and PostgreSQL are not yet implemented.
- Type: Integer
- Default: 0
This is an experimental feature. Alert if an SQL query contains one or more comments starting with --, /* or #. A value of 1 logs the alert; 2 or greater let the call fail.
Note: Mysql conditional statements starting with /*! are exempt if
used with Mysqli.
- Type: Integer
- Default: 0
This is an experimental feature. Alert if a MySQL comment was started
but not closed: /* without */. A value of 1 logs the alert; 2 or
greater let the call fail.
- Type: Integer
- Default: 0
This is an experimental feature. Alert if an SQL query contains more than one SELECT statement. A value of 1 logs the alert; 2 or greater let the call fail.
Note: This flag will recognise multiple statements as well as subselects, e.g. "SELECT 1; SELECT 2" and "SELECT * FROM (SELECT 1)".
- Type: Integer
- Default: 0
This is an experimental feature. Alert if an SQL query contains one or more UNIONs. A value of 1 logs the alert; 2 or greater let the call fail.
- Type: Boolean
- Default: On
Flag that decides if the transparent session encryption is activated or not.
- Type: String
- Default:
Session data can be encrypted transparently. The encryption key used consists of this user defined string (which can be altered by a script via ini_set()) and optionally the User-Agent, the Document-Root and 0-4 octects of the REMOTE_ADDR.
- Type: Boolean
- Default: Off
Flag that decides if the transparent session encryption key depends on the User-Agent field. (When activated this feature transparently adds a little bit protection against session fixation/hijacking attacks)
- Type: Boolean
- Default: On
Flag that decides if the transparent session encryption key depends on the Documentroot field.
- Type: Integer
- Default: 0
Number of octets (0-4) from the REMOTE_ADDR that the transparent session encryption key depends on. Keep in mind that this should not be used on sites that have visitors from big ISPs, because their IP address often changes during a session. But this feature might be interesting for admin interfaces or intranets. When used wisely this is a transparent protection against session hijacking/fixation. This feature supports IPv4 only.
- Type: Integer
- Default: 0
Number of octets (0-4) from the REMOTE_ADDR that have to match to decrypt the session. The difference to suhosin.session.cryptaddr is, that the IP is not part of the encryption key, so that the same session can be used for different areas with different protection levels on the site. This feature supports IPv4 only.
- Type: Boolean
- Default: Off
Flag that decides if the transparent cookie encryption is activated or not.
- Type: String
- Default:
Cookies can be encrypted transparently. The encryption key used consists of this user defined string and optionally the User-Agent, the Document-Root and 0-4 octects of the REMOTE_ADDR.
- Type: Boolean
- Default: On
Flag that decides if the transparent session encryption key depends on the User-Agent field. (When activated this feature transparently adds a little bit protection against session fixation/hijacking attacks (if only session cookies are allowed))
- Type: Boolean
- Default: On
Flag that decides if the transparent cookie encryption key depends on the Documentroot field.
- Type: Integer
- Default: 0
Number of octets (0-4) from the REMOTE_ADDR that the transparent cookie encryption key depends on. Keep in mind that this should not be used on sites that have visitors from big ISPs, because their IP address often changes during a session. But this feature might be interesting for admin interfaces or intranets. When used wisely this is a transparent protection against session hijacking/fixation. This feature supports IPv4 only.
- Type: Integer
- Default: 0
Number of octets (0-4) from the REMOTE_ADDR that have to match to decrypt the cookie. The difference to suhosin.cookie.cryptaddr is, that the IP is not part of the encryption key, so that the same cookie can be used for different areas with different protection levels on the site. This feature supports IPv4 only.
- Type: String
- Default:
In case not all cookies are supposed to get encrypted this is a comma separated list of cookie names that should get encrypted. All other cookies will not get touched.
Note: Cookies handled on client side with JavaScript as well as on server side should not be encrypted, e.g. listed in
- Type: String
- Default:
In case some cookies should not be encrypted this is a comma separated list of cookies that do not get encrypted. All other cookies will be encrypted.
Note: This setting deactivates suhosin.cookie.cryptlist.
- Type: Mixed
- Default:
Defines the reaction of Suhosin on a filter violation. Following possible actions are supported
Type Description
Normal action is simply blocking the
variable from being registered
402 Do not execute the script and return a HTTP 402 response code
[302,]http://www.example.com Redirect to http://www.example.com instead of executing. Optionally set a specific HTTP response code
[402,]/var/scripts/badguy.php Execute a specific PHP script instead of the requested script. Optionally set a specific HTTP response code
- Type: Integer
- Default: 50
Defines the maximum depth an array variable may have, when registered through the COOKIE.
Note: Array depth is not the number of elements within an array.
- Type: Integer
- Default: 64
Defines the maximum length of array indices for variables registered through the COOKIE.
- Type: Integer
- Default: 64
Defines the maximum length of variable names for variables registered through the COOKIE. For array variables this is the name in front of the indices.
- Type: Integer
- Default: 256
Defines the maximum length of the total variable name when registered through the COOKIE. For array variables this includes all indices.
- Type: Integer
- Default: 10000
Defines the maximum length of a variable that is registered through the COOKIE.
- Type: Integer
- Default: 100
Defines the maximum number of variables that may be registered through the COOKIE.
- Type: Boolean
- Default: On
When set to On ASCIIZ chars are not allowed in variables.
- Type: Boolean
- Default: On
Ignore cookies with names starting with whitespace.
- Type: Integer
- Default: 50
Defines the maximum depth an array variable may have, when registered through the URL.
Note: Array depth is not the number of elements within an array.
- Type: Integer
- Default: 64
Defines the maximum length of array indices for variables registered through the URL.
- Type: Integer
- Default: 64
Defines the maximum length of variable names for variables registered through the URL. For array variables this is the name in front of the indices.
- Type: Integer
- Default: 256
Defines the maximum length of the total variable name when registered through the URL. For array variables this includes all indices.
- Type: Integer
- Default: 512
Defines the maximum length of a variable that is registered through the URL.
- Type: Integer
- Default: 100
Defines the maximum number of variables that may be registered through the URL.
- Type: Boolean
- Default: On
When set to On ASCIIZ chars are not allowed in variables.
- Type: Boolean
- Default: Off
Ignore GET parameters with names starting with whitespace.
- Type: Integer
- Default: 50
Defines the maximum depth an array variable may have, when registered through a POST request.
Note: Array depth is not the number of elements within an array.
- Type: Integer
- Default: 64
Defines the maximum length of array indices for variables registered through a POST request.
- Type: Integer
- Default: 64
Defines the maximum length of variable names for variables registered through a POST request. For array variables this is the name in front of the indices.
- Type: Integer
- Default: 256
Defines the maximum length of the total variable name when registered through a POST request. For array variables this includes all indices.
- Type: Integer
- Default: 1000000
Defines the maximum length of a variable that is registered through a POST request.
- Type: Integer
- Default: 1000
Defines the maximum number of variables that may be registered through a POST request.
- Type: Boolean
- Default: On
When set to On ASCIIZ chars are not allowed in variables.
- Type: Boolean
- Default: Off
Ignore POST parameters with names starting with whitespace.
- Type: String
- Default: "'"+<>;()"
Defines a character blacklist for array indices not allowed in user input.
Note: The default value also contained '-' in 0.9.37, which was removed in 0.9.37.1 due to incompatibility issues.
- Type: String
- Default:
- Example: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
Defines a character whitelist for array indices allowed in user input.
Note: This setting deactivates suhosin.request.array_index_blacklist.
- Type: Integer
- Default: 50
Defines the maximum depth an array variable may have, when registered through GET , POST or COOKIE. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.
Note: Array depth is not the number of elements within an array.
- Type: Integer
- Default: 64
Defines the maximum length of array indices for variables registered through GET, POST or COOKIE. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.
- Type: Integer
- Default: 256
Defines the maximum length of variable names for variables registered through the COOKIE, the URL or through a POST request. This is the complete name string, including all indices. This setting is also an upper limit for the separate GET, POST, COOKIE configuration directives.
- Type: Integer
- Default: 1000000
Defines the maximum length of a variable that is registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.
- Type: Integer
- Default: 1000
Defines the maximum number of variables that may be registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.
- Type: Integer
- Default: 64
Defines the maximum name length (excluding possible array indices) of variables that may be registered through the COOKIE, the URL or through a POST request. This setting is also an upper limit for the variable origin specific configuration directives.
- Type: Boolean
- Default: On
When set to On ASCIIZ chars are not allowed in variables.
- Type: Boolean
- Default: Off
Ignore all variables with names starting with whitespace.
- Type: Integer
- Default: 25
Defines the maximum number of files that may be uploaded with one request.
- Type: Integer
- Default: 100
Defines the maximum number of newlines in rfc1867 mime headers. (added with version 0.9.38)
- Type: Boolean
- Default: On
When set to On it is not possible to upload ELF executables.
- Type: Boolean
- Default: Off
When set to On it is not possible to upload binary files.
- Type: Boolean
- Default: Off
When set to On binary content is removed from the uploaded files.
- Type: Boolean
- Default: Off
This is an experimental feature. This option allows UTF-8 along with ASCII when using [suhosin.upload.disallow_binary]{.title-ref} or [suhosin.upload.remove_binary]{.title-ref}.
- Type: String
- Default:
This defines the full path to a verification script for uploaded files. The script gets the temporary filename supplied and has to decide if the upload is allowed. A possible application for this is to scan uploaded files for viruses. The called script has to write a 1 as first line to standard output to allow the upload. Any other value or no output at all will result in the file being deleted.
- Type: Integer
- Default: 128
Specifies the maximum length of the session identifier that is allowed. When a longer session identifier is passed a new session identifier will be created. This feature is important to fight buffer overflows in 3rd party session handlers.
- Type: Boolean
- Default: On
Encode potentially dangerous characters in REQUEST_URI and QUERY_STRING with URL encoding.
- Type: Boolean
- Default: On
Replace potentially dangerous characters in PHP_SELF, PATH_INFO, PATH_TRANSLATED and HTTP_USER_AGENT with '?'.
- Type: String
- Default:
This string is added to the entropy pool for seeding the random number generator.
- Type: Boolean
- Default: Off
Controls if automatic reseeding of rand() / mt_rand() is done for every new request. Will improve security but decrease performance. In case the system's entry pool is exhausted, this flag may either significantly increase execution time or otherwise use less entropy (which is bad).
- Type: Boolean
- Default: On
Flag that controls if calls to srand() are ignored in favour of suhosin.'s own enhanced seeding - since 0.9.36 calls will trigger auto-reseeding.
- Type: Boolean
- Default: On
Flag that controls if calls to mt_srand() are ignored in favour of suhosin.'s own enhanced seeding - since 0.9.36 calls will trigger auto-reseeding.