docs: Add Patrole RBAC field guide
This documentation update adds a README.rst to
patrole_tempest_plugin/tests/api which explains the RBAC field
guide. It is modeled after Tempest's API field guide [0][1]. The
README.rst is then referenced in a new field_guide section
under doc/source/field_guide.
[0] 28b252f7f6/tempest/api
[1] https://docs.openstack.org/tempest/latest/field_guide/api.html#api-field-guide
Change-Id: I877ce4a1f681bd483c7f71b02fd7bb2b4d3b3e2a
This commit is contained in:
parent
1f2ba24f4d
commit
443d39c5a1
|
@ -9,9 +9,9 @@ Patrole - RBAC Integration Tempest Plugin
|
|||
=========================================
|
||||
|
||||
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.
|
||||
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 currently offers testing for the following OpenStack services: Nova,
|
||||
Neutron, Glance, Cinder and Keystone.
|
||||
|
@ -20,6 +20,8 @@ Patrole is currently undergoing heavy development. As more projects move
|
|||
toward policy in code, Patrole will align its testing with the appropriate
|
||||
documentation.
|
||||
|
||||
.. _Tempest: https://docs.openstack.org/tempest/latest/
|
||||
|
||||
Design Principles
|
||||
-----------------
|
||||
|
||||
|
|
|
@ -1,8 +1,8 @@
|
|||
.. _patrole-testing:
|
||||
.. _patrole-field-guide:
|
||||
|
||||
===============
|
||||
Patrole Testing
|
||||
===============
|
||||
============================
|
||||
Patrole Field Guide Overview
|
||||
============================
|
||||
|
||||
Testing Scope
|
||||
=============
|
||||
|
@ -14,6 +14,15 @@ endpoints are correctly using ``oslo.policy`` for authorization.
|
|||
|
||||
In other words, all tests in Patrole are RBAC tests.
|
||||
|
||||
:ref:`rbac_field_guide`
|
||||
=======================
|
||||
|
||||
RBAC tests are `Tempest`_-like API tests plus Patrole's
|
||||
:ref:`rbac-validation`. All Patrole tests are RBAC validation tests for the
|
||||
OpenStack API.
|
||||
|
||||
.. _Tempest: https://docs.openstack.org/tempest/latest/
|
||||
|
||||
Stable Tests
|
||||
============
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
.. _rbac_field_guide:
|
||||
|
||||
Patrole Field Guide to RBAC Tests
|
||||
=================================
|
||||
|
||||
|
||||
What are these tests?
|
||||
---------------------
|
||||
|
||||
Patrole's primary responsibility is to ensure that your OpenStack cloud
|
||||
has properly configured Role-Based Access Control (RBAC). All Patrole
|
||||
tests cases are devoted to this responsibility. Tempest API clients
|
||||
and utility functions are leveraged to accomplish this goal, but such
|
||||
functionality is secondary to RBAC validation.
|
||||
|
||||
Like Tempest, Patrole not only tests expected positive paths for RBAC
|
||||
validation, but also -- and more importantly -- negative paths. While
|
||||
Patrole could be thought of as validating RBAC, it more importantly
|
||||
verifies that your OpenStack cloud is secure from the perspective of
|
||||
RBAC (there are many gotchas when it comes to security, not just RBAC).
|
||||
|
||||
Negative paths are arguably more important than positive paths when it
|
||||
comes to RBAC and by extension security, because it is essential that
|
||||
your cloud be secure from unauthorized access. For example, while it is
|
||||
important to verify that the admin role has access to admin-level
|
||||
functionality, it is of critical importance to verify that non-admin roles
|
||||
*do not* have access to such functionality.
|
||||
|
||||
Unlike Tempest, Patrole accomplishes negative testing implicitly -- by
|
||||
abstracting it away in the background. Patrole dynamically determines
|
||||
whether a role should have access to an API depending on your cloud's
|
||||
policy configuration and then confirms whether that is true or false.
|
||||
|
||||
|
||||
Why are these tests in Patrole?
|
||||
-------------------------------
|
||||
|
||||
These tests constitute the core mission in Patrole: to verify RBAC. These
|
||||
tests are mainly intended to validate RBAC, but can also *unofficially*
|
||||
be used to discover the policy-to-API mapping for an OpenStack component.
|
||||
|
||||
It could be argued that some of these tests could be implemented in
|
||||
the projects themselves, but that approach has the following shortcomings:
|
||||
|
||||
* The projects do not validate RBAC from an integration testing perspective.
|
||||
* By extension, RBAC across cross-service communication is not usually
|
||||
validated.
|
||||
* The projects' tests do not pass all the metadata to ``oslo.policy`` that is
|
||||
in reality passed by the deployed server to that library to determine
|
||||
whether a given user is authorized to perform an API action.
|
||||
* The projects do not exhaustively do RBAC testing for all positive and
|
||||
negative paths.
|
||||
* Patrole is designed to work with any role via configuration settings, but
|
||||
on the other hand the projects handpick which roles to test.
|
||||
|
||||
|
||||
Scope of these tests
|
||||
--------------------
|
||||
|
||||
RBAC tests should always use the Tempest implementation of the
|
||||
OpenStack API, to take advantage of Tempest's stable library.
|
||||
|
||||
Each test should test a specific API endpoint and the related policy.
|
||||
|
||||
Each policy should be tested in isolation of one another -- or at least
|
||||
as close to this rule as possible -- to ensure proper validation of RBAC.
|
||||
|
||||
Each test should be able to work for positive and negative paths.
|
||||
|
||||
All tests should be able to be run on their own, not depending on the
|
||||
state created by a previous test.
|
|
@ -11,12 +11,27 @@ Patrole Configuration Guide
|
|||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
configuration
|
||||
usage
|
||||
testing
|
||||
sampleconf
|
||||
|
||||
Patrole Installation Guide
|
||||
--------------------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
installation
|
||||
|
||||
Field Guides
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
field_guide/index
|
||||
field_guide/rbac
|
||||
|
||||
Developer's Guide
|
||||
=================
|
||||
|
||||
|
|
Loading…
Reference in New Issue