feature #4651 Documented the security:check command (javiereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Documented the security:check command

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes
| Applies to    | all
| Fixed tickets | #4051

Commits
-------

897dc70 Added a lot of changes suggested by reviewers
fdfb1a0 Added a note about the SensioDistributionBundle necessary for security:check
3c9a962 Added a note about the security:check command
e552369 Added a missing link reference
0e7d0cd Added a note about the security advisories database
36d3f2b This command is available sin Symfony 2.5
7f3fb71 Documented the security:check command

book/installation.rst

@@ -287,6 +287,18 @@ them all at once:
 Depending on the complexity of your project, this update process can take up to
 several minutes to complete.
 
+.. tip::
+
+    Symfony provides a command to check whether your project's dependencies
+    contain any know security vulnerability:
+
+    .. code-block:: bash
+
+        $ php app/console security:check
+
+    A good security practice is to execute this command regularly to be able to
+    update or replace compromised dependencies as soon as possible.
+
 .. _installing-a-symfony2-distribution:
 
 Installing a Symfony Distribution

book/security.rst

@@ -1228,6 +1228,92 @@ cookie will be ever created by Symfony):
     If you use a form login, Symfony will create a cookie even if you set
     ``stateless`` to ``true``.
 
+Utilities
+---------
+
+.. versionadded:: 2.2
+    The ``StringUtils`` and ``SecureRandom`` classes were introduced in Symfony
+    2.2
+
+The Symfony Security component comes with a collection of nice utilities related
+to security. These utilities are used by Symfony, but you should also use
+them if you want to solve the problem they address.
+
+Comparing Strings
+~~~~~~~~~~~~~~~~~
+
+The time it takes to compare two strings depends on their differences. This
+can be used by an attacker when the two strings represent a password for
+instance; it is known as a `Timing attack`_.
+
+Internally, when comparing two passwords, Symfony uses a constant-time
+algorithm; you can use the same strategy in your own code thanks to the
+:class:`Symfony\\Component\\Security\\Core\\Util\\StringUtils` class::
+
+    use Symfony\Component\Security\Core\Util\StringUtils;
+
+    // is password1 equals to password2?
+    $bool = StringUtils::equals($password1, $password2);
+
+Generating a secure random Number
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Whenever you need to generate a secure random number, you are highly
+encouraged to use the Symfony
+:class:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom` class::
+
+    use Symfony\Component\Security\Core\Util\SecureRandom;
+
+    $generator = new SecureRandom();
+    $random = $generator->nextBytes(10);
+
+The
+:method:`Symfony\\Component\\Security\\Core\\Util\\SecureRandom::nextBytes`
+methods returns a random string composed of the number of characters passed as
+an argument (10 in the above example).
+
+The SecureRandom class works better when OpenSSL is installed but when it's
+not available, it falls back to an internal algorithm, which needs a seed file
+to work correctly. Just pass a file name to enable it::
+
+    $generator = new SecureRandom('/some/path/to/store/the/seed.txt');
+    $random = $generator->nextBytes(10);
+
+.. note::
+
+    You can also access a secure random instance directly from the Symfony
+    dependency injection container; its name is ``security.secure_random``.
+
+.. _book-security-checking-vulnerabilities:
+
+Checking for Known Security Vulnerabilities in Dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.5
+    The ``security:check`` command was introduced in Symfony 2.5. This command is
+    included in ``SensioDistributionBundle``, which has to be registered in your
+    application in order to use this command.
+
+When using lots of dependencies in your Symfony projects, some of them may
+contain security vulnerabilities. That's why Symfony includes a command called
+``security:check`` that checks your ``composer.lock`` file to find any known
+security vulnerability in your installed dependencies:
+
+.. code-block:: bash
+
+    $ php app/console security:check
+
+A good security practice is to execute this command regularly to be able to
+update or replace compromised dependencies as soon as possible. Internally,
+this command uses the public `security advisories database`_ published by the
+FriendsOfPHP organization.
+
+.. tip::
+
+    The ``security:check`` command terminates with a non-zero exit code if
+    any of your dependencies is affected by a known security vulnerability.
+    Therefore, you can easily integrate it in your build process.
+
 Final Words
 -----------
 
@@ -1256,3 +1342,4 @@ Learn more from the Cookbook
 
 .. _`online tool`: https://www.dailycred.com/blog/12/bcrypt-calculator
 .. _`frameworkextrabundle documentation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html
+.. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories

contributing/code/security.rst

@@ -38,6 +38,8 @@ confirmed, the core-team works on a solution following these steps:
 #. Publish the post on the official Symfony `blog`_ (it must also be added to
    the "`Security Advisories`_" category);
 #. Update the security advisory list (see below).
+#. Update the public `security advisories database`_ maintained by the
+   FriendsOfPHP organization and which is used by the ``security:check`` command.
 
 .. note::
 
@@ -93,6 +95,11 @@ of the downstream projects included in this process:
 Security Advisories
 -------------------
 
+.. tip::
+
+    You can check your Symfony application for known security vulnerabilities
+    using the ``security:check`` command. See :doc:`</book/security/checking-vulnerabilities>`
+
 This section indexes security vulnerabilities that were fixed in Symfony
 releases, starting from Symfony 1.0.0:
 
@@ -119,6 +126,7 @@ releases, starting from Symfony 1.0.0:
 * March 21, 2008: `symfony 1.0.12 is (finally) out ! <http://symfony.com/blog/symfony-1-0-12-is-finally-out>`_
 * June 25, 2007: `symfony 1.0.5 released (security fix) <http://symfony.com/blog/symfony-1-0-5-released-security-fix>`_
 
-.. _Git repository:      https://github.com/symfony/symfony
-.. _blog:                http://symfony.com/blog/
+.. _Git repository: https://github.com/symfony/symfony
+.. _blog: http://symfony.com/blog/
 .. _Security Advisories: http://symfony.com/blog/category/security-advisories
+.. _`security advisories database`: https://github.com/FriendsOfPHP/security-advisories