Update a bit the configuration

4 files changed, 57 insertions, 34 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index b2af5f2..2ec387d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -57,7 +57,7 @@ author = u'Sebastien Blot & Julien Voisin'
 # The short X.Y version.
 version = u'0.1'
 # The full version, including alpha/beta/rc tags.
-release = u'Public Alpha'
+release = u'beta'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/source/config.rst b/doc/source/config.rst
index 7299fb1..760ae1b 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -13,6 +13,7 @@ Some rules applies in a specific ``function`` (context), on a specific ``variabl
 (data), like ``disable_functions``, others can only be enabled/disabled, like
 ``harden_random``.
 
+
 .. warning::
 
   Careful, a wrongly configured Snuffleupagus might break your website.
@@ -20,6 +21,11 @@ Some rules applies in a specific ``function`` (context), on a specific ``variabl
   read the present documentation about how to configure them,
   evaluate your threat model, and write your configuration file accordingly.
 
+Most of the features can be used in ``simulation`` mode by appending the
+``.simulation()`` option to them (eg. ``sp.readonly_exec.simulation()enable();``) to see
+if they might break your website. The simulation mode won't block the request,
+but will write a warning in the log.
+
 The rules are evaluated in the order that they are written, and the **first** one
 to match will terminate the evaluation (except for rules in simulation mode).
 
@@ -34,7 +40,7 @@ global_strict
 forcing PHP to throw a `TypeError <https://secure.php.net/manual/en/class.typeerror.php>`_
 exception if an argument type being passed to a function does not match its corresponding declared parameter type.
 
-It can either be ``enabled`` or ``disabled``
+It can either be ``enabled`` or ``disabled``.
 
 ::
 
@@ -81,6 +87,8 @@ unserialize_hmac
 ``unserialize_hmac`` will add integrity check to ``unserialize`` calls, preventing
 abritrary code execution in their context.
 
+It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
+
 ::
 
   sp.unserialize_hmac.enable();
@@ -116,7 +124,7 @@ cookie_encryption
 
 ``cookie_secure`` will activate transparent encryption of specific cookies.
 
-It can either be ``enabled`` or ``disabled``.
+It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
 
 ::
 
@@ -130,7 +138,7 @@ readonly_exec
 
 ``readonly_exec`` will prevent the execution of writable PHP files.
 
-It can either be ``enabled`` or ``disabled``.
+It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
 
 ::
 
@@ -156,6 +164,8 @@ code, with something like `vld <https://derickrethans.nl/projects.html#vld>`_
 The upload will be **allowed** if the script return the value ``0``. Every other
 value will prevent the file from being uploaded.
 
+It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
+
 ::
 
   sp.upload_validation.script("/var/www/is_valid_php.py").enable();
@@ -191,22 +201,22 @@ Of course, this is a trivial example, and a lot can be achieved with this featur
 Filters
 ^^^^^^^
 
-- ``alias(:str)``: human-readable description of the rule
-- ``cidr(ip/mask:str)``: match on the client's `cidr <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>`_
-- ``filename(name:str)``: match in the file ``name``
-- ``filename_r(regexp:str)``: the file name matching the ``regexp``
-- ``function(name:str)``: match on function ``name``
-- ``function_r(regexp:str)``: the function matching the ``regexp``
-- ``hash(:str)``: match on the file's `sha256 <https://en.wikipedia.org/wiki/SHA-2>`_ sum
-- ``param(name:str)``: match on the function's parameter ``name``
-- ``param_r(regexp:str)``: match on the function's parameter ``regexp``
-- ``param_type(type:str)``: match on the function's parameter ``type``
-- ``ret(value:str)``: match on the function's return ``value``
-- ``ret_r(regexp:str)``: match with a ``regexp`` on the function's return
-- ``ret_type(type_name:str)``: match on the ``type_name`` of the function's return value
-- ``value(:str)``: match on a litteral value
-- ``value_r(:regexp)``: match on a value matching the ``regexp``
-- ``var(name:str)``: match on a **local variable** ``name``
+- ``alias(description)``: human-readable ``description`` of the rule
+- ``cidr(ip/mask)``: match on the client's `cidr <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing>`_
+- ``filename(name)``: match in the file ``name``
+- ``filename_r(regexp)``: the file name matching the ``regexp``
+- ``function(name)``: match on function ``name``
+- ``function_r(regexp)``: the function matching the ``regexp``
+- ``hash(sha256)``: match on the file's `sha256 <https://en.wikipedia.org/wiki/SHA-2>`_ sum
+- ``param(name)``: match on the function's parameter ``name``
+- ``param_r(regexp)``: match on the function's parameter ``regexp``
+- ``param_type(type)``: match on the function's parameter ``type``
+- ``ret(value)``: match on the function's return ``value``
+- ``ret_r(regexp)``: match with a ``regexp`` on the function's return
+- ``ret_type(type_name)``: match on the ``type_name`` of the function's return value
+- ``value(value)``: match on a litteral ``value``
+- ``value_r(regexp)``: match on a value matching the ``regexp``
+- ``var(name)``: match on a **local variable** ``name``
 
 The ``type`` must be one of the following values:
 
@@ -225,7 +235,7 @@ Actions
 
 - ``allow()``: **allow** the request if the rule matches
 - ``drop()``: **drop** the request if the rule matches
-- ``dump(directory:str)``: dump the request in the ``directory`` if it matches the rule
+- ``dump(directory)``: dump the request in the ``directory`` if it matches the rule
 - ``simulation()``: enabled the simulation mode
 
 Details
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index cd9dfe3..09cb244 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -36,13 +36,14 @@ Like PHP's `ElePHPant <https://secure.php.net/elephpant.php>`_,
 we thought that using an elephant as a mascot would be a great idea.
 
 
-Why did you write Snuffleupagus?
-""""""""""""""""""""""""""""""""
+Who are you and why did you write Snuffleupagus?
+""""""""""""""""""""""""""""""""""""""""""""""""
 
 We're working for `NBS System <https://nbs-system.com/en/>`__,
 a web hosting company (meaning that we're dealing with PHP code all day long),
 with a strong focus on security. We do have hardening
-(kernel, `WAF <https://naxsi.org>`_, `IDS <https://en.wikipedia.org/wiki/Intrusion_detection_system>`_, …)
+(`kernel <https://grsecurity.net/>`_, `WAF <https://naxsi.org>`_,
+`IDS <https://en.wikipedia.org/wiki/Intrusion_detection_system>`_, …)
 below the web stack, but most of the time, when a website is compromised,
 it's either to send ads, spam, deface it, steal data, …
 This is why we need to harden the website itself too, but we can't touch its
@@ -60,7 +61,8 @@ We're huge fans of `Suhosin <https://suhosin.org>`_, unfortunately:
 
 We're using the `disable_function <https://secure.php.net/manual/en/ini.core.php#ini.disable-functions>`_
 directive, but unfortunately, it doesn't provide enough usable granularity (guess how many CMS are using
-``system`` to do various mandatory maintenance tasks…).
+the `system <https://secure.php.net/manual/en/function.system.php#refsect1-function.system-notes>`_
+function to perform various mandatory maintenance tasks…).
 
 This is why we decided to write our own hardening module, in the spirit of Suhosin,
 via virtual-patching support, and other cool new features.
@@ -91,8 +93,8 @@ How mature is this project?
 """""""""""""""""""""""""""
 
 This project was floating around since early 2016, and we did the first commit
-the 28ᵗʰ of December of the same year. We're currently in a private alpha phase,
-finding and fixing as much bugs as possible with the help of friends.
+the 28ᵗʰ of December of the same year. We're currently in an alpha phase,
+finding and fixing as much bugs as possible before the beta.
 
 Are you saying that PHP isn't secure?
 """""""""""""""""""""""""""""""""""""
@@ -108,6 +110,9 @@ issues, as stated in their `documentation <https://wiki.php.net/security#not_a_s
 We do think that an security issue that "requires the use of code or settings known to be insecure"
 is still a security issue, and should be treated as such.
 
+We don't have the pretention to state that Snuffleupagus will magically solve
+all your security issues, but we believe that it might definitely help.
+
 Installation and configuration
 ------------------------------
 
@@ -115,8 +120,10 @@ Can snuffleupagus break my application?
 """""""""""""""""""""""""""""""""""""""
 Yes.
 
-Some options won't break anything, like ``harden_rand``, but some like ``global_strict``
-or overly-restrictives virtual-patching rules might pretty well break your website.
+Some options won't break anything, like :ref:`harden-rand <harden-rand-feature>`,
+but some like :ref:`global_strict <global-strict-feature>`
+or overly-restrictives :ref:`virtual-patching<virtual-patching-feature>`
+rules might pretty well break your website.
 It's up to you to configure Snuffleupaggus accordingly to your needs.
 
 You can also enable the ``simulation`` mode on features that you're not sure about,
@@ -130,7 +137,7 @@ By checking the logs; Snuffleupagus systematically prefix them with ``[snuffleup
 
 Does Snuffleupagus run on Windows?
 """"""""""""""""""""""""""""""""""
-No idea.
+No idea, feel free to `try <https://github.com/nbs-system/snuffleupagus/issues/2>`_.
 
 
 Will Snuffleupagus run on my old PHP 5?
@@ -206,7 +213,7 @@ Where can I find even more help?
 """"""""""""""""""""""""""""""""
 The :doc:`configuration page <config>` might be what you're looking for.
 If you're adventurous, you can also check the `issue tracker <https://github.com/nbs-system/snuffleupagus/issues/?q=is%3Aissue>`_
-(make sure to check the closed issues too).
+(make sure to check the `closed issues <https://github.com/nbs-system/snuffleupagus/issues?q=is%3Aissue+is%3Aclosed>`_ too).
 
 I need professional support for my company.
 """""""""""""""""""""""""""""""""""""""""""
diff --git a/doc/source/features.rst b/doc/source/features.rst
index b06aa98..076e4e4 100644
--- a/doc/source/features.rst
+++ b/doc/source/features.rst
@@ -150,6 +150,7 @@ This family of vulnerabilities lead to various CVE, like:
 - `CVE-2012-5692 <https://www.rapid7.com/db/modules/exploit/unix/webapp/invision_pboard_unserialize_exec>`_: Unauthenticated remote code execution in IP.Board
 
 
+.. _harden-rand-feature:
 
 Weak-PRNG via rand/mt_rand
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -238,6 +239,9 @@ This behaviour is suggested in the documentation:
 Exploitation, post-exploitation and general hardening
 -----------------------------------------------------
 
+
+.. _virtual-patching-feature:
+
 Virtual-patching
 ^^^^^^^^^^^^^^^^
 
@@ -262,6 +266,8 @@ of dangerous functions, droping them everywhere else:
 The intent is to make post-exploitation process (such as backdooring of legitimate code, or RAT usage) a lot harder for the attacker.
 
 
+.. _global-strict-feature:
+
 Global strict mode
 ^^^^^^^^^^^^^^^^^^
 
@@ -300,7 +306,7 @@ and using this feature to lock this up.
 
 Dumping capabilities
 ^^^^^^^^^^^^^^^^^^^^
-It's possible to apply the ``dump(:str)`` filter to any virtual-patching rule,
+It's possible to apply the ``dump()`` filter to any virtual-patching rule,
 to dump the complete web request, along with the filename and the corresponding 
 line number. By using the *right* set of restrictive rules (or by using the
 *overly* restrictives ones in ``simulation`` mode), you might be able
@@ -335,8 +341,8 @@ Arbitrary file inclusion hardening
 """"""""""""""""""""""""""""""""""
 
 Arbitrary file inclusion is a common vulnerability, that might be detected
-by preventing the use of anything else than a whitelist of extensions in calls
-to ``include`` or ``require``.
+by preventing the inclusion of anything that doens't match a strict set
+of file extensions in calls to ``include`` or ``require``.
 
 *Cheap* SQL injections detection
 """"""""""""""""""""""""""""""""