Grammar/Punctuation changes (#29)

1 files changed, 36 insertions, 37 deletions

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.