feat: Add support for updateable/customizable tool definitions

feat: Add support for Debricked CLI on fortify/github-action/setup

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2023 Open Text or one of its affiliates
+Copyright 2024 Open Text or one of its affiliates
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

action.yml

@@ -9,9 +9,9 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: fortify/github-action/fod-sast-scan@main
+    - uses: fortify/github-action/fod-sast-scan@feat-tool-definitions
       if: inputs['sast-scan']=='true' && env.FOD_URL
-    - uses: fortify/github-action/sc-sast-scan@main
+    - uses: fortify/github-action/sc-sast-scan@feat-tool-definitions
       if: inputs['sast-scan']=='true' && env.SSC_URL  
 
 branding:

doc-resources/action-fod-export.md

@@ -6,6 +6,8 @@ This action exports the latest vulnerability data from an FoD release to the Git
 
 {{include:env-fod-release.md}}
 
+{{include:env-setup.md}}
+
 ### 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.
@@ -17,4 +19,5 @@ The sample workflow below demonstrates how to configure the action for exporting
         env:
 {{include:nocomments.env-fod-connection-sample.md}}
 {{include:nocomments.env-fod-release-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```

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

@@ -14,6 +14,8 @@ Before running this action, please ensure that the appropriate release has been
 
 {{include:env-fod-sast-scan.md}}
 
+{{include:env-setup.md}}
+
 ### Sample usage
 
 The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
@@ -26,4 +28,5 @@ The sample workflow below demonstrates how to configure the action for running a
         uses: fortify/github-action/fod-sast-scan@{{var:action-major-version}}
         env:
 {{include:nocomments.env-fod-sast-scan-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```

doc-resources/action-package.md

@@ -4,6 +4,8 @@ This action packages application source code using [ScanCentral Client]({{var:sc
 
 {{include:env-package.md}}
 
+{{include:env-setup.md}}
+
 ### Sample usage
 
 The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
@@ -16,4 +18,5 @@ The sample workflow below demonstrates how to configure the action for running a
         uses: fortify/github-action/package@{{var:action-major-version}}
         env:
 {{include:nocomments.env-package-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```

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

@@ -12,6 +12,8 @@ Before running this action, please ensure that the appropriate application versi
 
 {{include:env-sc-sast-scan.md}}
 
+{{include:env-setup.md}}
+
 ### Sample usage
 
 The sample workflow below demonstrates how to configure the action for running a SAST scan on ScanCentral SAST.
@@ -24,4 +26,5 @@ The sample workflow below demonstrates how to configure the action for running a
         uses: fortify/github-action/sc-sast-scan@{{var:action-major-version}}
         env:
 {{include:nocomments.env-sc-sast-scan-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```

doc-resources/action-setup.md

@@ -1,6 +1,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.
 
 * [fcli](https://github.com/fortify/fcli)
+* [Debricked CLI](https://github.com/debricked/cli)
 * [ScanCentral Client]({{var:sc-client-doc-base-url}}#A_Clients.htm)
 * [FoDUploader](https://github.com/fod-dev/fod-uploader-java)
 * [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter)
@@ -11,6 +12,9 @@ This action allows for setting up the Fortify tools listed below. Which tools an
 **`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.
 
@@ -26,6 +30,13 @@ The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (def
 **`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.
@@ -54,12 +65,14 @@ The sample workflow below demonstrates how to configure the action for installin
       - 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

doc-resources/action-ssc-export.md

@@ -6,6 +6,8 @@ This action exports the latest vulnerability data from an SSC application versio
 
 {{include:env-ssc-appversion.md}}
 
+{{include:env-setup.md}}
+
 ### 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.
@@ -17,4 +19,5 @@ The sample workflow below demonstrates how to configure the action for exporting
         env:
 {{include:nocomments.env-ssc-connection-sample.md}}
 {{include:nocomments.env-ssc-appversion-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```

doc-resources/env-setup.md

@@ -0,0 +1,4 @@
+**`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.

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

@@ -0,0 +1 @@
+          # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip

doc-resources/repo-readme.md

@@ -45,10 +45,14 @@ If not specified or when set to false, no SAST scan will be performed. For now,
 
 {{include:env-fod-sast-scan.md}}
 
+{{include:env-setup.md}}
+
 #### ScanCentral SAST
 
 {{include:env-sc-sast-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.
@@ -65,6 +69,7 @@ The sample workflows below demonstrate how to configure the action for running a
           sast-scan: true
         env:
 {{include:nocomments.env-fod-sast-scan-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```
 
 #### ScanCentral SAST
@@ -79,6 +84,7 @@ The sample workflows below demonstrate how to configure the action for running a
           sast-scan: true
         env:
 {{include:nocomments.env-sc-sast-scan-sample.md}}
+{{include:nocomments.env-setup-sample.md}}
 ```
 
 ### More information

doc-resources/template-values.md

@@ -11,7 +11,7 @@ https://github.com/fortify/github-action
 v1
 
 # fcli-doc-base-url
-https://fortify.github.io/fcli/v2.0.0/
+https://fortify.github.io/fcli/v2.2.0/
 
 # sc-client-doc-base-url
 https://www.microfocus.com/documentation/fortify-software-security-center/2310/SC_SAST_Help_23.1.0/index.htm

fod-export/README.md

@@ -39,6 +39,17 @@ Fortify on Demand release to use with this action. This can be specified either
 <!-- END-INCLUDE:env-fod-release.md -->
 
 
+
+<!-- START-INCLUDE:env-setup.md -->
+
+**`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.
+
+<!-- END-INCLUDE:env-setup.md -->
+
+
 ### 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.
@@ -53,6 +64,7 @@ The sample workflow below demonstrates how to configure the action for exporting
           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
 ```
 
 <!-- END-INCLUDE:action-fod-export.md -->

fod-export/action.yml

@@ -4,8 +4,8 @@ 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@feat-tool-definitions
+    - uses: fortify/github-action/setup@feat-tool-definitions
       with:
         export-path: false
         vuln-exporter: action-default
@@ -15,7 +15,7 @@ runs:
           *) echo '_RELEASE_OPT="--fod.release.id=${FOD_RELEASE}"' >> $GITHUB_ENV ;;
         esac
       shell: bash
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${VULN_EXPORTER_CMD}" FoDToGitHub "--fod.baseUrl=${FOD_URL}" "--fod.tenant=${FOD_TENANT}" "--fod.user=${FOD_USER}" "--fod.password=${FOD_PASSWORD}" "--fod.clientID=${FOD_CLIENT_ID}" "--fod.clientSecret=${FOD_CLIENT_SECRET}" "${_RELEASE_OPT}"'
     # Uploaded the generated file containing Fortify vulnerabilities to GitHub.

fod-sast-scan/README.md

@@ -48,7 +48,7 @@ Required when authenticating with user credentials: FoD tenant, user and passwor
 
 
 **`EXTRA_FOD_LOGIN_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.0.0//manpage/fcli-fod-session-login.html)
+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.2.0//manpage/fcli-fod-session-login.html)
 
 <!-- END-INCLUDE:env-fod-login.md -->
 
@@ -78,7 +78,7 @@ As an example, if the build file that you want to use for packaging doesn't adhe
 
 
 **`EXTRA_FOD_SAST_SCAN_OPTS`** - OPTIONAL    
-Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.0.0//manpage/fcli-fod-sast-scan-start.html)
+Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v2.2.0//manpage/fcli-fod-sast-scan-start.html)
 
 
 <!-- START-INCLUDE:env-wait-export.md -->
@@ -95,6 +95,17 @@ If set to `true`, this action will export scan results to the GitHub Security Co
 <!-- END-INCLUDE:env-fod-sast-scan.md -->
 
 
+
+<!-- START-INCLUDE:env-setup.md -->
+
+**`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.
+
+<!-- END-INCLUDE:env-setup.md -->
+
+
 ### Sample usage
 
 The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
@@ -115,6 +126,7 @@ The sample workflow below demonstrates how to configure the action for running a
           # EXTRA_PACKAGE_OPTS: -oss
           # DO_WAIT: true
           # DO_EXPORT: true
+          # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip
 ```
 
 <!-- END-INCLUDE:action-fod-sast-scan.md -->

fod-sast-scan/action.yml

@@ -4,23 +4,23 @@ 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@feat-tool-definitions
+    - uses: fortify/github-action/setup@feat-tool-definitions
       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@main
+    - uses: fortify/github-action/internal/fod-login@feat-tool-definitions
+    - uses: fortify/github-action/package@feat-tool-definitions
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" fod sast-scan start --rel "${FOD_RELEASE}" -f package.zip --store fod_scan ${EXTRA_FOD_SAST_SCAN_OPTS}'
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       if: env.DO_WAIT == 'true' || env.DO_EXPORT == 'true'
       with:
         cmd: '"${FCLI_CMD}" fod sast-scan wait-for ::fod_scan::'
-    - uses: fortify/github-action/internal/fod-logout@main
+    - uses: fortify/github-action/internal/fod-logout@feat-tool-definitions
     - if: env.DO_EXPORT == 'true'
-      uses: fortify/github-action/fod-export@main
+      uses: fortify/github-action/fod-export@feat-tool-definitions
 
 branding:
   icon: 'shield'

internal/fod-login/action.yml

@@ -18,7 +18,7 @@ runs:
         fi
       shell: bash
     # Run fcli login command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" fod session login ${_FOD_LOGIN_OPTS}'  
     # Clean up temporary environment variables

internal/fod-logout/action.yml

@@ -5,7 +5,7 @@ runs:
   using: composite
   steps:
     # Run fcli logout command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" fod session logout'        
 branding:

internal/sc-sast-login/action.yml

@@ -21,7 +21,7 @@ runs:
         echo '_SC_SAST_LOGIN_OPTS=--ssc-url "${SSC_URL}" -t "${SSC_TOKEN}" -c "${SC_SAST_TOKEN}" ${EXTRA_SC_SAST_LOGIN_OPTS}' >> $GITHUB_ENV
       shell: bash
     # Run fcli login command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" sc-sast session login ${_SC_SAST_LOGIN_OPTS}' 
     # Clean up temporary environment variables

internal/sc-sast-logout/action.yml

@@ -5,7 +5,7 @@ runs:
   using: composite
   steps:
     # Run fcli logout command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         # TODO If we add functionality for generating a CIToken in the sc-sast-login
         #      action, we should clean it up here. 

internal/ssc-login/action.yml

@@ -18,7 +18,7 @@ runs:
         fi
       shell: bash
     # Run fcli login command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" ssc session login ${_SSC_LOGIN_OPTS}'   
     # Clean up temporary environment variables

internal/ssc-logout/action.yml

@@ -18,7 +18,7 @@ runs:
         fi
       shell: bash
     # Run fcli login command; note that the calling action/workflow is responsible for installing fcli
-    - uses: fortify/github-action/internal/run@main
+    - uses: fortify/github-action/internal/run@feat-tool-definitions
       with:
         cmd: '"${FCLI_CMD}" ssc session logout ${_SSC_LOGOUT_OPTS}' 
     # Clean up temporary environment variables 

package/README.md

@@ -26,6 +26,17 @@ As an example, if the build file that you want to use for packaging doesn't adhe
 <!-- END-INCLUDE:env-package.md -->
 
 
+
+<!-- START-INCLUDE:env-setup.md -->
+
+**`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.
+
+<!-- END-INCLUDE:env-setup.md -->
+
+
 ### Sample usage
 
 The sample workflow below demonstrates how to configure the action for running a SAST scan on FoD.
@@ -38,6 +49,7 @@ The sample workflow below demonstrates how to configure the action for running a
         uses: fortify/github-action/package@v1
         env:
           # EXTRA_PACKAGE_OPTS: -bf custom-pom.xml
+          # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip
 ```
 
 <!-- END-INCLUDE:action-package.md -->