Add --fail-on-violation flag to exit non-zero when violations are detected (#392)

* Add --fail-on-violation flag to exit non-zero when violations are detected

poutine always exited with code 0 after analysis, even when violations were found, making it unsuitable for use as a blocking CI gate. This adds an opt-in --fail-on-violation flag that exits with code 10 when violations are detected.

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Signed-off-by: Mikaël Barbero <mikael.barbero@eclipse-foundation.org>

* Address PR review feedback for --fail-on-violation

- Add SilenceUsage to prevent Cobra printing usage text on errors
- Extract checkViolations helper to deduplicate violation checks
- Improve error message from empty Msg("") to Msg("command failed")
- Rewrite tests to exercise checkViolations directly
- Fix missing space in README "organization (analyze_org)"

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Signed-off-by: Mikaël Barbero <mikael.barbero@eclipse-foundation.org>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: François Proulx <francois@boostsecurity.io>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 4 people

README.md

@@ -105,15 +105,16 @@ poutine analyze_org my-org/project --token "$GL_TOKEN" --scm gitlab --scm-base-u
 ### Configuration Options
 
 ```
---token          SCM access token (required for the commands analyze_repo, analyze_org) (env: GH_TOKEN)
---format         Output format (default: pretty, json, sarif)
---ignore-forks   Ignore forked repositories in the organization(analyze_org)
---scm            SCM platform (default: github, gitlab)
---scm-base-url   Base URI of the self-hosted SCM instance
---threads        Number of threads to use (default: 2)
---config         Path to the configuration file (default: .poutine.yml)
---skip           Add rules to the skip list for the current run (can be specified multiple times)
---verbose        Enable debug logging
+--token              SCM access token (required for the commands analyze_repo, analyze_org) (env: GH_TOKEN)
+--format             Output format (default: pretty, json, sarif)
+--ignore-forks       Ignore forked repositories in the organization (analyze_org)
+--scm                SCM platform (default: github, gitlab)
+--scm-base-url       Base URI of the self-hosted SCM instance
+--threads            Number of threads to use (default: 2)
+--config             Path to the configuration file (default: .poutine.yml)
+--skip               Add rules to the skip list for the current run (can be specified multiple times)
+--verbose            Enable debug logging
+--fail-on-violation  Exit with a non-zero code (10) when violations are found
 ```
 
 See [.poutine.sample.yml](.poutine.sample.yml) for an example configuration file.

cmd/analyzeLocal.go

@@ -37,11 +37,15 @@ Example: poutine analyze_local /path/to/repo`,
 
 		analyzer := analyze.NewAnalyzer(localScmClient, localGitClient, formatter, config, opaClient)
 
-		_, err = analyzer.AnalyzeLocalRepo(ctx, repoPath)
+		result, err := analyzer.AnalyzeLocalRepo(ctx, repoPath)
 		if err != nil {
 			return fmt.Errorf("failed to analyze repoPath %s: %w", repoPath, err)
 		}
 
+		if err := checkViolations(result); err != nil {
+			return err
+		}
+
 		return nil
 	},
 }

cmd/analyzeOrg.go

@@ -32,11 +32,15 @@ Note: This command will scan all repositories in the organization except those t
 
 		org := args[0]
 
-		_, err = analyzer.AnalyzeOrg(ctx, org, &threads)
+		results, err := analyzer.AnalyzeOrg(ctx, org, &threads)
 		if err != nil {
 			return fmt.Errorf("failed to analyze org %s: %w", org, err)
 		}
 
+		if err := checkViolations(results...); err != nil {
+			return err
+		}
+
 		return nil
 	},
 }

cmd/analyzeRepo.go

@@ -26,11 +26,15 @@ Example Scanning a remote Github Repository: poutine analyze_repo org/repo --tok
 
 		repo := args[0]
 
-		_, err = analyzer.AnalyzeRepo(ctx, repo, ref)
+		result, err := analyzer.AnalyzeRepo(ctx, repo, ref)
 		if err != nil {
 			return fmt.Errorf("failed to analyze repo %s: %w", repo, err)
 		}
 
+		if err := checkViolations(result); err != nil {
+			return err
+		}
+
 		return nil
 	},
 }

cmd/analyzeRepoStaleBranches.go

@@ -37,11 +37,15 @@ Example Scanning a remote Github Repository: poutine analyze_repo_stale_branches
 			return fmt.Errorf("error compiling regex: %w", err)
 		}
 
-		_, err = analyzer.AnalyzeStaleBranches(ctx, repo, &threads, &expand, reg)
+		result, err := analyzer.AnalyzeStaleBranches(ctx, repo, &threads, &expand, reg)
 		if err != nil {
 			return fmt.Errorf("failed to analyze repo %s: %w", repo, err)
 		}
 
+		if err := checkViolations(result); err != nil {
+			return err
+		}
+
 		return nil
 	},
 }

cmd/fail_on_violation_test.go

@@ -0,0 +1,102 @@
+package cmd
+
+import (
+	"testing"
+
+	"github.com/boostsecurityio/poutine/models"
+	"github.com/boostsecurityio/poutine/results"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestErrViolationsFound(t *testing.T) {
+	require.EqualError(t, ErrViolationsFound, "poutine: violations found")
+	assert.Implements(t, (*error)(nil), ErrViolationsFound)
+}
+
+func TestExitCodeViolations(t *testing.T) {
+	assert.Equal(t, 10, exitCodeViolations)
+}
+
+func TestFailOnViolationFlag(t *testing.T) {
+	flag := RootCmd.PersistentFlags().Lookup("fail-on-violation")
+	require.NotNil(t, flag, "--fail-on-violation flag should be registered")
+	assert.Equal(t, "false", flag.DefValue, "--fail-on-violation should default to false")
+}
+
+func TestCheckViolations(t *testing.T) {
+	pkgWithFindings := &models.PackageInsights{
+		FindingsResults: results.FindingsResult{
+			Findings: []results.Finding{
+				{RuleId: "injection", Purl: "pkg:github/example/repo"},
+			},
+		},
+	}
+	pkgNoFindings := &models.PackageInsights{
+		FindingsResults: results.FindingsResult{
+			Findings: []results.Finding{},
+		},
+	}
+
+	t.Run("returns nil when failOnViolation is false", func(t *testing.T) {
+		failOnViolation = false
+		defer func() { failOnViolation = false }()
+
+		assert.NoError(t, checkViolations(pkgWithFindings))
+	})
+
+	t.Run("returns ErrViolationsFound when findings exist", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		assert.ErrorIs(t, checkViolations(pkgWithFindings), ErrViolationsFound)
+	})
+
+	t.Run("returns nil when no findings", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		assert.NoError(t, checkViolations(pkgNoFindings))
+	})
+
+	t.Run("returns nil for nil package", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		assert.NoError(t, checkViolations(nil))
+	})
+
+	t.Run("returns nil when called with no args", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		assert.NoError(t, checkViolations())
+	})
+}
+
+func TestCheckViolationsOrg(t *testing.T) {
+	pkgWithFindings := &models.PackageInsights{
+		FindingsResults: results.FindingsResult{
+			Findings: []results.Finding{
+				{RuleId: "injection", Purl: "pkg:github/example/repo"},
+			},
+		},
+	}
+	pkgNoFindings := &models.PackageInsights{}
+
+	t.Run("returns ErrViolationsFound when any package has findings", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		err := checkViolations(pkgNoFindings, pkgWithFindings)
+		assert.ErrorIs(t, err, ErrViolationsFound)
+	})
+
+	t.Run("returns nil when no packages have findings", func(t *testing.T) {
+		failOnViolation = true
+		defer func() { failOnViolation = false }()
+
+		err := checkViolations(pkgNoFindings, pkgNoFindings)
+		assert.NoError(t, err)
+	})
+}

cmd/root.go

@@ -3,6 +3,7 @@ package cmd
 import (
 	"context"
 	"embed"
+	"errors"
 	"fmt"
 	"os"
 	"os/signal"
@@ -42,18 +43,39 @@ var cfgFile string
 var config *models.Config = models.DefaultConfig()
 var skipRules []string
 var allowedRules []string
+var failOnViolation bool
+
+// ErrViolationsFound is returned when violations are detected and --fail-on-violation is set.
+var ErrViolationsFound = errors.New("poutine: violations found")
+
+// checkViolations returns ErrViolationsFound if --fail-on-violation is set
+// and any of the provided packages contain findings.
+func checkViolations(pkgs ...*models.PackageInsights) error {
+	if !failOnViolation {
+		return nil
+	}
+	for _, pkg := range pkgs {
+		if pkg != nil && len(pkg.FindingsResults.Findings) > 0 {
+			return ErrViolationsFound
+		}
+	}
+	return nil
+}
 
 var legacyFlags = []string{"-token", "-format", "-verbose", "-scm", "-scm-base-uri", "-threads"}
 
 const (
-	exitCodeErr       = 1
-	exitCodeInterrupt = 2
+	exitCodeErr        = 1
+	exitCodeInterrupt  = 2
+	exitCodeViolations = 10
 )
 
 // RootCmd represents the base command when called without any subcommands
 var RootCmd = &cobra.Command{
-	Use:   "poutine",
-	Short: "A Supply Chain Vulnerability Scanner for Build Pipelines",
+	Use:           "poutine",
+	SilenceUsage:  true,
+	SilenceErrors: true,
+	Short:         "A Supply Chain Vulnerability Scanner for Build Pipelines",
 	Long: `A Supply Chain Vulnerability Scanner for Build Pipelines
 By BoostSecurity.io - https://github.com/boostsecurityio/poutine `,
 	PersistentPreRun: func(cmd *cobra.Command, args []string) {
@@ -95,7 +117,11 @@ func Execute() {
 
 	err := RootCmd.ExecuteContext(ctx)
 	if err != nil {
-		log.Error().Err(err).Msg("")
+		if errors.Is(err, ErrViolationsFound) {
+			log.Info().Msg("violations found")
+			os.Exit(exitCodeViolations)
+		}
+		log.Error().Err(err).Msg("command failed")
 		os.Exit(exitCodeErr)
 	}
 }
@@ -120,6 +146,7 @@ func init() {
 	RootCmd.PersistentFlags().BoolVarP(&config.Quiet, "quiet", "q", false, "Disable progress output")
 	RootCmd.PersistentFlags().StringSliceVar(&skipRules, "skip", []string{}, "Adds rules to the configured skip list for the current run (optional)")
 	RootCmd.PersistentFlags().StringSliceVar(&allowedRules, "allowed-rules", []string{}, "Overwrite the configured allowedRules list for the current run (optional)")
+	RootCmd.PersistentFlags().BoolVar(&failOnViolation, "fail-on-violation", false, "Exit with a non-zero code (10) when violations are found")
 
 	_ = viper.BindPFlag("quiet", RootCmd.PersistentFlags().Lookup("quiet"))
 }