Add oslopolicy-validator tool

As requested in the referenced RFE bug, this is a validator tool
similar to the oslo.config validator tool that operators can use to
look for basic errors in their policy files.

It's very similar to the redundant rule tool, but I decided not to
combine them because I feel like the target use cases are enough
different to warrant separate tools. Specifically, the redundant
rule tool is looking for perfectly valid rules that just happen to
be unnecessary. The validator is looking for errors in the policy
file. While it's unlikely someone looking for redundant rules wouldn't
also want to know if there is something broken in their policy file,
it's likely that someone just looking to sanity check their policy
before deployment wouldn't want to see a bunch of messages about
redundant rules that won't cause any problems.

Change-Id: I799a754aceac080c11baffd7ff635b2a9cb825f7
Closes-Bug: 1853038

1 files changed, 40 insertions, 0 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index c7023de..bef7c99 100644
--- a/doc/source/cli/index.rst
+++ b/doc/source/cli/index.rst
@@ -151,3 +151,43 @@ For more information regarding the options supported by this tool:
 .. code-block:: bash
 
    oslopolicy-list-redundant --help
+
+oslopolicy_validator
+====================
+
+The ``oslopolicy-validator`` tool can be used to perform basic sanity checks
+against a policy file. It will detect the following problems:
+
+* A missing policy file
+* Rules which have invalid syntax
+* Rules which reference non-existent other rules
+* Rules which form a cyclical reference with another rule
+* Rules which do not exist in the specified namespace
+
+This tool does very little validation of the content of the rules. Other tools,
+such as ``oslopolicy-checker``, should be used to check that rules do what is
+intended.
+
+``oslopolicy-validator`` exits with a ``0`` return code on success and ``1`` on
+failure.
+
+.. note:: At this time the policy validator can only handle single policy
+          files, not policy dirs.
+
+Examples
+--------
+
+Validate the policy file used for Keystone:
+
+.. code-block:: bash
+
+   oslopolicy-validator --config-file /etc/keystone/keystone.conf --namespace keystone
+
+Sample output from a failed validation::
+
+   $ oslopolicy-validator --config-file keystone.conf --namespace keystone
+   WARNING:oslo_policy.policy:Policies ['foo', 'bar'] are part of a cyclical reference.
+   Invalid rules found
+   Failed to parse rule: (role:admin and system_scope:all) or (role:foo and oken.domain.id:%(target.user.domain_id)s))
+   Unknown rule found in policy file: foo
+   Unknown rule found in policy file: bar