Merge pull request #624 from simonbaird/rule-description-edits

Rule description edits for consistency

checks/annotations_test.rego

@@ -53,7 +53,7 @@ opa_inspect_valid := {
 					"short_name": "pipelinerun_attestation_found",
 					"solution": "Make sure the attestation being verified was generated from a Tekton pipelineRun.",
 				},
-				"description": "At least one PipelineRun attestation must be present.",
+				"description": "Confirm at least one PipelineRun attestation is present.",
 				"scope": "rule",
 				"title": "PipelineRun attestation found",
 			},
@@ -78,7 +78,7 @@ opa_inspect_missing_annotations := {
 	"annotations": [{
 		"annotations": {
 			"scope": "rule",
-			"description": "Check for existence of a task bundle. Enforcing this rule will\nfail the contract if the task is not called from a bundle.",
+			"description": "Check for the existence of a task bundle. This rule will fail if the task is not called from a bundle.",
 			"custom": {
 				"flagiure_msg": "Task '%s' does not contain a bundle reference",
 				"short_name": "disallowed_task_reference",

policy/build_task/labels.rego

@@ -1,8 +1,9 @@
 #
 # METADATA
-# title: Checks related to build tasks
-# description: |-
-#   Checks related to build tasks
+# title: Tekton task build type label checks
+# description: >-
+#   Policies to verify that a Tekton build task definition has the
+#   required build type label.
 #
 package policy.build_task.labels
 
@@ -16,24 +17,26 @@ import data.lib.tkn
 build_label := "build.appstudio.redhat.com/build_type"
 
 # METADATA
-# title: Build task does not contain required label
-# description: |-
-#   This policy enforces that a required build label is present in a build task
+# title: Build task has build type label
+# description: >-
+#   Confirm the build task definition has the required build type label.
 # custom:
-#   short_name: build_task_label_missing
+#   short_name: build_type_label_set
 #   failure_msg: The required build label '%s' is missing
+#
 deny contains result if {
 	not build_label in object.keys(tkn.task_labels)
 	result := lib.result_helper(rego.metadata.chain(), [build_label])
 }
 
 # METADATA
-# title: Build task does not contain any labels
-# description: |-
-#   This policy enforces that the task contains a label
+# title: Build task has label
+# description: >-
+#   Confirm that the build task definition includes at least one label.
 # custom:
-#   short_name: build_task_no_labels
-#   failure_msg: The task does not contain labels
+#   short_name: build_task_has_label
+#   failure_msg: The task definition does not include any labels
+#
 deny contains result if {
 	not tkn.task_labels
 	result := lib.result_helper(rego.metadata.chain(), [])

policy/build_task/labels_test.rego

@@ -8,14 +8,14 @@ test_build_label_found {
 
 test_build_label_not_found {
 	lib.assert_equal_results(deny, {{
-		"code": "labels.build_task_label_missing",
+		"code": "labels.build_type_label_set",
 		"msg": "The required build label 'build.appstudio.redhat.com/build_type' is missing",
 	}}) with input as {"metadata": {"labels": {"bad": "docker"}}}
 }
 
 test_no_labels {
 	lib.assert_equal_results(deny, {{
-		"code": "labels.build_task_no_labels",
-		"msg": "The task does not contain labels",
+		"code": "labels.build_task_has_label",
+		"msg": "The task definition does not include any labels",
 	}}) with input as {"metadata": {"name": "no_labels"}}
 }

policy/pipeline/basic.rego

@@ -2,9 +2,7 @@
 # METADATA
 # title: Pipeline definition sanity checks
 # description: >-
-#   Currently there is just a check to confirm the input
-#   appears to be a Pipeline definition. We may add additional
-#   sanity checks in future.
+#   Policies to confirm the Tekton Pipeline definition has the expected kind.
 #
 package policy.pipeline.basic
 
@@ -20,12 +18,12 @@ expected_kind := "Pipeline"
 # Fixme: It doesn't fail if the kind key is entirely missing..
 
 # METADATA
-# title: Input data has unexpected kind
+# title: Pipeline definition has expected kind
 # description: >-
-#   A sanity check to confirm the input data has the kind "Pipeline"
+#   Confirm that the pipeline definition has the kind "Pipeline".
 # custom:
-#   short_name: unexpected_kind
-#   failure_msg: Unexpected kind '%s'
+#   short_name: expected_kind
+#   failure_msg: Unexpected kind '%s' for pipeline definition
 #
 deny contains result if {
 	expected_kind != input.kind

policy/pipeline/basic_test.rego

@@ -4,7 +4,7 @@ import data.lib
 
 test_unexpected_kind {
 	lib.assert_equal_results(deny, {{
-		"code": "basic.unexpected_kind",
-		"msg": "Unexpected kind 'Foo'",
+		"code": "basic.expected_kind",
+		"msg": "Unexpected kind 'Foo' for pipeline definition",
 	}}) with input.kind as "Foo"
 }

policy/pipeline/required_tasks.rego

@@ -1,9 +1,10 @@
 #
 # METADATA
+# title: Required tasks
 # description: >-
 #   RHTAP expects that certain Tekton tasks are executed during image builds.
 #   This package includes policy rules to confirm that the pipeline definition
-#   includes the required Tekton tasks.
+#   includes those required tasks.
 #
 package policy.pipeline.required_tasks
 
@@ -15,25 +16,25 @@ import data.lib
 import data.lib.tkn
 
 # METADATA
-# title: No tasks in Pipeline
+# title: Pipeline contains tasks
 # description: >-
-#   This policy enforces that at least one Task is present in the Pipeline
-#   definition.
+#   Confirm at least one task is present in the pipeline definition.
 # custom:
-#   short_name: tasks_missing
-#   failure_msg: No tasks found in Pipeline definition
+#   short_name: tasks_found
+#   failure_msg: No tasks found in pipeline
 deny contains result if {
 	input.kind == "Pipeline"
 	count(tkn.tasks(input)) == 0
 	result := lib.result_helper(rego.metadata.chain(), [])
 }
 
 # METADATA
-# title: Missing required pipeline tasks
+# title: Required tasks found in pipeline definition
 # description: >-
-#   This policy warns if a task list does not exist in the acceptable_bundles.yaml file
+#   Produce a warning if a task list does not exist in the acceptable
+#   bundles rule data.
 # custom:
-#   short_name: missing_required_pipeline_task
+#   short_name: required_tasks_found
 #   failure_msg: Required tasks do not exist for pipeline %q
 warn contains result if {
 	count(tkn.tasks(input)) > 0
@@ -49,7 +50,7 @@ warn contains result if {
 # METADATA
 # title: Missing required task
 # description: >-
-#   This policy enforces that the required set of tasks are included
+#   Ensure that the set of required tasks is included
 #   in the Pipeline definition.
 # custom:
 #   short_name: missing_required_task
@@ -68,8 +69,8 @@ deny contains result if {
 # METADATA
 # title: Missing future required task
 # description: >-
-#   This policy warns when a task that will be required in the future
-#   was not included in the Pipeline definition.
+#   Produce a warning when a task that will be required in the future
+#   is not currently included in the Pipeline definition.
 # custom:
 #   short_name: missing_future_required_task
 #   failure_msg: Task %q is missing and will be required in the future
@@ -86,12 +87,13 @@ warn contains result if {
 }
 
 # METADATA
-# title: Missing required tasks data
+# title: Required task list is present in rule data
 # description: >-
-#   The policy rules in this package require the required-tasks data to be provided.
+#   Confirm the `required-tasks` rule data was provided, since it's
+#   required by the policy rules in this package.
 # custom:
-#   short_name: missing_required_data
-#   failure_msg: Missing required task-bundles data
+#   short_name: required_tasks_list_present
+#   failure_msg: The required tasks list is missing from the rule data
 deny contains result if {
 	tkn.missing_required_tasks_data
 	not tkn.required_task_list(input)

policy/pipeline/required_tasks_test.rego

@@ -62,7 +62,7 @@ test_extra_tasks_ignored if {
 
 test_missing_pipeline_label if {
 	expected := {{
-		"code": "required_tasks.missing_required_pipeline_task",
+		"code": "required_tasks.required_tasks_found",
 		"msg": "Required tasks do not exist for pipeline \"fbc\"",
 	}}
 	pipeline := _pipeline_with_tasks(_expected_required_tasks, [], [])
@@ -140,8 +140,8 @@ test_current_equal_latest_also if {
 
 test_no_tasks_present if {
 	expected := {{
-		"code": "required_tasks.tasks_missing",
-		"msg": "No tasks found in Pipeline definition",
+		"code": "required_tasks.tasks_found",
+		"msg": "No tasks found in pipeline",
 	}}
 
 	lib.assert_equal_results(expected, deny) with data["pipeline-required-tasks"] as _time_based_pipeline_required_tasks
@@ -183,8 +183,8 @@ test_parameterized if {
 test_missing_required_tasks_data if {
 	pipeline := _pipeline_with_tasks_and_label(_expected_required_tasks, [], [])
 	expected := {{
-		"code": "required_tasks.missing_required_data",
-		"msg": "Missing required task-bundles data",
+		"code": "required_tasks.required_tasks_list_present",
+		"msg": "The required tasks list is missing from the rule data",
 	}}
 	lib.assert_equal_results(expected, deny) with data["required-tasks"] as []
 		with data["pipeline-required-tasks"] as {}
@@ -269,7 +269,7 @@ _missing_tasks_warning(tasks) = warnings if {
 _missing_pipeline_tasks_warning(name) = warnings if {
 	warnings := {warning |
 		warning := {
-			"code": "required_tasks.missing_required_pipeline_task",
+			"code": "required_tasks.required_tasks_found",
 			"msg": sprintf("Required tasks do not exist for pipeline %q", [name]),
 		}
 	}

policy/pipeline/task_bundle.rego

@@ -21,8 +21,8 @@ import data.lib.bundles
 # METADATA
 # title: Task bundle was not used or is not defined
 # description: >-
-#   Check for existence of a task bundle. Enforcing this rule will
-#   fail the contract if the task is not called from a bundle.
+#   Check for the existence of a task bundle. This rule will
+#   fail if the task is not called from a bundle.
 # custom:
 #   short_name: disallowed_task_reference
 #   failure_msg: Pipeline task '%s' does not contain a bundle reference
@@ -35,7 +35,7 @@ deny contains result if {
 # METADATA
 # title: Task bundle reference is empty
 # description: >-
-#   Check for a valid task bundle reference being used.
+#   Check that a valid task bundle reference is being used.
 # custom:
 #   short_name: empty_task_bundle_reference
 #   failure_msg: Pipeline task '%s' uses an empty bundle image reference
@@ -91,7 +91,8 @@ deny contains result if {
 # METADATA
 # title: Missing required data
 # description: >-
-#   The policy rules in this package require the task-bundles data to be provided.
+#   Confirm the `task-bundles` rule data was provided, since it's
+#   required by the policy rules in this package.
 # custom:
 #   short_name: missing_required_data
 #   failure_msg: Missing required task-bundles data

policy/release/attestation_task_bundle.rego

@@ -21,8 +21,8 @@ import data.lib.bundles
 # METADATA
 # title: Tasks defined using bundle references
 # description: >-
-#   Check for existence of a task bundle. Enforcing this rule will
-#   fail the contract if the task is not called from a bundle.
+#   Check for the existence of a task bundle. This rule will
+#   fail if the task is not called from a bundle.
 # custom:
 #   short_name: tasks_defined_in_bundle
 #   failure_msg: Pipeline task '%s' does not contain a bundle reference
@@ -40,7 +40,7 @@ deny contains result if {
 # METADATA
 # title: Task bundle references not empty
 # description: >-
-#   Check for a valid task bundle reference being used.
+#   Check that a valid task bundle reference is being used.
 # custom:
 #   short_name: task_ref_bundles_not_empty
 #   failure_msg: Pipeline task '%s' uses an empty bundle image reference
@@ -123,8 +123,8 @@ deny contains result if {
 # METADATA
 # title: An acceptable Tekton bundles list was provided
 # description: >-
-#   The policy rules in this package require the acceptable Tekton task bundles
-#   rule data to be provided.
+#   Confirm the `task-bundles` rule data was provided, since it's
+#   required by the policy rules in this package.
 # custom:
 #   short_name: acceptable_bundles_provided
 #   failure_msg: Missing required task-bundles data

policy/release/attestation_type.rego

@@ -14,7 +14,7 @@ import data.lib
 # METADATA
 # title: Known attestation type found
 # description: >-
-#   A sanity check to confirm the attestation found for the image has a known
+#   Confirm the attestation found for the image has a known
 #   attestation type.
 # custom:
 #   short_name: known_attestation_type
@@ -38,7 +38,7 @@ deny contains result if {
 # METADATA
 # title: PipelineRun attestation found
 # description: >-
-#   At least one PipelineRun attestation must be present.
+#   Confirm at least one PipelineRun attestation is present.
 # custom:
 #   short_name: pipelinerun_attestation_found
 #   failure_msg: Missing pipelinerun attestation

policy/release/base_image_registries.rego

@@ -16,8 +16,8 @@ import data.lib
 # METADATA
 # title: Base image comes from permitted registry
 # description: >-
-#   The base images used when building a container image must come from a known set
-#   of trusted registries to reduce potential supply chain attacks. By default this
+#   Verify that the base images used when building a container image come from a known
+#   set of trusted registries to reduce potential supply chain attacks. By default this
 #   policy defines trusted registries as registries that are fully maintained by Red
 #   Hat and only contain content produced by Red Hat. The list of permitted registries
 #   can be customized by setting the `allowed_registry_prefixes` list in the rule data.
@@ -43,14 +43,14 @@ deny contains result if {
 # METADATA
 # title: Base image task result was provided
 # description: >-
-#   The attestation must provide the expected information about which base images
+#   Verify the attestation provides the expected information about which base images
 #   were used during the build process. The base image information is expected to
-#   be found in a task result called `BASE_IMAGES_DIGESTS`.
+#   be found in a task result called BASE_IMAGES_DIGESTS.
 # custom:
 #   short_name: base_image_info_found
 #   failure_msg: Base images result is missing
 #   solution: >-
-#     A Tekton task must exist that emits a result named 'BASE_IMAGES_DIGESTS'.
+#     A Tekton task must exist that emits a result named BASE_IMAGES_DIGESTS.
 #   collections:
 #   - minimal
 #   - redhat
@@ -70,8 +70,8 @@ deny contains result if {
 # METADATA
 # title: Allowed base image registry prefixes list was provided
 # description: >-
-#   The policy rules in this package require the `allowed_registry_prefixes`
-#   rule data to be provided.
+#   Confirm the `allowed_registry_prefixes` rule data was provided, since it's
+#   required by the policy rules in this package.
 # custom:
 #   short_name: allowed_registries_provided
 #   failure_msg: Missing required allowed_registry_prefixes rule data

policy/release/buildah_build_task.rego

@@ -16,7 +16,7 @@ import data.lib
 # METADATA
 # title: Buildah task has Dockerfile param defined
 # description: >-
-#   This policy verifies that a DOCKERFILE parameter was provided to
+#   Verify that a DOCKERFILE parameter was provided to
 #   the buildah task.
 # custom:
 #   short_name: buildah_task_has_dockerfile_param
@@ -39,8 +39,8 @@ deny contains result if {
 # METADATA
 # title: Buildah task uses a local Dockerfile
 # description: >-
-#   This policy verifies that the Dockerfile used in the buildah task is not
-#   fetched from an external source
+#   Verify the Dockerfile used in the buildah task was not
+#   fetched from an external source.
 # custom:
 #   short_name: buildah_uses_local_dockerfile
 #   failure_msg: DOCKERFILE param value (%s) is an external source