feat: Add ability to run and import Debricked scans into SSC (closes #41

)
fortify · Jun 4, 2024 · c1564bc · c1564bc
1 parent b02d1d7
commit c1564bc
Show file tree

Hide file tree

Showing 40 changed files with 752 additions and 159 deletions.
diff --git a/README.md b/README.md
diff --git 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/[email protected]
-      if: inputs['sast-scan']=='true' && env.FOD_URL
+      if: inputs['sast-scan']=='true' && env.FOD_URL 
     - uses: fortify/github-action/[email protected]
-      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/[email protected]
+      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
@@ -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
@@ -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}}
+```
diff --git 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
@@ -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
@@ -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
@@ -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).
diff --git 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
@@ -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
diff --git 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
diff --git a/doc-resources/nocomments.env-ssc-debricked-scan-sample.md 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
diff --git a/doc-resources/nocomments.env-ssc-login-sample.md b/doc-resources/nocomments.env-ssc-login-sample.md
@@ -0,0 +1 @@
+          # EXTRA_SSC_LOGIN_OPTS: --socket-timeout=60s
diff --git 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}}
 
 
+<a name="fortify-github-action-ssc-debricked-scan"></a>
+
+## fortify/github-action/ssc-debricked-scan
+
+{{include:action-ssc-debricked-scan.md}}
+
+
 <a name="fortify-github-action-ssc-export"></a>
 
 ## 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
@@ -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)*
diff --git 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.
 
 <!-- END-INCLUDE:env-wait-export.md -->
 

diff --git a/internal/fod-login/action.yml b/internal/fod-login/action.yml
@@ -10,9 +10,8 @@ runs:
     - uses: fortify/github-action/internal/[email protected]
       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
@@ -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: <script name>
+        post:   <post-job script name>
+```
+
+Originally, the idea was to have these scripts located in each individual action directory, for example having `ssc-login.sh` and `ssc-logout.sh` scripts located in the `internal/ssc-login` directory. However, this proved to be difficult/impossible:
+
+- As scripts need to be run using `bash` (also on Windows), we need to convert `${{github.action_path}}` (which may include drive letter and backslashes on Windows) to `bash` format; an example of how this can be done is shown in `action.yml`.
+- GitHub lazily evaluates action inputs when running the post-job actions, but doesn't re-run any steps used to generate those inputs.
+
+So, suppose we'd generate a `BASH_ACTION_PATH` environment variable that contains `${{github.action_path}}` in `bash` format, we'd expect to be able to use something like:
+
+```yaml
+    - uses: fortify/github-action/internal/run-script/[email protected]
+      with: 
+        script: ${{ env.BASH_ACTION_PATH }}/ssc-login.sh
+        post:   ${{ env.BASH_ACTION_PATH }}/ssc-logout.sh
+```
+
+This works fine for `script:`, but the `post:` script would use whatever the value of `BASH_ACTION_PATH` is during post-job execution. So, if we'd run both `ssc-login` and `sc-sast-login` actions, the post-job action would try to run `..../internal/sc-sast-login/ssc-logout.sh`, which would fail because of the incorrect directory name.
+
+Several work-arounds were tried, but failed. Only way that this would likely work is to have the calling action pass something like a static action id, which would then be used by this action to set a `POST_<id>_SCRIPT=${{inputs.POST}}` environment variable. During post-job execution, we wouldn't look at any actual inputs, but instead just execute the script identified in the `POST_<id>_SCRIPT` environment variable.
+
+Apart from hosting the scripts together with the action that executes them, another advantage of such an id is that we can also provide out-of-the-box support for run-once actions, like the various `login` actions; this is currently handled by setting an environment variable in the `*-login.sh` and `*-logout.sh` scripts. As we may also have scripts that may need to be run multiple times, we should control this through a `run-once: true|false` input.
+
+Disadvantage, apart from slightly more complex implementation, is that each caller of this `run-script` action would also need to provide the value of `${{ github.action_path }}` as an input to this action, in order to have this action determine appropriate script location.
+
+