Patrole 0.12.0 has been released . This commit adds a new page for 0.12.0 release notes.  https://review.opendev.org/c/openstack/releases/+/783115 Change-Id: Ibbb1000d633372e2ca37b306fec3c284059905ba
|1 month ago|
|devstack||6 months ago|
|doc||12 months ago|
|etc||2 years ago|
|patrole_tempest_plugin||2 months ago|
|releasenotes||1 month ago|
|.coveragerc||4 years ago|
|.gitignore||2 years ago|
|.gitreview||2 years ago|
|.mailmap||4 years ago|
|.stestr.conf||3 years ago|
|.zuul.yaml||4 months ago|
|CONTRIBUTING.rst||1 year ago|
|HACKING.rst||1 year ago|
|LICENSE||4 years ago|
|README.rst||2 years ago|
|REVIEWING.rst||1 year ago|
|babel.cfg||4 years ago|
|lower-constraints.txt||9 months ago|
|requirements.txt||3 years ago|
|setup.cfg||1 year ago|
|setup.py||1 year ago|
|test-requirements.txt||9 months ago|
|tox.ini||2 months ago|
Patrole is a set of integration tests to be run against a live OpenStack cluster. It has a battery of tests dedicated to validating the correctness and integrity of the cloud's RBAC implementation.
More importantly, Patrole is a security validation tool for verifying that Role-Based Access Control is correctly configured and enforced in an OpenStack cloud. 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 is currently undergoing heavy development. As more projects move toward policy in code, Patrole will align its testing with the appropriate documentation.
Complete coverage. Patrole should validate all policy in code defaults. For testing, Patrole uses the API-to-policy mapping contained in each project's policy in code documentation where applicable.
For example, Nova's policy in code documentation is located in the Nova repository under
nova/policies. Likewise, Keystone's policy in code documentation is located in the Keystone repository under
keystone/common/policies. The other OpenStack services follow the same directory layout pattern with respect to policy in code.
Realistically this is not always possible because some services have not yet moved to policy in code.
Self-cleaning. Patrole should attempt to clean up after itself; whenever possible we should tear down resources when done.
Patrole modifies roles dynamically in the background, which affects pre-provisioned credentials. Work is currently underway to clean up modifications made to pre-provisioned credentials.
Patrole does not yet support policy.yaml files, the new file format for policy files in OpenStack.
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.
To run Patrole, you must first have Tempest installed and configured properly. Please reference Tempest_quickstart guide to do so. Follow all the steps outlined therein. Afterward, proceed with the steps below.
You first need to install Patrole. This is done with pip after you check out the Patrole repo:
$ git clone https://opendev.org/openstack/patrole $ pip install patrole/
This can be done within a venv.
You may also install Patrole from source code by running:
pip install -e patrole/
Once the configuration is done you're now ready to run Patrole. This can be done using the tempest_run command. This can be done by running:
$ tempest run --regex '^patrole_tempest_plugin\.tests\.api'
$ stestr --regex '(?!.*\[.*\bslow\b.*\])(^patrole_tempest_plugin\.tests\.api))'
will run the same set of tests as the default gate jobs.
You can also run Patrole tests using tox, but as Patrole needs access to global packages use
--sitepackages argument. To do so,
cd into the Tempest directory and run:
$ tox -eall --sitepackages -- patrole_tempest_plugin.tests.api
It is possible to run Patrole via
tox -eall in order to run Patrole isolated from other plugins. This can be accomplished by including the installation of services that currently use policy in code -- for example, Nova and Keystone. For example:
$ tox -evenv-tempest -- pip install /opt/stack/patrole /opt/stack/keystone /opt/stack/nova $ tox -eall -- patrole_tempest_plugin.tests.api
Log information from tests is captured in
tempest.log under the Tempest repository. Some Patrole debugging information is captured in that log related to expected test results and Role Overriding.
More detailed RBAC testing log output is emitted to
patrole.log under the Patrole repository. To configure Patrole's logging, see the Patrole Configuration Guide.
To change the roles that the patrole tests are being run as, edit
rbac_test_roles in the
patrole section of tempest.conf: :
[patrole] rbac_test_roles = member,reader ...
rbac_test_roles is service-specific. member, for example, is an arbitrary role, but by convention is used to designate the default non-admin role in the system. Most Patrole tests should be run with admin and member roles. However, other services may use entirely different roles or role combinations.
For more information about RBAC, reference the rbac-overview documentation page.
For information regarding which projects Patrole offers RBAC testing for, reference the HACKING documentation page.
Patrole also has a set of unit tests which test the Patrole code itself. These tests can be run by specifying the test discovery path:
$ stestr --test-path ./patrole_tempest_plugin/tests/unit run
--test-path option to
./patrole_tempest_plugin/tests/unit it specifies that test discovery should only be run on the unit test directory.
Alternatively, there are the py27 and py35 tox jobs which will run the unit tests with the corresponding version of Python.
One common activity is to just run a single test; you can do this with tox simply by specifying to just run py27 or py35 tests against a single test:
$ tox -e py27 -- -n patrole_tempest_plugin.tests.unit.test_rbac_utils.RBACUtilsTest.test_override_role_with_missing_admin_role
Or all tests in the test_rbac_utils.py file:
$ tox -e py27 -- -n patrole_tempest_plugin.tests.unit.test_rbac_utils
You may also use regular expressions to run any matching tests:
$ tox -e py27 -- test_rbac_utils
For more information on these options and details about stestr, please see the stestr documentation.
Patrole Release Notes shows which changes have been released for each version.
Patrole's release versioning follows Tempest's conventions. Like Tempest, Patrole is branchless and uses versioning instead.
Bugs and enhancements are tracked via Patrole's Storyboard Page.