Patrole project is not active anymore and its gate is broken.
We waited for couple of cycle to see if there is any interest
in this project and anyone can maintain it. But we did not get any
new maintainers and current QA team does not have bandwidth/interest
to continue maintaining it.
This project was for RBAc testing which is moving towards unit/functional
tests on service side as well as tempest plugins tests.
In QA 2023.2 PTG, we decided to retire this project
- https://etherpad.opendev.org/p/qa-bobcat-ptg
Change-Id: I7721cf06104e5871ec27cdd87d4608dace60a8b7
Switch to openstackdocstheme 2.2.0 and reno 3.1.0 versions. Using
these versions will allow especially:
* Linking from HTML to PDF document
* Allow parallel building of documents
* Fix some rendering problems
Update Sphinx version as well.
Remove docs requirements from lower-constraints, they are not needed
during install or test but only for docs building.
openstackdocstheme renames some variables, so follow the renames
before the next release removes them. A couple of variables are also
not needed anymore, remove them.
Set openstackdocs_pdf_link to link to PDF file. Note that
the link to the published document only works on docs.openstack.org
where the PDF file is placed in the top-level html directory. The
site-preview places the PDF in a pdf directory.
Set openstackdocs_auto_name to use 'project' as name.
Change-Id: I80932c070dbddf9a75f64b0a4d4c614efd5a06ff
This repo is now testing only with Python 3, so let's make
a few cleanups:
- Remove python 2.7 stanza from setup.py
- Remove obsolete sections from setup.cfg
- Update classifiers
- Use newer openstackdocstheme and Sphinx versions
- Cleanup */source/conf.py to remove now obsolete content.
- Remove install_command from tox.ini, the default is fine
- Remove hacking requirements from lower-constraints, they
are not needed for install
Change-Id: I150a5ee2cd08abf5ce9cf9daf2835007dea0dffd
This commit add PDF building tox.ini environment and options for LaTeX
output. The chapter header in README.rst has been changed because "Team
and repository tags" is not appropriate for the title of this document.
And, this commit also updates repository URLs to opendev.org.
Change-Id: I1337f3185d72108eef2968cca3cb81d52e742e90
Story: #2006070
Task: #35469
The 'openstack-tox-docs' gate is currently broken:
`html_static_path entry '_static' does not exist`
Removed the 'html_static_path' from 'doc/source/conf.py' as this is
also how Tempest is configured [0]
[0] https://github.com/openstack/tempest/blob/master/doc/source/conf.py#L125
Change-Id: I1244457428cbefb9341a1991839d41b592b6c469
The api documentation is now published on docs.openstack.org instead
of developer.openstack.org. Update all links that are changed to the
new location.
Note that redirects will be set up as well but let's point now to the
new location.
For details, see:
http://lists.openstack.org/pipermail/openstack-discuss/2019-July/007828.html
Change-Id: Ib854afe939791180153cccc4b0313e5b25842f7e
Some options are now automatically configured by the version 1.20:
- project
- html_last_updated_fmt
- latex_engine
- latex_elements
- version
- release.
Change-Id: Iad7ed84d2560c7829be20c24e41299b60283cccb
- When the URL refers to cloning or using git repositories, use the
cloning URL (https://git.openstack.org/<namespace>/<project>)
- When the URL refers to the browsable version of the repository, point to
the cgit frontend (https://git.openstack.org/cgit/<namespace>/<project>)
Change-Id: Iaeaa153a05aa85b9cf7451ae3c28aec56722222c
This package is used for automatic generation of autodoc
documentation which offers the following advantages:
* the Patrole framework for all modules is always built
and kept up to date
* it is isolated in its own page layout
* it can still be linked to by other documentation pages
easily
Change-Id: I101557efe47293f88ee65b99275fdc8424c02e35
This patch set adds documentation about white box vs block box
testing and their relationship in Patrole. This is so that
devs/test writers understand that Patrole is a bit different than
Tempest and requires digging a bit deeper in the internals of
the API implementation in order to properly test RBAC.
Also removes a misleading link in the README.rst section. The
discussion on member vs. _member_ role is very outdated and
so a link is provided to the RBAC overview section instead which
is concerned with documenting such information.
Change-Id: I0a014c2e917caeb058dd5b5294dd0af2e5e49132
This patchset eliminates different behaviour between
policy_authority and requirements_authority.
Problem description:
`rbac_test_roles = [member,]`
Policy authority:
`update_port: role:member and role:viewer`
Results in 403/False (we are member but not viewer).
Requirements authority:
```
req_auth:
update_port:
- member
- viewer
```
Results in 200/True (member in update_port list).
Proposed solution:
Change requirements_authority file sytax to support
comma separated roles to be considered as logical and.
Depends-On: https://review.openstack.org/#/c/606110/
Change-Id: I2e2a4a2020f5e85af15f1836d69386bc91a2d2ec
Co-Authored-By: Felipe Monteiro <felipe.monteiro@att.com>
This patchset replaces ``CONF.patrole.rbac_test_role`` with
``CONF.patrole.rbac_test_roles``, where instead of single role
we can specify list of roles to be assigned to test user.
Change-Id: Ia68bcbdbb523dfe7c4abd6107fb4c426a566ae9d
This patchset adds multi-policy validation documentation to the
developer's documentation section. Also adds REVIEWING guidelines
to help developers/reviewers understand guidelines/best practices
for writing such tests.
Change-Id: Ieb462e3b176a5dba40146ddd422e62e5715dc034
This documentation adds oslo.policy/policy related information
to Patrole RBAC documentation so users understand some limitations
related to current implementation of oslo.policy in OpenStack
and some limitations around edge case policy testing w.r.t custom
oslo.policy rulechecks.
* Currently admin context policy rule is used to skip over oslo.policy
authorization checks in many services -- this is important to note
as this means Patrole can't properly validate admin against
oslo.policy [0].
* Currently it is not possible to test policy rules that rely on
generic checks/oslo.policy checks defined in services themselves
like Neutron's FieldCheck [1] as Patrole has no way of importing such
code in order to get these checks registered.
[0] b4b725ade9/neutron/policy.py (L374)
[1] https://docs.openstack.org/neutron/pike/contributor/internals/policy.html#fieldcheck-verify-resource-attributes
Change-Id: I0e375a11eb323d83b1ece1537dbd008633126eb3
This patch set replaces deprecated occurrences of rule with
rules and expected_error_code with expected_error_codes in
rbac_rule_validation.action decorator.
Along with removing the parameters from the decorator, all the
API tests have been changed to use the non-deprecated parameters
instead. Unit tests have also been updated.
Change-Id: I6485b6c57795b5fe75e2b339d5c9720da30be564
This patch set doesn't really add new documentation but instead
moves documentation regarding RBAC testing guidelines and
examples out of framework/rbac_utils.rst and moves it into a
separate test_writing_guide.rst file located in the
"Developers' Guide" section.
This is because this information is directly relevant to developers
and should be included somewhere obvious where they can find it.
Including important testing examples and guidelines in the framework
documentation isn't too helpful.
Change-Id: I6e975cbf1b86d356e9f5d623f81fbf293efcc42c
This patchset adds an RBAC overview documentation section dedicated
to:
* Defining what RBAC is
* Policy in code and validation info related to it
* Custom policies and validation info related to it
* Multiple policies and validation info related to it
* Error codes
* Glossary
This way, users can learn about what RBAC is from a high level
and how Patrole uses validation to validate that it is working
correctly.
Change-Id: Ib411e4d06210135f7bd1cb90d5b6d59da2e5d076
This adds a README.rst in the devstack folder with information
about DevStack and how to install Patrole plugin in Devstack.
Change-Id: I31a92351211a2f37403c08406215bc10f3c3222e
This patchset adds reviewing documentation to Patrole which
is very similar to Tempest's reviewing documentation, except that
it omits sections that aren't so relevant (like requirements around
docstrings because currently Patrole has no such requirements) but
adds sections related to policy concerns.
Change-Id: I25c3a4b73f1d4f8beb7bce9c694f4bb3f904e038
There have been concerns raised as to why Patrole tests aren't
contained in Tempest (the concerns are not found in any written
discussion online). This documentation puts such concerns to
rest. It was agreed upon in the RBAC testing spec [0] that:
"rbac tests will live in separate tempest plugin." This
documentation formalizes that reasoning.
[0] comment in https://review.openstack.org/#/c/382672/
Change-Id: I31d956b42440a5448a5be0a7e2c5b3b7ddacfab5
This patchset brings the README.rst and the overview.rst
documentation together. Previously they were maintained
separately which causes maintenance issues. This adds
a symlink from the overview.rst to the README.rst so
that the overview documentation only needs to be maintained
for the README.
This also adds a Terminology subsection underneath the
"How it works" section which expands on essential terminology
needed to understand Patrole testing architecture:
* Expected 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 Success
* Expected: Pass | Actual: Fail - Test Case Failure
* Expected: Fail | Actual: Pass - Test Case Failure
* Expected: Fail | Actual: Fail (Expected exception) - Test Case Success
* Expected: Fail | Actual: Fail (Unexpected exception) - Test Case Failure
Change-Id: I1d640200c55ce26cfd38197ec6face1161217b17
This patchset updates rbac_exceptions by bringing the concept
of under-permission and over-permission together. An over-permission
occurs when an unauthorized role is allowed to perform an action
and an under-permission occurs when an authorized role is not
allowed to perform an action. Both of these are important failure
scenarios.
Current Patrole has an RbacOverPermission Exception but uses
a "Forbidden" as a pseudonym for the under-permission version
but this is not ideal for the following reasons:
* Patrole can expect a 404 Not Found due to Neutron policy enforcement [0]
* The naming is inconsistent with RbacOverPermission
* It should have a Patrole wrapper exception (NotFound is used directly
from Tempest)
So, this patchset:
* renames RbacOverPermission to RbacOverPermissionException
* replaces Forbidden exception with RbacUnderPermissionException
* updates documentation, docstrings and unit tests
In addition, this patchset introduces a new exception called
RbacExpectedWrongException which is raised when the expected
exception does not match the actual exception and both are instances
of 403 and 404, which means that the RBAC test uses the wrong
expected_error_codes.
Change-Id: I681610448cbe0269f02c34ea6afaaaf29c306121
This patchset adds a Patrole overview documentation
section which is sorely needed. It combines the previous
usage documentation into it.
Change-Id: Ia7412f2e99f33fbdfd2e60ba54ffdba757d1f886
This patchset includes documentation on the rbac_authority
and the requirements_authority modules. In addition,
the documentation for the policy_authority module is
expanded. All 3 modules are explained together, explaining
that the rbac_authority module contains an abstract
class consumed by the classes in the other two modules.
The use cases for each validation approach is also included
in the documentation.
Finally, some documentation syntax issues are corrected.
Change-Id: I33bbe2da67683faafd0749b687b99237ac815009
This is to add documentation on policy feature flags, recently
introduced in [0].
[0] Ia0d9847908a8e723446c16465d68cd7f622c04cc
Depends-On: Ia47132fa596918e58f21ba9810c2c28ddcf0d584
Change-Id: I3e630c535074e3a9ce8e9b07a1909984d70cef12
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