Grammar/Punctuation changes (#29)

5 files changed, 97 insertions, 99 deletions

diff --git a/doc/source/config.rst b/doc/source/config.rst
index 7170385..1b2ed09 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -2,33 +2,33 @@ Configuration
 =============
 
 Since PHP *ini-like* configuration model isn't flexible enough,
-Snuffleupagus is using its own format, in the file specified by
+Snuffleupagus is using its own format in the file specified by
 the directive ``sp.configuration_file`` (in your ``php.ini`` file),
 like ``sp.configuration_file=/etc/php/conf.d/snuffleupagus.ini``.
 
-Options are chainable by using dots (``.``), and string parameters
+Options are chainable by using dots (``.``) and string parameters
 **must** be quoted, while booleans and integers aren't.
 
 Comments are prefixed either with ``#``, or ``;``.
 
-Some rules applies in a specific ``function`` (context), on a specific ``variable``
-(data), like ``disable_functions``, others can only be enabled/disabled, like
+Some rules apply in a specific ``function`` (context) on a specific ``variable``
+(data), like ``disable_functions``. Others can only be enabled/disabled, like
 ``harden_random``.
 
 
 .. warning::
 
-  Careful, a wrongly configured Snuffleupagus might break your website.
-  It's up to you to understand its :doc:`features <features>`,
+  If you configure Snuffleupagus incorrectly, you could break your website.
+  It's up to you to understand the :doc:`features <features>`,
   read the present documentation about how to configure them,
-  evaluate your threat model, and write your configuration file accordingly.
+  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,
+whether or not they could 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
+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).
 
 Bugclass-killer features
@@ -70,12 +70,12 @@ It can either be ``enabled`` or ``disabled``.
 global
 ^^^^^^
 
-This configuration variable contain parameters that are used by other ones:
+This configuration variable contains parameters that are used by multiple functions:
 
 - ``secret_key``: A secret key used by various cryptographic features,
   like `cookies protection <features.html#session-cookie-stealing-via-xss>`__ or `unserialize protection <features.html#unserialize-related-magic>`__,
-  so do make sure that it's random and long enough.
-  You can generate it with something like this: ``head -c 256 /dev/urandom | tr -dc 'a-zA-Z0-9'``.
+  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'``.
 
 ::
 
@@ -86,10 +86,10 @@ unserialize_hmac
  * `default: disabled`
  * `more <features.html#unserialize-related-magic>`__
  
-``unserialize_hmac`` will add integrity check to ``unserialize`` calls, preventing
+``unserialize_hmac`` will add an integrity check to ``unserialize`` calls, preventing
 abritrary code execution in their context.
 
-It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
 
 ::
 
@@ -120,15 +120,15 @@ cookie_encryption
    
 .. warning::
 
-  To use this feature, you **must** set the :ref:`global.secret_key <config_global>` and
+  To use this feature, you **must** set the :ref:`global.secret_key <config_global>`
   and the :ref:`global.cookie_env_var <config_global>` variables.
-  This design decision prevents attacker from
+  This design decision prevents an attacker from
   `trivially bruteforcing <https://www.idontplaydarts.com/2011/11/decrypting-suhosin-sessions-and-cookies/>`_
   or re-using session cookies.
 
 ``cookie_secure`` will activate transparent encryption of specific cookies.
 
-It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
 
 ::
 
@@ -138,22 +138,22 @@ It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
 Choosing the proper environment variable
 """"""""""""""""""""""""""""""""""""""""
 
-It's up to you to chose a meaningul environment variable to derive the key from.
+It's up to you to choose a meaningful environment variable to derive the key from.
 Suhosin `is using <https://www.suhosin.org/stories/configuration.html#suhosin-session-cryptraddr>`_
 the ``REMOTE_ADDR`` one, tying the validity of the cookie to the IP address of the user;
 unfortunately, nowadays, people are `roaming <https://en.wikipedia.org/wiki/Roaming>`_ a lot on their smartphone,
-hopping from WiFi to 4G, …
+hopping from WiFi to 4G.
 
 This is why we recommend, if possible, to use the *extended master secret*
 from TLS connections (`RFC7627 <https://tools.ietf.org/html/rfc7627>`_)
-instead, to make the valitity of the cookie TLS-dependent, by using the ``SSL_SESSION_ID`` variable.
+instead. The will make the validity of the cookie TLS-dependent, by using the ``SSL_SESSION_ID`` variable.
 
 - In `Apache <https://httpd.apache.org/docs/current/mod/mod_ssl.html>`_,
-  it possible to enable by adding ``SSLOptions StdEnvVars`` in your Apache2 configuration.
+  it is possible to enable by adding ``SSLOptions StdEnvVars`` in your Apache2 configuration.
 - In `nginx <https://nginx.org/en/docs/http/ngx_http_ssl_module.html#variables>`_,
   you have to use ``fastcgi_param SSL_SESSION_ID $ssl_session_id if_not_empty;``.
 
-If you're not using TLS (you should.), you can always use the ``REMOTE_ADDR`` one,
+If you aren't using TLS (you should be), you can always use the ``REMOTE_ADDR`` one,
 or ``X-Real-IP`` if you're behind a reverse proxy.
 
 readonly_exec
@@ -162,7 +162,7 @@ readonly_exec
 
 ``readonly_exec`` will prevent the execution of writable PHP files.
 
-It can either be ``enabled`` or ``disabled``, and used in ``simulation`` mode.
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
 
 ::
 
@@ -174,7 +174,7 @@ upload_validation
  * `more <features.html#remote-code-execution-via-file-upload>`__
 
 ``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:
+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
@@ -185,10 +185,10 @@ This feature can be used, for example, to check if an uploaded file contains php
 code, with something like `vld <https://derickrethans.nl/projects.html#vld>`_
 (``php -d vld.execute=0 -d vld.active=1 -d extension=vld.so yourfile.php``).
 
-The upload will be **allowed** if the script return the value ``0``. Every other
+The upload will be **allowed** if the script returns 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.
+It can either be ``enabled`` or ``disabled`` and can be used in ``simulation`` mode.
 
 ::
 
@@ -210,8 +210,8 @@ disable_xxe
 Virtual-patching
 ----------------
 
-Snuffleupagus provides virtual-patching, via the ``disable_functions`` directive, allowing you to stop or control dangerous behaviours.
-Admitting you have a call to ``system()`` that lacks proper user-input validation, thus leading to an **RCE**, this might be the right tool.
+Snuffleupagus provides virtual-patching via the ``disable_functions`` directive, allowing you to stop or control dangerous behaviours.
+In the situation where you have a call to ``system()`` that lacks proper user-input validation, this could cause issues as it would lead to an **RCE**. The virtual-patching would allow this to be prevented.
 
 ::
    
@@ -219,7 +219,7 @@ Admitting you have a call to ``system()`` that lacks proper user-input validatio
   sp.disable_functions.function("system").filename("id.php").param("cmd").value("id").allow();
   sp.disable_functions.function("system").filename("id.php").drop()
 
-Of course, this is a trivial example, and a lot can be achieved with this feature, as you will see below.
+Of course, this is a trivial example,  a lot can be achieved with this feature, as you will see below.
 
 
 Filters
@@ -238,7 +238,7 @@ Filters
 - ``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(value)``: match on a literal ``value``
 - ``value_r(regexp)``: match on a value matching the ``regexp``
 - ``var(name)``: match on a **local variable** ``name``
 
@@ -267,22 +267,22 @@ Details
 
 The ``function`` filter is able to do various dereferencing:
 
-- ``function("AwesomeClass::my_method")`` will match in the method ``my_method`` in the class ``AwesomeClass``
-- ``function("AwesomeNamespace\\my_function")`` will match in the function ``my_function`` in the namespace ``AwesomeNamespace``
+- ``function("AwesomeClass::my_method")`` will match the method ``my_method`` in the class ``AwesomeClass``
+- ``function("AwesomeNamespace\\my_function")`` will match the function ``my_function`` in the namespace ``AwesomeNamespace``
 
 The ``param`` filter is also able to do some dereferencing:
 
-- ``param(foo[bar])`` will get match on the value corresponding to the ``bar`` key in the hashtable ``foo``.
+- ``param(foo[bar])`` will get a match on the value corresponding to the ``bar`` key in the hashtable ``foo``.
   Remember that in PHP, almost every data structure is a hashtable. You can of course nest this like
   ``param(foo[bar][baz][batman])``.
-- The ``var`` filter will walk the calltrace until it finds the variable's name, or the end of it,
-  allowing to match on global variables: ``.var("_GET[param]")`` will match on the GET parameter ``param``.
+- The ``var`` filter will walk the calltrace until it finds the variable name, or the end of the calltrace,
+  allowing the filter to match global variables: ``.var("_GET[param]")`` will match on the GET parameter ``param``.
 
-For clarity's sake, the presence of the ``allow`` or ``drop`` action is **mandatory**.
+For clarity, the presence of the ``allow`` or ``drop`` action is **mandatory**.
 
 .. warning::
 
-  When you're writing rules, please do keep in mind that the **order matters**.
+  When you're writing rules, please do keep in mind that **the order matters**.
   For example, if you're denying a call to ``system()`` and then allowing it in a
   more narrowed way later, the call will be denied,
   because it'll match the deny first.
diff --git a/doc/source/faq.rst b/doc/source/faq.rst
index 53d65ce..71326b6 100644
--- a/doc/source/faq.rst
+++ b/doc/source/faq.rst
@@ -8,19 +8,19 @@ What is Snuffleupagus?
 """"""""""""""""""""""
 
 Snuffleupagus is a `PHP7+ <http://php.net/manual/en/migration70.php>`_
-module designed to drastically raising the cost of attacks against website,
-by killing entire bug classes, and also providing a powerful virtual-patching system,
-allowing administrator to fix specific vulnerabilities without having to touch the PHP code.
+module designed to drastically raise the cost of attacks against websites. This is achieved
+by killing entire bug classes and providing a powerful virtual-patching system,
+allowing the administrator to fix specific vulnerabilities without having to touch the PHP code.
 
 
-Where does the name *Snuffeupagus* comes from?
+Where does the name *Snuffeupagus* come from?
 """"""""""""""""""""""""""""""""""""""""""""""
 
-  Aloysius Snuffleupagus, more commonly known as Mr. Snuffleupagus, Snuffleupagus
+  Aloysius Snuffleupagus, more commonly known as Mr. Snuffleupagus,
   or Snuffy for short, is one of the characters on Sesame Street,
   the educational television program for young children.
 
-  He was created as a woolly mammoth, without tusks or (visible) ears,
+  He was created as a woolly mammoth without tusks or (visible) ears,
   and has a long thick pointed tail, similar in shape to that of a dinosaur
   or other reptile. He has long thick brown hair and a trunk, or "snuffle",
   that drags along the ground. He is Big Bird's best friend and
@@ -43,9 +43,9 @@ 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 <https://grsecurity.net/>`_, `WAF <https://naxsi.org>`_,
-`IDS <https://en.wikipedia.org/wiki/Intrusion_detection_system>`_, …)
+`IDS <https://en.wikipedia.org/wiki/Intrusion_detection_system>`_, etc)
 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, …
+it's can be to send ads, spam, deface it, steal data etc.
 This is why we need to harden the website itself too, but we can't touch its
 source code.
 
@@ -62,7 +62,7 @@ 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
 the `system <https://secure.php.net/manual/en/function.system.php#refsect1-function.system-notes>`_
-function to perform various mandatory maintenance tasks…).
+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.
@@ -70,7 +70,7 @@ via virtual-patching support, and other cool new features.
 What license is Snuffleupagus under and why?
 """"""""""""""""""""""""""""""""""""""""""""
 
-Snuffleupagus is licensed under the `LGPL <https://www.gnu.org/copyleft/lesser.html>`_,
+Snuffleupagus is licensed under the `LGPL <https://www.gnu.org/copyleft/lesser.html>`_
 and is developed by the fine people from `NBS System <https://nbs-system.com/>`__.
 
 We chose the LGPL because we don't care that much how you're using Snuffleupagus,
@@ -92,22 +92,22 @@ it becomes compromised.
 How mature is this project?
 """""""""""""""""""""""""""
 
-This project was floating around since early 2016, and we did the first commit
+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 an alpha phase,
-finding and fixing as much bugs as possible before the beta.
+finding and fixing as many bugs as possible before the beta.
 
 Are you saying that PHP isn't secure?
 """""""""""""""""""""""""""""""""""""
 
 We don't like PHP's approach of security; namely (sometimes) adding warnings
 in the documentation and trusting the developer to not do any mistake,
-instead of focusing on the root cause, and killing the
-bug class one for all.
+instead of focusing on the root cause and killing the
+bug class once and for all.
 
 Moreover, it seems that the current attitude toward security in the PHP world
 is to `blame the user <https://externals.io/message/100147>`_ instead of acknowledging
 issues, as stated in their `documentation <https://wiki.php.net/security#not_a_security_issue>`_.
-We do think that an security issue that "requires the use of code or settings known to be insecure"
+We do think that a 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
@@ -133,12 +133,12 @@ Yes.
 
 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>`
+or overly-restrictive :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,
-to see what would snuffleupagus do to your application, before activating them for good.
+to see what snuffleupagus would do to your application, before activating them for good.
 
 How can I find out the problem when my application breaks?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""
diff --git a/doc/source/features.rst b/doc/source/features.rst
index c0fade3..3aab1a0 100644
--- a/doc/source/features.rst
+++ b/doc/source/features.rst
@@ -3,8 +3,8 @@ Features
 
 Snuffleupagus has a lot of features that can be divided in two main categories: bug-classes
 killers and virtual-patching. The first category provides primitives to kill various
-bug families (like arbitrary code execution via ``unserialize`` for example) or rise the
-cost of exploitation, the second one is a highly configurable system to patch functions in php itself.
+bug families (like arbitrary code execution via ``unserialize`` for example) or raise the
+cost of exploitation. The second category is a highly configurable system to patch functions in php itself.
 
 Bug classes killed or mitigated
 -------------------------------
@@ -12,9 +12,9 @@ Bug classes killed or mitigated
 ``system`` injections
 ^^^^^^^^^^^^^^^^^^^^^
 
-The ``system`` function execute an external program and displays the output.
-It's used to interract with various external tools, like file-format converters for example.
-Unfortunately, passing user-controlled parameters to it often leads to an arbitrary command execution.
+The ``system`` function executes an external program and displays the output.
+It is used to interact with various external tools, like file-format converters.
+Unfortunately, passing user-controlled parameters to it often leads to arbitrary command execution.
 
   When allowing user-supplied data to be passed to this function,
   use `escapeshellarg()` or `escapeshellcmd()` to ensure that users cannot trick
@@ -25,7 +25,7 @@ Unfortunately, passing user-controlled parameters to it often leads to an arbitr
 We're mitigating it by filtering the ``$``, ``|``, ``;``, `````, ``\n`` and ``&`` chars in our
 default configuration, making it a lot harder for an attacker to inject arbitrary commands.
 
-This family of vulnerabilities lead to various CVE, like:
+This family of vulnerabilities lead to various CVE entries, like:
 
 - `CVE-2017-7981 <https://tuleap.net/plugins/tracker/?aid=10159>`_: Authenticated remote code execution on Tuleap
 - `CVE-2014-4688 <https://www.pfsense.org/security/advisories/pfSense-SA-14_10.webgui.asc>`_: Authenticated remote code execution on pfSense
@@ -37,10 +37,10 @@ This family of vulnerabilities lead to various CVE, like:
 ``mail``-related injections
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This vulnerability is known `since 2011 <http://esec-pentest.sogeti.com/posts/2011/11/03/using-mail-for-remote-code-execution.html>`_,
+This vulnerability has been known `since 2011 <http://esec-pentest.sogeti.com/posts/2011/11/03/using-mail-for-remote-code-execution.html>`_
 and was popularized by `RIPS <https://www.ripstech.com/blog/2016/roundcube-command-execution-via-email/>`_ in 2016.
 The last flag of the `mail` function can be used to pass various parameters to
-the underlying binary used to send emails: this can lead to an arbitrary file write,
+the underlying binary used to send emails; this can lead to an arbitrary file write,
 often meaning an arbitrary code execution.
 
   The ``additional_parameters`` parameter can be used to pass additional flags
@@ -63,7 +63,7 @@ Session-cookie stealing via XSS
 The goto payload for XSS is often to steal cookies.
 Like *Suhosin*, we are encrypting the cookies with a secret key,
 an environment variable (usually the IP of the user)
-and its user-agent. This means that an attacker with an XSS won't be able to use
+and the user's user-agent. This means that an attacker with an XSS won't be able to use
 the stolen cookie, since he can't spoof the content of the value of the environment
 variable for the user. Please do read the :ref:`documentation about this feature <cookie-encryption_config>`
 if you're planning to use it.
@@ -81,10 +81,9 @@ library because of its portability, simplicity and reduced size (a single `.h` a
 Remote code execution via file-upload
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Some PHP applications allows users to upload contents, like avatars for a forum.
-Unfortunately, sometimes, content validation isn't implemented properly (if at all),
-meaning arbitrary file upload, often leading, contrary to what the documentation is saying,
-to an arbitrary code execution.
+Some PHP applications allows users to upload content like avatars to a forum.
+Unfortunately, content validation often isn't implemented properly (if at all),
+meaning arbitrary file upload often leads to an arbitrary code execution, contrary to the documentation.
 
   Not validating which file you operate on may mean that users can *access sensitive information* in other directories.
 
@@ -105,11 +104,11 @@ Unserialize-related magic
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
 PHP is able to *serialize* arbitrary objects, to easily store them.
-Unfortunately, it's often possible to gain arbitrary code execution upon deserialization
+Unfortunately, it is often possible to gain arbitrary code execution upon deserialization
 of user-supplied serialized objects.
 
   Do not pass untrusted user input to ``unserialize()`` regardless of the options value of allowed_classes.
-  Unserialization can result in code being loaded and executed due to object instantiation and autoloading,
+  Unserialization can result in code being loaded and executed due to object instantiation and autoloading
   and a malicious user may be able to exploit this.
 
   --- `The PHP documentation about serialize <https://secure.php.net/manual/en/function.serialize.php>`_
@@ -117,25 +116,25 @@ of user-supplied serialized objects.
 We're killing it by exploiting the fact that PHP will discard any garbage found at the end of a serialized object,
 allowing us to simply append a `HMAC <https://en.wikipedia.org/wiki/Hash-based_message_authentication_code>`_
 at the end of strings generated by the ``serialize``,
-hence guaranteeing that any object deserialized came from the application,
-and wasn't tampered with,
+hence guaranteeing that any object deserialized came from the application
+and wasn't tampered with.
 
-We're not encrypting it, like we do with the cookies,
+We aren't encrypting it, like we do with the cookies,
 allowing this feature to be disabled (or switch into leaning mode)
 without the need to invalidate any data.
 
 .. warning::
 
     This feature can't be deployed on websites that already stored serialized
-    objects (ie. in database), since they are missing the HMAC, and thus will be detected as
+    objects (ie. in database), since they are missing the HMAC and thus will be detected as
     an attack. If you're in this situation, you should use this feature with the
     ``simulation`` mode, and switch it off once you don't have any messages in your
     logs.
 
-A nice side-effect of this feature is that it'll defeat various memory corruption
+A nice side-effect of this feature is that it will defeat various memory corruption
 issues related to the complexity of ``unserialize``'s implementation,
 and the amount of control if provides to an attacker, like `CVE-2016-9137, CVE-2016-9138 <https://bugs.php.net/bug.php?id=73147>`_,
-`2016-7124 <https://bugs.php.net/bug.php?id=72663>`_, `CVE-2016-5771 and CVE-2016-5773 <https://www.evonide.com/how-we-broke-php-hacked-pornhub-and-earned-20000-dollar/>`_, …
+`2016-7124 <https://bugs.php.net/bug.php?id=72663>`_, `CVE-2016-5771 and CVE-2016-5773 <https://www.evonide.com/how-we-broke-php-hacked-pornhub-and-earned-20000-dollar/>`_.
 
 This family of vulnerabilities lead to various CVE, like:
 
@@ -155,8 +154,8 @@ Weak-PRNG via rand/mt_rand
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The functions ``rand`` and ``mt_rand`` are often used to generate random numbers used
-in sensitive context, like password generation, token creation, …
-Unfortunately, as said in the documentation, the quality of their entropy is low,
+in sensitive context, like password generation, token creation.
+Unfortunately, as stated in the documentation, the quality of their entropy is low,
 leading to the generation of guessable values.
 
   This function does not generate cryptographically secure values, and should not be used for cryptographic purposes.
@@ -195,16 +194,16 @@ XXE
 ^^^
 
 Despite the documentation saying nothing about this class of vulnerabilities,
-`XML eXternal Entitiy <https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing>`_  (XXE) are often leading to arbitrary file reading, SSRF, and sometimes even arbitrary
+`XML eXternal Entity <https://www.owasp.org/index.php/XML_External_Entity_(XXE)_Processing>`_  (XXE) often leads to arbitrary file reading, `SSRF <https://www.owasp.org/index.php/Server_Side_Request_Forgery>`_ and sometimes even arbitrary
 code execution.
 
 XML documents can contain a `Document Type Definition <https://www.w3.org/TR/REC-xml/#sec-prolog-dtd>`_ (DTD),
-enabling definition of XML entities. It's possible to define an (external) entity by an
-URI, that the parser will access, and embed its content back into the document
+enabling definition of XML entities. It is possible to define an (external) entity by a
+URI, that the parser will access and embed its content back into the document
 for further processing.
 
 For example, providing an url like ``file:///etc/passwd`` will read
-this file's content, and since it's not valid XML, the application
+the file's content. Since the file is not valid XML, the application
 will spit it out in an error message, thus leaking its content.
 
 We're killing this class of vulnerabilities by calling
@@ -212,7 +211,7 @@ the `libxml_disable_entity_loader <https://secure.php.net/manual/en/function.lib
 function with its parameter set to ``true`` at startup,
 and then *nop'ing* it, so it won't do anything if ever called again.
 
-This family of vulnerabilities lead to various CVE, like:
+This family of vulnerabilities lead to various CVE vulnerabilities, like:
 
 - `CVE-2015-5161 <https://legalhackers.com/advisories/eBay-Magento-XXE-Injection-Vulnerability.html>`_: Unauthenticated arbitrary file disclosure on Magento
 - `CVE-2014-8790 <https://github.com/GetSimpleCMS/GetSimpleCMS/issues/944>`_: Unauthenticated remote code execution in GetSimple CMS
@@ -245,14 +244,14 @@ Virtual-patching
 ^^^^^^^^^^^^^^^^
 
 PHP itself exposes a number of functions that might be considered **dangerous** and that have limited legitimate use cases.
-``system()``, ``exec()``, ``dlopen()`` - for example - fall into this category. By default, PHP only allows to globally disable some functions.
+``system()``, ``exec()``, ``dlopen()`` - for example - fall into this category. By default, PHP only allows us to globally disable some functions.
 
 
 However, (ie. ``system()``) they might have legitimate use cases in processes such as self upgrade etc., making it impossible to effectively
 disable them - at the risk of breaking critical features.
 
-SnuffleuPagus allows the user to restrict usage of specific functions per files, or per
-files with a matching (sha256) hash, thus allowing the use of such functions **only** in the intended places.
+Snuffleupagus allows the user to restrict usage of specific functions per file, or per
+file with a matching (sha256) hash, thus allowing the use of such functions **only** in the intended places.
 
 Furthermore, running the `following script <FIXME>`_  will generate an hash and line-based whitelist
 of dangerous functions, droping them everywhere else:
@@ -283,7 +282,7 @@ since every internal function from php has them.
 
 This option provide a switch to globally activate this strict mode,
 helping to uncover vulnerabilities like the classical
-`strcmp bypass <https://danuxx.blogspot.fr/2013/03/unauthorized-access-bypassing-php-strcmp.html>`_,
+`strcmp bypass <https://danuxx.blogspot.fr/2013/03/unauthorized-access-bypassing-php-strcmp.html>`_
 and various other types mismatch.
 
 This feature is largely inspired from the
@@ -297,7 +296,7 @@ If an attacker manages to upload an arbitrary file or to modify an existing one,
 odds are that (thanks to the default `umask <https://en.wikipedia.org/wiki/Umask>`_)
 this file is writable by the PHP process.
 
-Snuffleupagus can prevent the execution of this kind of files. A good practise
+Snuffleupagus can prevent the execution of this kind of file. A good practice
 would be to use a different user to run PHP than for administrating the website,
 and using this feature to lock this up.
 
@@ -321,9 +320,9 @@ various examples and ideas of things that you might want to enable (or not).
 Available functions recon
 """""""""""""""""""""""""
 
-After compromising a website, most of the time, the attacker does some recon
-within its webshell, to check which functions are available to execute arbitrary code,
-since it's not uncommon for some web-hoster to disable things like ``system`` or ``passthru``,
+Usually after compromising a website the attacker does some recon
+within its webshell, to check which functions are available to execute arbitrary code.
+Since it's not uncommon for some web-hosts to disable things like ``system`` or ``passthru``,
 or to check if mitigations are enabled, like ``open_basedir``.
 This behaviour can be detected by preventing the execution of functions like ``ini_get``
 or ``is_callable`` with *suspicious* parameters.
@@ -352,6 +351,6 @@ queries that contains some. The same filtering idea can be used against
 SQL functions that are frequently used in SQL injections, like ``sleep``, ``benchmark``
 or strings like ``version_info``.
 
-Still about SQL injections, if a function performing a query returns ``FALSE``
+On the topic of SQL injections, if a function performing a query returns ``FALSE``
 (indicating an error), it might be useful to dump the request for further analysis.
 
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 6de2fa8..9b91e18 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,11 +1,10 @@
 Snuffleupagus
 =============
 
-Snuffleupagus is a `PHP 7+ <https://secure.php.net/>`_ module designed to
-drastically raise the cost of attacks against website, by killing entire bug
-classes, and also providing a powerful virtual-patching system, allowing
-administrator to fix specific vulnerabilities and audit suspicious behaviours
-without having to touch the PHP code.
+Snuffleupagus is a `PHP7+ <http://php.net/manual/en/migration70.php>`_
+module designed to drastically raise the cost of attacks against websites. This is achieved
+by killing entire bug classes and providing a powerful virtual-patching system,
+allowing the administrator to fix specific vulnerabilities without having to touch the PHP code.
 
 Documentation
 -------------
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index fb68ccd..fb3e398 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -28,9 +28,9 @@ Quickstart
     make
     make install
 
-This should install ``snuffleupagus.so`` file in your extension directory.
-The final step is adding a load directive to ``php.ini``,
-and to specify the location of its :doc:`configuration file <config>`:
+This should install the ``snuffleupagus.so`` file in your extension directory.
+The final step is adding a load directive to ``php.ini``
+and to specify the location of the :doc:`configuration file <config>`:
 
 ::