chore: Improve consistency, add policy checks

fix: Deprecate EXTRA_*_OPTS variables; these are replaced by *_EXTRA_OPTS variables for consistency

feat: Add support for performing policy checks after scan completion

doc-resources/action-fod-sast-scan.md

@@ -13,7 +13,7 @@ The SAST and optional open source scan performed by this action consists of the
 Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action:
 
 * The appropriate application release exists on FoD and has been configured for SAST scans. Future versions of this action may add support for automating app/release creation and scan setup.
-* If open source scanning has been enabled in the FoD SAST scan configuration, be sure to pass the `-oss` option through the `EXTRA_PACKAGE_OPTS` environment variable.
+* If open source scanning has been enabled in the FoD SAST scan configuration, be sure to pass the `-oss` option through the `PACKAGE_EXTRA_OPTS` environment variable.
 
 ### Action environment variable inputs
 

doc-resources/env-do-policy-check.md

@@ -0,0 +1,2 @@
+**`CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL    
+These inputs allow for running policy checks after scan completion. As security policies are different for every Fortify customer, we don't provide a default policy check action. `POLICY_CHECK_ACTION` may point to a local file or URL; this custom fcli action must accept at least the `--av` (for SSC) or `--rel` (for FoD) option. Any extra options for this custom fcli action can be passed through the `CHECK_POLICY_EXTRA_OPTS` environment variable, which may include fcli options to allow unsigned custom actions to be used. Please see {{var:fcli-doc-base-url}}#_actions for more information. 

doc-resources/env-fod-login.md

@@ -1,4 +1,4 @@
 {{include:env-fod-connection.md}}
 
-**`EXTRA_FOD_LOGIN_OPTS`** - OPTIONAL   
+**`EXTRA_FOD_LOGIN_OPTS` (deprecated), `FOD_LOGIN_EXTRA_OPTS`** - OPTIONAL   
 Extra FoD login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-session-login.html)

doc-resources/env-fod-package.md

@@ -1,8 +1,8 @@
-**`EXTRA_PACKAGE_OPTS`** - OPTIONAL     
-By default, this action runs `scancentral package -o package.zip` to package application source code. The `EXTRA_PACKAGE_OPTS` environment variable can be used to specify additional packaging options. 
+**`EXTRA_PACKAGE_OPTS` (deprecated), `PACKAGE_EXTRA_OPTS`** - OPTIONAL     
+By default, this action runs `scancentral package -o package.zip` to package application source code. The `PACKAGE_EXTRA_OPTS` environment variable can be used to specify additional packaging options. 
 
 If FoD Software Composition Analysis has been purchased and configured on the applicable release, you'll need to pass the `-oss` option through this environment variable to generate and package the additional dependency files required. 
 
-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. 
+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 `PACKAGE_EXTRA_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 <custom build file>` 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.
+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 <custom build file>` option using the `PACKAGE_EXTRA_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.

doc-resources/env-fod-sast-scan.md

@@ -5,11 +5,13 @@
 
 {{include:env-fod-package.md}}
 
-**`EXTRA_FOD_SAST_SCAN_OPTS`** - OPTIONAL    
+**`EXTRA_FOD_SAST_SCAN_OPTS` (deprecated), `FOD_SAST_SCAN_EXTRA_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-policy-check.md}}
+
 {{include:env-do-job-summary.md}}
 
 {{include:env-do-export.md}}

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. 
+**`EXTRA_PACKAGE_OPTS` (deprecated), `PACKAGE_EXTRA_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 `PACKAGE_EXTRA_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 <custom build file>` 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.
+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 <custom build file>` option using the `PACKAGE_EXTRA_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.

doc-resources/env-sc-sast-login.md

@@ -1,5 +1,5 @@
 **`SC_SAST_TOKEN`** - REQUIRED    
 Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller.
 
-**`EXTRA_SC_SAST_LOGIN_OPTS`** - OPTIONAL    
+**`EXTRA_SC_SAST_LOGIN_OPTS` (deprecated), `SC_SAST_LOGIN_EXTRA_OPTS`** - OPTIONAL    
 Extra ScanCentral SAST login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli sc-sast session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-sc-sast-session-login.html).

doc-resources/env-sc-sast-scan.md

@@ -17,11 +17,13 @@ Required when performing a Debricked Software Composition Analysis scan; see the
 **`SC_SAST_SENSOR_VERSION`** - REQUIRED     
 Version of the ScanCentral SAST sensor on which the scan should be performed. See [`fcli sc-sast scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-sc-sast-scan-start.html#_options_for_scanning_a_package_file) for details.
 
-**`EXTRA_SC_SAST_SCAN_OPTS`** - OPTIONAL    
+**`EXTRA_SC_SAST_SCAN_OPTS` (deprecated), `SC_SAST_SCAN_EXTRA_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-policy-check.md}}
+
 {{include:env-do-job-summary.md}}
 
 {{include:env-do-export.md}}

doc-resources/env-ssc-debricked-scan.md

@@ -9,6 +9,8 @@ See the [Generate access token](https://docs.debricked.com/product/administratio
 
 {{include:env-do-wait.md}}
 
+{{include:env-do-policy-check.md}}
+
 {{include:env-do-job-summary.md}}
 
 {{include:env-do-pr-comment.md}}

doc-resources/env-ssc-login.md

@@ -1,2 +1,2 @@
-**`EXTRA_SSC_LOGIN_OPTS`** - OPTIONAL    
+**`EXTRA_SSC_LOGIN_OPTS` (deprecated), `SSC_LOGIN_EXTRA_OPTS`** - OPTIONAL    
 Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli ssc session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-ssc-session-login.html).

doc-resources/nocomments.env-fod-login-sample.md

@@ -1,2 +1,2 @@
 {{include:nocomments.env-fod-connection-sample.md}}
-          # EXTRA_FOD_LOGIN_OPTS: --socket-timeout=60s
+          # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s

doc-resources/nocomments.env-fod-package-sample.md

@@ -1 +1 @@
-          # EXTRA_PACKAGE_OPTS: -oss
+          # PACKAGE_EXTRA_OPTS: -oss

doc-resources/nocomments.env-package-sample.md

@@ -1 +1 @@
-          # EXTRA_PACKAGE_OPTS: -bf custom-pom.xml
+          # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml

doc-resources/nocomments.env-sc-sast-login-sample.md

@@ -1,2 +1,2 @@
           SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}}
-          # EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s
+          # SC_SAST_LOGIN_EXTRA_OPTS: --socket-timeout=60s

doc-resources/nocomments.env-ssc-login-sample.md

@@ -1 +1 @@
-          # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s
+          # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s

fod-sast-scan/README.md

@@ -39,7 +39,7 @@ This action assumes the standard software packages as provided by GitHub-hosted
 Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action:
 
 * The appropriate application release exists on FoD and has been configured for SAST scans. Future versions of this action may add support for automating app/release creation and scan setup.
-* If open source scanning has been enabled in the FoD SAST scan configuration, be sure to pass the `-oss` option through the `EXTRA_PACKAGE_OPTS` environment variable.
+* If open source scanning has been enabled in the FoD SAST scan configuration, be sure to pass the `-oss` option through the `PACKAGE_EXTRA_OPTS` environment variable.
 
 ### Action environment variable inputs
 
@@ -65,7 +65,7 @@ Required when authenticating with user credentials: FoD tenant, user and passwor
 <!-- END-INCLUDE:env-fod-connection.md -->
 
 
-**`EXTRA_FOD_LOGIN_OPTS`** - OPTIONAL   
+**`EXTRA_FOD_LOGIN_OPTS` (deprecated), `FOD_LOGIN_EXTRA_OPTS`** - OPTIONAL   
 Extra FoD login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v2.6.0//manpage/fcli-fod-session-login.html)
 
 <!-- END-INCLUDE:env-fod-login.md -->
@@ -83,19 +83,19 @@ Fortify on Demand release to use with this action. This can be specified either
 
 <!-- START-INCLUDE:env-fod-package.md -->
 
-**`EXTRA_PACKAGE_OPTS`** - OPTIONAL     
-By default, this action runs `scancentral package -o package.zip` to package application source code. The `EXTRA_PACKAGE_OPTS` environment variable can be used to specify additional packaging options. 
+**`EXTRA_PACKAGE_OPTS` (deprecated), `PACKAGE_EXTRA_OPTS`** - OPTIONAL     
+By default, this action runs `scancentral package -o package.zip` to package application source code. The `PACKAGE_EXTRA_OPTS` environment variable can be used to specify additional packaging options. 
 
 If FoD Software Composition Analysis has been purchased and configured on the applicable release, you'll need to pass the `-oss` option through this environment variable to generate and package the additional dependency files required. 
 
-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. 
+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 `PACKAGE_EXTRA_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 <custom build file>` 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.
+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 <custom build file>` option using the `PACKAGE_EXTRA_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.
 
 <!-- END-INCLUDE:env-fod-package.md -->
 
 
-**`EXTRA_FOD_SAST_SCAN_OPTS`** - OPTIONAL    
+**`EXTRA_FOD_SAST_SCAN_OPTS` (deprecated), `FOD_SAST_SCAN_EXTRA_OPTS`** - OPTIONAL    
 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)
 
 
@@ -108,6 +108,15 @@ By default, this action will not wait until scans have been completed. To have t
 
 
 
+<!-- START-INCLUDE:env-do-policy-check.md -->
+
+**`CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL    
+These inputs allow for running policy checks after scan completion. As security policies are different for every Fortify customer, we don't provide a default policy check action. `POLICY_CHECK_ACTION` may point to a local file or URL; this custom fcli action must accept at least the `--av` (for SSC) or `--rel` (for FoD) option. Any extra options for this custom fcli action can be passed through the `CHECK_POLICY_EXTRA_OPTS` environment variable, which may include fcli options to allow unsigned custom actions to be used. Please see https://fortify.github.io/fcli/v2.6.0/#_actions for more information. 
+
+<!-- END-INCLUDE:env-do-policy-check.md -->
+
+
+
 <!-- START-INCLUDE:env-do-job-summary.md -->
 
 **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL    
@@ -173,9 +182,9 @@ The sample workflow below demonstrates how to configure the action for running a
           FOD_TENANT: ${{secrets.FOD_TENANT}}
           FOD_USER: ${{secrets.FOD_USER}}
           FOD_PASSWORD: ${{secrets.FOD_PAT}}
-          # EXTRA_FOD_LOGIN_OPTS: --socket-timeout=60s
+          # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s
           # FOD_RELEASE: MyApp:MyRelease
-          # EXTRA_PACKAGE_OPTS: -oss
+          # PACKAGE_EXTRA_OPTS: -oss
           # DO_WAIT: true
           # DO_EXPORT: true
           # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip

internal/run-script/scripts/common.sh

@@ -38,7 +38,7 @@ function printOutput {
 # arguments specify the command to run together with its arguments.
 #
 # Command arguments may contain environment variable references in the 
-# format __expand:<VARNAME>, for example __expand:EXTRA_SC_SAST_SCAN_OPTS;
+# format __expand:<VARNAME>, for example __expand:SC_SAST_SCAN_EXTRA_OPTS;
 # these will be expanded before running the given command. The environment
 # variable to be expanded may contain multiple arguments, including properly
 # quoted arguments containing whitespace.
@@ -250,26 +250,36 @@ function requireSCSastSession {
 
 #############################################################################
 # Function to determine whether PR comments should be generated. PR comments
-# are only generated if DO_PR_COMMENT is set to true, required GITHUB_*
-# environment variables are available, and GITHUB_REF_NAME points to a PR.
+# are only generated if any of the PR_COMMENT variables is set, required 
+# GITHUB_* environment variables are available, and GITHUB_REF_NAME points to
+# a PR.
 function doPRComment {
-  [ "${DO_PR_COMMENT}" == "true" ] \
-  && [ -n "${GITHUB_TOKEN}" ] \
-  && [ -n "${GITHUB_REPOSITORY_OWNER}" ] \
-  && [ -n "${GITHUB_REPOSITORY}" ] \
-  && [ -n "${GITHUB_REF_NAME}" ] \
-  && [ -n "${GITHUB_SHA}" ] \
-  && [[ "${GITHUB_REF_NAME}" == */merge ]]
+  [[ ("${DO_PR_COMMENT}" == "true" || -n "${PR_COMMENT_ACTION}" || -n "${PR_COMMENT_EXTRA_OPTS}") \
+  && -n "${GITHUB_TOKEN}" ] \
+  && -n "${GITHUB_REPOSITORY_OWNER}" ] \
+  && -n "${GITHUB_REPOSITORY}" ] \
+  && -n "${GITHUB_REF_NAME}" ] \
+  && -n "${GITHUB_SHA}" ] \
+  && "${GITHUB_REF_NAME}" == */merge ]]
 }
 
 #############################################################################
-# Function to determine whether job summary should be generated.
+# Function to determine whether PR comments should be generated. Job summary 
+# is enabled if any of the JOB_SUMMARY variables is set.
 function doJobSummary {
-  [ "${DO_JOB_SUMMARY}" == "true" ]
+  [[ "${DO_JOB_SUMMARY}" == "true" || -n "${JOB_SUMMARY_ACTION}" || -n "${JOB_SUMMARY_EXTRA_OPTS} ]]
+}
+
+#############################################################################
+# Function to determine whether policy check should be run. Policy checks
+# are enabled if POLICY_CHECK_ACTION is defined (as we don't provide a
+# default action).
+function doPolicyCheck {
+  [[ -n "${POLICY_CHECK_ACTION}" ]]
 }
 
 #############################################################################
 # Function to determine whether we should wait for scan completion.
 function doWait {
-  [ "${DO_WAIT}" == "true" ] || [ "${DO_EXPORT}" == "true" ] || doJobSummary || doPRComment
+  [ "${DO_WAIT}" == "true" ] || [ "${DO_EXPORT}" == "true" ] || doJobSummary || doPRComment || doPolicyCheck
 }

internal/run-script/scripts/export.sh

@@ -5,6 +5,6 @@ requireFcli
 requireVar "PRODUCT"
 checkRequirements
 
-run "EXPORT" "${FCLI_CMD}" "${PRODUCT}" action run "${EXPORT_ACTION:-github-sast-report}" __expand:DEFAULT_OPTS __expand:EXTRA_EXPORT_OPTS
+run "EXPORT" "${FCLI_CMD}" "${PRODUCT}" action run "${EXPORT_ACTION:-github-sast-report}" __expand:DEFAULT_OPTS __expand:EXPORT_EXTRA_OPTS
 printRunSummary
 failOnError

internal/run-script/scripts/fod-login.sh

@@ -10,9 +10,9 @@ requireIfVar "FOD_USER" "FOD_TENANT"
 checkRequirements
 
 if [ -n "${FOD_CLIENT_ID}" ]; then
-  run "FOD_LOGIN" "${FCLI_CMD}" fod session login --url "${FOD_URL}" --client-id "${FOD_CLIENT_ID}" --client-secret "${FOD_CLIENT_SECRET}" __expand:EXTRA_FOD_LOGIN_OPTS
+  run "FOD_LOGIN" "${FCLI_CMD}" fod session login --url "${FOD_URL}" --client-id "${FOD_CLIENT_ID}" --client-secret "${FOD_CLIENT_SECRET}" __expand:EXTRA_FOD_LOGIN_OPTS __expand:FOD_LOGIN_EXTRA_OPTS
 else
-  run "FOD_LOGIN" "${FCLI_CMD}" fod session login --url "${FOD_URL}" -t "${FOD_TENANT}" -u "${FOD_USER}" -p "${FOD_PASSWORD}" __expand:EXTRA_FOD_LOGIN_OPTS
+  run "FOD_LOGIN" "${FCLI_CMD}" fod session login --url "${FOD_URL}" -t "${FOD_TENANT}" -u "${FOD_USER}" -p "${FOD_PASSWORD}" __expand:EXTRA_FOD_LOGIN_OPTS __expand:FOD_LOGIN_EXTRA_OPTS
 fi
 
 printRunSummary

internal/run-script/scripts/fod-scan.sh

@@ -10,12 +10,18 @@ checkRequirements
 
 run "SAST_SCAN" "${FCLI_CMD}" fod sast-scan start \
     --rel "${FOD_RELEASE}" -f package.zip \
-    --store fod_sast_scan __expand:EXTRA_FOD_SAST_SCAN_OPTS
+    --store fod_sast_scan __expand:EXTRA_FOD_SAST_SCAN_OPTS __expand:FOD_SAST_SCAN_EXTRA_OPTS
 if doWait; then
   ifRun "SAST_SCAN" && run "SAST_PUBLISH" \
     "${FCLI_CMD}" fod sast-scan wait-for ::fod_sast_scan::
 fi
 
+if doPolicyCheck; then
+  run "POLICY_CHECK" "${FCLI_CMD}" ssc action run "${POLICY_CHECK_ACTION}" \
+    --av "${SSC_APPVERSION}" --progress=none __expand:POLICY_CHECK_EXTRA_OPTS
+fi
+
+# TODO Add policy check output to job summary
 if doJobSummary; then
   # Collect scan/publish statuses for inclusion in job summary.
   SAST_SCAN_STATUS=$(printRunStatus "SAST_SCAN")

internal/run-script/scripts/package.sh

@@ -4,6 +4,6 @@
 requireScanCentralClient
 checkRequirements
 
-run "PACKAGE" "${SC_CLIENT_CMD}" package -o package.zip __expand:EXTRA_PACKAGE_OPTS
+run "PACKAGE" "${SC_CLIENT_CMD}" package -o package.zip __expand:EXTRA_PACKAGE_OPTS __expand:PACKAGE_EXTRA_OPTS
 printRunSummary
 failOnError