Log explanation of non-zero exit with found results (trufflesecurity#431

)

* Log explanation of non-zero exit with found results

* Change exit code and add documentation

* Adjust exit code handling

* Make action fail on found results

* Use new overseer

* Improve wording

* Update README.md

README.md

@@ -138,6 +138,10 @@ For example, to scan a  `git` repository, start with
 $ trufflehog git https://github.com/trufflesecurity/trufflehog.git
 ```
 
+Exit Codes:
+- 0: No errors and no results were found.
+- 1: An error was encountered. Sources may not have completed scans.
+- 183: No errors were encountered, but results were found. Will only be returned if `--fail` flag is used.
 
 #### Scanning an organization
 

action.yml

@@ -25,3 +25,4 @@ runs:
     - ${{ inputs.base }}
     - --branch
     - ${{ inputs.head }}
+    - --fail

go.mod

@@ -2,7 +2,7 @@ module github.com/trufflesecurity/trufflehog/v3
 
 go 1.17
 
-replace github.com/jpillora/overseer => github.com/trufflesecurity/overseer v1.1.7-custom4
+replace github.com/jpillora/overseer => github.com/trufflesecurity/overseer v1.1.7-custom5
 
 replace github.com/zricethezav/gitleaks/v8 => github.com/trufflesecurity/gitleaks/v8 v8.6.1-custom3
 

go.sum

@@ -449,8 +449,8 @@ github.com/tailscale/depaware v0.0.0-20210622194025-720c4b409502 h1:34icjjmqJ2HP
 github.com/tailscale/depaware v0.0.0-20210622194025-720c4b409502/go.mod h1:p9lPsd+cx33L3H9nNoecRRxPssFKUwwI50I3pZ0yT+8=
 github.com/trufflesecurity/gitleaks/v8 v8.6.1-custom3 h1:Xc61NkfI7aDHd8eHa0gglK0ZVF5UF54M4u4C5tuAKcw=
 github.com/trufflesecurity/gitleaks/v8 v8.6.1-custom3/go.mod h1:Em2rda83ePrhmaX4ZdvNjnUADRiOJirEAqln0ZtN8og=
-github.com/trufflesecurity/overseer v1.1.7-custom4 h1:5ed5+2+N3ZaW7oc4n7PIjkybGHUZmdCH9iAztB/2+Cc=
-github.com/trufflesecurity/overseer v1.1.7-custom4/go.mod h1:nT9w37AiO1Nop2VhVhNfzAFaPjthvxgpDV3XKsxYkcI=
+github.com/trufflesecurity/overseer v1.1.7-custom5 h1:xu+Fg6fkSRifUPzUCl7N8HmobJ6WGOkIApGnM7mJS6w=
+github.com/trufflesecurity/overseer v1.1.7-custom5/go.mod h1:nT9w37AiO1Nop2VhVhNfzAFaPjthvxgpDV3XKsxYkcI=
 github.com/xanzy/go-gitlab v0.63.0 h1:a9fXpKWykUS6dowapFej/2Wjf4aOAEFC1q2ZIcz4IpI=
 github.com/xanzy/go-gitlab v0.63.0/go.mod h1:F0QEXwmqiBUxCgJm8fE9S+1veX4XC9Z4cfaAbqwk4YM=
 github.com/xanzy/ssh-agent v0.3.0 h1:wUMzuKtKilRgBAD1sUb8gOwwRr2FGoBVumcjoOACClI=

main.go

@@ -42,6 +42,7 @@ var (
 	// rules = cli.Flag("rules", "Path to file with custom rules.").String()
 	printAvgDetectorTime = cli.Flag("print-avg-detector-time", "Print the average time spent on each detector.").Bool()
 	noUpdate             = cli.Flag("no-update", "Don't check for updates.").Bool()
+	fail                 = cli.Flag("fail", "Exit with code 183 if results are found.").Bool()
 
 	gitScan             = cli.Command("git", "Find credentials in git repositories.")
 	gitScanURI          = gitScan.Arg("uri", "Git repository URL. https:// or file:// schema expected.").Required().String()
@@ -240,8 +241,9 @@ func run(state overseer.State) {
 		printAverageDetectorTime(e)
 	}
 
-	if foundResults {
-		os.Exit(1)
+	if foundResults && *fail {
+		logrus.Debug("exiting with code 183 because results were found")
+		os.Exit(183)
 	}
 }