feat(#32): improve configuration API

Changes urls -> targets
Changes slack-channel -> slack-channels
Adds readme with details of all configuration options

Author: sacha-c

README.md

@@ -19,6 +19,21 @@ Sheriff is a tool to scan repositories and generate security reports.
   - [CLI flags](#cli-flags)
   - [Environment variables](#environment-variables)
   - [Configuration file](#configuration-file)
+  - [Configuration options](#configuration-options)
+    - [Miscellaneous](#miscellaneous)
+      - [config](#config)
+      - [verbose](#verbose)
+    - [Scanning](#scanning)
+      - [targets](#targets)
+    - [Reporting](#reporting)
+      - [report to issue](#report-to-issue)
+      - [report to email (TODO #12)](#report-to-email-todo-12)
+      - [report to slack channels](#report-to-slack-channels)
+      - [enable project report to](#enable-project-report-to)
+      - [silent](#silent)
+    - [Tokens](#tokens)
+      - [gitlab token](#gitlab-token)
+      - [slack token](#slack-token)
 - [Supported platforms](#supported-platforms)
   - [Source code hosting services](#source-code-hosting-services)
   - [Messaging services](#messaging-services)
@@ -28,7 +43,7 @@ Sheriff is a tool to scan repositories and generate security reports.
 ## Quick Usage
 
 ```sh
-sheriff patrol --url gitlab://your-namespace-or-group --report-to-issue
+sheriff patrol --target gitlab://your-namespace-or-group --report-to-issue
 ```
 
 ## How it works
@@ -104,16 +119,109 @@ Only the **Reporting** and **Scanning** sections of configuration parameters are
 In this case you may choose to create a config file such as the following:
 
 ```toml
-url = ["namespace/group", "namespace/group/cool-repo"]
-report-to-slack-channel = "sheriff-report-test"
-report-to-gitlab-issue = true
+targets = ["namespace/group", "namespace/group/cool-repo"]
+[report.to]
+slack-channel = "sheriff-report-test"
+issue = true
 ```
 
 And if you wish to specify a different file, you can do so with `sheriff patrol --config your-config-file.toml`.
 
 > [!NOTE]
 > When using several types of configurations at once there is an order of preference: **cli flags** > **env vars** > **config file**
 
+### Configuration options
+
+#### Miscellaneous
+
+##### config
+
+| CLI options | File config |
+|---|---|
+| `--config` | - |
+
+Sets the path of your sheriff configuration file
+
+##### verbose
+
+| CLI options | File config |
+|---|---|
+| `--verbose`/`-v` | - |
+
+Sets the log level to verbose
+
+#### Scanning
+
+##### targets
+
+| CLI options | File config |
+|---|---|
+| (repeatable) `--target` | `targets` |
+
+Sets the list of groups and projects to be scanned.
+The expected format of a target is `platform://path/to/your/group-or-project`
+
+For example:
+`--target gitlab://namespace/group --target github://organization/project`
+
+#### Reporting
+
+##### report to issue
+
+| CLI options | File config |
+|---|---|
+| `--report-to-issue` | <code>[report.to]<br>issue</code> |
+
+Enables reporting to an issue on the project's platform
+
+##### report to email (TODO #12)
+
+| CLI options | File config |
+|---|---|
+| (repeatable) `--report-to-email` | <code>[report.to]<br>emails</code> |
+
+Sets the list of email to which a full scan report should be sent
+
+##### report to slack channels
+
+| CLI options | File config |
+|---|---|
+| (repeatable) `--report-to-slack-channels` | <code>[report.to]<br>slack-channels</code> |
+
+##### enable project report to
+
+| CLI options | File config |
+|---|---|
+| `--report-to-enable-project-report-to` | <code>[report.to]<br>enable-project-report-to</code> |
+
+Enable project-level configuration `report-to` to allow projects to control where their individual reports are sent
+
+##### silent
+
+| CLI options | File config |
+|---|---|
+| `--report-silent` | <code>[report]<br>silent</code> |
+
+Disable printing the report in the bash output
+
+#### Tokens
+
+##### gitlab token
+
+| ENV VAR |
+|---|
+| `$GITLAB_TOKEN` |
+
+Sets the token to be used when fetching projects from gitlab
+
+##### slack token
+
+| ENV VAR |
+|---|
+| `$SLACK_TOKEN` |
+
+Sets the token to be used when reporting the security report on slack
+
 ## Supported platforms
 
 ### Source code hosting services

internal/cli/patrol.go

@@ -26,7 +26,7 @@ const (
 
 const configFlag = "config"
 const verboseFlag = "verbose"
-const urlFlag = "url"
+const targetFlag = "target"
 const reportToEmailFlag = "report-to-email"
 const reportToIssueFlag = "report-to-issue"
 const reportToSlackChannel = "report-to-slack-channel"
@@ -51,7 +51,7 @@ var PatrolFlags = []cli.Flag{
 		Value:    false,
 	},
 	&cli.StringSliceFlag{
-		Name:     urlFlag,
+		Name:     targetFlag,
 		Usage:    "Groups and projects to scan for vulnerabilities (list argument which can be repeated)",
 		Category: string(Scanning),
 	},
@@ -65,9 +65,9 @@ var PatrolFlags = []cli.Flag{
 		Usage:    "Enable or disable reporting to the project's issue on the associated platform (gitlab, github, ...)",
 		Category: string(Reporting),
 	},
-	&cli.StringFlag{
+	&cli.StringSliceFlag{
 		Name:     reportToSlackChannel,
-		Usage:    "Enable reporting to the provided slack channel",
+		Usage:    "Enable reporting to the provided slack channels",
 		Category: string(Reporting),
 	},
 	&cli.BoolFlag{
@@ -101,12 +101,12 @@ var PatrolFlags = []cli.Flag{
 func PatrolAction(cCtx *cli.Context) error {
 	config, err := config.GetPatrolConfiguration(config.PatrolCLIOpts{
 		PatrolCommonOpts: config.PatrolCommonOpts{
-			Urls: getStringSliceIfSet(cCtx, urlFlag),
+			Targets: getStringSliceIfSet(cCtx, targetFlag),
 			Report: config.PatrolReportOpts{
 				To: config.PatrolReportToOpts{
 					Issue:                 getBoolIfSet(cCtx, reportToIssueFlag),
 					Emails:                getStringSliceIfSet(cCtx, reportToEmailFlag),
-					SlackChannel:          getStringIfSet(cCtx, reportToSlackChannel),
+					SlackChannels:         getStringSliceIfSet(cCtx, reportToSlackChannel),
 					EnableProjectReportTo: getBoolIfSet(cCtx, reportEnableProjectReportToFlag),
 				},
 				SilentReport: getBoolIfSet(cCtx, silentReportFlag),

internal/config/patrol.go

@@ -24,7 +24,7 @@ type ProjectLocation struct {
 type PatrolConfig struct {
 	Locations             []ProjectLocation
 	ReportToEmails        []string
-	ReportToSlackChannel  string
+	ReportToSlackChannels []string
 	ReportToIssue         bool
 	EnableProjectReportTo bool
 	SilentReport          bool
@@ -34,7 +34,7 @@ type PatrolConfig struct {
 // Options common in both the CLI options & file options
 type PatrolReportToOpts struct {
 	Emails                *[]string `toml:"emails"`
-	SlackChannel          *string   `toml:"slack-channel"`
+	SlackChannels         *[]string `toml:"slack-channels"`
 	Issue                 *bool     `toml:"issue"`
 	EnableProjectReportTo *bool     `toml:"enable-project-report-to"`
 }
@@ -45,8 +45,8 @@ type PatrolReportOpts struct {
 }
 
 type PatrolCommonOpts struct {
-	Urls   *[]string        `toml:"urls"`
-	Report PatrolReportOpts `toml:"report"`
+	Targets *[]string        `toml:"targets"`
+	Report  PatrolReportOpts `toml:"report"`
 }
 
 // Options only available from CLI configuration
@@ -86,17 +86,17 @@ func GetPatrolConfiguration(cliOpts PatrolCLIOpts) (config PatrolConfig, err err
 }
 
 func mergeConfigs(cliOpts PatrolCLIOpts, fileOpts PatrolFileOpts) (config PatrolConfig, err error) {
-	locations := getCliOrFileOption(cliOpts.Urls, fileOpts.Urls, []string{})
-	parsedLocations, err := parseUrls(locations)
+	locations := getCliOrFileOption(cliOpts.Targets, fileOpts.Targets, []string{})
+	parsedLocations, err := parseTargets(locations)
 	if err != nil {
-		return config, errors.Join(errors.New("could not parse urls from CLI options"), err)
+		return config, errors.Join(errors.New("could not parse targets from CLI options"), err)
 	}
 
 	config = PatrolConfig{
 		Locations:             parsedLocations,
 		ReportToIssue:         getCliOrFileOption(cliOpts.Report.To.Issue, fileOpts.Report.To.Issue, false),
 		ReportToEmails:        getCliOrFileOption(cliOpts.Report.To.Emails, fileOpts.Report.To.Emails, []string{}),
-		ReportToSlackChannel:  getCliOrFileOption(cliOpts.Report.To.SlackChannel, fileOpts.Report.To.SlackChannel, ""),
+		ReportToSlackChannels: getCliOrFileOption(cliOpts.Report.To.SlackChannels, fileOpts.Report.To.SlackChannels, []string{}),
 		EnableProjectReportTo: getCliOrFileOption(cliOpts.Report.To.EnableProjectReportTo, fileOpts.Report.To.EnableProjectReportTo, false),
 		SilentReport:          getCliOrFileOption(cliOpts.Report.SilentReport, fileOpts.Report.SilentReport, false),
 		Verbose:               cliOpts.Verbose,
@@ -118,16 +118,16 @@ func getCliOrFileOption[T interface{}](valueA *T, valueB *T, def T) (r T) {
 	return def
 }
 
-func parseUrls(uris []string) ([]ProjectLocation, error) {
-	locations := make([]ProjectLocation, len(uris))
-	for i, uri := range uris {
-		parsed, err := url.Parse(uri)
+func parseTargets(targets []string) ([]ProjectLocation, error) {
+	locations := make([]ProjectLocation, len(targets))
+	for i, t := range targets {
+		parsed, err := url.Parse(t)
 		if err != nil || parsed == nil {
 			return nil, errors.Join(fmt.Errorf("failed to parse uri"), err)
 		}
 
 		if !parsed.IsAbs() {
-			return nil, fmt.Errorf("url missing platform scheme %v", uri)
+			return nil, fmt.Errorf("target missing platform scheme %v", t)
 		}
 
 		if parsed.Scheme == string(Github) {
@@ -138,7 +138,7 @@ func parseUrls(uris []string) ([]ProjectLocation, error) {
 
 		path, err := url.JoinPath(parsed.Host, parsed.Path)
 		if err != nil {
-			return nil, fmt.Errorf("failed to join host and path %v", uri)
+			return nil, fmt.Errorf("failed to join host and path %v", t)
 		}
 
 		locations[i] = ProjectLocation{

internal/config/patrol_test.go

@@ -1,7 +1,6 @@
 package config
 
 import (
-	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -11,7 +10,7 @@ func TestGetPatrolConfiguration(t *testing.T) {
 	want := PatrolConfig{
 		Locations:             []ProjectLocation{{Type: Gitlab, Path: "group1"}, {Type: Gitlab, Path: "group2/project1"}},
 		ReportToEmails:        []string{"[email protected]"},
-		ReportToSlackChannel:  "report-slack-channel",
+		ReportToSlackChannels: []string{"report-slack-channel"},
 		ReportToIssue:         true,
 		EnableProjectReportTo: true,
 		SilentReport:          true,
@@ -31,7 +30,7 @@ func TestGetPatrolConfigurationCLIOverridesFile(t *testing.T) {
 	want := PatrolConfig{
 		Locations:             []ProjectLocation{{Type: Gitlab, Path: "group1"}, {Type: Gitlab, Path: "group2/project1"}},
 		ReportToEmails:        []string{"[email protected]", "[email protected]"},
-		ReportToSlackChannel:  "other-slack-channel",
+		ReportToSlackChannels: []string{"other-slack-channel"},
 		ReportToIssue:         false,
 		EnableProjectReportTo: false, // Here we test overriding with a zero-value, which works!
 		SilentReport:          false,
@@ -42,11 +41,11 @@ func TestGetPatrolConfigurationCLIOverridesFile(t *testing.T) {
 		Config:  "testdata/patrol/valid.toml",
 		Verbose: true,
 		PatrolCommonOpts: PatrolCommonOpts{
-			Urls: &[]string{"gitlab://group1", "gitlab://group2/project1"},
+			Targets: &[]string{"gitlab://group1", "gitlab://group2/project1"},
 			Report: PatrolReportOpts{
 				To: PatrolReportToOpts{
 					Emails:                &want.ReportToEmails,
-					SlackChannel:          &want.ReportToSlackChannel,
+					SlackChannels:         &want.ReportToSlackChannels,
 					Issue:                 &want.ReportToIssue,
 					EnableProjectReportTo: &want.EnableProjectReportTo,
 				},
@@ -90,18 +89,16 @@ func TestParseUrls(t *testing.T) {
 		{[]string{"github://organization/project"}, &ProjectLocation{Type: "github", Path: "organization/project"}, true},
 		{[]string{"unknown://namespace/project"}, nil, true},
 		{[]string{"unknown://not a path"}, nil, true},
-		{[]string{"not a url"}, nil, true},
+		{[]string{"not a target"}, nil, true},
 	}
 
 	for _, tc := range testCases {
-		urls, err := parseUrls(tc.paths)
-
-		fmt.Print(urls)
+		targets, err := parseTargets(tc.paths)
 
 		if tc.wantError {
 			assert.NotNil(t, err)
 		} else {
-			assert.Equal(t, tc.wantProjectLocation, &(urls[0]))
+			assert.Equal(t, tc.wantProjectLocation, &(targets[0]))
 		}
 	}
 }

internal/config/testdata/patrol/valid.toml

@@ -1,10 +1,10 @@
-urls = ["gitlab://group1", "gitlab://group2/project1"]
+targets = ["gitlab://group1", "gitlab://group2/project1"]
 
 [report]
 silent = true
 
 [report.to]
 emails = ["[email protected]"]
-slack-channel = "report-slack-channel"
+slack-channels = ["report-slack-channel"]
 issue = true
 enable-project-report-to = true

internal/patrol/patrol.go

@@ -73,11 +73,12 @@ func (s *sheriffService) Patrol(args config.PatrolConfig) (warn error, err error
 	}
 
 	if s.slackService != nil {
-		if args.ReportToSlackChannel != "" {
-			log.Info().Str("slackChannel", args.ReportToSlackChannel).Msg("Posting report to slack channel")
+		if len(args.ReportToSlackChannels) > 0 {
+			// TODO #36 support sending to multiple slack channels (for now only the first is sent)
+			log.Info().Str("slackChannel", args.ReportToSlackChannels[0]).Msg("Posting report to slack channel")
 
 			paths := pie.Map(args.Locations, func(v config.ProjectLocation) string { return v.Path })
-			if err := publish.PublishAsGeneralSlackMessage(args.ReportToSlackChannel, scanReports, paths, s.slackService); err != nil {
+			if err := publish.PublishAsGeneralSlackMessage(args.ReportToSlackChannels[0], scanReports, paths, s.slackService); err != nil {
 				log.Error().Err(err).Msg("Failed to post slack report")
 				err = errors.Join(errors.New("failed to post slack report"), err)
 				warn = errors.Join(err, warn)

internal/patrol/patrol_test.go

@@ -34,7 +34,7 @@ func TestScanNoProjects(t *testing.T) {
 	warn, err := svc.Patrol(config.PatrolConfig{
 		Locations:             []config.ProjectLocation{{Type: config.Gitlab, Path: "group/to/scan"}},
 		ReportToEmails:        []string{},
-		ReportToSlackChannel:  "channel",
+		ReportToSlackChannels: []string{"channel"},
 		ReportToIssue:         true,
 		EnableProjectReportTo: true,
 		Verbose:               true,
@@ -67,7 +67,7 @@ func TestScanNonVulnerableProject(t *testing.T) {
 	warn, err := svc.Patrol(config.PatrolConfig{
 		Locations:             []config.ProjectLocation{{Type: config.Gitlab, Path: "group/to/scan"}},
 		ReportToEmails:        []string{},
-		ReportToSlackChannel:  "channel",
+		ReportToSlackChannels: []string{"channel"},
 		ReportToIssue:         true,
 		EnableProjectReportTo: true,
 		Verbose:               true,
@@ -108,7 +108,7 @@ func TestScanVulnerableProject(t *testing.T) {
 	warn, err := svc.Patrol(config.PatrolConfig{
 		Locations:             []config.ProjectLocation{{Type: config.Gitlab, Path: "group/to/scan"}},
 		ReportToEmails:        []string{},
-		ReportToSlackChannel:  "channel",
+		ReportToSlackChannels: []string{"channel"},
 		ReportToIssue:         true,
 		EnableProjectReportTo: true,
 		Verbose:               true,

internal/publish/to_slack.go

@@ -140,7 +140,7 @@ func formatSummary(reportsBySeverityKind map[scanner.SeverityScoreKind][]scanner
 			true, false,
 		),
 	)
-	subtitleGroups := formatSubtitleList("urls", paths)
+	subtitleGroups := formatSubtitleList("targets", paths)
 	subtitleCount := goslack.NewContextBlock("subtitleCount", goslack.NewTextBlockObject("mrkdwn", fmt.Sprintf("Total projects scanned: %v", totalReports), false, false))
 
 	counts := pie.Map(severityScoreOrder, func(kind scanner.SeverityScoreKind) *goslack.TextBlockObject {