From 32e8d5723582e06bc20f26beafded14f8e265ea5 Mon Sep 17 00:00:00 2001 From: Ruud Senden <8635138+rsenden@users.noreply.github.com> Date: Wed, 11 Sep 2024 15:04:18 +0200 Subject: [PATCH] docs: Fix ScanCentral Client URLs --- README.md | 140 +++++++++++++++--------- doc-resources/action-package.md | 2 +- doc-resources/action-setup.md | 2 +- doc-resources/env-fod-package.md | 2 +- doc-resources/env-fod-sast-scan.md | 4 +- doc-resources/env-package.md | 2 +- doc-resources/env-sc-sast-scan.md | 4 +- doc-resources/env-ssc-debricked-scan.md | 4 +- doc-resources/repo-readme.md | 4 +- fod-sast-scan/README.md | 20 ++-- package/README.md | 4 +- sc-sast-scan/README.md | 20 ++-- setup/README.md | 2 +- ssc-debricked-scan/README.md | 25 ++++- 14 files changed, 144 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index d944692..5838d1b 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ The [Fortify github-action repository](https://github.com/fortify/github-action) * [`fortify/github-action/fod-export`](#fortify-github-action-fod-export) Export SAST vulnerability data from Fortify on Demand to the GitHub Security dashboard. * [`fortify/github-action/setup`](#fortify-github-action-setup) - Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline + Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline **Fortify Sofware Security Center (SSC) / ScanCentral SAST / Debricked** @@ -39,7 +39,7 @@ The [Fortify github-action repository](https://github.com/fortify/github-action) * [`fortify/github-action/ssc-export`](#fortify-github-action-ssc-export) Export SAST vulnerability data from Fortify SSC to the GitHub Security dashboard. * [`fortify/github-action/setup`](#fortify-github-action-setup) - Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline + Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline @@ -135,7 +135,7 @@ If FoD Software Composition Analysis has been purchased and configured on the ap Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient to properly package application source code. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -144,6 +144,15 @@ As an example, if the build file that you want to use for packaging doesn't adhe Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-fod-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -180,15 +189,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - @@ -265,7 +265,7 @@ Fortify SSC application version to use with this action. This can be specified e **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -277,6 +277,15 @@ Version of the ScanCentral SAST sensor on which the scan should be performed. Se Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-sc-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -313,15 +322,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - @@ -378,6 +378,15 @@ Fortify SSC application version to use with this action. This can be specified e + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -387,12 +396,20 @@ If `DO_JOB_SUMMARY` is set to `true` (which implies `DO_WAIT`), this action will - + -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. +**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL +If `DO_PR_COMMENT` is set to `true` (which implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided `github-pr-comment` action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. `PR_COMMENT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see https://fortify.github.io/fcli/v2.6.0/#_actions for more information. - +Note that pull request comments will only be generated under the following conditions: + +* `GITHUB_TOKEN` environment variable needs to be set to a valid GitHub token, for example from `{{ secrets.GITHUB_TOKEN }}`. +* Standard `GITHUB_REF_NAME` environment variable points to a pull request. +* All other standard GitHub environment variables like `GITHUB_REPOSITORY` and `GITHUB_SHA` are set. + +PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application version/release; it won't detect any new/removed issues from older scans. For best results, you should configure the GitHub Action to run only on pull request creation (not on every commit) and optionally allow for manual runs (if you want to re-run the scan after a PR is updated). You should also configure the action to automatically create a dedicated application version/release for the current branch/PR, copying state from the main/parent branch version/release. This will allow the action to compare scan results for the current GitHub Action run against the last scan results of the main/parent branch. + + @@ -503,7 +520,7 @@ This action allows for setting up the Fortify tools listed below. Which tools an * [fcli](https://github.com/fortify/fcli) * [Debricked CLI](https://github.com/debricked/cli) -* [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm) +* [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/intro.htm) * [FoDUploader](https://github.com/fod-dev/fod-uploader-java) * [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) * [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) @@ -615,7 +632,7 @@ The sample workflow below demonstrates how to configure the action for installin -This action packages application source code using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm). The output package is saved as `package.zip`. +This action packages application source code using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm). The output package is saved as `package.zip`. @@ -640,7 +657,7 @@ This action assumes the standard software packages as provided by GitHub-hosted **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -761,7 +778,7 @@ If FoD Software Composition Analysis has been purchased and configured on the ap Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient to properly package application source code. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -770,6 +787,15 @@ As an example, if the build file that you want to use for packaging doesn't adhe Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-fod-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -806,15 +832,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - @@ -1047,7 +1064,7 @@ Fortify SSC application version to use with this action. This can be specified e **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -1059,6 +1076,15 @@ Version of the ScanCentral SAST sensor on which the scan should be performed. Se Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-sc-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -1095,15 +1121,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - @@ -1226,6 +1243,15 @@ Fortify SSC application version to use with this action. This can be specified e + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -1235,12 +1261,20 @@ If `DO_JOB_SUMMARY` is set to `true` (which implies `DO_WAIT`), this action will - + -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. +**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL +If `DO_PR_COMMENT` is set to `true` (which implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided `github-pr-comment` action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. `PR_COMMENT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see https://fortify.github.io/fcli/v2.6.0/#_actions for more information. - +Note that pull request comments will only be generated under the following conditions: + +* `GITHUB_TOKEN` environment variable needs to be set to a valid GitHub token, for example from `{{ secrets.GITHUB_TOKEN }}`. +* Standard `GITHUB_REF_NAME` environment variable points to a pull request. +* All other standard GitHub environment variables like `GITHUB_REPOSITORY` and `GITHUB_SHA` are set. + +PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application version/release; it won't detect any new/removed issues from older scans. For best results, you should configure the GitHub Action to run only on pull request creation (not on every commit) and optionally allow for manual runs (if you want to re-run the scan after a PR is updated). You should also configure the action to automatically create a dedicated application version/release for the current branch/PR, copying state from the main/parent branch version/release. This will allow the action to compare scan results for the current GitHub Action run against the last scan results of the main/parent branch. + + diff --git a/doc-resources/action-package.md b/doc-resources/action-package.md index 2aff912..50f1471 100644 --- a/doc-resources/action-package.md +++ b/doc-resources/action-package.md @@ -1,4 +1,4 @@ -This action packages application source code using [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm). The output package is saved as `package.zip`. +This action packages application source code using [ScanCentral Client]({{var:sc-client-doc-base-url}}#cli/package-cmd.htm). The output package is saved as `package.zip`. {{include:action-prerequisites.md}} diff --git a/doc-resources/action-setup.md b/doc-resources/action-setup.md index 61e7692..43e63fd 100644 --- a/doc-resources/action-setup.md +++ b/doc-resources/action-setup.md @@ -2,7 +2,7 @@ This action allows for setting up the Fortify tools listed below. Which tools an * [fcli](https://github.com/fortify/fcli) * [Debricked CLI](https://github.com/debricked/cli) -* [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm) +* [ScanCentral Client]({{var:sc-client-doc-base-url}}#cli/intro.htm) * [FoDUploader](https://github.com/fod-dev/fod-uploader-java) * [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) * [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) diff --git a/doc-resources/env-fod-package.md b/doc-resources/env-fod-package.md index 6f033d2..7ffb7fe 100644 --- a/doc-resources/env-fod-package.md +++ b/doc-resources/env-fod-package.md @@ -5,4 +5,4 @@ If FoD Software Composition Analysis has been purchased and configured on the ap Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient to properly package application source code. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url}}#cli/package-cmd.htm) for more information on available options. diff --git a/doc-resources/env-fod-sast-scan.md b/doc-resources/env-fod-sast-scan.md index f82b407..373961d 100644 --- a/doc-resources/env-fod-sast-scan.md +++ b/doc-resources/env-fod-sast-scan.md @@ -8,11 +8,11 @@ **`EXTRA_FOD_SAST_SCAN_OPTS`** - OPTIONAL Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-sast-scan-start.html) +{{include:env-do-wait.md}} + {{include:env-do-job-summary.md}} {{include:env-do-export.md}} {{include:env-do-pr-comment.md}} -{{include:env-do-wait.md}} - diff --git a/doc-resources/env-package.md b/doc-resources/env-package.md index c521ccc..2e8d0aa 100644 --- a/doc-resources/env-package.md +++ b/doc-resources/env-package.md @@ -1,4 +1,4 @@ **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url}}#cli/package-cmd.htm) for more information on available options. diff --git a/doc-resources/env-sc-sast-scan.md b/doc-resources/env-sc-sast-scan.md index 5f13ba2..51fcbfb 100644 --- a/doc-resources/env-sc-sast-scan.md +++ b/doc-resources/env-sc-sast-scan.md @@ -20,11 +20,11 @@ Version of the ScanCentral SAST sensor on which the scan should be performed. Se **`EXTRA_SC_SAST_SCAN_OPTS`** - OPTIONAL Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-sc-sast-scan-start.html) +{{include:env-do-wait.md}} + {{include:env-do-job-summary.md}} {{include:env-do-export.md}} {{include:env-do-pr-comment.md}} -{{include:env-do-wait.md}} - diff --git a/doc-resources/env-ssc-debricked-scan.md b/doc-resources/env-ssc-debricked-scan.md index 665681d..cbb85e5 100644 --- a/doc-resources/env-ssc-debricked-scan.md +++ b/doc-resources/env-ssc-debricked-scan.md @@ -7,6 +7,8 @@ See the [Generate access token](https://docs.debricked.com/product/administratio {{include:env-ssc-appversion.md}} +{{include:env-do-wait.md}} + {{include:env-do-job-summary.md}} -{{include:env-do-wait.md}} +{{include:env-do-pr-comment.md}} diff --git a/doc-resources/repo-readme.md b/doc-resources/repo-readme.md index aea65ac..cd629ae 100644 --- a/doc-resources/repo-readme.md +++ b/doc-resources/repo-readme.md @@ -11,7 +11,7 @@ The [Fortify github-action repository]({{var:repo-url}}) hosts various Fortify-r * [`fortify/github-action/fod-export`](#fortify-github-action-fod-export) Export SAST vulnerability data from Fortify on Demand to the GitHub Security dashboard. * [`fortify/github-action/setup`](#fortify-github-action-setup) - Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline + Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client]({{var:sc-client-doc-base-url}}#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline **Fortify Sofware Security Center (SSC) / ScanCentral SAST / Debricked** @@ -26,7 +26,7 @@ The [Fortify github-action repository]({{var:repo-url}}) hosts various Fortify-r * [`fortify/github-action/ssc-export`](#fortify-github-action-ssc-export) Export SAST vulnerability data from Fortify SSC to the GitHub Security dashboard. * [`fortify/github-action/setup`](#fortify-github-action-setup) - Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline + Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client]({{var:sc-client-doc-base-url}}#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline diff --git a/fod-sast-scan/README.md b/fod-sast-scan/README.md index 5a05b13..e5b0031 100644 --- a/fod-sast-scan/README.md +++ b/fod-sast-scan/README.md @@ -90,7 +90,7 @@ If FoD Software Composition Analysis has been purchased and configured on the ap Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient to properly package application source code. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -99,6 +99,15 @@ As an example, if the build file that you want to use for packaging doesn't adhe Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-fod-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -135,15 +144,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - diff --git a/package/README.md b/package/README.md index f194de7..a824b81 100644 --- a/package/README.md +++ b/package/README.md @@ -11,7 +11,7 @@ -This action packages application source code using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm). The output package is saved as `package.zip`. +This action packages application source code using [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm). The output package is saved as `package.zip`. @@ -36,7 +36,7 @@ This action assumes the standard software packages as provided by GitHub-hosted **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. diff --git a/sc-sast-scan/README.md b/sc-sast-scan/README.md index 78343b9..978b2a1 100644 --- a/sc-sast-scan/README.md +++ b/sc-sast-scan/README.md @@ -102,7 +102,7 @@ Fortify SSC application version to use with this action. This can be specified e **`EXTRA_PACKAGE_OPTS`** - OPTIONAL By default, this action runs `scancentral package -o package.zip` to package application source code. Based on the automated build tool detection feature provided by ScanCentral Client, this default `scancentral` command is often sufficient. Depending on your build setup, you may however need to configure the `EXTRA_PACKAGE_OPTS` environment variable to specify additional packaging options. -As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command]({{var:sc-client-doc-base-url#CLI.htm#Package}}) for more information on available options. +As an example, if the build file that you want to use for packaging doesn't adhere to common naming conventions, you can configure the `-bf ` option using the `EXTRA_PACKAGE_OPTS` environment variable. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/package-cmd.htm) for more information on available options. @@ -114,6 +114,15 @@ Version of the ScanCentral SAST sensor on which the scan should be performed. Se Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-sc-sast-scan-start.html) + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -150,15 +159,6 @@ PR comments are generated by comparing scan results from the current GitHub Acti - - - -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. - - - - diff --git a/setup/README.md b/setup/README.md index 8017345..8228d61 100644 --- a/setup/README.md +++ b/setup/README.md @@ -15,7 +15,7 @@ This action allows for setting up the Fortify tools listed below. Which tools an * [fcli](https://github.com/fortify/fcli) * [Debricked CLI](https://github.com/debricked/cli) -* [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#A_Clients.htm) +* [ScanCentral Client](https://www.microfocus.com/documentation/fortify-software-security-center/2420/SC_SAST_Help_24.2.0/index.htm#cli/intro.htm) * [FoDUploader](https://github.com/fod-dev/fod-uploader-java) * [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) * [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) diff --git a/ssc-debricked-scan/README.md b/ssc-debricked-scan/README.md index 9e7233a..2d02b0f 100644 --- a/ssc-debricked-scan/README.md +++ b/ssc-debricked-scan/README.md @@ -82,6 +82,15 @@ Fortify SSC application version to use with this action. This can be specified e + + +**`DO_WAIT`** - OPTIONAL +By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. + + + + + **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL @@ -91,12 +100,20 @@ If `DO_JOB_SUMMARY` is set to `true` (which implies `DO_WAIT`), this action will - + -**`DO_WAIT`** - OPTIONAL -By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating workflow summaries. This behavior is documented in the applicable environment variable descriptions. +**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL +If `DO_PR_COMMENT` is set to `true` (which implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided `github-pr-comment` action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. `PR_COMMENT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see https://fortify.github.io/fcli/v2.6.0/#_actions for more information. - +Note that pull request comments will only be generated under the following conditions: + +* `GITHUB_TOKEN` environment variable needs to be set to a valid GitHub token, for example from `{{ secrets.GITHUB_TOKEN }}`. +* Standard `GITHUB_REF_NAME` environment variable points to a pull request. +* All other standard GitHub environment variables like `GITHUB_REPOSITORY` and `GITHUB_SHA` are set. + +PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application version/release; it won't detect any new/removed issues from older scans. For best results, you should configure the GitHub Action to run only on pull request creation (not on every commit) and optionally allow for manual runs (if you want to re-run the scan after a PR is updated). You should also configure the action to automatically create a dedicated application version/release for the current branch/PR, copying state from the main/parent branch version/release. This will allow the action to compare scan results for the current GitHub Action run against the last scan results of the main/parent branch. + +