Package: patrole
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 runsTempest-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.Free software: Apache licenseDocumentation:https://docs.openstack.org/patrole/latestSource:https://opendev.org/openstack/patroleBugs:https://storyboard.openstack.org/#!/project/openstack/patroleRelease notes:https://docs.openstack.org/releasenotes/patrole/Team and repository tagsDesign PrinciplesAs aTempest plugin, Patrole borrows some design principles fromTempest design principles,
but not all, as its testing scope is confined to policies.Stability. Patrole uses OpenStack public interfaces. Tests in Patrole
should only touch public OpenStack APIs.Atomicity. Patrole tests should be atomic: they should test policies in
isolation. Unlike Tempest, a Patrole test strives to only call a single
endpoint at a time. This is because it is important to validate each policy
is authorized correctly and the best way to do that is to validate each
policy alone, to avoid test contamination.Complete coverage. Patrole should validate all policy in code defaults. For
testing, Patrole uses the API-to-policy mapping contained in each project’spolicy in codedocumentation where applicable.For example, Nova’s policy in code documentation is located in theNova repositoryundernova/policies. Likewise, Keystone’s policy in
code documentation is located in theKeystone repositoryunderkeystone/common/policies. The other OpenStack services follow the same
directory layout pattern with respect to policy in code.NoteRealistically this is not always possible because some services have
not yet moved to policy in code.Customizable. Patrole should be able to validate custom policy overrides to
ensure that those overrides enhance rather than undermine the cloud’s RBAC
configuration. In addition, Patrole should be able to validate any role.Self-cleaning. Patrole should attempt to clean up after itself; whenever
possible we should tear down resources when done.NotePatrole modifies roles dynamically in the background, which affects
pre-provisioned credentials. Work is currently underway to clean up
modifications made to pre-provisioned credentials.Self-testing. Patrole should be self-testing.FeaturesValidation 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.NotePatrole does not yet support policy.yaml files, the new file format for
policy files in OpenStack.How It WorksPatrole leveragesoslo.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 fromoslo.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.TerminologyExpected Result - The expected result of a given test.Actual Result - The actual result of a given test.Final Result - A match between both expected and actual results. A mismatch
in the expected result and the actual result will result in a test failure.Expected: Pass | Actual: Pass - Test Case SuccessExpected: Pass | Actual: Fail - Test Case Under-Permission FailureExpected: Fail | Actual: Pass - Test Case Over-Permission FailureExpected: Fail | Actual: Fail (Expected exception) - Test Case SuccessExpected: Fail | Actual: Fail (Unexpected exception) - Test Case FailureQuickstartTo run Patrole, you must first haveTempestinstalled and configured
properly. Please referenceTempest_quickstartguide 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.NoteYou may also install Patrole from source code by running:pip install -e patrole/Next you must properly configure Patrole, which is relatively
straightforward. For details on configuring Patrole refer to thePatrole Configuration.Once the configuration is done you’re now ready to run Patrole. This can
be done using thetempest_runcommand. This can be done by running:$ tempest run --regex '^patrole_tempest_plugin\.tests\.api'There is also the option to use testr directly, or anytestrbased test
runner, likeostestr. For example, from the workspace dir run:$ 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 usingtox, but as Patrole needs access to
global packages use--sitepackagesargument. To do so,cdinto theTempestdirectory and run:$ tox -eall --sitepackages -- patrole_tempest_plugin.tests.apiNoteIt is possible to run Patrole viatox-eallin 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.apiLog information from tests is captured intempest.logunder the Tempest
repository. Some Patrole debugging information is captured in that log
related to expected test results andRole Overriding.More detailed RBAC testing log output is emitted topatrole.logunder
the Patrole repository. To configure Patrole’s logging, see thePatrole Configuration Guide.RBAC TestsTo change the roles that the patrole tests are being run as, editrbac_test_rolesin thepatrolesection of tempest.conf:[patrole]
rbac_test_roles = member,reader
...NoteTherbac_test_rolesis 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 withadminandmemberroles. However, other services may use entirely
different roles or role combinations.For more information about RBAC, reference therbac-overviewdocumentation page.For information regarding which projects Patrole offers RBAC testing for,
reference theHACKINGdocumentation page.Unit TestsPatrole 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 runBy setting--test-pathoption to./patrole_tempest_plugin/tests/unitit 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_roleOr all tests in the test_rbac_utils.py file:$ tox -e py27 -- -n patrole_tempest_plugin.tests.unit.test_rbac_utilsYou may also use regular expressions to run any matching tests:$ tox -e py27 -- test_rbac_utilsFor more information on these options and details about stestr, please see thestestr documentation.Release VersioningPatrole Release Notesshows 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.StoryboardBugs and enhancements are tracked via Patrole’sStoryboard Page.