From 56e56e2e21a8b8352171ce5623c93e28cd7b4d09 Mon Sep 17 00:00:00 2001 From: elsapet Date: Mon, 21 Aug 2023 15:58:12 +0200 Subject: [PATCH] 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 | 1 + docs/_data/bearer_ignore_add.yaml | 23 +++++++ docs/_data/bearer_ignore_migrate.yaml | 21 ++++++ docs/_data/bearer_ignore_show.yaml | 14 ++++ docs/guides/configure-scan.md | 19 ++---- docs/reference/commands.njk | 6 +- docs/reference/config.md | 2 - e2e/flags/.snapshots/TestInitCommand | 1 - .../.snapshots/TestMetadataFlags-help-scan | 9 ++- .../.snapshots/TestMetadataFlags-scan-help | 9 ++- ...ReportFlagsShouldFail-invalid-context-flag | 9 ++- ...lagsShouldFail-invalid-format-flag-privacy | 9 ++- ...agsShouldFail-invalid-format-flag-security | 9 ++- ...tReportFlagsShouldFail-invalid-report-flag | 9 ++- pkg/flag/report_flags.go | 11 ++-- .../security/.snapshots/TestBuildReportString | 4 +- pkg/report/output/security/security.go | 65 ++++++++++++------- scripts/gen-doc-yaml.go | 10 ++- 18 files changed, 154 insertions(+), 77 deletions(-) create mode 100644 docs/_data/bearer_ignore_add.yaml create mode 100644 docs/_data/bearer_ignore_migrate.yaml create mode 100644 docs/_data/bearer_ignore_show.yaml diff --git a/docs/_data/bearer.yaml b/docs/_data/bearer.yaml index 22656fded..0cb801c5d 100644 --- a/docs/_data/bearer.yaml +++ b/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' diff --git a/docs/_data/bearer_ignore_add.yaml b/docs/_data/bearer_ignore_add.yaml new file mode 100644 index 000000000..eb4bb00c2 --- /dev/null +++ b/docs/_data/bearer_ignore_add.yaml @@ -0,0 +1,23 @@ +name: ' ignore add' +synopsis: Add an ignored fingerprint +usage: ' ignore add [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 --author Mish --comment "Possible false positive" +see_also: + - ' ignore - Manage ignored fingerprints' +aliases: diff --git a/docs/_data/bearer_ignore_migrate.yaml b/docs/_data/bearer_ignore_migrate.yaml new file mode 100644 index 000000000..428d14198 --- /dev/null +++ b/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: diff --git a/docs/_data/bearer_ignore_show.yaml b/docs/_data/bearer_ignore_show.yaml new file mode 100644 index 000000000..757c4d90d --- /dev/null +++ b/docs/_data/bearer_ignore_show.yaml @@ -0,0 +1,14 @@ +name: ' ignore show' +synopsis: Show an ignored fingerprint +usage: ' ignore show [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 +see_also: + - ' ignore - Manage ignored fingerprints' +aliases: diff --git a/docs/guides/configure-scan.md b/docs/guides/configure-scan.md index 2da936779..3e6cf98c3 100644 --- a/docs/guides/configure-scan.md +++ b/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 -```
{% callout "info" %} If you're looking for more options when it comes to managing findings, take a look at Bearer Cloud. {% endcallout %} diff --git a/docs/reference/commands.njk b/docs/reference/commands.njk index cee10ef77..b4ed2449d 100644 --- a/docs/reference/commands.njk +++ b/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 {% for item in items %} -

bearer {{ item.name | trim | escape }}

+

bearer {{ item.name | trim | escape }}

{{item.synopsis}}

diff --git a/docs/reference/config.md b/docs/reference/config.md index e4dffe787..ac360dfa2 100644 --- a/docs/reference/config.md +++ b/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. diff --git a/e2e/flags/.snapshots/TestInitCommand b/e2e/flags/.snapshots/TestInitCommand index d991935f6..4260c415a 100644 --- a/e2e/flags/.snapshots/TestInitCommand +++ b/e2e/flags/.snapshots/TestInitCommand @@ -1,6 +1,5 @@ disable-version-check: false report: - exclude-fingerprint: [] format: "" no-color: false output: "" diff --git a/e2e/flags/.snapshots/TestMetadataFlags-help-scan b/e2e/flags/.snapshots/TestMetadataFlags-help-scan index 1eadafc84..0e7301715 100644 --- a/e2e/flags/.snapshots/TestMetadataFlags-help-scan +++ b/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. diff --git a/e2e/flags/.snapshots/TestMetadataFlags-scan-help b/e2e/flags/.snapshots/TestMetadataFlags-scan-help index 1eadafc84..0e7301715 100644 --- a/e2e/flags/.snapshots/TestMetadataFlags-scan-help +++ b/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. diff --git a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-context-flag b/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-context-flag index 001edeb66..b8067898b 100644 --- a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-context-flag +++ b/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. diff --git a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-privacy b/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-privacy index 24f03a1b7..e0a0040df 100644 --- a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-privacy +++ b/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. diff --git a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-security b/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-security index 2c40cf5e4..6f354b34f 100644 --- a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-format-flag-security +++ b/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. diff --git a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-report-flag b/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-report-flag index 9d888d911..f2d8ac8bf 100644 --- a/e2e/flags/.snapshots/TestReportFlagsShouldFail-invalid-report-flag +++ b/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. diff --git a/pkg/flag/report_flags.go b/pkg/flag/report_flags.go index 4e33e2ae2..662cf6d39 100644 --- a/pkg/flag/report_flags.go +++ b/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, } ) diff --git a/pkg/report/output/security/.snapshots/TestBuildReportString b/pkg/report/output/security/.snapshots/TestBuildReportString index 7a1624ad8..c4defd86e 100644 --- a/pkg/report/output/security/.snapshots/TestBuildReportString +++ b/pkg/report/output/security/.snapshots/TestBuildReportString @@ -12,7 +12,7 @@ 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 @@ -20,7 +20,7 @@ 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 diff --git a/pkg/report/output/security/security.go b/pkg/report/output/security/security.go index d0e9c5a30..42f3864a2 100644 --- a/pkg/report/output/security/security.go +++ b/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") diff --git a/scripts/gen-doc-yaml.go b/scripts/gen-doc-yaml.go index 3608441d2..40852326c 100644 --- a/scripts/gen-doc-yaml.go +++ b/scripts/gen-doc-yaml.go @@ -33,6 +33,14 @@ func writeDocs(cmd *cobra.Command, dir string) error { if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { continue } + if c.HasSubCommands() { + for _, subCmd := range c.Commands() { + if err := writeDocs(subCmd, dir); err != nil { + return err + } + } + continue + } if err := writeDocs(c, dir); err != nil { return err } @@ -42,7 +50,7 @@ func writeDocs(cmd *cobra.Command, dir string) error { basename := "bearer.yaml" if cmd.CommandPath() != "" { - basename = strings.Replace(cmd.CommandPath(), " ", "bearer_", -1) + ".yaml" + basename = fmt.Sprintf("bearer%s.yaml", strings.Replace(cmd.CommandPath(), " ", "_", -1)) } filename := filepath.Join(dir, basename)