Add guidance to rule types

database/migrations/000001_init.up.sql

@@ -167,6 +167,7 @@ CREATE TABLE rule_type (
     provider TEXT NOT NULL,
     group_id INTEGER NOT NULL REFERENCES groups(id) ON DELETE CASCADE,
     description TEXT NOT NULL,
+    guidance TEXT NOT NULL,
     definition JSONB NOT NULL,
     created_at TIMESTAMP NOT NULL DEFAULT NOW(),
     updated_at TIMESTAMP NOT NULL DEFAULT NOW()

database/query/rule_types.sql

@@ -4,7 +4,8 @@ INSERT INTO rule_type (
     provider,
     group_id,
     description,
-    definition) VALUES ($1, $2, $3, $4, sqlc.arg(definition)::jsonb) RETURNING *;
+    guidance,
+    definition) VALUES ($1, $2, $3, $4, $5, sqlc.arg(definition)::jsonb) RETURNING *;
 
 -- name: ListRuleTypesByProviderAndGroup :many
 SELECT * FROM rule_type WHERE provider = $1 AND group_id = $2;

examples/github/rule-types/secret_scanning.yaml

@@ -6,6 +6,13 @@ context:
   provider: github
   group: Root Group
 description: Verifies that secret scanning is enabled for a given repository.
+guidance: |
+  Secret scanning is a feature that scans repositories for secrets and alerts
+  the repository owner when a secret is found. To enable this feature in github,
+  you must enable it in the repository settings. See the GitHub documentation
+  for more information. [1]
+
+  [1] https://docs.github.com/en/github/administering-a-repository/about-secret-scanning
 def:
   # Defines the section of the pipeline the rule will appear in.
   # This will affect the template that is used to render multiple parts

internal/engine/rule_types.go

@@ -270,6 +270,7 @@ func RuleTypePBFromDB(rt *db.RuleType, ectx *EntityContext) (*pb.RuleType, error
 			Group:    &gname,
 		},
 		Description: rt.Description,
+		Guidance:    rt.Guidance,
 		Def:         def,
 	}, nil
 }

pkg/controlplane/handlers_policy.go

@@ -408,6 +408,16 @@ func (s *Server) GetPolicyStatusById(ctx context.Context,
 
 		rulestats = make([]*pb.RuleEvaluationStatus, 0, len(dbrulestat))
 		for _, rs := range dbrulestat {
+			var guidance string
+			if rs.EvalStatus == db.EvalStatusTypesFailure || rs.EvalStatus == db.EvalStatusTypesError {
+				ruleTypeInfo, err := s.store.GetRuleTypeByID(ctx, rs.RuleTypeID)
+				if err != nil {
+					log.Printf("error getting rule type info: %v", err)
+				} else {
+					guidance = ruleTypeInfo.Guidance
+				}
+			}
+
 			st := &pb.RuleEvaluationStatus{
 				PolicyId: in.PolicyId,
 				RuleId:   rs.RuleTypeID,
@@ -421,6 +431,7 @@ func (s *Server) GetPolicyStatusById(ctx context.Context,
 					"repo_owner":    rs.RepoOwner,
 					"provider":      rs.Provider,
 				},
+				Guidance:    guidance,
 				LastUpdated: timestamppb.New(rs.LastUpdated),
 			}
 
@@ -603,6 +614,7 @@ func (s *Server) CreateRuleType(ctx context.Context, crt *pb.CreateRuleTypeReque
 		GroupID:     entityCtx.GetGroup().GetID(),
 		Description: in.GetDescription(),
 		Definition:  def,
+		Guidance:    in.GetGuidance(),
 	})
 	if err != nil {
 		return nil, status.Errorf(codes.Unknown, "failed to create rule type: %s", err)