From 44255b8dbf5c98c8d110c2e3918298ee6978b93c Mon Sep 17 00:00:00 2001 From: jvoisin Date: Fri, 12 Jan 2018 12:09:52 +0100 Subject: Massive overhaul of the documentation --- doc/source/config.rst | 105 ++++++++++++++++++++++++------------------------ doc/source/features.rst | 19 ++++++--- 2 files changed, 67 insertions(+), 57 deletions(-) (limited to 'doc/source') diff --git a/doc/source/config.rst b/doc/source/config.rst index 85e9da5..9244668 100644 --- a/doc/source/config.rst +++ b/doc/source/config.rst @@ -34,14 +34,34 @@ but will write a warning in the log. The rules are evaluated in the order that they are written, the **first** one to match will terminate the evaluation (except for rules in simulation mode). + +Miscellaneous +------------- + +global +^^^^^^ + +This configuration variable contains parameters that are used by multiple features: + +- ``secret_key``: A secret key used by various cryptographic features, + like `cookies protection `__ or `unserialize protection `__, + please ensure the length and complexity is sufficient. + You can generate it with functions such as: ``head -c 256 /dev/urandom | tr -dc 'a-zA-Z0-9'``. + +:: + + sp.global.secret_key("44239bd400aa82e125337c9d4eb8315767411ccd"); + +- ``cookie_env_var``: A environment variable used as part of cookies encryption. + See the :ref:`relevant documentation `. + Bugclass-killer features ------------------------ global_strict ^^^^^^^^^^^^^ -`default: disabled` -``global_strict`` will enable the `strict `_ mode globally, +:ref:`global_strict `, disabled by default, will enable the `strict `_ mode globally, forcing PHP to throw a `TypeError `_ exception if an argument type being passed to a function does not match its corresponding declared parameter type. @@ -54,12 +74,13 @@ It can either be ``enabled`` or ``disabled``. harden_random ^^^^^^^^^^^^^ - * `default: enabled` - * `more `__ -``harden_random`` will silently replace the insecure `rand `_ -and `mt_rand `_ functions with -the secure PRNG `random_int `_. +:ref:`harden_random `, enabled by default, will silently +replace the insecure `rand +`_ and `mt_rand +`_ functions with the +secure PRNG `random_int +`_. It can either be ``enabled`` or ``disabled``. @@ -70,27 +91,12 @@ It can either be ``enabled`` or ``disabled``. .. _config_global: -global -^^^^^^ - -This configuration variable contains parameters that are used by multiple functions: - -- ``secret_key``: A secret key used by various cryptographic features, - like `cookies protection `__ or `unserialize protection `__, - please ensure the length and complexity is sufficient. - You can generate it with functions such as: ``head -c 256 /dev/urandom | tr -dc 'a-zA-Z0-9'``. - -:: - - sp.global.secret_key("44239bd400aa82e125337c9d4eb8315767411ccd"); - unserialize_hmac ^^^^^^^^^^^^^^^^ - * `default: disabled` - * `more `__ -``unserialize_hmac`` will add an integrity check to ``unserialize`` calls, preventing -abritrary code execution in their context. +:ref:`unserialize_hmac `, disabled by default, will add an +integrity check to ``unserialize`` calls, preventing arbitrary code execution +in their context. It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode. @@ -102,11 +108,11 @@ It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` m auto_cookie_secure ^^^^^^^^^^^^^^^^^^ - * `default: disabled` - * `more `__ -``auto_cookie_secure`` will automatically mark cookies as `secure `_ -when the web page is requested over HTTPS. +:ref:`auto_cookie_secure `, disabled by default, +will automatically mark cookies as `secure +`_ when the web page +is requested over HTTPS. It can either be ``enabled`` or ``disabled``. @@ -117,11 +123,12 @@ It can either be ``enabled`` or ``disabled``. cookie_samesite ^^^^^^^^^^^^^^^^ - * `default: disabled` -``samesite`` will add the `samesite `_ -attribute to cookies. It `prevents CSRF `_ -but is not implemented by `all web browsers `_ yet. +:ref:`samesite `, disabled by default, will add the `samesite +`_ attribute to +cookies. It `prevents CSRF `_ but is +not implemented by `all web browsers `_ +yet. It can either be set to ``strict`` or ``lax``: @@ -139,9 +146,6 @@ It can either be set to ``strict`` or ``lax``: cookie_encryption ^^^^^^^^^^^^^^^^^ - - * `default: disabled` - * `more `__ .. warning:: @@ -151,7 +155,7 @@ cookie_encryption `trivially bruteforcing `_ or re-using session cookies. -``cookie_secure`` will activate transparent encryption of specific cookies. +:ref:`cookie_secure `, disabled by default, will activate transparent encryption of specific cookies. It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode. @@ -174,6 +178,8 @@ it to your php process. We think that this use case is too exotic to be worth implementing as a proper configuration directive. +.. _env-var-config: + Choosing the proper environment variable """""""""""""""""""""""""""""""""""""""" @@ -197,9 +203,9 @@ or ``X-Real-IP`` if you're behind a reverse proxy. readonly_exec ^^^^^^^^^^^^^ - * `default: disabled` -``readonly_exec`` will prevent the execution of writable PHP files. +:ref:`readonly_exec `, disabled by default, will prevent +the execution of writeable PHP files. It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode. @@ -209,11 +215,10 @@ It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` m upload_validation ^^^^^^^^^^^^^^^^^ - * `default: disabled` - * `more `__ -``upload_validation`` will call a given script upon a file upload, with the path -to the file being uploaded as argument and various information about it in the environment: +:ref:`upload_validation `, disabled by default, will call a +given script upon a file upload, with the path to the file being uploaded as +argument and various information about it in the environment: * ``SP_FILENAME``: the name of the uploaded file * ``SP_FILESIZE``: the size of the file being uploaded @@ -236,10 +241,8 @@ It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` m disable_xxe ^^^^^^^^^^^ - * `default: enabled` - * `more `__ -``disable_xxe`` will prevent XXE attacks by disabling the loading of external entities (``libxml_disable_entity_loader``) in the XML parser. +:ref:`disable_xxe `, enabled by default, will prevent XXE attacks by disabling the loading of external entities (``libxml_disable_entity_loader``) in the XML parser. :: @@ -248,12 +251,10 @@ disable_xxe Eval white and blacklist ^^^^^^^^^^^^^^^^^^^^^^^^ - * `default: disabled` - * :ref:`more ` -``eval_whitelist`` and ``eval_blacklist`` allow to respectively specify -functions allowed and forbidden from being called inside ``eval``. The -functions names are comma-separated. +:ref:`eval_whitelist and eval_blacklist `, disabled by default, +allow to respectively specify functions allowed and forbidden from being called +inside ``eval``. The functions names are comma-separated. :: @@ -366,7 +367,7 @@ It's currently not possible to: - Hook every `language construct `__, because each of them requires a specific implementation. - Hook on the return value of user-defined functions -- Use extra-convoluted rulesfor matching, like ``${$A}$$B->${'}[1]``, because if you're writing +- Use extra-convoluted rules for matching, like ``${$A}$$B->${'}[1]``, because if you're writing things like this, odds are that you're doing something wrong anyway. diff --git a/doc/source/features.rst b/doc/source/features.rst index 86b81fd..24c5074 100644 --- a/doc/source/features.rst +++ b/doc/source/features.rst @@ -61,6 +61,8 @@ Examples of related vulnerabilities - `CVE-2016-10033 `_: remote code execution in PHPMailer - `CVE-2016-9920 `_: Unauthenticated remote code execution in Roundcube +.. _cookie-encryption-feature: + Session-cookie stealing via XSS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -82,6 +84,9 @@ thus using curve25519, xsalsa20 and poly1305 for the encryption. We chose this library because of its portability, simplicity and reduced size (a single `.h` and `.c` file.). + +.. _fileupload-feature: + Remote code execution via file-upload ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -114,6 +119,8 @@ Examples of related vulnerabilities - `EDB-19154 `_: Authenticated remote code execution in qdPM +.. _unserialize-feature: + Unserialize-related magic ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -191,11 +198,6 @@ It's worth noting that the PHP documentation contains the following warning: This is of course addressed as well by the ``harden_rand`` feature. -.. warning:: - - Activating this feature will raise an `Error `_ - exception if ``min`` is superior to ``max``, while the default dehaviour is simply to swap them. - Examples of related vulnerabilities """"""""""""""""""""""""""""""""""" @@ -209,6 +211,8 @@ Examples of related vulnerabilities - `CVE-2008-4102 `_: Unauthenticated accounts takeover in Joomla - `CVE-2006-0632 `_: Unauthenticated account takeover in phpBB +.. _xxe-feature: + XXE ^^^ @@ -239,6 +243,8 @@ Examples of related vulnerabilities - `CVE-2011-4107 `_: Authenticated local file disclosure in PHPMyAdmin +.. _auto-cookie-secure-feature: + Cookie stealing via HTTP MITM ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -313,6 +319,8 @@ This feature is largely inspired from the `autostrict `_ module from `krakjoe `__. +.. _readonly-exec-feature: + Preventing execution of writable PHP files ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -337,6 +345,7 @@ it's broadly (mis)used all around the web. Snuffleupagus provides a white and blacklist mechanism, to explicitly allow and forbid specific functions call from being issued inside ``eval``. +.. _samesite-feature: Protection against cross site request forgery ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.3