diff --git a/README.md b/README.md index 357ded6..90e49c0 100644 --- a/README.md +++ b/README.md @@ -9,56 +9,21 @@ - + -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 +## Prerequisites - -## 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. - - - + ### Prerequisites @@ -69,464 +34,12 @@ 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` - - - -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. +## Application Security Testing with Fortify on Demand -**`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 +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: @@ -536,1068 +49,58 @@ The sample workflows below demonstrate how to configure the action for running a uses: fortify/github-action@v1 with: sast-scan: true + debricked-sca-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 +{x{include:nocomments.env-fod-sast-scan-sample.md}} ``` -#### ScanCentral SAST with optional Debricked scan +In this example, the `with` clause specifies what scans to run: -```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 -``` +| 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. | + +The `env` clause specifies environment variables to configure those scans. The following environment variables are currently supported: + +{x{include:env-fod-sast-scan.md}} -#### Debricked-only scan and publish to SSC +{x{include:env-setup.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 Debricked Scan + - name: Run FoD SAST Scan uses: fortify/github-action@v1 with: - sast-scan: false + 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}} ``` -### 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 - - - +In this example, the `with` clause specifies what scans to run: -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. +| 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. | -* [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) +The `env` clause specifies environment variables to configure these scans. The following environment variables are currently supported: +{x{include:env-sc-sast-scan.md}} - - -### 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: - -* 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 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. - -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. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run ScanCentral SAST Scan - uses: fortify/github-action/sc-sast-scan@v1 - 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 -``` - - - - - - - -## 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` - - - - -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. -* 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). - - - - -**`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 usage - -The sample workflow below demonstrates how to configure the action for running a Debricked scan and publishing the results to Fortify SSC. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Debricked Scan - uses: fortify/github-action/ssc-debricked-scan@v1 - 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 -``` - - - - - - - -## 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 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. - - - - - - - -**`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. - -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-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..ec1d58a --- /dev/null +++ b/doc-resources/action/_root/readme.md @@ -0,0 +1,74 @@ +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) + +## Prerequisites + +{{include:action/prerequisites.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: +{x{include:nocomments.env-fod-sast-scan-sample.md}} +``` + +In this example, the `with` clause specifies what scans to run: + +{{include:action/generic/nocomments.input-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. | + +The `env` clause specifies environment variables to configure those scans. The following environment variables are currently supported: + +{x{include:env-fod-sast-scan.md}} + +{x{include:env-setup.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}} +``` + +In this example, the `with` clause specifies what scans to run: + +{{include:action/generic/nocomments.input-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. | + +The `env` clause specifies environment variables to configure these scans. The following environment variables are currently supported: + +{x{include:env-sc-sast-scan.md}} + +{x{include:env-setup.md}} + +## Building blocks for custom workflows + diff --git a/doc-resources/env-do-export.md b/doc-resources/action/fod-export/nocomments.env-do-export.md similarity index 100% rename from doc-resources/env-do-export.md rename to doc-resources/action/fod-export/nocomments.env-do-export.md diff --git a/doc-resources/action-fod-export.md b/doc-resources/action/fod-export/readme.md similarity index 58% rename from doc-resources/action-fod-export.md rename to doc-resources/action/fod-export/readme.md index 10e332d..90677ee 100644 --- a/doc-resources/action-fod-export.md +++ b/doc-resources/action/fod-export/readme.md @@ -1,16 +1,14 @@ 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}} +{{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/nocomments.env-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-do-export.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} ### Sample usage @@ -21,7 +19,7 @@ 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/setup/nocomments.snippet-tool-definitions.md}} ``` diff --git a/doc-resources/action-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/readme.md similarity index 97% rename from doc-resources/action-fod-sast-scan.md rename to doc-resources/action/fod-sast-scan/readme.md index e244a7b..8c7a9ac 100644 --- a/doc-resources/action-fod-sast-scan.md +++ b/doc-resources/action/fod-sast-scan/readme.md @@ -8,7 +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}} +{{include:action/prerequisites.md}} Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: 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..dca91a0 --- /dev/null +++ b/doc-resources/action/generic/fod/nocomments.env-fod-login.md @@ -0,0 +1,5 @@ +| **`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 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) | +| `EXTRA_FOD_LOGIN_OPTS` | 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..da29802 --- /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 [`:`](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/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-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-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/package/nocomments.env-package-extra-opts.md b/doc-resources/action/package/nocomments.env-package-extra-opts.md new file mode 100644 index 0000000..501de2a --- /dev/null +++ b/doc-resources/action/package/nocomments.env-package-extra-opts.md @@ -0,0 +1,2 @@ +|`PACKAGE_EXTRA_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. | +|`EXTRA_PACKAGE_OPTS`| 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 61% rename from doc-resources/action-package.md rename to doc-resources/action/package/readme.md index 50f1471..a2f3ec9 100644 --- a/doc-resources/action-package.md +++ b/doc-resources/action/package/readme.md @@ -1,12 +1,12 @@ 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}} +{{include:action/prerequisites.md}} ### Action environment variable inputs -{{include:env-package.md}} - -{{include:env-setup.md}} +{{include:action/generic/nocomments.env-table-header.md}} +{{include:action/package/nocomments.env-package-extra-opts.md}} +{{include:action/setup/nocomments.env-tool-definitions.md}} ### Sample usage @@ -19,6 +19,6 @@ 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}} +{{include:action/package/nocomments.snippet-package-extra-opts.md}} +{{include:action/setup/nocomments.snippet-tool-definitions.md}} ``` \ No newline at end of file diff --git a/doc-resources/action-prerequisites.md b/doc-resources/action/prerequisites.md similarity index 100% rename from doc-resources/action-prerequisites.md rename to doc-resources/action/prerequisites.md diff --git a/doc-resources/action-sc-sast-scan.md b/doc-resources/action/sc-sast-scan/readme.md similarity index 97% rename from doc-resources/action-sc-sast-scan.md rename to doc-resources/action/sc-sast-scan/readme.md index 9f5e133..bbeb605 100644 --- a/doc-resources/action-sc-sast-scan.md +++ b/doc-resources/action/sc-sast-scan/readme.md @@ -7,7 +7,7 @@ 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/prerequisites.md}} Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: diff --git a/doc-resources/env-setup.md b/doc-resources/action/setup/nocomments.env-tool-definitions.md similarity index 100% rename from doc-resources/env-setup.md rename to doc-resources/action/setup/nocomments.env-tool-definitions.md 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..718980c --- /dev/null +++ b/doc-resources/action/setup/readme.md @@ -0,0 +1,63 @@ +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 + +{{include:action/generic/nocomments.input-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. | + +### Action environment variable inputs + +{{include:action/generic/nocomments.env-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. | +| `_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-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..e86fa76 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/prerequisites.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.md b/doc-resources/action/ssc-export/readme.md similarity index 96% rename from doc-resources/action-ssc-export.md rename to doc-resources/action/ssc-export/readme.md index 166a444..ab81615 100644 --- a/doc-resources/action-ssc-export.md +++ b/doc-resources/action/ssc-export/readme.md @@ -1,6 +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}} +{{include:action/prerequisites.md}} ### Action environment variable inputs 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-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-do-job-summary.md b/doc-resources/env/fod/env-do-job-summary.md similarity index 100% rename from doc-resources/env-do-job-summary.md rename to doc-resources/env/fod/env-do-job-summary.md diff --git a/doc-resources/env-do-policy-check.md b/doc-resources/env/fod/env-do-policy-check.md similarity index 100% rename from doc-resources/env-do-policy-check.md rename to doc-resources/env/fod/env-do-policy-check.md diff --git a/doc-resources/env-do-pr-comment.md b/doc-resources/env/fod/env-do-pr-comment.md similarity index 100% rename from doc-resources/env-do-pr-comment.md rename to doc-resources/env/fod/env-do-pr-comment.md diff --git a/doc-resources/env-do-setup.md b/doc-resources/env/fod/env-do-setup.md similarity index 100% rename from doc-resources/env-do-setup.md rename to doc-resources/env/fod/env-do-setup.md diff --git a/doc-resources/env-do-wait.md b/doc-resources/env/fod/env-do-wait.md similarity index 100% rename from doc-resources/env-do-wait.md rename to doc-resources/env/fod/env-do-wait.md diff --git a/doc-resources/env-fod-sast-scan.md b/doc-resources/env/fod/env-fod-sast-scan.md similarity index 100% rename from doc-resources/env-fod-sast-scan.md rename to doc-resources/env/fod/env-fod-sast-scan.md diff --git a/doc-resources/env/sc-sast/env-do-wait.md b/doc-resources/env/sc-sast/env-do-wait.md new file mode 100644 index 0000000..13a4bcf --- /dev/null +++ b/doc-resources/env/sc-sast/env-do-wait.md @@ -0,0 +1,2 @@ +**`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. 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/ssc/env-do-export.md b/doc-resources/env/ssc/env-do-export.md new file mode 100644 index 0000000..90a1a3e --- /dev/null +++ b/doc-resources/env/ssc/env-do-export.md @@ -0,0 +1,4 @@ +**`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`]({{var:fcli-doc-base-url}}fod-actions.html#_github_sast_report) or [SSC `github-sast-action`]({{var:fcli-doc-base-url}}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. \ No newline at end of file diff --git a/doc-resources/env/ssc/env-do-job-summary.md b/doc-resources/env/ssc/env-do-job-summary.md new file mode 100644 index 0000000..ab14d00 --- /dev/null +++ b/doc-resources/env/ssc/env-do-job-summary.md @@ -0,0 +1,2 @@ +**`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`]({{var:fcli-doc-base-url}}fod-actions.html#_release_summary) or [SSC `appversion-summary`]({{var:fcli-doc-base-url}}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. \ No newline at end of file diff --git a/doc-resources/env/ssc/env-do-policy-check.md b/doc-resources/env/ssc/env-do-policy-check.md new file mode 100644 index 0000000..1db5e59 --- /dev/null +++ b/doc-resources/env/ssc/env-do-policy-check.md @@ -0,0 +1,2 @@ +**`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`]({{var:fcli-doc-base-url}}fod-actions.html#_check_policy) or [SSC `check-policy`]({{var:fcli-doc-base-url}}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. \ No newline at end of file diff --git a/doc-resources/env/ssc/env-do-pr-comment.md b/doc-resources/env/ssc/env-do-pr-comment.md new file mode 100644 index 0000000..f6f7640 --- /dev/null +++ b/doc-resources/env/ssc/env-do-pr-comment.md @@ -0,0 +1,22 @@ +**`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`]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`]({{var:fcli-doc-base-url}}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. diff --git a/doc-resources/env/ssc/env-do-setup.md b/doc-resources/env/ssc/env-do-setup.md new file mode 100644 index 0000000..30f2d68 --- /dev/null +++ b/doc-resources/env/ssc/env-do-setup.md @@ -0,0 +1,4 @@ +**`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`]({{var:fcli-doc-base-url}}fod-actions.html#_setup_release) or [SSC `setup-appversion`]({{var:fcli-doc-base-url}}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. \ No newline at end of file diff --git a/doc-resources/env-ssc-appversion.md b/doc-resources/env/ssc/env-ssc-appversion.md similarity index 100% rename from doc-resources/env-ssc-appversion.md rename to doc-resources/env/ssc/env-ssc-appversion.md diff --git a/doc-resources/env-ssc-connection.md b/doc-resources/env/ssc/env-ssc-connection.md similarity index 100% rename from doc-resources/env-ssc-connection.md rename to doc-resources/env/ssc/env-ssc-connection.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/env-ssc-login.md b/doc-resources/env/ssc/env-ssc-login.md similarity index 100% rename from doc-resources/env-ssc-login.md rename to doc-resources/env/ssc/env-ssc-login.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/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/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/fod-sast-scan/README.template.md b/doc-resources/todo/templates/fod-sast-scan/README.template.md similarity index 87% rename from doc-resources/templates/fod-sast-scan/README.template.md rename to doc-resources/todo/templates/fod-sast-scan/README.template.md index 3bdb4bb..b6c1d2f 100644 --- a/doc-resources/templates/fod-sast-scan/README.template.md +++ b/doc-resources/todo/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.md}} {{include:h2.support.md}} 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/doc-resources/templates/ssc-export/README.template.md b/doc-resources/todo/templates/ssc-export/README.template.md similarity index 88% rename from doc-resources/templates/ssc-export/README.template.md rename to doc-resources/todo/templates/ssc-export/README.template.md index 8e21021..e49c975 100644 --- a/doc-resources/templates/ssc-export/README.template.md +++ b/doc-resources/todo/templates/ssc-export/README.template.md @@ -2,7 +2,7 @@ {{include:p.marketing-intro.md}} -{{include:action-ssc-export.md}} +{{include:action/ssc-export.md}} {{include:h2.support.md}} diff --git a/fod-export/README.md b/fod-export/README.md index 331ad45..9169b7a 100644 --- a/fod-export/README.md +++ b/fod-export/README.md @@ -9,12 +9,12 @@ - + 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 @@ -25,57 +25,28 @@ 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. - - - - - - - -**`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. - - - - - - - +| 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 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) | +| `EXTRA_FOD_LOGIN_OPTS` | 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 [`:`](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. @@ -89,11 +60,12 @@ The sample workflow below demonstrates how to configure the action for exporting 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 # 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..bb4e578 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,7 +22,7 @@ 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 @@ -33,7 +33,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: @@ -213,7 +213,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/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..a88d426 100644 --- a/package/README.md +++ b/package/README.md @@ -9,12 +9,12 @@ - + 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 @@ -25,33 +25,20 @@ 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. - - - - - - - +| Environment variable | Description | +| :--- | :--- | +|`PACKAGE_EXTRA_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. | +|`EXTRA_PACKAGE_OPTS`| Deprecated; please use `PACKAGE_EXTRA_OPTS` | **`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. @@ -63,11 +50,11 @@ 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 ``` - + 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..ece7321 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,7 +21,7 @@ This action allows for setting up the Fortify tools listed below. Which tools an * [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) - + ### Prerequisites @@ -32,63 +32,41 @@ 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 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 - - - +| Environment variable | Description | +| :--- | :--- | **`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`. +| 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. | +| `_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 +94,7 @@ The sample workflow below demonstrates how to configure the action for installin run: ${FCLI_CMD} -V ``` - + 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..d602e80 100644 --- a/ssc-export/README.md +++ b/ssc-export/README.md @@ -9,12 +9,12 @@ - + 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 @@ -25,7 +25,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` - + ### Action environment variable inputs @@ -91,7 +91,7 @@ The sample workflow below demonstrates how to configure the action for exporting # 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: