Add support for setting the constraint enforcement action per policy (#71)

* Add @enforcement to Rego comment header block

* generate updated cli docs

Co-authored-by: konstraint-bot <konstraint-bot@dev.null>

Author: James Alseth

docs/cli/konstraint.md

@@ -17,4 +17,4 @@ A tool to create and manage Gatekeeper CRDs from Rego
 * [konstraint create](konstraint_create.md)	 - Create Gatekeeper constraints from Rego policies
 * [konstraint doc](konstraint_doc.md)	 - Generate documentation from Rego policies
 
-###### Auto generated by spf13/cobra on 26-Aug-2020
+###### Auto generated by spf13/cobra on 30-Sep-2020

docs/cli/konstraint_create.md

@@ -26,7 +26,7 @@ Create constraints with the Gatekeeper enforcement action set to dryrun
 ### Options
 
 ```
-  -d, --dryrun          Sets the enforcement action of the constraints to dryrun
+  -d, --dryrun          Sets the enforcement action of the constraints to dryrun, overriding the @enforcement tag
   -h, --help            help for create
   -o, --output string   Specify an output directory for the Gatekeeper resources
 ```
@@ -35,4 +35,4 @@ Create constraints with the Gatekeeper enforcement action set to dryrun
 
 * [konstraint](konstraint.md)	 - Konstraint
 
-###### Auto generated by spf13/cobra on 26-Aug-2020
+###### Auto generated by spf13/cobra on 30-Sep-2020

docs/cli/konstraint_doc.md

@@ -35,4 +35,4 @@ Set the URL where the policies are hosted at
 
 * [konstraint](konstraint.md)	 - Konstraint
 
-###### Auto generated by spf13/cobra on 26-Aug-2020
+###### Auto generated by spf13/cobra on 30-Sep-2020

docs/constraint_creation.md

@@ -48,12 +48,15 @@ This comment block should:
 - Include a human readable description of what the policy does.
 - Set the matchers used when generating the Constraints.
 
+It may also specify the enforcment action (either `deny` or `dryrun`) that Gatekeeper should take when a resource violates the constraint. If no enforcement action is specified, Konstraint defaults to using `deny` to align with Gatekeeper's default action. If the enforcement is set to `dryrun`, the policy will be skipped in the documentation generation.
+
 ```rego
 # @title Pods must not run with access to the host IPC
 #
 # Pods that are allowed to access the host IPC can read memory of
 # the other containers, breaking that security boundary.
 #
+# @enforcement deny
 # @kinds apps/DaemonSet apps/Deployment apps/StatefulSet core/Pod
 package pod_deny_host_ipc
 

internal/commands/create.go

@@ -49,7 +49,7 @@ Create constraints with the Gatekeeper enforcement action set to dryrun
 	}
 
 	cmd.PersistentFlags().StringP("output", "o", "", "Specify an output directory for the Gatekeeper resources")
-	cmd.PersistentFlags().BoolP("dryrun", "d", false, "Sets the enforcement action of the constraints to dryrun")
+	cmd.PersistentFlags().BoolP("dryrun", "d", false, "Sets the enforcement action of the constraints to dryrun, overriding the @enforcement tag")
 
 	return &cmd
 }
@@ -140,8 +140,9 @@ func getConstraint(violation rego.Rego) (unstructured.Unstructured, error) {
 	constraint.SetGroupVersionKind(gvk)
 	constraint.SetName(violation.Name())
 
+	// the dryrun flag overrides any enforcement action specified in the rego header
 	dryrun := viper.GetBool("dryrun")
-	if dryrun {
+	if dryrun || violation.Enforcement() == "dryrun" {
 		if err := unstructured.SetNestedField(constraint.Object, "dryrun", "spec", "enforcementAction"); err != nil {
 			return unstructured.Unstructured{}, fmt.Errorf("set constraint dryrun: %w", err)
 		}

internal/commands/document.go

@@ -101,6 +101,10 @@ func getDocumentation(path string, outputDirectory string) (map[rego.Severity][]
 			continue
 		}
 
+		if policy.Enforcement() == "dryrun" {
+			continue
+		}
+
 		var url string
 		if viper.GetString("url") != "" {
 			url = viper.GetString("url") + "/" + policy.Path()

internal/rego/rego.go

@@ -129,6 +129,22 @@ func (r Rego) Title() string {
 	return trimString(title)
 }
 
+// Enforcement returns the enforcement action in the header comment
+// Defaults to deny if no enforcement action is specified
+func (r Rego) Enforcement() string {
+	enforcement := "deny"
+	for _, comment := range r.comments {
+		if !strings.Contains(comment, "@enforcement") {
+			continue
+		}
+
+		enforcement = strings.SplitAfter(comment, "@enforcement")[1]
+		break
+	}
+
+	return trimString(enforcement)
+}
+
 // Description returns the entire description
 // found in the header comment of the rego file.
 func (r Rego) Description() string {

internal/rego/rego_test.go

@@ -105,3 +105,27 @@ third`
 		t.Errorf("unexpected Source. expected %v, actual %v", expected, actual)
 	}
 }
+
+func TestEnforcement(t *testing.T) {
+	comments := []string{
+		"@title Test",
+		"description",
+		"@enforcement dryrun",
+		"@kinds apps/Deployment",
+	}
+	rego := Rego{
+		comments: comments,
+	}
+
+	actual := rego.Enforcement()
+	const expected = "dryrun"
+	if actual != expected {
+		t.Errorf("unexpected Enforcement. expected %v, actual %v", expected, actual)
+	}
+
+	actualDefault := Rego{}.Enforcement()
+	const expectedDefault = "deny"
+	if actualDefault != expectedDefault {
+		t.Errorf("unexpected Enforcement. expected %v, actual %v", expectedDefault, actualDefault)
+	}
+}