add docs module and add documentation to SARIF (boostsecurityio#23)

docs/content.go

@@ -0,0 +1,50 @@
+package docs
+
+import (
+	"embed"
+	"fmt"
+	"path"
+	"strings"
+)
+
+//go:embed content
+var content embed.FS
+
+type Page struct {
+	Content string `yaml:"-"`
+}
+
+func GetPagesContent() map[string]string {
+	docs := map[string]string{}
+	entries, err := content.ReadDir(path.Join("content", "en", "rules"))
+	if err != nil {
+		return docs
+	}
+
+	for _, entry := range entries {
+		ruleId := strings.TrimSuffix(entry.Name(), ".md")
+		page, err := GetPage(ruleId)
+		if err != nil {
+			continue
+		}
+
+		docs[ruleId] = page.Content
+	}
+
+	return docs
+}
+
+func GetPage(ruleId string) (*Page, error) {
+	doc, err := content.ReadFile(
+		path.Join("content", "en", "rules", ruleId+".md"))
+	if err != nil {
+		return nil, err
+	}
+
+	parts := strings.SplitAfterN(string(doc), "---\n", 3)
+	if len(parts) != 3 {
+		return nil, fmt.Errorf("invalid doc page %s.md", ruleId)
+	}
+
+	return &Page{Content: strings.TrimSpace(parts[2])}, nil
+}

docs/content_test.go

@@ -0,0 +1,18 @@
+package docs
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestGetRuleDocs(t *testing.T) {
+	page, err := GetPage("debug_enabled")
+
+	assert.Nil(t, err)
+	assert.True(t,
+		strings.HasPrefix(page.Content, "## Description"),
+		"content should be trimmed '%s'...", page.Content[0:10],
+	)
+}

formatters/sarif/sarif.go

@@ -3,11 +3,13 @@ package sarif
 import (
 	"context"
 	"fmt"
+	"io"
+	"strings"
+
+	"github.com/boostsecurityio/poutine/docs"
 	"github.com/boostsecurityio/poutine/models"
 	"github.com/boostsecurityio/poutine/opa"
 	"github.com/owenrumney/go-sarif/v2/sarif"
-	"io"
-	"strings"
 )
 
 func NewFormat(out io.Writer) *Format {
@@ -36,6 +38,8 @@ func (f *Format) Format(ctx context.Context, report *opa.FindingsResult, package
 		findingsByPurl[finding.Purl] = append(findingsByPurl[finding.Purl], finding)
 	}
 
+	docs := docs.GetPagesContent()
+
 	for _, pkg := range packages {
 		run := sarif.NewRunWithInformationURI("poutine", "https://github.com/boostsecurityio/poutine")
 		run.Tool.Driver.WithSemanticVersion("0.9.0")
@@ -68,12 +72,13 @@ func (f *Format) Format(ctx context.Context, report *opa.FindingsResult, package
 			if line == 0 {
 				line = 1
 			}
+			ruleDoc := docs[ruleId]
 
 			run.AddRule(ruleId).
 				WithName(rule.Title).
 				WithDescription(rule.Title).
 				WithFullDescription(
-					sarif.NewMultiformatMessageString(ruleDescription),
+					sarif.NewMarkdownMultiformatMessageString(ruleDoc),
 				).
 				WithHelpURI(
 					fmt.Sprintf("https://github.com/boostsecurityio/poutine/tree/main/docs/content/en/rules/%s.md", ruleId),