From 3040b02639bd71dbcd936311546ef9296165aea5 Mon Sep 17 00:00:00 2001 From: jvoisin Date: Tue, 26 Sep 2017 17:57:30 +0200 Subject: Update a bit the configuration --- doc/source/conf.py | 2 +- doc/source/config.rst | 50 +++++++++++++++++++++++++++++-------------------- doc/source/faq.rst | 27 ++++++++++++++++---------- doc/source/features.rst | 12 +++++++++--- 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 `_ 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 `_ 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 `_ -- ``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 `_ 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 `_ +- ``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 `_ 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 `_, 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 `__, 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 `_, `IDS `_, …) +(`kernel `_, `WAF `_, +`IDS `_, …) 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 `_, unfortunately: We're using the `disable_function `_ 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 `_ +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 `, +but some like :ref:`global_strict ` +or overly-restrictives :ref:`virtual-patching` +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 `_. Will Snuffleupagus run on my old PHP 5? @@ -206,7 +213,7 @@ Where can I find even more help? """""""""""""""""""""""""""""""" The :doc:`configuration page ` might be what you're looking for. If you're adventurous, you can also check the `issue tracker `_ -(make sure to check the closed issues too). +(make sure to check the `closed issues `_ 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 `_: 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 """""""""""""""""""""""""""""""" -- cgit v1.3