docs: add bearer ignore (#1182)

* docs: add bearer ignore to commands page

* docs: replace exclude-fingerprint with bearer ignore

* fix: update stale snapshots

* docs: add warning message in security report if legacy ignore functionality is used

* fix: remove unused doc page

* docs: add ignore migrate page

* fix: prefer sprintf to concatenation

* fix:  mark exclude-fingerprints flag as deprecated

* fix: replace space with underscore for ignore docs

docs/_data/bearer.yaml

@@ -5,6 +5,7 @@ options:
       default_value: "false"
       usage: help for this command
 see_also:
+    - ' ignore - Manage ignored fingerprints'
     - ' init - Generates a default config to `bearer.yml`'
     - ' scan - Scan a directory or file'
     - ' version - Print the version'

docs/_data/bearer_ignore_add.yaml

@@ -0,0 +1,23 @@
+name: ' ignore add'
+synopsis: Add an ignored fingerprint
+usage: ' ignore add <fingerprint> [flags]'
+options:
+    - name: author
+      shorthand: a
+      usage: |
+        Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+    - name: comment
+      usage: Add a comment to this ignored finding.
+    - name: force
+      default_value: "false"
+      usage: Overwrite an existing ignored finding.
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for add
+example: |-
+    # Add an ignored fingerprint to your bearer.ignore file
+    $ bearer ignore add <fingerprint> --author Mish --comment "Possible false positive"
+see_also:
+    - ' ignore - Manage ignored fingerprints'
+aliases: 

docs/_data/bearer_ignore_migrate.yaml

@@ -0,0 +1,21 @@
+name: ' ignore migrate'
+synopsis: |
+    Migrate ignored fingerprints from bearer.yml to bearer.ignore
+usage: ' ignore migrate [flags]'
+options:
+    - name: config-file
+      default_value: bearer.yml
+      usage: Load configuration from the specified path.
+    - name: force
+      default_value: "false"
+      usage: Overwrite an existing ignored finding.
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for migrate
+example: |-
+    # Migrate existing ignored (excluded) fingerprints from bearer.yml file to bearer.ignore
+    $ bearer ignore migrate
+see_also:
+    - ' ignore - Manage ignored fingerprints'
+aliases:

docs/_data/bearer_ignore_show.yaml

@@ -0,0 +1,14 @@
+name: ' ignore show'
+synopsis: Show an ignored fingerprint
+usage: ' ignore show <fingerprint> [flags]'
+options:
+    - name: help
+      shorthand: h
+      default_value: "false"
+      usage: help for show
+example: |-
+    # Show the details of an ignored fingerprint from your bearer.ignore file
+    $ bearer ignore show <fingerprint>
+see_also:
+    - ' ignore - Manage ignored fingerprints'
+aliases: 

docs/guides/configure-scan.md

@@ -48,30 +48,25 @@ See our [guide to using the GitHub action](/guides/github-action/#pull-request-d
 [guide to using GitLab](/guides/gitlab/#gitlab-merge-request-diff) for
 information on using this feature with those services.
 
-## Exclude specific findings
+## Ignore specific findings
 
 Every finding is associated with a unique fingerprint visible directly in the CLI output, for example:
 
 ```bash
 HIGH: SQL injection vulnerability detected. [CWE-89]
 https://docs.bearer.com/reference/rules/javascript_lang_sql_injection
-To exclude this finding, use the flag --exclude-fingerprint=4b0883d52334dfd9a4acce2fcf810121_0
+To ignore this finding, run: bearer ignore add 4b0883d52334dfd9a4acce2fcf810121_0
 ...
 ```
 
-If a finding is not relevant, you can exclude it by using the `--exclude-fingerprint` command, for example:
+If a finding is not relevant, you can ignore it automatically from future scans using the ```bearer ignore add``` command. This adds the finding's fingerprint to your bearer.ignore file. You can also provide optional author information or a comment:
+
 ```bash
-bearer scan . --exclude-fingerprint=4b0883d52334dfd9a4acce2fcf810121_0
+bearer ignore add 4b0883d52334dfd9a4acce2fcf810121_0 \
+  --author="Mish Bear" \
+  --comment="Ignore this finding"
 ```
 
-If you want to exclude findings automatically from future scans, you can add them to your [bearer config](/reference/config) file in the ```exclude-fingerprint``` node:
-
-```yml
-report:
-  exclude-fingerprint:
-    - 4b0883d52334dfd9a4acce2fcf810121_0
-    - 42a76a8c10a52b38c1b8729a2f211830_0
-```
 <br/>
 {% callout "info" %} If you're looking for more options when it comes to managing findings, take a look at <a href="/guides/bearer-cloud">Bearer Cloud</a>. {% endcallout %}
 

docs/reference/commands.njk

@@ -6,7 +6,7 @@ layout: layouts/doc.njk
 They can be found here: https://github.com/Bearer/bearer/tree/main/pkg/commands
  #}
 
-{% set items = [bearer_scan, bearer_init, bearer_version] %}
+{% set items = [bearer_scan, bearer_init, bearer_ignore_add, bearer_ignore_show, bearer_ignore_migrate, bearer_version] %}
 {% renderTemplate "md" %}
 # Commands
 
@@ -15,13 +15,13 @@ Bearer CLI offers a number of commands to use and customize the CLI to your need
 <ul>
   {% for item in items %}
     <li>
-      <a href="#{{ item.name | trim}}">{{ item.name | trim}}</a>: {{item.synopsis}}
+      <a href="#{{ item.name | trim | replace(" ", "_") }}">{{ item.name | trim}}</a>: {{item.synopsis}}
     </li>
   {% endfor %}
 </ul>
 
 {% for item in items %}
-  <h2 class="inline-block text-neutral-100 bg-code p-1 rounded-md leading-none font-mono" id="{{ item.name | trim | e}}">bearer {{ item.name | trim | escape }}</h2>
+  <h2 class="inline-block text-neutral-100 bg-code p-1 rounded-md leading-none font-mono" id="{{ item.name | trim | e | replace(" ", "_")}}">bearer {{ item.name | trim | escape }}</h2>
 
   <p>{{item.synopsis}}</p>
 

docs/reference/config.md

@@ -18,8 +18,6 @@ This creates a config file in your current directory. Below is an annotated vers
 ```yml
 # Report settings
 report:
-    # Specify fingerprints of the findings you would like to exclude.
-    exclude-fingerprint: []
     # Specify report format (json, yaml, sarif, gitlab-sast)
     format: ""
     # Specify the output path for the report.

e2e/flags/.snapshots/TestInitCommand

@@ -1,6 +1,5 @@
 disable-version-check: false
 report:
-    exclude-fingerprint: []
     format: ""
     no-color: false
     output: ""

e2e/flags/.snapshots/TestMetadataFlags-help-scan

@@ -10,11 +10,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

e2e/flags/.snapshots/TestMetadataFlags-scan-help

@@ -10,11 +10,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-context-flag

@@ -11,11 +11,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-privacy

@@ -11,11 +11,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-security

@@ -11,11 +11,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-report-flag

@@ -11,11 +11,10 @@ Examples:
 
 
 Report Flags
-      --exclude-fingerprint strings   Specify the comma-separated fingerprints of the findings you would like to exclude from the report.
-  -f, --format string                 Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
-      --output string                 Specify the output path for the report.
-      --report string                 Specify the type of report (security, privacy, dataflow). (default "security")
-      --severity string               Specify which severities are included in the report. (default "critical,high,medium,low,warning")
+  -f, --format string     Specify report format (json, yaml, sarif, gitlab-sast, rdjson, html)
+      --output string     Specify the output path for the report.
+      --report string     Specify the type of report (security, privacy, dataflow). (default "security")
+      --severity string   Specify which severities are included in the report. (default "critical,high,medium,low,warning")
 
 Rule Flags
       --disable-default-rules   Disables all default and built-in rules.

pkg/flag/report_flags.go

@@ -58,10 +58,13 @@ var (
 		Usage:      "Specify which severities are included in the report.",
 	}
 	ExcludeFingerprintFlag = Flag{
-		Name:       "exclude-fingerprint",
-		ConfigName: "report.exclude-fingerprint",
-		Value:      []string{},
-		Usage:      "Specify the comma-separated fingerprints of the findings you would like to exclude from the report.",
+		Name:            "exclude-fingerprint",
+		ConfigName:      "report.exclude-fingerprint",
+		Value:           []string{},
+		Usage:           "Specify the comma-separated fingerprints of the findings you would like to exclude from the report.",
+		DisableInConfig: true,
+		Hide:            true,
+		Deprecated:      true,
 	}
 )
 

pkg/report/output/security/.snapshots/TestBuildReportString

@@ -12,15 +12,15 @@ Language  Default Rules  Custom Rules  Files
 
 CRITICAL: Sensitive data sent to Rails loggers detected. [CWE-209, CWE-532]
 https://docs.bearer.com/reference/rules/ruby_rails_logger
-To exclude this finding, use the flag --exclude-fingerprint=375d7c2e9977cf2ce5dbf04b04237bea_0
+To ignore this finding, run: bearer ignore add 375d7c2e9977cf2ce5dbf04b04237bea_0
 
 File: :1
 
 
 
 HIGH: Missing SSL certificate verification detected. [CWE-295]
 https://docs.bearer.com/reference/rules/ruby_lang_ssl_verification
-To exclude this finding, use the flag --exclude-fingerprint=9005ef3db844b32c1a0317e032f4a16a_0
+To ignore this finding, run: bearer ignore add 9005ef3db844b32c1a0317e032f4a16a_0
 
 File: :2
 

pkg/report/output/security/security.go

@@ -148,20 +148,7 @@ func GetOutput(
 	}
 
 	if !config.Scan.Quiet {
-		fingerprints = append(fingerprints, builtInFingerprints...)
-		unusedFingerprints := removeUnusedFingerprints(
-			fingerprints,
-			config.Report.ExcludeFingerprint,
-			config.IgnoredFingerprints,
-		)
-		if len(unusedFingerprints) > 0 {
-			output.StdErrLog("\n=====================================\n")
-			output.StdErrLog(fmt.Sprintf("%d excluded fingerprints present in your Bearer configuration file are no longer detected:", len(unusedFingerprints)))
-			for _, fingerprint := range unusedFingerprints {
-				output.StdErrLog(fmt.Sprintf("  - %s", fingerprint))
-			}
-			output.StdErrLog("\n=====================================")
-		}
+		fingerprintOutput(append(fingerprints, builtInFingerprints...), config.Report.ExcludeFingerprint, config.IgnoredFingerprints)
 	}
 
 	// fail the report if we have failures above the severity threshold
@@ -316,25 +303,59 @@ func evaluateRules(
 	return fingerprints, nil
 }
 
+func fingerprintOutput(fingerprints []string, legacyExcludedFingerprints map[string]bool, ignoredFingerprints map[string]ignore.IgnoredFingerprint) {
+	unusedFingerprints, unusedLegacyFingerprints := removeUnusedFingerprints(
+		fingerprints,
+		legacyExcludedFingerprints,
+		ignoredFingerprints,
+	)
+	if len(legacyExcludedFingerprints) > 0 || len(unusedFingerprints) > 0 || len(unusedLegacyFingerprints) > 0 {
+		output.StdErrLog("\n=====================================\n")
+		// legacy
+		if len(legacyExcludedFingerprints) > 0 {
+			output.StdErrLog("\nNote: exclude_fingerprints is legacy. To use new ignore functionality, run bearer ignore migrate. See https://docs.bearer.com/reference/commands/#ignore_migrate.\n\n")
+		}
+
+		if len(unusedLegacyFingerprints) > 0 {
+			output.StdErrLog(fmt.Sprintf("%d ignored fingerprints present in your Bearer Configuration file are no longer detected:", len(unusedLegacyFingerprints)))
+			for _, fingerprint := range unusedLegacyFingerprints {
+				output.StdErrLog(fmt.Sprintf("  - %s", fingerprint))
+			}
+		}
+		// end legacy
+
+		if len(unusedFingerprints) > 0 {
+			output.StdErrLog(fmt.Sprintf("%d ignored fingerprints present in your bearer.ignore file are no longer detected:", len(unusedFingerprints)))
+			for _, fingerprint := range unusedFingerprints {
+				output.StdErrLog(fmt.Sprintf("  - %s", fingerprint))
+			}
+		}
+		output.StdErrLog("\n=====================================")
+	}
+}
+
 func removeUnusedFingerprints(
 	detectedFingerprints []string,
 	excludeFingerprints map[string]bool,
-	ignoredFingerprints map[string]ignore.IgnoredFingerprint) []string {
-	filteredFingerprints := make(map[string]bool)
+	ignoredFingerprints map[string]ignore.IgnoredFingerprint) ([]string, []string) {
 
-	for fingerprint := range excludeFingerprints {
+	filteredBearerIgnoreFingerprints := make(map[string]bool)
+	for fingerprint := range ignoredFingerprints {
 		if !slices.Contains(detectedFingerprints, fingerprint) {
-			filteredFingerprints[fingerprint] = true
+			filteredBearerIgnoreFingerprints[fingerprint] = true
 		}
 	}
 
-	for fingerprint := range ignoredFingerprints {
+	// legacy
+	filteredExcludeFingerprints := make(map[string]bool)
+	for fingerprint := range excludeFingerprints {
 		if !slices.Contains(detectedFingerprints, fingerprint) {
-			filteredFingerprints[fingerprint] = true
+			filteredExcludeFingerprints[fingerprint] = true
 		}
 	}
+	// end legacy
 
-	return maps.Keys(filteredFingerprints)
+	return maps.Keys(filteredBearerIgnoreFingerprints), maps.Keys(filteredExcludeFingerprints)
 }
 
 func getExtract(rawCodeExtract []file.Line) string {
@@ -679,7 +700,7 @@ func writeFailureToString(reportStr *strings.Builder, result Result, severity st
 		reportStr.WriteString(color.HiBlackString(result.DocumentationUrl + "\n"))
 	}
 
-	reportStr.WriteString(color.HiBlackString("To exclude this finding, use the flag --exclude-fingerprint=" + result.Fingerprint + "\n"))
+	reportStr.WriteString(color.HiBlackString("To ignore this finding, run: bearer ignore add " + result.Fingerprint + "\n"))
 	reportStr.WriteString("\n")
 	if result.DetailedContext != "" {
 		reportStr.WriteString("Detected: " + result.DetailedContext + "\n\n")