From c1564bc6d88917299f8905d650582d5c7959f800 Mon Sep 17 00:00:00 2001 From: Ruud Senden <8635138+rsenden@users.noreply.github.com> Date: Tue, 4 Jun 2024 07:54:33 +0200 Subject: [PATCH] feat: Add ability to run and import Debricked scans into SSC (closes #41) --- README.md | 281 ++++++++++++++++-- action.yml | 12 +- doc-resources/action-sc-sast-scan.md | 3 +- doc-resources/action-ssc-debricked-scan.md | 35 +++ doc-resources/env-sc-sast-login.md | 2 - doc-resources/env-sc-sast-scan.md | 9 + doc-resources/env-ssc-debricked-scan.md | 13 + doc-resources/env-ssc-login.md | 2 - doc-resources/env-wait-export.md | 2 +- .../nocomments.env-sc-sast-login-sample.md | 1 - .../nocomments.env-sc-sast-scan-sample.md | 4 + ...ocomments.env-ssc-debricked-scan-sample.md | 5 + .../nocomments.env-ssc-login-sample.md | 1 + doc-resources/repo-readme.md | 49 ++- .../ssc-debricked-scan/README.template.md | 11 + fod-sast-scan/README.md | 2 +- internal/fod-login/action.yml | 5 +- internal/run-script/README.md | 34 +++ internal/run-script/action.yml | 31 +- internal/run-script/js/action.yml | 19 ++ internal/run-script/js/main.js | 3 + .../run-script/{ => js}/package-lock.json | 0 internal/run-script/js/post.js | 3 + internal/run-script/js/util.js | 12 + internal/run-script/main.js | 22 -- .../scripts/common.sh} | 11 +- .../scripts}/fod-login.sh | 14 +- internal/run-script/scripts/fod-logout.sh | 8 + .../scripts/sc-sast-and-debricked-scan.sh | 33 ++ .../scripts}/sc-sast-login.sh | 14 +- internal/run-script/scripts/sc-sast-logout.sh | 8 + .../scripts}/ssc-login.sh | 14 +- .../scripts}/ssc-logout.sh | 14 +- internal/sc-sast-login/action.yml | 5 +- internal/sc-sast-login/sc-sast-logout.sh | 16 - internal/ssc-login/action.yml | 5 +- sc-sast-scan/README.md | 30 +- sc-sast-scan/action.yml | 12 +- ssc-debricked-scan/README.md | 143 +++++++++ ssc-debricked-scan/action.yml | 23 ++ 40 files changed, 752 insertions(+), 159 deletions(-) create mode 100644 doc-resources/action-ssc-debricked-scan.md create mode 100644 doc-resources/env-ssc-debricked-scan.md create mode 100644 doc-resources/nocomments.env-ssc-debricked-scan-sample.md create mode 100644 doc-resources/nocomments.env-ssc-login-sample.md create mode 100644 doc-resources/templates/ssc-debricked-scan/README.template.md create mode 100644 internal/run-script/README.md create mode 100644 internal/run-script/js/action.yml create mode 100644 internal/run-script/js/main.js rename internal/run-script/{ => js}/package-lock.json (100%) create mode 100644 internal/run-script/js/post.js create mode 100644 internal/run-script/js/util.js delete mode 100644 internal/run-script/main.js rename internal/{fod-login/fod-logout.sh => run-script/scripts/common.sh} (52%) mode change 100755 => 100644 rename internal/{fod-login => run-script/scripts}/fod-login.sh (64%) create mode 100755 internal/run-script/scripts/fod-logout.sh create mode 100755 internal/run-script/scripts/sc-sast-and-debricked-scan.sh rename internal/{sc-sast-login => run-script/scripts}/sc-sast-login.sh (50%) create mode 100755 internal/run-script/scripts/sc-sast-logout.sh rename internal/{ssc-login => run-script/scripts}/ssc-login.sh (58%) rename internal/{ssc-login => run-script/scripts}/ssc-logout.sh (58%) delete mode 100755 internal/sc-sast-login/sc-sast-logout.sh create mode 100644 ssc-debricked-scan/README.md create mode 100644 ssc-debricked-scan/action.yml diff --git a/README.md b/README.md index 96075d0..3d6cb9c 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The [Fortify github-action repository](https://github.com/fortify/github-action) **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 actions. + 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) @@ -26,12 +26,14 @@ The [Fortify github-action repository](https://github.com/fortify/github-action) * [`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/2310/SC_SAST_Help_23.1.0/index.htm#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline -**Fortify Sofware Security Center (SSC) / ScanCentral SAST** +**Fortify Sofware Security Center (SSC) / ScanCentral SAST / Debricked** * [`fortify/github-action`](#fortify-github-action) - For now, this action provides the same functionality as the `sc-sast-scan` action listed below. Future versions may add support for running other types of scans or performing other SSC / ScanCentral actions. + 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) - Package source code, submit SAST scan request to ScanCentral SAST, optionally wait for completion and export results back to the GitHub Security dashboard. + 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) @@ -65,7 +67,10 @@ This action assumes the standard software packages as provided by GitHub-hosted **`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 now, this means that the action will complete without doing any work. Future versions of this action may provide additional inputs, for example allowing you to run a dynamic application security testing (DAST) scan instead of a SAST scan. +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 @@ -133,7 +138,7 @@ Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](http By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. @@ -152,16 +157,12 @@ This environment variable allows for overriding the default tool definitions, po -#### ScanCentral SAST +#### ScanCentral SAST with optional Debricked scan - - - - **`SSC_URL`** - REQUIRED @@ -176,6 +177,18 @@ Required when authenticating with SSC user credentials. + + + +**`EXTRA_SSC_LOGIN_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.3.0//manpage/fcli-ssc-session-login.html). + + + + + + + **`SC_SAST_TOKEN`** - REQUIRED Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. @@ -185,6 +198,12 @@ Extra ScanCentral SAST login options, for example for disabling SSL checks or ch +**`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. + @@ -218,7 +237,7 @@ Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentatio By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. @@ -227,6 +246,66 @@ If set to `true`, this action will export scan results to the GitHub Security Co + + +**`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/ + +**`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`** - 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.3.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_WAIT`** - OPTIONAL +By default, this action will complete immediately after Debricked scan results have been uploaded to SSC. To have the workflow wait until the Debricked results have been processed by SSC (potentially failing if the results cannot be successfully processed), set the `DO_WAIT` environment variable to `true`. + +For consistency with other actions, `DO_WAIT` is implied if `DO_EXPORT` is set to `true`, but since GitHub doesn't support importing Software Composition Analysis results, Debricked results will not be published to GitHub even if `DO_EXPORT` is set to `true`. + + + + + **`TOOL_DEFINITIONS`** - OPTIONAL @@ -264,7 +343,7 @@ The sample workflows below demonstrate how to configure the action for running a # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` -#### ScanCentral SAST +#### ScanCentral SAST with optional Debricked scan ```yaml steps: @@ -274,19 +353,44 @@ 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: SSC_URL: ${{secrets.SSC_URL}} SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}} # EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s # SSC_APPVERSION: MyApp:MyVersion # EXTRA_PACKAGE_OPTS: -bf custom-pom.xml SC_SAST_SENSOR_VERSION: 23.2 + # DO_DEBRICKED_SCAN: true # Or debricked-sca-scan input on top-level action + # DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} # DO_WAIT: true # DO_EXPORT: true # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip ``` +#### Debricked-only scan and publish to SSC + +```yaml + steps: + - name: Check out source code + uses: actions/checkout@v4 + - name: Run Debricked Scan + uses: fortify/github-action@v1 + with: + sast-scan: false + debricked-sca-scan: true + env: + SSC_URL: ${{secrets.SSC_URL}} + SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s + # SSC_APPVERSION: MyApp:MyVersion + DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} + # DO_WAIT: true + # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip +``` + ### More information Depending on input, this action delegates to the appropriate sub-action(s). Please refer to the documentation of these actions for a more detailed description of action behavior & requirements: @@ -576,7 +680,7 @@ Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](http By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. @@ -716,7 +820,8 @@ This action performs a SAST scan on ScanCentral SAST, consisting of the followin * 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 wait for the scan to complete +* 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 Before running this action, please ensure that the appropriate application version has been created on SSC. Future versions of this action may add support for automating application version creation. @@ -742,10 +847,6 @@ This action assumes the standard software packages as provided by GitHub-hosted - - - - **`SSC_URL`** - REQUIRED @@ -760,6 +861,18 @@ Required when authenticating with SSC user credentials. + + + +**`EXTRA_SSC_LOGIN_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.3.0//manpage/fcli-ssc-session-login.html). + + + + + + + **`SC_SAST_TOKEN`** - REQUIRED Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. @@ -769,6 +882,12 @@ Extra ScanCentral SAST login options, for example for disabling SSL checks or ch +**`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. + @@ -802,7 +921,7 @@ Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentatio By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. @@ -834,11 +953,14 @@ The sample workflow below demonstrates how to configure the action for running a env: SSC_URL: ${{secrets.SSC_URL}} SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}} # EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s # SSC_APPVERSION: MyApp:MyVersion # EXTRA_PACKAGE_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 @@ -848,6 +970,125 @@ The sample workflow below demonstrates how to configure the action for running a + + +## 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 + +Before running this action, please ensure that the appropriate application version has been created on SSC. Future versions of this action may add support for automating application version creation. + +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 general action prerequisites listed above, this specific action also 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. + +### Action environment variable inputs + + + + + + + +**`SSC_URL`** - REQUIRED +Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/ + +**`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`** - 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.3.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_WAIT`** - OPTIONAL +By default, this action will complete immediately after Debricked scan results have been uploaded to SSC. To have the workflow wait until the Debricked results have been processed by SSC (potentially failing if the results cannot be successfully processed), set the `DO_WAIT` environment variable to `true`. + +For consistency with other actions, `DO_WAIT` is implied if `DO_EXPORT` is set to `true`, but since GitHub doesn't support importing Software Composition Analysis results, Debricked results will not be published to GitHub even if `DO_EXPORT` is set to `true`. + + + + + + + +**`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: ${{secrets.SSC_URL}} + SSC_TOKEN: ${{secrets.SSC_TOKEN}} + # EXTRA_SSC_LOGIN_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 diff --git a/action.yml b/action.yml index 038a169..6d5e5bf 100644 --- a/action.yml +++ b/action.yml @@ -6,13 +6,21 @@ inputs: description: 'Run a SAST scan, takes either true or false (default)' default: 'false' required: false + debricked-sca-scan: + description: 'Run a Debricked Software Composition Analysis, takes either true or false (default)' + default: 'false' + required: false runs: using: composite steps: - uses: fortify/github-action/fod-sast-scan@feat-1.3.0 - if: inputs['sast-scan']=='true' && env.FOD_URL + if: inputs['sast-scan']=='true' && env.FOD_URL - uses: fortify/github-action/sc-sast-scan@feat-1.3.0 - if: inputs['sast-scan']=='true' && env.SSC_URL + if: inputs['sast-scan']=='true' && env.SSC_URL + env: + DO_DEBRICKED_SCAN: inputs['debricked-sca-scan'] + - uses: fortify/github-action/ssc-debricked-scan@feat-1.3.0 + if: inputs['sast-scan']=='false' && inputs['debricked-sca-scan']=='true' && env.SSC_URL branding: icon: 'shield' diff --git a/doc-resources/action-sc-sast-scan.md b/doc-resources/action-sc-sast-scan.md index cfe3f4d..3ccf374 100644 --- a/doc-resources/action-sc-sast-scan.md +++ b/doc-resources/action-sc-sast-scan.md @@ -3,7 +3,8 @@ This action performs a SAST scan on ScanCentral SAST, consisting of the followin * 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 wait for the scan to complete +* 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 Before running this action, please ensure that the appropriate application version has been created on SSC. Future versions of this action may add support for automating application version creation. diff --git a/doc-resources/action-ssc-debricked-scan.md b/doc-resources/action-ssc-debricked-scan.md new file mode 100644 index 0000000..f77a055 --- /dev/null +++ b/doc-resources/action-ssc-debricked-scan.md @@ -0,0 +1,35 @@ +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 + +Before running this action, please ensure that the appropriate application version has been created on SSC. Future versions of this action may add support for automating application version creation. + +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}} + +Apart from the general action prerequisites listed above, this specific action also 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. + +### Action environment variable inputs + +{{include:env-ssc-debricked-scan.md}} + +{{include:env-setup.md}} + +### 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@{{var:action-major-version}} + env: +{{include:nocomments.env-ssc-debricked-scan-sample.md}} +{{include:nocomments.env-setup-sample.md}} +``` \ No newline at end of file diff --git a/doc-resources/env-sc-sast-login.md b/doc-resources/env-sc-sast-login.md index 527caff..3f93b91 100644 --- a/doc-resources/env-sc-sast-login.md +++ b/doc-resources/env-sc-sast-login.md @@ -1,5 +1,3 @@ -{{include:env-ssc-connection.md}} - **`SC_SAST_TOKEN`** - REQUIRED Required: ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. diff --git a/doc-resources/env-sc-sast-scan.md b/doc-resources/env-sc-sast-scan.md index 693169d..94ba914 100644 --- a/doc-resources/env-sc-sast-scan.md +++ b/doc-resources/env-sc-sast-scan.md @@ -1,6 +1,15 @@ +{{include:env-ssc-connection.md}} + +{{include:env-ssc-login.md}} {{include:env-sc-sast-login.md}} +**`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. + {{include:env-ssc-appversion.md}} {{include:env-package.md}} diff --git a/doc-resources/env-ssc-debricked-scan.md b/doc-resources/env-ssc-debricked-scan.md new file mode 100644 index 0000000..10a64c0 --- /dev/null +++ b/doc-resources/env-ssc-debricked-scan.md @@ -0,0 +1,13 @@ +{{include:env-ssc-connection.md}} + +{{include:env-ssc-login.md}} + +**`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. + +{{include:env-ssc-appversion.md}} + +**`DO_WAIT`** - OPTIONAL +By default, this action will complete immediately after Debricked scan results have been uploaded to SSC. To have the workflow wait until the Debricked results have been processed by SSC (potentially failing if the results cannot be successfully processed), set the `DO_WAIT` environment variable to `true`. + +For consistency with other actions, `DO_WAIT` is implied if `DO_EXPORT` is set to `true`, but since GitHub doesn't support importing Software Composition Analysis results, Debricked results will not be published to GitHub even if `DO_EXPORT` is set to `true`. diff --git a/doc-resources/env-ssc-login.md b/doc-resources/env-ssc-login.md index f93dba5..89e4eea 100644 --- a/doc-resources/env-ssc-login.md +++ b/doc-resources/env-ssc-login.md @@ -1,4 +1,2 @@ -{{include:env-ssc-connection.md}} - **`EXTRA_SSC_LOGIN_OPTS`** - OPTIONAL Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli ssc session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-ssc-session-login.html). \ No newline at end of file diff --git a/doc-resources/env-wait-export.md b/doc-resources/env-wait-export.md index 0fd02a5..9d8e875 100644 --- a/doc-resources/env-wait-export.md +++ b/doc-resources/env-wait-export.md @@ -2,4 +2,4 @@ By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. diff --git a/doc-resources/nocomments.env-sc-sast-login-sample.md b/doc-resources/nocomments.env-sc-sast-login-sample.md index 032705e..6583ba4 100644 --- a/doc-resources/nocomments.env-sc-sast-login-sample.md +++ b/doc-resources/nocomments.env-sc-sast-login-sample.md @@ -1,3 +1,2 @@ -{{include:nocomments.env-ssc-connection-sample.md}} SC_SAST_TOKEN: ${{secrets.CLIENT_AUTH_TOKEN}} # EXTRA_SC_SAST_LOGIN_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/nocomments.env-sc-sast-scan-sample.md b/doc-resources/nocomments.env-sc-sast-scan-sample.md index 620a559..5ddb07d 100644 --- a/doc-resources/nocomments.env-sc-sast-scan-sample.md +++ b/doc-resources/nocomments.env-sc-sast-scan-sample.md @@ -1,6 +1,10 @@ +{{include:nocomments.env-ssc-connection-sample.md}} +{{include:nocomments.env-ssc-login-sample.md}} {{include:nocomments.env-sc-sast-login-sample.md}} {{include:nocomments.env-ssc-appversion-sample.md}} {{include:nocomments.env-package-sample.md}} 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 \ No newline at end of file diff --git a/doc-resources/nocomments.env-ssc-debricked-scan-sample.md b/doc-resources/nocomments.env-ssc-debricked-scan-sample.md new file mode 100644 index 0000000..dda6a27 --- /dev/null +++ b/doc-resources/nocomments.env-ssc-debricked-scan-sample.md @@ -0,0 +1,5 @@ +{{include:nocomments.env-ssc-connection-sample.md}} +{{include:nocomments.env-ssc-login-sample.md}} +{{include:nocomments.env-ssc-appversion-sample.md}} + DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} + # DO_WAIT: true \ No newline at end of file diff --git a/doc-resources/nocomments.env-ssc-login-sample.md b/doc-resources/nocomments.env-ssc-login-sample.md new file mode 100644 index 0000000..9cdcc3b --- /dev/null +++ b/doc-resources/nocomments.env-ssc-login-sample.md @@ -0,0 +1 @@ + # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/repo-readme.md b/doc-resources/repo-readme.md index 6d42ae9..3ff27ba 100644 --- a/doc-resources/repo-readme.md +++ b/doc-resources/repo-readme.md @@ -3,7 +3,7 @@ The [Fortify github-action repository]({{var:repo-url}}) hosts various Fortify-r **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 actions. + 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) @@ -13,12 +13,14 @@ The [Fortify github-action repository]({{var:repo-url}}) hosts various Fortify-r * [`fortify/github-action/setup`](#fortify-github-action-setup) Install various Fortify tools like [fcli](https://github.com/fortify/fcli), [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm), [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) and [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) for use in your pipeline -**Fortify Sofware Security Center (SSC) / ScanCentral SAST** +**Fortify Sofware Security Center (SSC) / ScanCentral SAST / Debricked** * [`fortify/github-action`](#fortify-github-action) - For now, this action provides the same functionality as the `sc-sast-scan` action listed below. Future versions may add support for running other types of scans or performing other SSC / ScanCentral actions. + 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) - Package source code, submit SAST scan request to ScanCentral SAST, optionally wait for completion and export results back to the GitHub Security dashboard. + 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) @@ -39,7 +41,10 @@ The primary `fortify/github-action` action currently allows for running SAST sca **`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 now, this means that the action will complete without doing any work. Future versions of this action may provide additional inputs, for example allowing you to run a dynamic application security testing (DAST) scan instead of a SAST scan. +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 @@ -49,12 +54,18 @@ If not specified or when set to false, no SAST scan will be performed. For now, {{include:env-setup.md}} -#### ScanCentral SAST +#### 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. @@ -74,7 +85,7 @@ The sample workflows below demonstrate how to configure the action for running a {{include:nocomments.env-setup-sample.md}} ``` -#### ScanCentral SAST +#### ScanCentral SAST with optional Debricked scan ```yaml steps: @@ -84,11 +95,28 @@ The sample workflows below demonstrate how to configure the action for running a 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: @@ -132,6 +160,13 @@ Depending on input, this action delegates to the appropriate sub-action(s). Plea {{include:action-sc-sast-scan.md}} + + +## fortify/github-action/ssc-debricked-scan + +{{include:action-ssc-debricked-scan.md}} + + ## fortify/github-action/ssc-export diff --git a/doc-resources/templates/ssc-debricked-scan/README.template.md b/doc-resources/templates/ssc-debricked-scan/README.template.md new file mode 100644 index 0000000..4583920 --- /dev/null +++ b/doc-resources/templates/ssc-debricked-scan/README.template.md @@ -0,0 +1,11 @@ +# fortify/github-action/ssc-debricked-scan@{{var:action-major-version}} + +{{include:p.marketing-intro.md}} + +{{include:action-ssc-debricked-scan.md}} + +{{include:h2.support.md}} + +--- + +*[This document was auto-generated; do not edit by hand](https://github.com/fortify/shared-doc-resources/blob/main/USAGE.md)* \ No newline at end of file diff --git a/fod-sast-scan/README.md b/fod-sast-scan/README.md index 7e1c690..7f0080f 100644 --- a/fod-sast-scan/README.md +++ b/fod-sast-scan/README.md @@ -102,7 +102,7 @@ Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](http By default, this action will not wait until the scan has been completed. To have the workflow wait until the scan has been completed, set the `DO_WAIT` environment variable to `true`. Note that `DO_WAIT` is implied if `DO_EXPORT` is set to `true`; see below. **`DO_EXPORT`** - OPTIONAL -If set to `true`, this action will export scan results to the GitHub Security 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. +If set to `true`, this action will export scan results to the GitHub Security 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. Note that GitHub only supports importing SAST results; other results will not exported to GitHub. diff --git a/internal/fod-login/action.yml b/internal/fod-login/action.yml index 96282f3..fe6a9e6 100644 --- a/internal/fod-login/action.yml +++ b/internal/fod-login/action.yml @@ -10,9 +10,8 @@ runs: - uses: fortify/github-action/internal/run-script@feat-1.3.0 if: ${{ !env._FOD_LOGGED_IN }} with: - cwd: ${{ github.action_path }} - script: ./fod-login.sh - post: ./fod-logout.sh + script: fod-login.sh + post: fod-logout.sh branding: icon: 'shield' diff --git a/internal/run-script/README.md b/internal/run-script/README.md new file mode 100644 index 0000000..751bf10 --- /dev/null +++ b/internal/run-script/README.md @@ -0,0 +1,34 @@ +# fortify/github-action/internal/run-script + +This action can run any of the scripts located in the `scripts` directory of this action, including the ability to run post-job scripts, for example to handle session logout. + +```yaml + - uses: fortify/github-action/internal/run-script@v1 + with: + script: