From f44787dafc755cfd105eb9336927f1c5d65e753f Mon Sep 17 00:00:00 2001 From: Ruud Senden <8635138+rsenden@users.noreply.github.com> Date: Thu, 31 Oct 2024 16:46:09 +0100 Subject: [PATCH] chore: Incomplete doc updates --- README.md | 1610 ++--------------- action.yml | 6 +- doc-resources/action-setup.md | 82 - doc-resources/action/_root/readme.md | 68 + .../nocomments.env-export-optional.md | 1 + .../fod-export/nocomments.env-export.md | 1 + .../fod-export/readme.md} | 27 +- .../nocomments.env-fod-sast-scan.md | 11 + .../nocomments.env-job-summary.md | 1 + .../nocomments.env-policy-check.md | 1 + .../nocomments.env-pr-comment.md | 1 + .../fod-sast-scan/nocomments.env-setup.md | 1 + .../nocomments.snippet-fod-sast-scan.md | 9 + .../fod-sast-scan/readme.md} | 24 +- doc-resources/action/generic/fcli-actions.md | 4 + .../action/generic/fod/fod-fcli-actions.md | 9 + doc-resources/action/generic/fod/fod-pr.md | 27 + .../generic/fod/nocomments.env-fod-login.md | 4 + .../generic/fod/nocomments.env-fod-release.md | 1 + .../fod/nocomments.snippet-fod-login.md} | 3 +- .../fod/nocomments.snippet-fod-release.md} | 0 .../action/generic/nocomments.env-do-wait.md | 1 + ...nocomments.env-section-and-table-header.md | 5 + .../generic/nocomments.env-table-header.md | 2 + ...comments.input-section-and-table-header.md | 5 + .../generic/nocomments.input-table-header.md | 2 + .../nocomments.snippet-export-optional.md | 2 + .../generic/nocomments.snippet-export.md | 2 + .../generic/nocomments.snippet-job-summary.md | 3 + .../nocomments.snippet-policy-check.md | 3 + .../generic/nocomments.snippet-pr-comment.md | 3 + .../generic/nocomments.snippet-setup.md | 3 + .../action/generic/prerequisites-h2.md | 3 + .../action/generic/prerequisites-h3.md | 3 + .../generic/prerequisites.md} | 2 - .../ssc/nocomments.env-ssc-appversion.md | 1 + .../generic/ssc/nocomments.env-ssc-login.md | 4 + .../ssc/nocomments.snippet-ssc-appversion.md} | 0 .../ssc/nocomments.snippet-ssc-login.md | 3 + .../action/generic/ssc/ssc-fcli-actions.md | 9 + doc-resources/action/generic/ssc/ssc-pr.md | 27 + .../nocomments.env-package-extra-opts.md | 1 + .../nocomments.snippet-package-extra-opts.md | 1 + .../package/readme.md} | 18 +- .../sc-sast-scan/readme.md} | 3 +- .../setup/nocomments.env-tool-definitions.md | 1 + .../nocomments.snippet-tool-definitions.md} | 0 doc-resources/action/setup/readme.md | 59 + .../ssc-debricked-scan/readme.md} | 2 +- .../nocomments.env-export-optional.md | 1 + .../ssc-export/nocomments.env-export.md | 1 + .../ssc-export/readme.md} | 27 +- doc-resources/env-fod-connection.md | 8 - doc-resources/env-fod-login.md | 4 - doc-resources/env-fod-package.md | 8 - doc-resources/env-fod-release.md | 2 - doc-resources/env-fod-sast-scan.md | 22 - doc-resources/env-package.md | 4 - doc-resources/env-setup.md | 4 - doc-resources/env-ssc-appversion.md | 2 - doc-resources/env-ssc-connection.md | 8 - doc-resources/env-ssc-login.md | 2 - .../{ => env/sc-sast}/env-do-wait.md | 0 .../{ => env/sc-sast}/env-sc-sast-login.md | 0 .../{ => env/sc-sast}/env-sc-sast-scan.md | 0 doc-resources/{ => env/ssc}/env-do-export.md | 0 .../{ => env/ssc}/env-do-job-summary.md | 0 .../{ => env/ssc}/env-do-policy-check.md | 0 .../{ => env/ssc}/env-do-pr-comment.md | 0 doc-resources/{ => env/ssc}/env-do-setup.md | 0 .../{ => env/ssc}/env-ssc-debricked-scan.md | 0 .../nocomments.env-fod-login-sample.md | 2 - .../nocomments.env-fod-package-sample.md | 1 - .../nocomments.env-package-sample.md | 1 - .../nocomments.env-ssc-connection-sample.md | 2 - .../nocomments.env-ssc-login-sample.md | 1 - doc-resources/repo-readme.md | 186 -- doc-resources/templates/README.template.md | 2 +- .../templates/fod-export/README.template.md | 2 +- .../fod-sast-scan/README.template.md | 2 +- .../templates/package/README.template.md | 2 +- .../templates/setup/README.template.md | 2 +- .../templates/ssc-export/README.template.md | 2 +- .../fod-sast-scan/README.template.md | 11 + .../templates/sc-sast-scan/README.template.md | 2 +- .../ssc-debricked-scan/README.template.md | 2 +- fod-export/README.md | 93 +- fod-export/action.yml | 8 +- fod-sast-scan/README.md | 225 +-- fod-sast-scan/action.yml | 12 +- internal/fod-login/action.yml | 2 +- internal/run-script/action.yml | 2 +- internal/sc-sast-login/action.yml | 2 +- internal/ssc-login/action.yml | 2 +- package/README.md | 45 +- package/action.yml | 8 +- sc-sast-scan/README.md | 8 +- sc-sast-scan/action.yml | 14 +- setup/README.md | 99 +- ssc-debricked-scan/README.md | 8 +- ssc-debricked-scan/action.yml | 8 +- ssc-export/README.md | 89 +- ssc-export/action.yml | 8 +- 103 files changed, 740 insertions(+), 2265 deletions(-) delete mode 100644 doc-resources/action-setup.md create mode 100644 doc-resources/action/_root/readme.md create mode 100644 doc-resources/action/fod-export/nocomments.env-export-optional.md create mode 100644 doc-resources/action/fod-export/nocomments.env-export.md rename doc-resources/{action-fod-export.md => action/fod-export/readme.md} (51%) create mode 100644 doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md create mode 100644 doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md create mode 100644 doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md create mode 100644 doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md create mode 100644 doc-resources/action/fod-sast-scan/nocomments.env-setup.md create mode 100644 doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md rename doc-resources/{action-fod-sast-scan.md => action/fod-sast-scan/readme.md} (57%) create mode 100644 doc-resources/action/generic/fcli-actions.md create mode 100644 doc-resources/action/generic/fod/fod-fcli-actions.md create mode 100644 doc-resources/action/generic/fod/fod-pr.md create mode 100644 doc-resources/action/generic/fod/nocomments.env-fod-login.md create mode 100644 doc-resources/action/generic/fod/nocomments.env-fod-release.md rename doc-resources/{nocomments.env-fod-connection-sample.md => action/generic/fod/nocomments.snippet-fod-login.md} (56%) rename doc-resources/{nocomments.env-fod-release-sample.md => action/generic/fod/nocomments.snippet-fod-release.md} (100%) create mode 100644 doc-resources/action/generic/nocomments.env-do-wait.md create mode 100644 doc-resources/action/generic/nocomments.env-section-and-table-header.md create mode 100644 doc-resources/action/generic/nocomments.env-table-header.md create mode 100644 doc-resources/action/generic/nocomments.input-section-and-table-header.md create mode 100644 doc-resources/action/generic/nocomments.input-table-header.md create mode 100644 doc-resources/action/generic/nocomments.snippet-export-optional.md create mode 100644 doc-resources/action/generic/nocomments.snippet-export.md create mode 100644 doc-resources/action/generic/nocomments.snippet-job-summary.md create mode 100644 doc-resources/action/generic/nocomments.snippet-policy-check.md create mode 100644 doc-resources/action/generic/nocomments.snippet-pr-comment.md create mode 100644 doc-resources/action/generic/nocomments.snippet-setup.md create mode 100644 doc-resources/action/generic/prerequisites-h2.md create mode 100644 doc-resources/action/generic/prerequisites-h3.md rename doc-resources/{action-prerequisites.md => action/generic/prerequisites.md} (97%) create mode 100644 doc-resources/action/generic/ssc/nocomments.env-ssc-appversion.md create mode 100644 doc-resources/action/generic/ssc/nocomments.env-ssc-login.md rename doc-resources/{nocomments.env-ssc-appversion-sample.md => action/generic/ssc/nocomments.snippet-ssc-appversion.md} (100%) create mode 100644 doc-resources/action/generic/ssc/nocomments.snippet-ssc-login.md create mode 100644 doc-resources/action/generic/ssc/ssc-fcli-actions.md create mode 100644 doc-resources/action/generic/ssc/ssc-pr.md create mode 100644 doc-resources/action/package/nocomments.env-package-extra-opts.md create mode 100644 doc-resources/action/package/nocomments.snippet-package-extra-opts.md rename doc-resources/{action-package.md => action/package/readme.md} (57%) rename doc-resources/{action-sc-sast-scan.md => action/sc-sast-scan/readme.md} (88%) create mode 100644 doc-resources/action/setup/nocomments.env-tool-definitions.md rename doc-resources/{nocomments.env-setup-sample.md => action/setup/nocomments.snippet-tool-definitions.md} (100%) create mode 100644 doc-resources/action/setup/readme.md rename doc-resources/{action-ssc-debricked-scan.md => action/ssc-debricked-scan/readme.md} (97%) create mode 100644 doc-resources/action/ssc-export/nocomments.env-export-optional.md create mode 100644 doc-resources/action/ssc-export/nocomments.env-export.md rename doc-resources/{action-ssc-export.md => action/ssc-export/readme.md} (51%) delete mode 100644 doc-resources/env-fod-connection.md delete mode 100644 doc-resources/env-fod-login.md delete mode 100644 doc-resources/env-fod-package.md delete mode 100644 doc-resources/env-fod-release.md delete mode 100644 doc-resources/env-fod-sast-scan.md delete mode 100644 doc-resources/env-package.md delete mode 100644 doc-resources/env-setup.md delete mode 100644 doc-resources/env-ssc-appversion.md delete mode 100644 doc-resources/env-ssc-connection.md delete mode 100644 doc-resources/env-ssc-login.md rename doc-resources/{ => env/sc-sast}/env-do-wait.md (100%) rename doc-resources/{ => env/sc-sast}/env-sc-sast-login.md (100%) rename doc-resources/{ => env/sc-sast}/env-sc-sast-scan.md (100%) rename doc-resources/{ => env/ssc}/env-do-export.md (100%) rename doc-resources/{ => env/ssc}/env-do-job-summary.md (100%) rename doc-resources/{ => env/ssc}/env-do-policy-check.md (100%) rename doc-resources/{ => env/ssc}/env-do-pr-comment.md (100%) rename doc-resources/{ => env/ssc}/env-do-setup.md (100%) rename doc-resources/{ => env/ssc}/env-ssc-debricked-scan.md (100%) delete mode 100644 doc-resources/nocomments.env-fod-login-sample.md delete mode 100644 doc-resources/nocomments.env-fod-package-sample.md delete mode 100644 doc-resources/nocomments.env-package-sample.md delete mode 100644 doc-resources/nocomments.env-ssc-connection-sample.md delete mode 100644 doc-resources/nocomments.env-ssc-login-sample.md delete mode 100644 doc-resources/repo-readme.md create mode 100644 doc-resources/todo/templates/fod-sast-scan/README.template.md rename doc-resources/{ => todo}/templates/sc-sast-scan/README.template.md (88%) rename doc-resources/{ => todo}/templates/ssc-debricked-scan/README.template.md (86%) diff --git a/README.md b/README.md index 357ded6..0c26b37 100644 --- a/README.md +++ b/README.md @@ -9,1111 +9,24 @@ - + -The [Fortify github-action repository](https://github.com/fortify/github-action) hosts various Fortify-related GitHub Actions as listed in the sections below. +This GitHub Action allows for easy integration of Fortify Application Security Testing (AST) into your GitHub Action workflows. It provides out-of-the-box support for Static Application Security Testing (SAST) and Software Composition Analysis (SCA); support for Dynamic or Mobile Application Security Testing (DAST & MAST) may be added in the future. Apart from utilizing the standard scan workflows provided by this GitHub Action, you may also choose to utilize the various building blocks to implement custom workflows, which can be either customized SAST or SCA workflows, or your own DAST or MAST workflows. -**Fortify on Demand** +The following sections describe these topics in more detail: -* [`fortify/github-action`](#fortify-github-action) - For now, this action provides the same functionality as the `fod-sast-scan` action listed below. Future versions may add support for running other types of scans or performing other FoD operations. -* [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) - Package source code, submit static application security testing (SAST) scan request to Fortify on Demand, optionally wait for completion and export results back to the GitHub Security dashboard. -* [`fortify/github-action/package`](#fortify-github-action-package) - Package source code for running a SAST scan, using the latest version of ScanCentral Client. Optionally resolve dependencies for Software Composition Analysis (SCA) of open source components with integrated Debricked analysis via Fortify on Demand. -* [`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#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** +* [Prerequisites](#prerequisites) +* [Application Security Testing with Fortify on Demand](#application-security-testing-with-fortify-on-demand) +* [Application Security Testing with SSC/ScanCentral](#application-security-testing-with-ssc-scancentral) +* [Building blocks for custom workflows](#building-blocks-for-custom-workflows) -* [`fortify/github-action`](#fortify-github-action) - Depending on inputs, this action will run either or both a ScanCentral SAST and Debricked Software Composition Analysis (SCA) scan and publish scan results to SSC. Future versions may add support for running other types of scans or performing other SSC / ScanCentral operations. -* [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) - Run a ScanCentral SAST and optionally Debricked Software Composition Analysis scan by packaging source code, submitting ScanCentral SAST scan and optional Debricked scan request, and optionally waiting for completion and exporting SAST results back to the GitHub Security dashboard. -* [`fortify/github-action/ssc-debricked-scan`](#fortify-github-action-ssc-debricked-scan) - Run a Debricked Software Composition Analysis scan and publish scan results to SSC, optionally waiting for scan results to be fully processed on SSC. -* [`fortify/github-action/package`](#fortify-github-action-package) - Package source code for running a SAST scan, using the latest version of ScanCentral Client. -* [`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#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline - + -## fortify/github-action +## Prerequisites -The primary `fortify/github-action` action currently allows for running SAST and optional Software Composition Analysis scans on either Fortify on Demand or ScanCentral SAST / Debricked. Which activities to perform is controlled through action inputs, the input for those activities is provided through environment variables. -Based on inputs and environment variables, this action will simply configure and run one of the following sub-actions: - -| Conditions | Sub-action | -| ---------- | ---------- | -| `sast-scan: true`
`FOD_URL` specified | [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) | -| `sast-scan: true`
`SSC_URL` specified | [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) | -| `sast-scan: false`
`debricked-sca-scan: true`
`SSC_URL` specified | [`fortify/github-action/ssc-debricked-scan`](#fortify-github-action-ssc-debricked-scan) | - -If none of the conditions listed above are met, this action will complete without performing any work. - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - -Depending on inputs, additional prerequisites may apply as listed in the documentation for the sub-actions listed in the table above. - -### Action inputs - -**`sast-scan`** - OPTIONAL -When set to true, the action will run a SAST scan on either Fortify on Demand (if the `FOD_URL` environment variable has been specified), or on ScanCentral SAST (if the `SSC_URL` environment variable has been specified). This includes packaging the source code, running the scan, and optionally reporting SAST scan results back into GitHub. - -If not specified or when set to false, no SAST scan will be performed. For FoD, this means that the action will complete without doing any work. For SSC, the action could still run a Debricked-only scan based on the `debricked-sca-scan` input as listed below. Future versions of this action may provide additional inputs, for example allowing you to run a dynamic application security testing (DAST) scan instead of (or in combination with) a SAST scan. - -**`debricked-sca-scan`** - OPTIONAL -(Not applicable to Fortify on Demand) When set to true, the action will run a Debricked Software Composition Analysis (SCA) scan and publish the results to Fortify SSC. You can either run a Debricked-only scan (`sast-scan` set to `false`), or both SAST and Debricked SCA scan if both inputs are set to `true`. - -### Action environment variable inputs - -#### Fortify on Demand - - - - - - - - - - - -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). - -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. - - - - -**`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.9.0//manpage/fcli-fod-session-login.html) - - - - - - - -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 `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 ` 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. - - - - -**`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.9.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 job summaries. This behavior is documented in the applicable environment variable descriptions. - - - - - - - -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. - - - - - - - -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. - -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: - -* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). -* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: - -- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -#### ScanCentral SAST with optional Debricked scan - - - - - - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - - - - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-ssc-session-login.html). - - - - - - - -**`SC_SAST_TOKEN`** - REQUIRED -Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-sc-sast-session-login.html). - - - - -**`DO_DEBRICKED_SCAN`** - OPTIONAL -If set to `true`, this action will run both ScanCentral SAST and Debricked Software Composition Analysis (SCA) scans and publish both results to SSC. This is equivalent to setting the `debricked-sca-scan` input on the top-level `fortify/github-action` action. Note that this requires the [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) to be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. - -**`DEBRICKED_TOKEN`** - REQUIRED* -Required when performing a Debricked Software Composition Analysis scan; see the [Generate access token](https://docs.debricked.com/product/administration/generate-access-token) section in the Debricked documentation for details on how to generate this token. - - - - -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 ` 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. - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-sc-sast-scan-start.html#_options_for_scanning_a_package_file) for details. - -**`EXTRA_SC_SAST_SCAN_OPTS` (deprecated), `SC_SAST_SCAN_EXTRA_OPTS`** - OPTIONAL -Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v2.9.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 job summaries. This behavior is documented in the applicable environment variable descriptions. - - - - - - - -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. - - - - - - - -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. - -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: - -* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). -* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: - -- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -#### Debricked-only scan and publish to SSC - - - - - - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - - - - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-ssc-session-login.html). - - - - -**`DEBRICKED_TOKEN`** - REQUIRED -See the [Generate access token](https://docs.debricked.com/product/administration/generate-access-token) section in the Debricked documentation for details on how to generate this token. - - - - -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 job summaries. This behavior is documented in the applicable environment variable descriptions. - - - - - - - -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. - - - - - - - -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. - - - - - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: - -* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). -* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: - -- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample workflows - -The sample workflows below demonstrate how to configure the action for running a SAST scan on either Fortify on Demand or ScanCentral SAST. - -#### Fortify on Demand - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run FoD SAST Scan - uses: fortify/github-action@v1 - with: - sast-scan: true - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # PACKAGE_EXTRA_OPTS: -oss - # DO_WAIT: true - # DO_EXPORT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - -#### ScanCentral SAST with optional Debricked scan - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run ScanCentral SAST Scan - uses: fortify/github-action@v1 - with: - sast-scan: true - # debricked-sca-scan: true - env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s - SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}} - # SC_SAST_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # SSC_APPVERSION: MyApp:MyVersion - # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml - SC_SAST_SENSOR_VERSION: 23.2 - # DO_DEBRICKED_SCAN: true # Or debricked-sca-scan input on top-level action - # DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} - # DO_WAIT: true - # DO_EXPORT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - -#### Debricked-only scan and publish to SSC - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Debricked Scan - uses: fortify/github-action@v1 - with: - sast-scan: false - debricked-sca-scan: true - env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # SSC_APPVERSION: MyApp:MyVersion - DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} - # DO_WAIT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - -### More information - -Depending on input, this action delegates to the appropriate sub-action(s). Please refer to the documentation of these actions for a more detailed description of action behavior & requirements: - -* FoD SAST & optional SCA (open source) scan: [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) -* ScanCentral SAST scan: [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) - - - - -## fortify/github-action/setup - - - - -This action allows for setting up the Fortify tools listed below. Which tools and which versions to install, and whether to add the tool bin-directories to the system path, is controlled through action inputs as listed in the next section. - -* [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#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) - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - -### Action inputs - -**`export-path`** - OPTIONAL -Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` - -**`tool-definitions`** - OPTIONAL -Allows for overriding the location of the Fortify tool definitions bundle. This can be specified either as an action input or through the `TOOL_DEFINITIONS` environment variable; see the 'Action environment variable inputs' section below for details. - -**`fcli`** - OPTIONAL -The fcli version to install. Allowed values: `skip` (default value, do not install fcli), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.0` and `2.0.0` are semantically the same. - -**`sc-client`** - OPTIONAL -The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. - -**`fod-uploader`** - OPTIONAL -The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. - -**`vuln-exporter`** - OPTIONAL -The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.4` and `2.0.4` are semantically the same. - -**`bugtracker-utility`** - OPTIONAL -The FortifyBugTrackerUtility version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v4` will install the latest known `4.x` version. Version may be specified either with or without the `v` prefix, for example `v4.12` and `4.12` are semantically the same. - -**`debricked-cli`** - OPTIONAL -The Debricked CLI version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v1` will install the latest known `1.x` version. Version may be specified either with or without the `v` prefix, for example `v1` and `1` are semantically the same. - -### Action environment variable inputs - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Action outputs - -For each tool being installed, the action outputs several environment variables for use by later workflow steps. - -**`PATH`** -If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. - -**`_INSTALL_DIR`** -Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. - -**`_BIN_DIR`** -Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. - -**`_CMD`** -Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. - -### Sample usage - -The sample workflow below demonstrates how to configure the action for installing the various Fortify tools and how to run these tools. Some notes: - -* The `export-path` and `bugtracker-utility` inputs are set to their default values, and thus could have been omitted. -* The action supports semantic versioning, so the `vuln-exporter` input will install the latest known v2.x.y version of FortifyVulnerabilityExporter. - -```yaml - steps: - - name: Setup Fortify tools - uses: fortify/github-action/setup@v1 - with: - tool-definitions: https://github.com/fortify/tool-definitions/releases/download/v1/tool-definitions.yaml.zip - export-path: true - fcli: latest - sc-client: 23.1.0 - fod-uploader: latest - vuln-exporter: v2 - bugtracker-utility: skip - debricked-cli: skip - - name: Run fcli from PATH - run: fcli -V - - name: Run fcli using FCLI_CMD environment variable - run: ${FCLI_CMD} -V -``` - - - - - - - -## fortify/github-action/package - - - - -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`. - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - -### Action environment variable inputs - - - - -**`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 ` 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. - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Package source code - uses: fortify/github-action/package@v1 - env: - # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - - - - - - - -## fortify/github-action/fod-sast-scan - - - - -This action performs a SAST scan on Fortify on Demand (FoD). If software composition analysis of open source has been purchased and configured on the applicable release, this action can be used to perform a combined SAST and SCA (open source) scan. - -The SAST and optional open source scan performed by this action consists of the following steps: - -* Login to FoD -* Package application source code using ScanCentral Client -* Submit the source code package to be scanned to FoD -* Optionally wait for the scan to complete -* Optionally export scan results to the GitHub Code Scanning dashboard - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - -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 `PACKAGE_EXTRA_OPTS` environment variable. - -### Action environment variable inputs - - - - - - - - - - - -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). - -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. - - - - -**`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.9.0//manpage/fcli-fod-session-login.html) - - - - - - - -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 `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 ` 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. - - - - -**`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.9.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 job summaries. This behavior is documented in the applicable environment variable descriptions. - - - - - - - -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. - - - - - - - -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. - -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: - -* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). -* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: - -- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run FoD SAST Scan - uses: fortify/github-action/fod-sast-scan@v1 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # PACKAGE_EXTRA_OPTS: -oss - # DO_WAIT: true - # DO_EXPORT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - - - - - - - -## fortify/github-action/fod-export - - - - -This action exports the latest vulnerability data from an FoD release to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - -### Action environment variable inputs - - - - -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). - -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. - - - - - - - -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. - -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for exporting FoD SAST vulnerability data to the GitHub Security Code Scanning dashboard. - -```yaml - steps: - - name: Export FoD vulnerability data to GitHub - uses: fortify/github-action/fod-export@v1 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_RELEASE: MyApp:MyRelease - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - - - - - - - -## fortify/github-action/sc-sast-scan - - - - -This action performs a SAST scan on ScanCentral SAST, consisting of the following steps: - -* Login to ScanCentral SAST Controller -* Package application source code using ScanCentral Client -* Submit the source code package to be scanned to ScanCentral SAST Controller -* Optionally run a Debricked Software Composition Analysis scan -* Optionally wait for all scans to complete and results having been processed by SSC -* Optionally export scan results to the GitHub Code Scanning dashboard - - - - -### Prerequisites + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: @@ -1122,482 +35,179 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: - -* The appropriate application version must exist on SSC. Future versions of this action may add support for automating application version creation. -* If Debricked scanning is enabled, the [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) must be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. - -### Action environment variable inputs - - - - - - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - - - - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-ssc-session-login.html). - - - - - - - -**`SC_SAST_TOKEN`** - REQUIRED -Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-sc-sast-session-login.html). - - - - -**`DO_DEBRICKED_SCAN`** - OPTIONAL -If set to `true`, this action will run both ScanCentral SAST and Debricked Software Composition Analysis (SCA) scans and publish both results to SSC. This is equivalent to setting the `debricked-sca-scan` input on the top-level `fortify/github-action` action. Note that this requires the [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) to be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. - -**`DEBRICKED_TOKEN`** - REQUIRED* -Required when performing a Debricked Software Composition Analysis scan; see the [Generate access token](https://docs.debricked.com/product/administration/generate-access-token) section in the Debricked documentation for details on how to generate this token. - - - - -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 ` 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. - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-sc-sast-scan-start.html#_options_for_scanning_a_package_file) for details. - -**`EXTRA_SC_SAST_SCAN_OPTS` (deprecated), `SC_SAST_SCAN_EXTRA_OPTS`** - OPTIONAL -Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v2.9.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 job summaries. This behavior is documented in the applicable environment variable descriptions. - - - - - - - -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. - - - - - - - -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. - -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: - -* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). -* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: - -- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - + + - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. +## Application Security Testing with Fortify on Demand -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on ScanCentral SAST. +The standard workflow provided by this GitHub Action allows for running a Static scan and optional open-source scan (software composition analysis) on Fortify on Demand. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow: ```yaml steps: - name: Check out source code uses: actions/checkout@v4 - - name: Run ScanCentral SAST Scan - uses: fortify/github-action/sc-sast-scan@v1 + - name: Run FoD SAST Scan + uses: fortify/github-action@v1 + with: + sast-scan: true + debricked-sca-scan: true env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s - SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}} - # SC_SAST_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # SSC_APPVERSION: MyApp:MyVersion - # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml - SC_SAST_SENSOR_VERSION: 23.2 - # DO_DEBRICKED_SCAN: true # Or debricked-sca-scan input on top-level action - # DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} - # DO_WAIT: true + FOD_URL: https://ams.fortify.com + FOD_TENANT: ${{secrets.FOD_TENANT}} + FOD_USER: ${{secrets.FOD_USER}} + FOD_PASSWORD: ${{secrets.FOD_PAT}} + # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s + # FOD_RELEASE: MyApp:MyRelease + # PACKAGE_EXTRA_OPTS: -oss -bt mvn + # DO_SETUP: true + # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml + # SETUP_EXTRA_OPTS: --on-unsigned=ignore + # DO_POLICY_CHECK: true + # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml + # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore + # DO_JOB_SUMMARY: true + # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml + # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore + # DO_PR_COMMENT: true + # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml + # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore # DO_EXPORT: true + # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml + # EXPORT_EXTRA_OPTS: --on-unsigned=ignore # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` - - - - - - -## fortify/github-action/ssc-debricked-scan - - - - -This action performs a Debricked Software Composition Analysis (SCA) scan, consisting of the following steps: - -* Login to Fortify SSC -* Run Debricked scan -* Publish Debricked scan results to Fortify SSC -* Optionally wait for SSC artifact processing to complete - -Note that this action is explicitly meant for Debricked/SSC integration. If you wish to run a Debricked scan without publishing the results to SSC, please see the [Debricked GitHub Integration documentation](https://portal.debricked.com/integrations-48/integration-with-github-214#github-actions) - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - +### Action inputs -Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: +This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. -* The appropriate application version must exist on SSC. Future versions of this action may add support for automating application version creation. -* The [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) must be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. +| Action input | Description | +| :--- | :--- | +| sast‑scan | If set to `true`, run a static scan. If not specified or set to `false`, the action will run neither static or open-source scan (independent of `debricked-sca-scan` setting), as open-source scans are currently only run in combination with a static scan. | +| debricked‑sca‑scan | Configure the static scan to also run an open-source scan. Depending on FoD configuration, this may be either a Debricked or a Sonatype scan. Effectively, this adds dependency data to the scan payload, and enables the open-source scan setting in the FoD scan configuration. Note that any existing FoD scan configuration will not be updated, so if the scan has already been configured in FoD, an open-source scan will only be performed if previously enabled in the existing scan configuration. | ### Action environment variable inputs +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - - - - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - - - - - - - -**`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](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-ssc-session-login.html). - - - - -**`DEBRICKED_TOKEN`** - REQUIRED -See the [Generate access token](https://docs.debricked.com/product/administration/generate-access-token) section in the Debricked documentation for details on how to generate this token. - - - - -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. - - - - +| Environment variable | Description | +| :--- | :--- | +| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | +| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). | +| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | +| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | 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.9.0//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| +| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | +|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the FoD application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy state from an existing release using the `--copy-from` option, or to allow an unsigned custom action to be used. If the FoD application may need to be created, you must configure at least the `--app-owner` option. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| +|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. 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. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| +|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.| +| DO_WAIT | 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 job summaries. This behavior is documented in the applicable environment variable descriptions. | +|DO_POLICY_CHECK
CHECK_POLICY_ACTION
CHECK_POLICY_EXTRA_OPTS|If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. Extra options for a 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 the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| +|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
JOB_SUMMARY_EXTRA_OPTS|If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), a job summary listing scan status and issue counts will be generated using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. Extra options for the fcli action can be passed through the `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details. | +| DO_EXPORT
EXPORT_ACTION
EXPORT_EXTRA_OPTS | If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.

Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. | +|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
PR_COMMENT_EXTRA_OPTS|If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. Extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) and [FoD Pull Request Comments](#fod-pull-request-comments) sections below for more details.| +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. + -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. +### FoD fcli actions - + + - +As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. -**`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 job summaries. This behavior is documented in the applicable environment variable descriptions. +For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v2.9.0/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - + +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the FoD release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. + - + - +### FoD Pull Request Comments -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. + - +This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. +**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - - - -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. - -Note that pull request comments will only be generated under the following conditions: +Pull request comments will only be generated under the following conditions: * Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). * All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: +PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application release; it won't detect any new/removed issues from older scans. For best results, you should configure your workflow as follows: - For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. +- Don't set `FOD_RELEASE`, to use the default value that corresponds to repository and branch name. +- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. +- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - +- Create a new application release named `/:`. +- Copy state from the application release identified by the `--copy-from` option to this new application release. +- Run a new scan of the branch associated with the current PR, and upload results to the application release created above. +- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the application release identified by the `--copy-from` option. +If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - + -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. +## Application Security Testing with SSC/ScanCentral - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a Debricked scan and publishing the results to Fortify SSC. +The standard workflow provided by this GitHub Action allows for running a static scan on ScanCentral SAST and/or running software composition analysis on Debricked. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow: ```yaml steps: - name: Check out source code uses: actions/checkout@v4 - - name: Run Debricked Scan - uses: fortify/github-action/ssc-debricked-scan@v1 + - name: Run FoD SAST Scan + uses: fortify/github-action@v1 + with: + sast-scan: true + debricked-sca-scan: true env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # SSC_APPVERSION: MyApp:MyVersion - DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} - # DO_WAIT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip +{x{include:nocomments.env-sc-sast-scan-sample.md}} ``` - - - - - - -## fortify/github-action/ssc-export - - - - -This action exports the latest vulnerability data from an SSC application version to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. - - - - -### Prerequisites - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` +### Action inputs - +This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. +| Action input | Description | +| :--- | :--- | +| `sast-scan` | If set to `true`, run a static scan. If not specified or set to `false`, no static scan will be run. | +| `debricked-sca-scan` | If set to `true`, run Debricked Software Composition Analysis. If not specified or set to `false`, no software composition analysis will be performed. | ### Action environment variable inputs +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - - - - - - - -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. - - - - - - - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. +| Environment variable | Description | +| :--- | :--- | -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for exporting SSC SAST vulnerability data to the GitHub Security Code Scanning dashboard. - -```yaml - steps: - - name: Export SSC vulnerability data to GitHub - uses: fortify/github-action/ssc-export@v1 - env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_APPVERSION: MyApp:MyVersion - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` +{x{include:env-sc-sast-scan.md}} - +{x{include:env-setup.md}} +## Building blocks for custom workflows - + diff --git a/action.yml b/action.yml index f99c9db..449a064 100644 --- a/action.yml +++ b/action.yml @@ -13,15 +13,15 @@ inputs: runs: using: composite steps: - - uses: fortify/github-action/fod-sast-scan@main + - uses: fortify/github-action/fod-sast-scan@doc-updates if: inputs['sast-scan']=='true' && env.FOD_URL env: DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }} - - uses: fortify/github-action/sc-sast-scan@main + - uses: fortify/github-action/sc-sast-scan@doc-updates if: inputs['sast-scan']=='true' && env.SSC_URL env: DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }} - - uses: fortify/github-action/ssc-debricked-scan@main + - uses: fortify/github-action/ssc-debricked-scan@doc-updates if: inputs['sast-scan']=='false' && inputs['debricked-sca-scan']=='true' && env.SSC_URL branding: diff --git a/doc-resources/action-setup.md b/doc-resources/action-setup.md deleted file mode 100644 index 43e63fd..0000000 --- a/doc-resources/action-setup.md +++ /dev/null @@ -1,82 +0,0 @@ -This action allows for setting up the Fortify tools listed below. Which tools and which versions to install, and whether to add the tool bin-directories to the system path, is controlled through action inputs as listed in the next section. - -* [fcli](https://github.com/fortify/fcli) -* [Debricked CLI](https://github.com/debricked/cli) -* [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) - -{{include:action-prerequisites.md}} - -### Action inputs - -**`export-path`** - OPTIONAL -Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` - -**`tool-definitions`** - OPTIONAL -Allows for overriding the location of the Fortify tool definitions bundle. This can be specified either as an action input or through the `TOOL_DEFINITIONS` environment variable; see the 'Action environment variable inputs' section below for details. - -**`fcli`** - OPTIONAL -The fcli version to install. Allowed values: `skip` (default value, do not install fcli), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.0` and `2.0.0` are semantically the same. - -**`sc-client`** - OPTIONAL -The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. - -**`fod-uploader`** - OPTIONAL -The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. - -**`vuln-exporter`** - OPTIONAL -The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.4` and `2.0.4` are semantically the same. - -**`bugtracker-utility`** - OPTIONAL -The FortifyBugTrackerUtility version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v4` will install the latest known `4.x` version. Version may be specified either with or without the `v` prefix, for example `v4.12` and `4.12` are semantically the same. - -**`debricked-cli`** - OPTIONAL -The Debricked CLI version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v1` will install the latest known `1.x` version. Version may be specified either with or without the `v` prefix, for example `v1` and `1` are semantically the same. - -### Action environment variable inputs - -{{include:env-setup.md}} - -### Action outputs - -For each tool being installed, the action outputs several environment variables for use by later workflow steps. - -**`PATH`** -If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. - -**`_INSTALL_DIR`** -Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. - -**`_BIN_DIR`** -Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. - -**`_CMD`** -Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. - -### Sample usage - -The sample workflow below demonstrates how to configure the action for installing the various Fortify tools and how to run these tools. Some notes: - -* The `export-path` and `bugtracker-utility` inputs are set to their default values, and thus could have been omitted. -* The action supports semantic versioning, so the `vuln-exporter` input will install the latest known v2.x.y version of FortifyVulnerabilityExporter. - -```yaml - steps: - - name: Setup Fortify tools - uses: fortify/github-action/setup@{{var:action-major-version}} - with: - tool-definitions: https://github.com/fortify/tool-definitions/releases/download/v1/tool-definitions.yaml.zip - export-path: true - fcli: latest - sc-client: 23.1.0 - fod-uploader: latest - vuln-exporter: v2 - bugtracker-utility: skip - debricked-cli: skip - - name: Run fcli from PATH - run: fcli -V - - name: Run fcli using FCLI_CMD environment variable - run: ${FCLI_CMD} -V -``` \ No newline at end of file diff --git a/doc-resources/action/_root/readme.md b/doc-resources/action/_root/readme.md new file mode 100644 index 0000000..d55693d --- /dev/null +++ b/doc-resources/action/_root/readme.md @@ -0,0 +1,68 @@ +This GitHub Action allows for easy integration of Fortify Application Security Testing (AST) into your GitHub Action workflows. It provides out-of-the-box support for Static Application Security Testing (SAST) and Software Composition Analysis (SCA); support for Dynamic or Mobile Application Security Testing (DAST & MAST) may be added in the future. Apart from utilizing the standard scan workflows provided by this GitHub Action, you may also choose to utilize the various building blocks to implement custom workflows, which can be either customized SAST or SCA workflows, or your own DAST or MAST workflows. + +The following sections describe these topics in more detail: + +* [Prerequisites](#prerequisites) +* [Application Security Testing with Fortify on Demand](#application-security-testing-with-fortify-on-demand) +* [Application Security Testing with SSC/ScanCentral](#application-security-testing-with-ssc-scancentral) +* [Building blocks for custom workflows](#building-blocks-for-custom-workflows) + +{{include:action/generic/prerequisites-h2.md}} + +## Application Security Testing with Fortify on Demand + +The standard workflow provided by this GitHub Action allows for running a Static scan and optional open-source scan (software composition analysis) on Fortify on Demand. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow: + +```yaml + steps: + - name: Check out source code + uses: actions/checkout@v4 + - name: Run FoD SAST Scan + uses: fortify/github-action@{{var:action-major-version}} + with: + sast-scan: true + debricked-sca-scan: true + env: +{{include:action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md}} +``` + +{{include:action/generic/nocomments.input-section-and-table-header.md}} +| sast‑scan | If set to `true`, run a static scan. If not specified or set to `false`, the action will run neither static or open-source scan (independent of `debricked-sca-scan` setting), as open-source scans are currently only run in combination with a static scan. | +| debricked‑sca‑scan | Configure the static scan to also run an open-source scan. Depending on FoD configuration, this may be either a Debricked or a Sonatype scan. Effectively, this adds dependency data to the scan payload, and enables the open-source scan setting in the FoD scan configuration. Note that any existing FoD scan configuration will not be updated, so if the scan has already been configured in FoD, an open-source scan will only be performed if previously enabled in the existing scan configuration. | + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/fod-sast-scan/nocomments.env-fod-sast-scan.md}} + +{{include:action/generic/fod/fod-fcli-actions.md}} + +{{include:action/generic/fod/fod-pr.md}} + +## Application Security Testing with SSC/ScanCentral + +The standard workflow provided by this GitHub Action allows for running a static scan on ScanCentral SAST and/or running software composition analysis on Debricked. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow: + +```yaml + steps: + - name: Check out source code + uses: actions/checkout@v4 + - name: Run FoD SAST Scan + uses: fortify/github-action@{{var:action-major-version}} + with: + sast-scan: true + debricked-sca-scan: true + env: +{x{include:nocomments.env-sc-sast-scan-sample.md}} +``` + +{{include:action/generic/nocomments.input-section-and-table-header.md}} +| `sast-scan` | If set to `true`, run a static scan. If not specified or set to `false`, no static scan will be run. | +| `debricked-sca-scan` | If set to `true`, run Debricked Software Composition Analysis. If not specified or set to `false`, no software composition analysis will be performed. | + +{{include:action/generic/nocomments.env-section-and-table-header.md}} + +{x{include:env-sc-sast-scan.md}} + +{x{include:env-setup.md}} + +## Building blocks for custom workflows + diff --git a/doc-resources/action/fod-export/nocomments.env-export-optional.md b/doc-resources/action/fod-export/nocomments.env-export-optional.md new file mode 100644 index 0000000..46364cb --- /dev/null +++ b/doc-resources/action/fod-export/nocomments.env-export-optional.md @@ -0,0 +1 @@ +| DO_EXPORT
EXPORT_ACTION
EXPORT_EXTRA_OPTS | If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`]({{var:fcli-doc-base-url}}fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.

Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. | \ No newline at end of file diff --git a/doc-resources/action/fod-export/nocomments.env-export.md b/doc-resources/action/fod-export/nocomments.env-export.md new file mode 100644 index 0000000..798cc2d --- /dev/null +++ b/doc-resources/action/fod-export/nocomments.env-export.md @@ -0,0 +1 @@ +| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`]({{var:fcli-doc-base-url}}fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action-fod-export.md b/doc-resources/action/fod-export/readme.md similarity index 51% rename from doc-resources/action-fod-export.md rename to doc-resources/action/fod-export/readme.md index 10e332d..00191b5 100644 --- a/doc-resources/action-fod-export.md +++ b/doc-resources/action/fod-export/readme.md @@ -1,16 +1,6 @@ This action exports the latest vulnerability data from an FoD release to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. -{{include:action-prerequisites.md}} - -### Action environment variable inputs - -{{include:env-fod-connection.md}} - -{{include:env-fod-release.md}} - -{{include:env-do-export.md}} - -{{include:env-setup.md}} +{{include:action/generic/prerequisites-h3.md}} ### Sample usage @@ -21,7 +11,16 @@ The sample workflow below demonstrates how to configure the action for exporting - name: Export FoD vulnerability data to GitHub uses: fortify/github-action/fod-export@{{var:action-major-version}} env: -{{include:nocomments.env-fod-connection-sample.md}} -{{include:nocomments.env-fod-release-sample.md}} -{{include:nocomments.env-setup-sample.md}} +{{include:action/generic/fod/nocomments.snippet-fod-login.md}} +{{include:action/generic/fod/nocomments.snippet-fod-release.md}} +{{include:action/generic/nocomments.snippet-export.md}} +{{include:action/setup/nocomments.snippet-tool-definitions.md}} ``` + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/generic/fod/nocomments.env-fod-login.md}} +{{include:action/generic/fod/nocomments.env-fod-release.md}} +{{include:action/fod-export/nocomments.env-export.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} + +{{include:action/generic/fod/fod-fcli-actions.md}} \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md new file mode 100644 index 0000000..4987c3b --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md @@ -0,0 +1,11 @@ +{{include:action/generic/fod/nocomments.env-fod-login.md}} +{{include:action/generic/fod/nocomments.env-fod-release.md}} +{{include:action/fod-sast-scan/nocomments.env-setup.md}} +{{include:action/package/nocomments.env-package-extra-opts.md}} +|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.| +{{include:action/generic/nocomments.env-do-wait.md}} +{{include:action/fod-sast-scan/nocomments.env-policy-check.md}} +{{include:action/fod-sast-scan/nocomments.env-job-summary.md}} +{{include:action/fod-export/nocomments.env-export-optional.md}} +{{include:action/fod-sast-scan/nocomments.env-pr-comment.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md b/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md new file mode 100644 index 0000000..3f4f443 --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md @@ -0,0 +1 @@ +|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
JOB_SUMMARY_EXTRA_OPTS|If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), a job summary listing scan status and issue counts will be generated using the fcli-provided [FoD `release-summary`]({{var:fcli-doc-base-url}}fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. Extra options for the fcli action can be passed through the `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md b/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md new file mode 100644 index 0000000..81b384f --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md @@ -0,0 +1 @@ +|DO_POLICY_CHECK
CHECK_POLICY_ACTION
CHECK_POLICY_EXTRA_OPTS|If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`]({{var:fcli-doc-base-url}}fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. Extra options for a 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 the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md b/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md new file mode 100644 index 0000000..98b1c06 --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md @@ -0,0 +1 @@ +|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
PR_COMMENT_EXTRA_OPTS|If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [FoD `github-pr-comment`]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. Extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) and [FoD Pull Request Comments](#fod-pull-request-comments) sections below for more details.| diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-setup.md b/doc-resources/action/fod-sast-scan/nocomments.env-setup.md new file mode 100644 index 0000000..6b28f0a --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.env-setup.md @@ -0,0 +1 @@ +|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the FoD application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [FoD `setup-release`]({{var:fcli-doc-base-url}}fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy state from an existing release using the `--copy-from` option, or to allow an unsigned custom action to be used. If the FoD application may need to be created, you must configure at least the `--app-owner` option. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md new file mode 100644 index 0000000..a671a9a --- /dev/null +++ b/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md @@ -0,0 +1,9 @@ +{{include:action/generic/fod/nocomments.snippet-fod-login.md}} +{{include:action/generic/fod/nocomments.snippet-fod-release.md}} +{{include:action/package/nocomments.snippet-package-extra-opts.md}} +{{include:action/generic/nocomments.snippet-setup.md}} +{{include:action/generic/nocomments.snippet-policy-check.md}} +{{include:action/generic/nocomments.snippet-job-summary.md}} +{{include:action/generic/nocomments.snippet-pr-comment.md}} +{{include:action/generic/nocomments.snippet-export-optional.md}} +{{include:action/setup/nocomments.snippet-tool-definitions.md}} \ No newline at end of file diff --git a/doc-resources/action-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/readme.md similarity index 57% rename from doc-resources/action-fod-sast-scan.md rename to doc-resources/action/fod-sast-scan/readme.md index e244a7b..42678ad 100644 --- a/doc-resources/action-fod-sast-scan.md +++ b/doc-resources/action/fod-sast-scan/readme.md @@ -8,18 +8,7 @@ The SAST and optional open source scan performed by this action consists of the * Optionally wait for the scan to complete * Optionally export scan results to the GitHub Code Scanning dashboard -{{include:action-prerequisites.md}} - -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 `PACKAGE_EXTRA_OPTS` environment variable. - -### Action environment variable inputs - -{{include:env-fod-sast-scan.md}} - -{{include:env-setup.md}} +{{include:action/generic/prerequisites-h3.md}} ### Sample usage @@ -32,6 +21,13 @@ The sample workflow below demonstrates how to configure the action for running a - name: Run FoD SAST Scan uses: fortify/github-action/fod-sast-scan@{{var:action-major-version}} env: -{{include:nocomments.env-fod-sast-scan-sample.md}} -{{include:nocomments.env-setup-sample.md}} +{{include:action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md}} ``` + + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/fod-sast-scan/nocomments.env-fod-sast-scan.md}} + +{{include:action/generic/fod/fod-fcli-actions.md}} + +{{include:action/generic/fod/fod-pr.md}} diff --git a/doc-resources/action/generic/fcli-actions.md b/doc-resources/action/generic/fcli-actions.md new file mode 100644 index 0000000..ba1edee --- /dev/null +++ b/doc-resources/action/generic/fcli-actions.md @@ -0,0 +1,4 @@ +As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. + +For more information on fcli actions and custom action development, please see the [fcli action documentation]({{var:fcli-doc-base-url}}#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. + diff --git a/doc-resources/action/generic/fod/fod-fcli-actions.md b/doc-resources/action/generic/fod/fod-fcli-actions.md new file mode 100644 index 0000000..c5d45c8 --- /dev/null +++ b/doc-resources/action/generic/fod/fod-fcli-actions.md @@ -0,0 +1,9 @@ +### FoD fcli actions + + + +{{include:action/generic/fcli-actions.md}} + +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the FoD release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. + +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. diff --git a/doc-resources/action/generic/fod/fod-pr.md b/doc-resources/action/generic/fod/fod-pr.md new file mode 100644 index 0000000..3772c3d --- /dev/null +++ b/doc-resources/action/generic/fod/fod-pr.md @@ -0,0 +1,27 @@ +### FoD Pull Request Comments + + + +This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [FoD `github-pr-comment`]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. + +**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. + +Pull request comments will only be generated under the following conditions: + +* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). +* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 release; it won't detect any new/removed issues from older scans. For best results, you should configure your workflow as follows: + +- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. +- Don't set `FOD_RELEASE`, to use the default value that corresponds to repository and branch name. +- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. +- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. + +With a setup like this, whenever a new PR is created, the GitHub Action will: +- Create a new application release named `/:`. +- Copy state from the application release identified by the `--copy-from` option to this new application release. +- Run a new scan of the branch associated with the current PR, and upload results to the application release created above. +- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the application release identified by the `--copy-from` option. + +If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. diff --git a/doc-resources/action/generic/fod/nocomments.env-fod-login.md b/doc-resources/action/generic/fod/nocomments.env-fod-login.md new file mode 100644 index 0000000..d5aef4b --- /dev/null +++ b/doc-resources/action/generic/fod/nocomments.env-fod-login.md @@ -0,0 +1,4 @@ +| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | +| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). | +| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | +| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | 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) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/generic/fod/nocomments.env-fod-release.md b/doc-resources/action/generic/fod/nocomments.env-fod-release.md new file mode 100644 index 0000000..a19db74 --- /dev/null +++ b/doc-resources/action/generic/fod/nocomments.env-fod-release.md @@ -0,0 +1 @@ +| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | \ No newline at end of file diff --git a/doc-resources/nocomments.env-fod-connection-sample.md b/doc-resources/action/generic/fod/nocomments.snippet-fod-login.md similarity index 56% rename from doc-resources/nocomments.env-fod-connection-sample.md rename to doc-resources/action/generic/fod/nocomments.snippet-fod-login.md index 1efb5ab..452c761 100644 --- a/doc-resources/nocomments.env-fod-connection-sample.md +++ b/doc-resources/action/generic/fod/nocomments.snippet-fod-login.md @@ -1,4 +1,5 @@ FOD_URL: https://ams.fortify.com FOD_TENANT: ${{secrets.FOD_TENANT}} FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} \ No newline at end of file + FOD_PASSWORD: ${{secrets.FOD_PAT}} + # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/nocomments.env-fod-release-sample.md b/doc-resources/action/generic/fod/nocomments.snippet-fod-release.md similarity index 100% rename from doc-resources/nocomments.env-fod-release-sample.md rename to doc-resources/action/generic/fod/nocomments.snippet-fod-release.md diff --git a/doc-resources/action/generic/nocomments.env-do-wait.md b/doc-resources/action/generic/nocomments.env-do-wait.md new file mode 100644 index 0000000..4b06081 --- /dev/null +++ b/doc-resources/action/generic/nocomments.env-do-wait.md @@ -0,0 +1 @@ +| DO_WAIT | 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 job summaries. This behavior is documented in the applicable environment variable descriptions. | diff --git a/doc-resources/action/generic/nocomments.env-section-and-table-header.md b/doc-resources/action/generic/nocomments.env-section-and-table-header.md new file mode 100644 index 0000000..e652cf4 --- /dev/null +++ b/doc-resources/action/generic/nocomments.env-section-and-table-header.md @@ -0,0 +1,5 @@ +### Action environment variable inputs + +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. + +{{include:action/generic/nocomments.env-table-header.md}} \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.env-table-header.md b/doc-resources/action/generic/nocomments.env-table-header.md new file mode 100644 index 0000000..e988eb5 --- /dev/null +++ b/doc-resources/action/generic/nocomments.env-table-header.md @@ -0,0 +1,2 @@ +| Environment variable | Description | +| :--- | :--- | \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.input-section-and-table-header.md b/doc-resources/action/generic/nocomments.input-section-and-table-header.md new file mode 100644 index 0000000..8f0162e --- /dev/null +++ b/doc-resources/action/generic/nocomments.input-section-and-table-header.md @@ -0,0 +1,5 @@ +### Action inputs + +This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. + +{{include:action/generic/nocomments.input-table-header.md}} \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.input-table-header.md b/doc-resources/action/generic/nocomments.input-table-header.md new file mode 100644 index 0000000..2397370 --- /dev/null +++ b/doc-resources/action/generic/nocomments.input-table-header.md @@ -0,0 +1,2 @@ +| Action input | Description | +| :--- | :--- | \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-export-optional.md b/doc-resources/action/generic/nocomments.snippet-export-optional.md new file mode 100644 index 0000000..9ea2a62 --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-export-optional.md @@ -0,0 +1,2 @@ + # DO_EXPORT: true +{{include:action/generic/nocomments.snippet-export.md}} \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-export.md b/doc-resources/action/generic/nocomments.snippet-export.md new file mode 100644 index 0000000..49399f8 --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-export.md @@ -0,0 +1,2 @@ + # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml + # EXPORT_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-job-summary.md b/doc-resources/action/generic/nocomments.snippet-job-summary.md new file mode 100644 index 0000000..78a89d3 --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-job-summary.md @@ -0,0 +1,3 @@ + # DO_JOB_SUMMARY: true + # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml + # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-policy-check.md b/doc-resources/action/generic/nocomments.snippet-policy-check.md new file mode 100644 index 0000000..37af8fd --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-policy-check.md @@ -0,0 +1,3 @@ + # DO_POLICY_CHECK: true + # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml + # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-pr-comment.md b/doc-resources/action/generic/nocomments.snippet-pr-comment.md new file mode 100644 index 0000000..c5b682d --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-pr-comment.md @@ -0,0 +1,3 @@ + # DO_PR_COMMENT: true + # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml + # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/generic/nocomments.snippet-setup.md b/doc-resources/action/generic/nocomments.snippet-setup.md new file mode 100644 index 0000000..58aa83e --- /dev/null +++ b/doc-resources/action/generic/nocomments.snippet-setup.md @@ -0,0 +1,3 @@ + # DO_SETUP: true + # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml + # SETUP_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/generic/prerequisites-h2.md b/doc-resources/action/generic/prerequisites-h2.md new file mode 100644 index 0000000..a4bf813 --- /dev/null +++ b/doc-resources/action/generic/prerequisites-h2.md @@ -0,0 +1,3 @@ +## Prerequisites + +{{include:action/generic/prerequisites.md}} \ No newline at end of file diff --git a/doc-resources/action/generic/prerequisites-h3.md b/doc-resources/action/generic/prerequisites-h3.md new file mode 100644 index 0000000..59e2752 --- /dev/null +++ b/doc-resources/action/generic/prerequisites-h3.md @@ -0,0 +1,3 @@ +### Prerequisites + +{{include:action/generic/prerequisites.md}} \ No newline at end of file diff --git a/doc-resources/action-prerequisites.md b/doc-resources/action/generic/prerequisites.md similarity index 97% rename from doc-resources/action-prerequisites.md rename to doc-resources/action/generic/prerequisites.md index 7a42269..5220ca8 100644 --- a/doc-resources/action-prerequisites.md +++ b/doc-resources/action/generic/prerequisites.md @@ -1,5 +1,3 @@ -### Prerequisites - This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js diff --git a/doc-resources/action/generic/ssc/nocomments.env-ssc-appversion.md b/doc-resources/action/generic/ssc/nocomments.env-ssc-appversion.md new file mode 100644 index 0000000..7729d07 --- /dev/null +++ b/doc-resources/action/generic/ssc/nocomments.env-ssc-appversion.md @@ -0,0 +1 @@ +|SSC_APPVERSION|Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`.| \ No newline at end of file diff --git a/doc-resources/action/generic/ssc/nocomments.env-ssc-login.md b/doc-resources/action/generic/ssc/nocomments.env-ssc-login.md new file mode 100644 index 0000000..fe2b0ae --- /dev/null +++ b/doc-resources/action/generic/ssc/nocomments.env-ssc-login.md @@ -0,0 +1,4 @@ +|**SSC_URL**|Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets.| +|**SSC_TOKEN**|Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`.| +|**SSC_USER
SSC_PASSWORD**|Required when authenticating with SSC user credentials.| +|SSC_LOGIN_EXTRA_OPTS
EXTRA_SSC_LOGIN_OPTS|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). Note that `EXTRA_SSC_LOGIN_OPTS` is deprecated; please use `SSC_LOGIN_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/nocomments.env-ssc-appversion-sample.md b/doc-resources/action/generic/ssc/nocomments.snippet-ssc-appversion.md similarity index 100% rename from doc-resources/nocomments.env-ssc-appversion-sample.md rename to doc-resources/action/generic/ssc/nocomments.snippet-ssc-appversion.md diff --git a/doc-resources/action/generic/ssc/nocomments.snippet-ssc-login.md b/doc-resources/action/generic/ssc/nocomments.snippet-ssc-login.md new file mode 100644 index 0000000..a21a0f6 --- /dev/null +++ b/doc-resources/action/generic/ssc/nocomments.snippet-ssc-login.md @@ -0,0 +1,3 @@ + SSC_URL: ${{vars.SSC_URL}} + SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/action/generic/ssc/ssc-fcli-actions.md b/doc-resources/action/generic/ssc/ssc-fcli-actions.md new file mode 100644 index 0000000..4a90a39 --- /dev/null +++ b/doc-resources/action/generic/ssc/ssc-fcli-actions.md @@ -0,0 +1,9 @@ +### SSC fcli actions + + + +{{include:action/generic/fcli-actions.md}} + +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--av` / `--appversion` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the SSC application version to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. + +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. diff --git a/doc-resources/action/generic/ssc/ssc-pr.md b/doc-resources/action/generic/ssc/ssc-pr.md new file mode 100644 index 0000000..a8a9024 --- /dev/null +++ b/doc-resources/action/generic/ssc/ssc-pr.md @@ -0,0 +1,27 @@ +### SSC Pull Request Comments + + + +This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [SSC `github-pr-comment`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. + +**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. + +Pull request comments will only be generated under the following conditions: + +* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). +* All other standard GitHub environment variables like `GITHUB_TOKEN`, `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; it won't detect any new/removed issues from older scans. For best results, you should configure your workflow as follows: + +- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. +- Don't set `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. +- Set `DO_SETUP` to `true`, to allow a branch-specific application version to be automatically created. +- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the application version that represents the PR target branch or your main branch into the newly created application version. + +With a setup like this, whenever a new PR is created, the GitHub Action will: +- Create a new application version named `/:`. +- Copy state from the application version identified by the `--copy-from` option to this new application version. +- Run a new scan of the branch associated with the current PR, and upload results to the application version created above. +- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the application version identified by the `--copy-from` option. + +If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. diff --git a/doc-resources/action/package/nocomments.env-package-extra-opts.md b/doc-resources/action/package/nocomments.env-package-extra-opts.md new file mode 100644 index 0000000..04473a2 --- /dev/null +++ b/doc-resources/action/package/nocomments.env-package-extra-opts.md @@ -0,0 +1 @@ +|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. See [Command-line options for the package command]({{var:sc-client-doc-base-url}}#cli/package-cmd.htm) for more information on available options. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/package/nocomments.snippet-package-extra-opts.md b/doc-resources/action/package/nocomments.snippet-package-extra-opts.md new file mode 100644 index 0000000..8050831 --- /dev/null +++ b/doc-resources/action/package/nocomments.snippet-package-extra-opts.md @@ -0,0 +1 @@ + # PACKAGE_EXTRA_OPTS: -oss -bt mvn \ No newline at end of file diff --git a/doc-resources/action-package.md b/doc-resources/action/package/readme.md similarity index 57% rename from doc-resources/action-package.md rename to doc-resources/action/package/readme.md index 50f1471..0d5edb0 100644 --- a/doc-resources/action-package.md +++ b/doc-resources/action/package/readme.md @@ -1,12 +1,6 @@ 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}} - -### Action environment variable inputs - -{{include:env-package.md}} - -{{include:env-setup.md}} +{{include:action/generic/prerequisites-h3.md}} ### Sample usage @@ -19,6 +13,10 @@ The sample workflow below demonstrates how to configure the action for running a - name: Package source code uses: fortify/github-action/package@{{var:action-major-version}} env: -{{include:nocomments.env-package-sample.md}} -{{include:nocomments.env-setup-sample.md}} -``` \ No newline at end of file +{{include:action/package/nocomments.snippet-package-extra-opts.md}} +{{include:action/setup/nocomments.snippet-tool-definitions.md}} +``` + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/package/nocomments.env-package-extra-opts.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} \ No newline at end of file diff --git a/doc-resources/action-sc-sast-scan.md b/doc-resources/action/sc-sast-scan/readme.md similarity index 88% rename from doc-resources/action-sc-sast-scan.md rename to doc-resources/action/sc-sast-scan/readme.md index 9f5e133..41ab639 100644 --- a/doc-resources/action-sc-sast-scan.md +++ b/doc-resources/action/sc-sast-scan/readme.md @@ -7,11 +7,10 @@ This action performs a SAST scan on ScanCentral SAST, consisting of the followin * Optionally wait for all scans to complete and results having been processed by SSC * Optionally export scan results to the GitHub Code Scanning dashboard -{{include:action-prerequisites.md}} +{{include:action/generic/prerequisites-h3.md}} Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: -* The appropriate application version must exist on SSC. Future versions of this action may add support for automating application version creation. * If Debricked scanning is enabled, the [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) must be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. ### Action environment variable inputs diff --git a/doc-resources/action/setup/nocomments.env-tool-definitions.md b/doc-resources/action/setup/nocomments.env-tool-definitions.md new file mode 100644 index 0000000..82e90e0 --- /dev/null +++ b/doc-resources/action/setup/nocomments.env-tool-definitions.md @@ -0,0 +1 @@ +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | diff --git a/doc-resources/nocomments.env-setup-sample.md b/doc-resources/action/setup/nocomments.snippet-tool-definitions.md similarity index 100% rename from doc-resources/nocomments.env-setup-sample.md rename to doc-resources/action/setup/nocomments.snippet-tool-definitions.md diff --git a/doc-resources/action/setup/readme.md b/doc-resources/action/setup/readme.md new file mode 100644 index 0000000..211d046 --- /dev/null +++ b/doc-resources/action/setup/readme.md @@ -0,0 +1,59 @@ +This action allows for setting up the Fortify tools listed below. Which tools and which versions to install, and whether to add the tool bin-directories to the system path, is controlled through action inputs as listed in the next section. + +* [fcli](https://github.com/fortify/fcli) +* [Debricked CLI](https://github.com/debricked/cli) +* [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) + +{{include:action/generic/prerequisites-h3.md}} + +### Sample usage + +The sample workflow below demonstrates how to configure the action for installing the various Fortify tools and how to run these tools. Some notes: + +* The `export-path` and `bugtracker-utility` inputs are set to their default values, and thus could have been omitted. +* The action supports semantic versioning, so the `vuln-exporter` input will install the latest known v2.x.y version of FortifyVulnerabilityExporter. + +```yaml + steps: + - name: Setup Fortify tools + uses: fortify/github-action/setup@{{var:action-major-version}} + with: + tool-definitions: https://github.com/fortify/tool-definitions/releases/download/v1/tool-definitions.yaml.zip + export-path: true + fcli: latest + sc-client: 23.1.0 + fod-uploader: latest + vuln-exporter: v2 + bugtracker-utility: skip + debricked-cli: skip + - name: Run fcli from PATH + run: fcli -V + - name: Run fcli using FCLI_CMD environment variable + run: ${FCLI_CMD} -V +``` + +{{include:action/generic/nocomments.input-section-and-table-header.md}} +| export‑path | Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` | +| tool‑definitions | Allows for overriding the location of the Fortify tool definitions bundle. This can be specified either as an action input or through the `TOOL_DEFINITIONS` environment variable; see the 'Action environment variable inputs' section below for details. | +| fcli | The fcli version to install. Allowed values: `skip` (default value, do not install fcli), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.0` and `2.0.0` are semantically the same. | +| sc‑client | The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. | +| fod‑uploader | The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. | +| vuln‑exporter | The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.4` and `2.0.4` are semantically the same. | +| bugtracker‑utility | The FortifyBugTrackerUtility version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v4` will install the latest known `4.x` version. Version may be specified either with or without the `v` prefix, for example `v4.12` and `4.12` are semantically the same. | +| debricked‑cli | The Debricked CLI version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v1` will install the latest known `1.x` version. Version may be specified either with or without the `v` prefix, for example `v1` and `1` are semantically the same. | + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} + +### Action outputs + +For each tool being installed, the action outputs several environment variables for use by later workflow steps. + +{{include:action/generic/nocomments.env-table-header.md}} +| PATH | If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. | +| <TOOL_NAME>_INSTALL_DIR | Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. | +| <TOOL_NAME>_BIN_DIR | Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. | +| <TOOL_NAME>_CMD | Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. | diff --git a/doc-resources/action-ssc-debricked-scan.md b/doc-resources/action/ssc-debricked-scan/readme.md similarity index 97% rename from doc-resources/action-ssc-debricked-scan.md rename to doc-resources/action/ssc-debricked-scan/readme.md index 9a5fe4c..aed27f8 100644 --- a/doc-resources/action-ssc-debricked-scan.md +++ b/doc-resources/action/ssc-debricked-scan/readme.md @@ -7,7 +7,7 @@ This action performs a Debricked Software Composition Analysis (SCA) scan, consi Note that this action is explicitly meant for Debricked/SSC integration. If you wish to run a Debricked scan without publishing the results to SSC, please see the [Debricked GitHub Integration documentation](https://portal.debricked.com/integrations-48/integration-with-github-214#github-actions) -{{include:action-prerequisites.md}} +{{include:action/generic/prerequisites-h3.md}} Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: diff --git a/doc-resources/action/ssc-export/nocomments.env-export-optional.md b/doc-resources/action/ssc-export/nocomments.env-export-optional.md new file mode 100644 index 0000000..5b8819c --- /dev/null +++ b/doc-resources/action/ssc-export/nocomments.env-export-optional.md @@ -0,0 +1 @@ +| DO_EXPORT
EXPORT_ACTION
EXPORT_EXTRA_OPTS | If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`), this GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.

Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. | \ No newline at end of file diff --git a/doc-resources/action/ssc-export/nocomments.env-export.md b/doc-resources/action/ssc-export/nocomments.env-export.md new file mode 100644 index 0000000..27c0b8c --- /dev/null +++ b/doc-resources/action/ssc-export/nocomments.env-export.md @@ -0,0 +1 @@ +| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action-ssc-export.md b/doc-resources/action/ssc-export/readme.md similarity index 51% rename from doc-resources/action-ssc-export.md rename to doc-resources/action/ssc-export/readme.md index 166a444..4eeaf2f 100644 --- a/doc-resources/action-ssc-export.md +++ b/doc-resources/action/ssc-export/readme.md @@ -1,16 +1,6 @@ This action exports the latest vulnerability data from an SSC application version to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. -{{include:action-prerequisites.md}} - -### Action environment variable inputs - -{{include:env-ssc-connection.md}} - -{{include:env-ssc-appversion.md}} - -{{include:env-do-export.md}} - -{{include:env-setup.md}} +{{include:action/generic/prerequisites-h3.md}} ### Sample usage @@ -21,7 +11,16 @@ The sample workflow below demonstrates how to configure the action for exporting - name: Export SSC vulnerability data to GitHub uses: fortify/github-action/ssc-export@{{var:action-major-version}} env: -{{include:nocomments.env-ssc-connection-sample.md}} -{{include:nocomments.env-ssc-appversion-sample.md}} -{{include:nocomments.env-setup-sample.md}} +{{include:action/generic/ssc/nocomments.snippet-ssc-login.md}} +{{include:action/generic/ssc/nocomments.snippet-ssc-appversion.md}} +{{include:action/generic/nocomments.snippet-export.md}} +{{include:action/setup/nocomments.snippet-tool-definitions.md}} ``` + +{{include:action/generic/nocomments.env-section-and-table-header.md}} +{{include:action/generic/ssc/nocomments.env-ssc-login.md}} +{{include:action/generic/ssc/nocomments.env-ssc-appversion.md}} +{{include:action/ssc-export/nocomments.env-export.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} + +{{include:action/generic/ssc/ssc-fcli-actions.md}} diff --git a/doc-resources/env-fod-connection.md b/doc-resources/env-fod-connection.md deleted file mode 100644 index 8d481af..0000000 --- a/doc-resources/env-fod-connection.md +++ /dev/null @@ -1,8 +0,0 @@ -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). - -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. diff --git a/doc-resources/env-fod-login.md b/doc-resources/env-fod-login.md deleted file mode 100644 index 74648c2..0000000 --- a/doc-resources/env-fod-login.md +++ /dev/null @@ -1,4 +0,0 @@ -{{include:env-fod-connection.md}} - -**`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) \ No newline at end of file diff --git a/doc-resources/env-fod-package.md b/doc-resources/env-fod-package.md deleted file mode 100644 index 76243cb..0000000 --- a/doc-resources/env-fod-package.md +++ /dev/null @@ -1,8 +0,0 @@ -**`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 `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 ` 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. diff --git a/doc-resources/env-fod-release.md b/doc-resources/env-fod-release.md deleted file mode 100644 index 5b36e7e..0000000 --- a/doc-resources/env-fod-release.md +++ /dev/null @@ -1,2 +0,0 @@ -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. \ No newline at end of file diff --git a/doc-resources/env-fod-sast-scan.md b/doc-resources/env-fod-sast-scan.md deleted file mode 100644 index 66bfdcc..0000000 --- a/doc-resources/env-fod-sast-scan.md +++ /dev/null @@ -1,22 +0,0 @@ - -{{include:env-fod-login.md}} - -{{include:env-fod-release.md}} - -{{include:env-do-setup.md}} - -{{include:env-fod-package.md}} - -**`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}} - -{{include:env-do-pr-comment.md}} - diff --git a/doc-resources/env-package.md b/doc-resources/env-package.md deleted file mode 100644 index 7414d76..0000000 --- a/doc-resources/env-package.md +++ /dev/null @@ -1,4 +0,0 @@ -**`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 ` 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. diff --git a/doc-resources/env-setup.md b/doc-resources/env-setup.md deleted file mode 100644 index 09e2e88..0000000 --- a/doc-resources/env-setup.md +++ /dev/null @@ -1,4 +0,0 @@ -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. diff --git a/doc-resources/env-ssc-appversion.md b/doc-resources/env-ssc-appversion.md deleted file mode 100644 index f3ebe32..0000000 --- a/doc-resources/env-ssc-appversion.md +++ /dev/null @@ -1,2 +0,0 @@ -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. \ No newline at end of file diff --git a/doc-resources/env-ssc-connection.md b/doc-resources/env-ssc-connection.md deleted file mode 100644 index 3854feb..0000000 --- a/doc-resources/env-ssc-connection.md +++ /dev/null @@ -1,8 +0,0 @@ -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. - -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. \ No newline at end of file diff --git a/doc-resources/env-ssc-login.md b/doc-resources/env-ssc-login.md deleted file mode 100644 index 4ee4a8c..0000000 --- a/doc-resources/env-ssc-login.md +++ /dev/null @@ -1,2 +0,0 @@ -**`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). \ No newline at end of file diff --git a/doc-resources/env-do-wait.md b/doc-resources/env/sc-sast/env-do-wait.md similarity index 100% rename from doc-resources/env-do-wait.md rename to doc-resources/env/sc-sast/env-do-wait.md diff --git a/doc-resources/env-sc-sast-login.md b/doc-resources/env/sc-sast/env-sc-sast-login.md similarity index 100% rename from doc-resources/env-sc-sast-login.md rename to doc-resources/env/sc-sast/env-sc-sast-login.md diff --git a/doc-resources/env-sc-sast-scan.md b/doc-resources/env/sc-sast/env-sc-sast-scan.md similarity index 100% rename from doc-resources/env-sc-sast-scan.md rename to doc-resources/env/sc-sast/env-sc-sast-scan.md diff --git a/doc-resources/env-do-export.md b/doc-resources/env/ssc/env-do-export.md similarity index 100% rename from doc-resources/env-do-export.md rename to doc-resources/env/ssc/env-do-export.md diff --git a/doc-resources/env-do-job-summary.md b/doc-resources/env/ssc/env-do-job-summary.md similarity index 100% rename from doc-resources/env-do-job-summary.md rename to doc-resources/env/ssc/env-do-job-summary.md diff --git a/doc-resources/env-do-policy-check.md b/doc-resources/env/ssc/env-do-policy-check.md similarity index 100% rename from doc-resources/env-do-policy-check.md rename to doc-resources/env/ssc/env-do-policy-check.md diff --git a/doc-resources/env-do-pr-comment.md b/doc-resources/env/ssc/env-do-pr-comment.md similarity index 100% rename from doc-resources/env-do-pr-comment.md rename to doc-resources/env/ssc/env-do-pr-comment.md diff --git a/doc-resources/env-do-setup.md b/doc-resources/env/ssc/env-do-setup.md similarity index 100% rename from doc-resources/env-do-setup.md rename to doc-resources/env/ssc/env-do-setup.md diff --git a/doc-resources/env-ssc-debricked-scan.md b/doc-resources/env/ssc/env-ssc-debricked-scan.md similarity index 100% rename from doc-resources/env-ssc-debricked-scan.md rename to doc-resources/env/ssc/env-ssc-debricked-scan.md diff --git a/doc-resources/nocomments.env-fod-login-sample.md b/doc-resources/nocomments.env-fod-login-sample.md deleted file mode 100644 index 3e10927..0000000 --- a/doc-resources/nocomments.env-fod-login-sample.md +++ /dev/null @@ -1,2 +0,0 @@ -{{include:nocomments.env-fod-connection-sample.md}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/nocomments.env-fod-package-sample.md b/doc-resources/nocomments.env-fod-package-sample.md deleted file mode 100644 index 0d7363e..0000000 --- a/doc-resources/nocomments.env-fod-package-sample.md +++ /dev/null @@ -1 +0,0 @@ - # PACKAGE_EXTRA_OPTS: -oss \ No newline at end of file diff --git a/doc-resources/nocomments.env-package-sample.md b/doc-resources/nocomments.env-package-sample.md deleted file mode 100644 index 08eca1a..0000000 --- a/doc-resources/nocomments.env-package-sample.md +++ /dev/null @@ -1 +0,0 @@ - # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml \ No newline at end of file diff --git a/doc-resources/nocomments.env-ssc-connection-sample.md b/doc-resources/nocomments.env-ssc-connection-sample.md deleted file mode 100644 index 79bc9b0..0000000 --- a/doc-resources/nocomments.env-ssc-connection-sample.md +++ /dev/null @@ -1,2 +0,0 @@ - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} \ No newline at end of file diff --git a/doc-resources/nocomments.env-ssc-login-sample.md b/doc-resources/nocomments.env-ssc-login-sample.md deleted file mode 100644 index c2b41fc..0000000 --- a/doc-resources/nocomments.env-ssc-login-sample.md +++ /dev/null @@ -1 +0,0 @@ - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/repo-readme.md b/doc-resources/repo-readme.md deleted file mode 100644 index cd629ae..0000000 --- a/doc-resources/repo-readme.md +++ /dev/null @@ -1,186 +0,0 @@ -The [Fortify github-action repository]({{var:repo-url}}) hosts various Fortify-related GitHub Actions as listed in the sections below. - -**Fortify on Demand** - -* [`fortify/github-action`](#fortify-github-action) - For now, this action provides the same functionality as the `fod-sast-scan` action listed below. Future versions may add support for running other types of scans or performing other FoD operations. -* [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) - Package source code, submit static application security testing (SAST) scan request to Fortify on Demand, optionally wait for completion and export results back to the GitHub Security dashboard. -* [`fortify/github-action/package`](#fortify-github-action-package) - Package source code for running a SAST scan, using the latest version of ScanCentral Client. Optionally resolve dependencies for Software Composition Analysis (SCA) of open source components with integrated Debricked analysis via Fortify on Demand. -* [`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}}#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** - -* [`fortify/github-action`](#fortify-github-action) - Depending on inputs, this action will run either or both a ScanCentral SAST and Debricked Software Composition Analysis (SCA) scan and publish scan results to SSC. Future versions may add support for running other types of scans or performing other SSC / ScanCentral operations. -* [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) - Run a ScanCentral SAST and optionally Debricked Software Composition Analysis scan by packaging source code, submitting ScanCentral SAST scan and optional Debricked scan request, and optionally waiting for completion and exporting SAST results back to the GitHub Security dashboard. -* [`fortify/github-action/ssc-debricked-scan`](#fortify-github-action-ssc-debricked-scan) - Run a Debricked Software Composition Analysis scan and publish scan results to SSC, optionally waiting for scan results to be fully processed on SSC. -* [`fortify/github-action/package`](#fortify-github-action-package) - Package source code for running a SAST scan, using the latest version of ScanCentral Client. -* [`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}}#cli/intro.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline - - - -## fortify/github-action - -The primary `fortify/github-action` action currently allows for running SAST and optional Software Composition Analysis scans on either Fortify on Demand or ScanCentral SAST / Debricked. Which activities to perform is controlled through action inputs, the input for those activities is provided through environment variables. - -Based on inputs and environment variables, this action will simply configure and run one of the following sub-actions: - -| Conditions | Sub-action | -| ---------- | ---------- | -| `sast-scan: true`
`FOD_URL` specified | [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) | -| `sast-scan: true`
`SSC_URL` specified | [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) | -| `sast-scan: false`
`debricked-sca-scan: true`
`SSC_URL` specified | [`fortify/github-action/ssc-debricked-scan`](#fortify-github-action-ssc-debricked-scan) | - -If none of the conditions listed above are met, this action will complete without performing any work. - -{{include:action-prerequisites.md}} - -Depending on inputs, additional prerequisites may apply as listed in the documentation for the sub-actions listed in the table above. - -### Action inputs - -**`sast-scan`** - OPTIONAL -When set to true, the action will run a SAST scan on either Fortify on Demand (if the `FOD_URL` environment variable has been specified), or on ScanCentral SAST (if the `SSC_URL` environment variable has been specified). This includes packaging the source code, running the scan, and optionally reporting SAST scan results back into GitHub. - -If not specified or when set to false, no SAST scan will be performed. For FoD, this means that the action will complete without doing any work. For SSC, the action could still run a Debricked-only scan based on the `debricked-sca-scan` input as listed below. Future versions of this action may provide additional inputs, for example allowing you to run a dynamic application security testing (DAST) scan instead of (or in combination with) a SAST scan. - -**`debricked-sca-scan`** - OPTIONAL -(Not applicable to Fortify on Demand) When set to true, the action will run a Debricked Software Composition Analysis (SCA) scan and publish the results to Fortify SSC. You can either run a Debricked-only scan (`sast-scan` set to `false`), or both SAST and Debricked SCA scan if both inputs are set to `true`. - -### Action environment variable inputs - -#### Fortify on Demand - -{{include:env-fod-sast-scan.md}} - -{{include:env-setup.md}} - -#### ScanCentral SAST with optional Debricked scan - -{{include:env-sc-sast-scan.md}} - -{{include:env-setup.md}} - -#### Debricked-only scan and publish to SSC - -{{include:env-ssc-debricked-scan.md}} - -{{include:env-setup.md}} - -### Sample workflows - -The sample workflows below demonstrate how to configure the action for running a SAST scan on either Fortify on Demand or ScanCentral SAST. - -#### Fortify on Demand - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run FoD SAST Scan - uses: fortify/github-action@{{var:action-major-version}} - with: - sast-scan: true - env: -{{include:nocomments.env-fod-sast-scan-sample.md}} -{{include:nocomments.env-setup-sample.md}} -``` - -#### ScanCentral SAST with optional Debricked scan - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run ScanCentral SAST Scan - uses: fortify/github-action@{{var:action-major-version}} - with: - sast-scan: true - # debricked-sca-scan: true - env: -{{include:nocomments.env-sc-sast-scan-sample.md}} -{{include:nocomments.env-setup-sample.md}} -``` - -#### Debricked-only scan and publish to SSC - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Debricked Scan - uses: fortify/github-action@{{var:action-major-version}} - with: - sast-scan: false - debricked-sca-scan: true - env: -{{include:nocomments.env-ssc-debricked-scan-sample.md}} -{{include:nocomments.env-setup-sample.md}} -``` - -### More information - -Depending on input, this action delegates to the appropriate sub-action(s). Please refer to the documentation of these actions for a more detailed description of action behavior & requirements: - -* FoD SAST & optional SCA (open source) scan: [`fortify/github-action/fod-sast-scan`](#fortify-github-action-fod-sast-scan) -* ScanCentral SAST scan: [`fortify/github-action/sc-sast-scan`](#fortify-github-action-sc-sast-scan) - - - - -## fortify/github-action/setup - -{{include:action-setup.md}} - - - - -## fortify/github-action/package - -{{include:action-package.md}} - - - - -## fortify/github-action/fod-sast-scan - -{{include:action-fod-sast-scan.md}} - - - - -## fortify/github-action/fod-export - -{{include:action-fod-export.md}} - - - - -## fortify/github-action/sc-sast-scan - -{{include:action-sc-sast-scan.md}} - - - - -## fortify/github-action/ssc-debricked-scan - -{{include:action-ssc-debricked-scan.md}} - - - - -## fortify/github-action/ssc-export - -{{include:action-ssc-export.md}} diff --git a/doc-resources/templates/README.template.md b/doc-resources/templates/README.template.md index e24f8c0..dde6a65 100644 --- a/doc-resources/templates/README.template.md +++ b/doc-resources/templates/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:repo-readme.md}} +{{include:action/_root/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/fod-export/README.template.md b/doc-resources/templates/fod-export/README.template.md index 53bc1a1..b8da685 100644 --- a/doc-resources/templates/fod-export/README.template.md +++ b/doc-resources/templates/fod-export/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-fod-export.md}} +{{include:action/fod-export/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/fod-sast-scan/README.template.md b/doc-resources/templates/fod-sast-scan/README.template.md index 3bdb4bb..63c57e8 100644 --- a/doc-resources/templates/fod-sast-scan/README.template.md +++ b/doc-resources/templates/fod-sast-scan/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-fod-sast-scan.md}} +{{include:action/fod-sast-scan/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/package/README.template.md b/doc-resources/templates/package/README.template.md index 736ca7f..a7b78ef 100644 --- a/doc-resources/templates/package/README.template.md +++ b/doc-resources/templates/package/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-package.md}} +{{include:action/package/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/setup/README.template.md b/doc-resources/templates/setup/README.template.md index e08f766..e0e05a6 100644 --- a/doc-resources/templates/setup/README.template.md +++ b/doc-resources/templates/setup/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-setup.md}} +{{include:action/setup/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/ssc-export/README.template.md b/doc-resources/templates/ssc-export/README.template.md index 8e21021..9fddf86 100644 --- a/doc-resources/templates/ssc-export/README.template.md +++ b/doc-resources/templates/ssc-export/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-ssc-export.md}} +{{include:action/ssc-export/readme.md}} {{include:h2.support.md}} diff --git a/doc-resources/todo/templates/fod-sast-scan/README.template.md b/doc-resources/todo/templates/fod-sast-scan/README.template.md new file mode 100644 index 0000000..b6c1d2f --- /dev/null +++ b/doc-resources/todo/templates/fod-sast-scan/README.template.md @@ -0,0 +1,11 @@ +# fortify/github-action/fod-sast-scan@{{var:action-major-version}} + +{{include:p.marketing-intro.md}} + +{{include:action/fod-sast-scan.md}} + +{{include:h2.support.md}} + +--- + +*[This document was auto-generated; do not edit by hand](https://github.com/fortify/shared-doc-resources/blob/main/USAGE.md)* \ No newline at end of file diff --git a/doc-resources/templates/sc-sast-scan/README.template.md b/doc-resources/todo/templates/sc-sast-scan/README.template.md similarity index 88% rename from doc-resources/templates/sc-sast-scan/README.template.md rename to doc-resources/todo/templates/sc-sast-scan/README.template.md index ce6d261..e4cb597 100644 --- a/doc-resources/templates/sc-sast-scan/README.template.md +++ b/doc-resources/todo/templates/sc-sast-scan/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-sc-sast-scan.md}} +{{include:action/sc-sast-scan.md}} {{include:h2.support.md}} diff --git a/doc-resources/templates/ssc-debricked-scan/README.template.md b/doc-resources/todo/templates/ssc-debricked-scan/README.template.md similarity index 86% rename from doc-resources/templates/ssc-debricked-scan/README.template.md rename to doc-resources/todo/templates/ssc-debricked-scan/README.template.md index 4583920..0343757 100644 --- a/doc-resources/templates/ssc-debricked-scan/README.template.md +++ b/doc-resources/todo/templates/ssc-debricked-scan/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-ssc-debricked-scan.md}} +{{include:action/ssc-debricked-scan.md}} {{include:h2.support.md}} diff --git a/fod-export/README.md b/fod-export/README.md index 331ad45..5c7cecf 100644 --- a/fod-export/README.md +++ b/fod-export/README.md @@ -9,15 +9,18 @@ - + This action exports the latest vulnerability data from an FoD release to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. - + ### Prerequisites + + + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js @@ -25,75 +28,71 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -### Action environment variable inputs - - - - -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. + -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. - - + +### Sample usage - +The sample workflow below demonstrates how to configure the action for exporting FoD SAST vulnerability data to the GitHub Security Code Scanning dashboard. -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. +```yaml + steps: + - name: Export FoD vulnerability data to GitHub + uses: fortify/github-action/fod-export@v1 + env: + FOD_URL: https://ams.fortify.com + FOD_TENANT: ${{secrets.FOD_TENANT}} + FOD_USER: ${{secrets.FOD_USER}} + FOD_PASSWORD: ${{secrets.FOD_PAT}} + # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s + # FOD_RELEASE: MyApp:MyRelease + # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml + # EXPORT_EXTRA_OPTS: --on-unsigned=ignore + # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip +``` - +### Action environment variable inputs +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. +| Environment variable | Description | +| :--- | :--- | +| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | +| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). | +| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | +| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | 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.9.0//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| +| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | +| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details. | +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. + -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. +### FoD fcli actions - + + - +As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. +For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v2.9.0/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. + - +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the FoD release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. -### Sample usage +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. -The sample workflow below demonstrates how to configure the action for exporting FoD SAST vulnerability data to the GitHub Security Code Scanning dashboard. + -```yaml - steps: - - name: Export FoD vulnerability data to GitHub - uses: fortify/github-action/fod-export@v1 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_RELEASE: MyApp:MyRelease - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - + diff --git a/fod-export/action.yml b/fod-export/action.yml index 53ab728..308821d 100644 --- a/fod-export/action.yml +++ b/fod-export/action.yml @@ -4,13 +4,13 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-fod-var-defaults@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-fod-var-defaults@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false fcli: action-default - - uses: fortify/github-action/internal/fod-login@main - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/fod-login@doc-updates + - uses: fortify/github-action/internal/run-script@doc-updates with: script: export.sh env: diff --git a/fod-sast-scan/README.md b/fod-sast-scan/README.md index c1176a7..7b271c9 100644 --- a/fod-sast-scan/README.md +++ b/fod-sast-scan/README.md @@ -9,7 +9,7 @@ - + This action performs a SAST scan on Fortify on Demand (FoD). If software composition analysis of open source has been purchased and configured on the applicable release, this action can be used to perform a combined SAST and SCA (open source) scan. @@ -22,10 +22,13 @@ The SAST and optional open source scan performed by this action consists of the * Optionally export scan results to the GitHub Code Scanning dashboard - + ### Prerequisites + + + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js @@ -33,187 +36,129 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -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 `PACKAGE_EXTRA_OPTS` environment variable. - -### Action environment variable inputs - - - - - - - - - - - -**`FOD_URL`** - REQUIRED -Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`FOD_CLIENT_ID` & `FOD_CLIENT_SECRET`** - REQUIRED* -Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). - -**`FOD_TENANT`, `FOD_USER` & `FOD_PASSWORD`** - REQUIRED* -Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. - - - - -**`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.9.0//manpage/fcli-fod-session-login.html) - - + + - -**`FOD_RELEASE`** - OPTIONAL -Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. - - - - - - - -**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL -If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or [SSC `setup-appversion`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_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 `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used. - -Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id. - - - - - - - -**`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 `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 ` 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. - - +### Sample usage +The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD. -**`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.9.0//manpage/fcli-fod-sast-scan-start.html) +```yaml + steps: + - name: Check out source code + uses: actions/checkout@v4 + - name: Run FoD SAST Scan + uses: fortify/github-action/fod-sast-scan@v1 + env: + FOD_URL: https://ams.fortify.com + FOD_TENANT: ${{secrets.FOD_TENANT}} + FOD_USER: ${{secrets.FOD_USER}} + FOD_PASSWORD: ${{secrets.FOD_PAT}} + # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s + # FOD_RELEASE: MyApp:MyRelease + # PACKAGE_EXTRA_OPTS: -oss -bt mvn + # DO_SETUP: true + # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml + # SETUP_EXTRA_OPTS: --on-unsigned=ignore + # DO_POLICY_CHECK: true + # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml + # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore + # DO_JOB_SUMMARY: true + # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml + # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore + # DO_PR_COMMENT: true + # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml + # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore + # DO_EXPORT: true + # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml + # EXPORT_EXTRA_OPTS: --on-unsigned=ignore + # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip +``` - +### Action environment variable inputs -**`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 job summaries. This behavior is documented in the applicable environment variable descriptions. +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - +| Environment variable | Description | +| :--- | :--- | +| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to FoD to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | +| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: FoD Client ID (API key) and Secret (API secret). | +| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: FoD tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | +| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | 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.9.0//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| +| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | +|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the FoD application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [FoD `setup-release`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy state from an existing release using the `--copy-from` option, or to allow an unsigned custom action to be used. If the FoD application may need to be created, you must configure at least the `--app-owner` option. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| +|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. 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. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| +|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.| +| DO_WAIT | 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 job summaries. This behavior is documented in the applicable environment variable descriptions. | +|DO_POLICY_CHECK
CHECK_POLICY_ACTION
CHECK_POLICY_EXTRA_OPTS|If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. Extra options for a 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 the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.| +|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
JOB_SUMMARY_EXTRA_OPTS|If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), a job summary listing scan status and issue counts will be generated using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. Extra options for the fcli action can be passed through the `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details. | +| DO_EXPORT
EXPORT_ACTION
EXPORT_EXTRA_OPTS | If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) section below for more details.

Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. | +|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
PR_COMMENT_EXTRA_OPTS|If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. Extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to allow an unsigned custom action to be used. Please see the [FoD Fcli Actions](#fod-fcli-actions) and [FoD Pull Request Comments](#fod-pull-request-comments) sections below for more details.| +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | + - +### FoD fcli actions -**`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL -If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_check_policy) or [SSC `check-policy`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_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. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. + - + +As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - +For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v2.9.0/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. -**`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL -If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_release_summary) or [SSC `appversion-summary`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_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 `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. + - +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the FoD release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. - + -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. - + +### FoD Pull Request Comments + - +This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. -**`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL *(PREVIEW)* -If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_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. +**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. -Note that pull request comments will only be generated under the following conditions: +Pull request comments will only be generated under the following conditions: * Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request). * All other standard GitHub environment variables like `GITHUB_TOKEN`, `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 your workflow as follows: +PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application release; it won't detect any new/removed issues from older scans. For best results, you should configure your workflow as follows: - For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches. -- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created. -- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release. +- Don't set `FOD_RELEASE`, to use the default value that corresponds to repository and branch name. +- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. +- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version/release named `/:`. -- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release. -- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above. -- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option. - -If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - - - - - - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. +- Create a new application release named `/:`. +- Copy state from the application release identified by the `--copy-from` option to this new application release. +- Run a new scan of the branch associated with the current PR, and upload results to the application release created above. +- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the application release identified by the `--copy-from` option. -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. +If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR. - + -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run FoD SAST Scan - uses: fortify/github-action/fod-sast-scan@v1 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # PACKAGE_EXTRA_OPTS: -oss - # DO_WAIT: true - # DO_EXPORT: true - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - - + diff --git a/fod-sast-scan/action.yml b/fod-sast-scan/action.yml index c423edf..13ebf03 100644 --- a/fod-sast-scan/action.yml +++ b/fod-sast-scan/action.yml @@ -4,21 +4,21 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-fod-var-defaults@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-fod-var-defaults@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false fcli: action-default - - uses: fortify/github-action/internal/fod-login@main - - uses: fortify/github-action/package@main - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/fod-login@doc-updates + - uses: fortify/github-action/package@doc-updates + - uses: fortify/github-action/internal/run-script@doc-updates with: script: fod-scan.sh env: DO_SAST_SCAN: true # Not used for now GITHUB_TOKEN: ${{ github.token }} - if: env.DO_EXPORT == 'true' - uses: fortify/github-action/fod-export@main + uses: fortify/github-action/fod-export@doc-updates branding: icon: 'shield' diff --git a/internal/fod-login/action.yml b/internal/fod-login/action.yml index e8071d9..2dc97fa 100644 --- a/internal/fod-login/action.yml +++ b/internal/fod-login/action.yml @@ -7,7 +7,7 @@ runs: # If not run before: check preconditions, run fcli login command, and run # post-job fcli logout command. # Note that the calling action/workflow is responsible for installing fcli - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/run-script@doc-updates if: ${{ !env._FOD_LOGGED_IN }} with: script: fod-login.sh diff --git a/internal/run-script/action.yml b/internal/run-script/action.yml index f72d8f1..19669e1 100644 --- a/internal/run-script/action.yml +++ b/internal/run-script/action.yml @@ -30,7 +30,7 @@ runs: - run: echo "TEMP_DIR=$(pwd)" >> $GITHUB_ENV shell: bash working-directory: ${{ runner.temp }} - - uses: fortify/github-action/internal/run-script/js@main + - uses: fortify/github-action/internal/run-script/js@doc-updates with: dir: ${{ env._RUN_SCRIPTS_DIR }} script: ${{ inputs.script }} diff --git a/internal/sc-sast-login/action.yml b/internal/sc-sast-login/action.yml index e62ee76..fe106f4 100644 --- a/internal/sc-sast-login/action.yml +++ b/internal/sc-sast-login/action.yml @@ -11,7 +11,7 @@ runs: # If not run before: check preconditions, run fcli login command, and run # post-job fcli logout command. # Note that the calling action/workflow is responsible for installing fcli - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/run-script@doc-updates if: ${{ !env._SC_SAST_LOGGED_IN }} with: script: sc-sast-login.sh diff --git a/internal/ssc-login/action.yml b/internal/ssc-login/action.yml index 7bbe601..18e33a7 100644 --- a/internal/ssc-login/action.yml +++ b/internal/ssc-login/action.yml @@ -7,7 +7,7 @@ runs: # If not run before: check preconditions, run fcli login command, and run # post-job fcli logout command. # Note that the calling action/workflow is responsible for installing fcli - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/run-script@doc-updates if: ${{ !env._SSC_LOGGED_IN }} with: script: ssc-login.sh diff --git a/package/README.md b/package/README.md index 6e852a6..75d64e0 100644 --- a/package/README.md +++ b/package/README.md @@ -9,15 +9,18 @@ - + 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`. - + ### Prerequisites + + + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js @@ -25,31 +28,10 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -### Action environment variable inputs - - - - -**`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 ` 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. + - - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - + ### Sample usage @@ -63,11 +45,20 @@ The sample workflow below demonstrates how to configure the action for running a - name: Package source code uses: fortify/github-action/package@v1 env: - # PACKAGE_EXTRA_OPTS: -bf custom-pom.xml + # PACKAGE_EXTRA_OPTS: -oss -bt mvn # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` - +### Action environment variable inputs + +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. + +| Environment variable | Description | +| :--- | :--- | +|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. 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. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | + + diff --git a/package/action.yml b/package/action.yml index 1188651..3eccb5a 100644 --- a/package/action.yml +++ b/package/action.yml @@ -4,13 +4,13 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-fod-var-defaults@main - - uses: fortify/github-action/internal/setup-java-for-sc-client@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-fod-var-defaults@doc-updates + - uses: fortify/github-action/internal/setup-java-for-sc-client@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false sc-client: action-default - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/run-script@doc-updates with: script: package.sh diff --git a/sc-sast-scan/README.md b/sc-sast-scan/README.md index 8e59914..cfca757 100644 --- a/sc-sast-scan/README.md +++ b/sc-sast-scan/README.md @@ -9,7 +9,7 @@ - + This action performs a SAST scan on ScanCentral SAST, consisting of the following steps: @@ -21,7 +21,7 @@ This action performs a SAST scan on ScanCentral SAST, consisting of the followin * Optionally export scan results to the GitHub Code Scanning dashboard - + ### Prerequisites @@ -32,7 +32,7 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - + Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: @@ -231,7 +231,7 @@ The sample workflow below demonstrates how to configure the action for running a # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` - + diff --git a/sc-sast-scan/action.yml b/sc-sast-scan/action.yml index 8445fb6..cb01601 100644 --- a/sc-sast-scan/action.yml +++ b/sc-sast-scan/action.yml @@ -4,23 +4,23 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-ssc-var-defaults@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-ssc-var-defaults@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false fcli: action-default debricked-cli: ${{ env.DO_DEBRICKED_SCAN=='true' && 'action-default' || 'skip' }} - - uses: fortify/github-action/internal/ssc-login@main - - uses: fortify/github-action/internal/sc-sast-login@main - - uses: fortify/github-action/package@main - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/ssc-login@doc-updates + - uses: fortify/github-action/internal/sc-sast-login@doc-updates + - uses: fortify/github-action/package@doc-updates + - uses: fortify/github-action/internal/run-script@doc-updates with: script: sc-sast-and-debricked-scan.sh env: DO_SC_SAST_SCAN: true GITHUB_TOKEN: ${{ github.token }} - if: env.DO_EXPORT == 'true' - uses: fortify/github-action/ssc-export@main + uses: fortify/github-action/ssc-export@doc-updates branding: icon: 'shield' diff --git a/setup/README.md b/setup/README.md index 8228d61..9941c0e 100644 --- a/setup/README.md +++ b/setup/README.md @@ -9,7 +9,7 @@ - + This action allows for setting up the Fortify tools listed below. Which tools and which versions to install, and whether to add the tool bin-directories to the system path, is controlled through action inputs as listed in the next section. @@ -21,10 +21,13 @@ This action allows for setting up the Fortify tools listed below. Which tools an * [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) - + ### Prerequisites + + + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js @@ -32,63 +35,11 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -### Action inputs - -**`export-path`** - OPTIONAL -Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` - -**`tool-definitions`** - OPTIONAL -Allows for overriding the location of the Fortify tool definitions bundle. This can be specified either as an action input or through the `TOOL_DEFINITIONS` environment variable; see the 'Action environment variable inputs' section below for details. - -**`fcli`** - OPTIONAL -The fcli version to install. Allowed values: `skip` (default value, do not install fcli), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.0` and `2.0.0` are semantically the same. - -**`sc-client`** - OPTIONAL -The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. - -**`fod-uploader`** - OPTIONAL -The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. + -**`vuln-exporter`** - OPTIONAL -The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.4` and `2.0.4` are semantically the same. -**`bugtracker-utility`** - OPTIONAL -The FortifyBugTrackerUtility version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v4` will install the latest known `4.x` version. Version may be specified either with or without the `v` prefix, for example `v4.12` and `4.12` are semantically the same. + -**`debricked-cli`** - OPTIONAL -The Debricked CLI version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v1` will install the latest known `1.x` version. Version may be specified either with or without the `v` prefix, for example `v1` and `1` are semantically the same. - -### Action environment variable inputs - - - - -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. - -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. - - - - -### Action outputs - -For each tool being installed, the action outputs several environment variables for use by later workflow steps. - -**`PATH`** -If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. - -**`_INSTALL_DIR`** -Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. - -**`_BIN_DIR`** -Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. - -**`_CMD`** -Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. ### Sample usage @@ -116,7 +67,41 @@ The sample workflow below demonstrates how to configure the action for installin run: ${FCLI_CMD} -V ``` - +### Action inputs + +This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. + +| Action input | Description | +| :--- | :--- | +| export‑path | Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` | +| tool‑definitions | Allows for overriding the location of the Fortify tool definitions bundle. This can be specified either as an action input or through the `TOOL_DEFINITIONS` environment variable; see the 'Action environment variable inputs' section below for details. | +| fcli | The fcli version to install. Allowed values: `skip` (default value, do not install fcli), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.0` and `2.0.0` are semantically the same. | +| sc‑client | The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. | +| fod‑uploader | The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. | +| vuln‑exporter | The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v2` will install the latest known `2.x.y` version. Version may be specified either with or without the `v` prefix, for example `v2.0.4` and `2.0.4` are semantically the same. | +| bugtracker‑utility | The FortifyBugTrackerUtility version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v4` will install the latest known `4.x` version. Version may be specified either with or without the `v` prefix, for example `v4.12` and `4.12` are semantically the same. | +| debricked‑cli | The Debricked CLI version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v1` will install the latest known `1.x` version. Version may be specified either with or without the `v` prefix, for example `v1` and `1` are semantically the same. | + +### Action environment variable inputs + +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. + +| Environment variable | Description | +| :--- | :--- | +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | + +### Action outputs + +For each tool being installed, the action outputs several environment variables for use by later workflow steps. + +| Environment variable | Description | +| :--- | :--- | +| PATH | If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. | +| <TOOL_NAME>_INSTALL_DIR | Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. | +| <TOOL_NAME>_BIN_DIR | Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. | +| <TOOL_NAME>_CMD | Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. | + + diff --git a/ssc-debricked-scan/README.md b/ssc-debricked-scan/README.md index d1fa230..782082d 100644 --- a/ssc-debricked-scan/README.md +++ b/ssc-debricked-scan/README.md @@ -9,7 +9,7 @@ - + This action performs a Debricked Software Composition Analysis (SCA) scan, consisting of the following steps: @@ -21,7 +21,7 @@ This action performs a Debricked Software Composition Analysis (SCA) scan, consi Note that this action is explicitly meant for Debricked/SSC integration. If you wish to run a Debricked scan without publishing the results to SSC, please see the [Debricked GitHub Integration documentation](https://portal.debricked.com/integrations-48/integration-with-github-214#github-actions) - + ### Prerequisites @@ -32,7 +32,7 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - + Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: @@ -182,7 +182,7 @@ The sample workflow below demonstrates how to configure the action for running a # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` - + diff --git a/ssc-debricked-scan/action.yml b/ssc-debricked-scan/action.yml index 72ea583..c2fa199 100644 --- a/ssc-debricked-scan/action.yml +++ b/ssc-debricked-scan/action.yml @@ -4,14 +4,14 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-ssc-var-defaults@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-ssc-var-defaults@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false fcli: action-default debricked-cli: action-default - - uses: fortify/github-action/internal/ssc-login@main - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/ssc-login@doc-updates + - uses: fortify/github-action/internal/run-script@doc-updates with: script: sc-sast-and-debricked-scan.sh env: diff --git a/ssc-export/README.md b/ssc-export/README.md index b619392..7478d5c 100644 --- a/ssc-export/README.md +++ b/ssc-export/README.md @@ -9,15 +9,18 @@ - + This action exports the latest vulnerability data from an SSC application version to the GitHub Code Scanning dashboard. Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. - + ### Prerequisites + + + This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: * Node.js @@ -25,73 +28,69 @@ This action assumes the standard software packages as provided by GitHub-hosted * Bash shell If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - -### Action environment variable inputs - - - - -**`SSC_URL`** - REQUIRED -Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. - -**`SSC_TOKEN`** - REQUIRED* -Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`. + -**`SSC_USER` & `SSC_PASSWORD`** - REQUIRED* -Required when authenticating with SSC user credentials. - + +### Sample usage - +The sample workflow below demonstrates how to configure the action for exporting SSC SAST vulnerability data to the GitHub Security Code Scanning dashboard. -**`SSC_APPVERSION`** - OPTIONAL -Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is [`:`](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context), for example `myOrg/myRepo:myBranch`. +```yaml + steps: + - name: Export SSC vulnerability data to GitHub + uses: fortify/github-action/ssc-export@v1 + env: + SSC_URL: ${{vars.SSC_URL}} + SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s + # SSC_APPVERSION: MyApp:MyVersion + # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml + # EXPORT_EXTRA_OPTS: --on-unsigned=ignore + # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip +``` - +### Action environment variable inputs +This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. +| Environment variable | Description | +| :--- | :--- | +|**SSC_URL**|Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets.| +|**SSC_TOKEN**|Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`.| +|**SSC_USER
SSC_PASSWORD**|Required when authenticating with SSC user credentials.| +|SSC_LOGIN_EXTRA_OPTS
EXTRA_SSC_LOGIN_OPTS|Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli ssc session login` documentation](https://fortify.github.io/fcli/v2.9.0//manpage/fcli-ssc-session-login.html). Note that `EXTRA_SSC_LOGIN_OPTS` is deprecated; please use `SSC_LOGIN_EXTRA_OPTS`.| +|SSC_APPVERSION|Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`.| +| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. Extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to to allow an unsigned custom action to be used or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details. | +| TOOL_DEFINITIONS | Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used.

This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. | - -**`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL -If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/v2.9.0/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/v2.9.0/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. `EXPORT_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 `EXPORT_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. + -Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub. +### SSC fcli actions - + + - +As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. -**`TOOL_DEFINITIONS`** - OPTIONAL -Fortify tool definitions are used by this GitHub Action to determine available versions, download location and other details of various Fortify-related tools, as required for action execution. By default, the Fortify-provided tool definitions hosted at https://github.com/fortify/tool-definitions/releases/tag/v1 will be used. +For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v2.9.0/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. -This environment variable allows for overriding the default tool definitions, pointing to either a URL or local (workspace) file. For example, if GitHub workflows are not allowed to download tools from their public internet locations, customers may host the tool installation bundles on an internal server, together with a customized tool definitions bundle that lists the alternative download URLs. + - +When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--av` / `--appversion` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the SSC application version to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. -### Sample usage +Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. -The sample workflow below demonstrates how to configure the action for exporting SSC SAST vulnerability data to the GitHub Security Code Scanning dashboard. + -```yaml - steps: - - name: Export SSC vulnerability data to GitHub - uses: fortify/github-action/ssc-export@v1 - env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - # SSC_APPVERSION: MyApp:MyVersion - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - + diff --git a/ssc-export/action.yml b/ssc-export/action.yml index 36061e2..8e4f709 100644 --- a/ssc-export/action.yml +++ b/ssc-export/action.yml @@ -4,13 +4,13 @@ author: 'Fortify' runs: using: composite steps: - - uses: fortify/github-action/internal/set-ssc-var-defaults@main - - uses: fortify/github-action/setup@main + - uses: fortify/github-action/internal/set-ssc-var-defaults@doc-updates + - uses: fortify/github-action/setup@doc-updates with: export-path: false fcli: action-default - - uses: fortify/github-action/internal/ssc-login@main - - uses: fortify/github-action/internal/run-script@main + - uses: fortify/github-action/internal/ssc-login@doc-updates + - uses: fortify/github-action/internal/run-script@doc-updates with: script: export.sh env: