Rewrite Patrole README to be high-level document
This commit improves the Patrole README by making it a high-level
introduction to Patrole. Implementation-specific details have been
removed from the README; they will be included in greater detail
in the Patrole documentation in a follow-up commit.
Change-Id: I6a0b4a4ef8017df24a8b8465750dae21039b1afc
Depends-On: I4d468b7f1bb6a000fde42d656635159176d5ef7f
diff --git a/README.rst b/README.rst
index f5b4c00..949f9c0 100644
--- a/README.rst
+++ b/README.rst
@@ -5,174 +5,86 @@
.. image:: http://governance.openstack.org/badges/patrole.svg
:target: http://governance.openstack.org/reference/tags/index.html
-..
-
=========================================
Patrole - RBAC Integration Tempest Plugin
=========================================
-Patrole is a tool for verifying that Role-Based Access Control is being
-correctly enforced.
+Patrole is a security validation tool for verifying that Role-Based Access
+Control is correctly configured and enforced in a system. It runs Tempest-based
+API tests using specified RBAC roles, thus allowing deployments to verify that
+only intended roles have access to those APIs.
-Patrole allows users to run API tests using specified RBAC roles. This allows
-deployments to verify that only intended roles have access to those APIs.
-This is critical to ensure security, especially in large deployments with
-custom roles.
-
-* Free software: Apache license
-* Documentation: https://docs.openstack.org/developer/patrole
-* Source: https://git.openstack.org/cgit/openstack/patrole
-* Bugs: https://bugs.launchpad.net/patrole
+Patrole currently offers testing for the following OpenStack services: Nova,
+Neutron, Glance, Cinder and Keystone.
Features
-========
-Patrole offers RBAC testing for various OpenStack RBAC policies. It includes
-a decorator that wraps around tests which verifies that when the test calls the
-corresponding API endpoint, access is only granted for correct roles.
-
-Currently, Patrole supports policies contained in code and in policy.json files.
-If both exist, the policy actions in the policy.json are prioritized.
-
-Stable Interface
-----------------
-Patrole offers a stable interface that is guaranteed to be backwards compatible and
-can be directly consumed by other projects. Currently, rbac_exceptions.py and
-rbac_policy_parser.py are guaranteed to be stable.
-
-Release Versioning
-------------------
-`Patrole Release Notes <https://docs.openstack.org/releasenotes/patrole/>`_ show
-what changes have been released.
-
-.. _test-flows:
-
-Test Flows
-----------
-There are several possible test flows.
-
-If the ``rbac_test_role`` is allowed to access the endpoint:
-
-* The test passes if no 403 ``Forbidden`` or ``RbacActionFailed`` exception is raised.
-
-If the ``rbac_test_role`` is not allowed to access the endpoint:
-
-* If the endpoint returns a 403 `Forbidden` exception the test will pass.
-* If the endpoint returns successfully, then the test will fail with an
- ``RbacOverPermission`` exception.
-* If the endpoint returns something other than a 403 ``Forbidden`` to indicate
- that the role is not allowed, the test will raise an ``RbacActionFailed`` exception.
+--------
+* Validation of default policy definitions located in policy.json files.
+* Validation of in-code policy definitions.
+* Validation of custom policy file definitions that override default policy
+ definitions.
+* Built-in positive and negative testing. Positive and negative testing
+ are performed using the same tests and role-switching.
+* Valdation of custom roles as well as default OpenStack roles.
.. note::
- Certain services like Neutron *intentionally* raise a 404 instead of a 403
- for security concerns. Patrole accomodates this behavior by anticipating
- a 404 instead of a 403, using the ``expected_exception`` argument. For more
- information about Neutron's policy enforcement, see:
- `<https://docs.openstack.org/developer/neutron/devref/policy.html#request-authorization>`__.
+ Patrole does not yet support policy.yaml files, the new file format for
+ policy files in OpenStack.
How It Works
-============
-Patrole leverages oslo_policy (OpenStack's policy enforcement engine) to
-determine whether a given role is allowed to perform a policy action given a
-specific rule and OpenStack service. This is done before test execution inside
-the ``rbac_rule_validation.action`` decorator. Then, inside the test, the API
-that does policy enforcement for the same rule is called. The outcome is
-compared against the result from oslo_policy and a pass or fail is determined
-as outlined above: `Test Flows`_.
+------------
+Patrole leverages ``oslo.policy`` (OpenStack's policy enforcement engine) to
+determine whether a given role is allowed to perform a policy action, given a
+specific role and OpenStack service. The output from ``oslo.policy`` (the
+expected result) and the actual result from test execution are compared to
+each other: if both results match, then the test passes; else it fails.
-.. note::
+* Documentation: https://docs.openstack.org/developer/patrole
+* Bugs: https://bugs.launchpad.net/patrole
- Currently, Patrole does not support checking multiple rules against a single
- API call. Even though some APIs enforce multiple rules (some indirectly),
- it is increasingly difficult to maintain the tests if multiple policy
- actions are expected to be called.
+Quickstart
+==========
-Test Execution Workflow
------------------------
-The workflow is as follows:
+Tempest is a prerequisite for running Patrole. If you do not have Tempest
+installed, please reference the official Tempest documentation for guidance.
-#. Each test uses the ``rbac_rule_validation.action`` decorator, like below: ::
+Assuming Tempest is installed, the simplest way to configure Patrole is:
- @rbac_rule_validation.action(
- service="nova",
- rule="os_compute_api:servers:stop")
- @decorators.idempotent_id('ab4a17d2-166f-4a6d-9944-f17baa576cf2')
- def test_stop_server(self):
- # Set the primary credential's role to "rbac_test_role".
- self.rbac_utils.switch_role(self, toggle_rbac_role=True)
- # Call the API that enforces the policy action specified by "rule".
- self._test_stop_server()
+1. Open up the ``tempest.conf`` configuration file and include the following
+settings:
- The ``service`` attribute accepts an OpenStack service and the ``rule`` attribute
- accepts a valid OpenStack policy action, like "os_compute_api:servers:stop".
+.. code-block:: ini
-#. The ``rbac_rule_validation.action`` decorator passes these attributes,
- along with user_id and project_id information derived from the primary
- Tempest credential (``self.os.credentials.user_id`` and ``self.os.credentials.project_id``),
- to the ``rbac_policy_parser``.
+ [rbac]
+ enable_rbac = True
+ rbac_test_role = admin
-#. The logic in ``rbac_policy_parser`` then passes all this information along
- and the role in ``CONF.rbac.rbac_test_role`` to oslo_policy to determine whether
- the ``rbac_test_role`` is authorized to perform the policy action for the given
- service.
+These settings tell Patrole to run RBAC tests using the "admin" role (which
+is the default admin role in OpenStack) to verify the default policy
+definitions used by OpenStack services. Specifying a different role
+for ``rbac_test_role`` will run Patrole tests against that role. For additional
+information about Patrole's configuration settings, please refer to
+:ref:`patrole-configuration` and :ref:`patrole-sampleconf` for a sample
+configuration file.
-#. After all of the logic above has executed inside the rbac decorator, the
- test is executed. The test then sets up test-level resources, if necessary,
- with **admin** credentials implicitly. This is accomplished through
- ``rbac_utils.switch_role(toggle_rbac_role=False)``, which is done as part of
- client setup (inside the call to ``rbac_utils.RbacUtils``): ::
+2. You are now ready to run Patrole. To do so, you can use any testr-based test
+runner::
- @classmethod
- def setup_clients(cls):
- super(BaseV2ComputeRbacTest, cls).setup_clients()
- cls.auth_provider = cls.os_primary.auth_provider
- cls.rbac_utils = rbac_utils.RbacUtils(cls)
- ...
+ $ testr run patrole_tempest_plugin.tests.api
- This code has *already* executed when the test class is instantiated, because
- it is located in the base rbac test class. Whenever ``cls.rbac_utils.switch_role``
- is called, one of two behaviors are possible:
+or::
- #. The primary credential's role is changed to admin if ``toggle_rbac_role=False``
- #. The primary credential's role is changed to ``rbac_test_role`` if
- ``toggle_rbac_role=True``
+ $ ostestr --regex '(?!.*\[.*\bslow\b.*\])(^patrole_tempest_plugin\.tests\.api)'
- Thus, at the *beginning* of every test and during ``resource_setup`` and
- ``resource_cleanup``, the primary credential has the admin role.
+It is also possible to run Patrole using tox::
-#. After preliminary test-level setup is performed, like creating a server, a
- second call to ``self.rbac_utils.switch_role`` is done: ::
+ tox -eall-plugin -- patrole_tempest_plugin.tests.api
- self.rbac_utils.switch_role(cls, toggle_rbac_role=True)
+Release Versioning
+==================
+`Patrole Release Notes <https://docs.openstack.org/releasenotes/patrole/>`_
+shows which changes have been released for each version.
- Now the primary credential has the role specified by ``rbac_test_role``.
-
-#. The API endpoint in which policy enforcement of "os_compute_api:servers:stop"
- is performed can now be called.
-
- .. note:
-
- To determine whether a policy action is enforced, refer to the relevant
- controller code to make sure that the policy action is indeed enforced.
-
-#. Now that a call is made to "stop_server" with the primary credentials having
- the role specified by ``rbac_test_role``, either the nova contoller will allow
- or disallow the action to be performed. Since the "stop_server" policy action in
- nova is defined as "base.RULE_ADMIN_OR_OWNER", the API will most likely
- return a successful status code. For more information about this policy action,
- see `<https://github.com/openstack/nova/blob/master/nova/policies/servers.py>`__.
-
-#. As mentioned above, the result from the API call and the result from oslo_policy
- are compared for consistency.
-
-#. Finally, after the test has executed, but before ``tearDown`` or ``resource_cleanup``
- is called, ``self.rbac_utils.switch_role(cls, toggle_rbac_role=False)`` is
- called, so that the primary credential yet again has admin permissions for
- test clean up. This call is always performed in the "finally" block inside
- the ``rbac_rule_validation`` decorator.
-
-.. warning::
-
- Failure to call ``self.rbac_utils.switch_role(cls, toggle_rbac_role=True)``
- inside a test with the ``rbac_rule_validation`` decorator applied results
- in a ``RbacResourceSetupFailed`` being raised, causing the test to fail.
+Patrole's release versioning follows Tempest's conventions. Like Tempest,
+Patrole is branchless and uses versioning instead.