chore: Update actions

fortify · Sep 23, 2024 · 14626d7 · 14626d7
1 parent e2077b9
commit 14626d7
Show file tree

Hide file tree

Showing 4 changed files with 64 additions and 40 deletions.
diff --git a/fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/github-pr-comment.yaml b/fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/github-pr-comment.yaml
@@ -12,15 +12,24 @@ usage:
     This action adds review comments to a GitHub Pull Request. Currently
     this is marked as PREVIEW as we build out this functionality; later
     versions may have different behavior and/or require different action
-    parameters. In particular, note that comments are generated based on
-    current (latest) FoD release state, i.e., based on the last uploaded 
-    scan results. As such, to ensure the comments are accurate for the 
-    given PR/commit id, this action should be run immediately after scan 
-    results have been published, before any subsequent scans are being 
-    published. Also, for now this action doesn't generate any source code 
-    annotations, as GitHub will return an error if vulnerability path & file 
-    name don't match exactly with repository path & file name.
-  
+    parameters. 
+    
+    The current implementation simply compares current scan results 
+    against previous scan results in the given FoD release, listing 
+    all new, re-introduced and removed issues in a new PR comment. 
+    
+    For best results, this fcli action should only be run on GitHub 
+    pull_request triggers. Upon PR creation, a new FoD release should 
+    be created, copying state from the FoD release that represents the 
+    branch into which the PR will be merged, and a new scan should be 
+    run on the current PR branch before invoking this fcli action.
+    
+    This will ensure that scan results for the current PR will be
+    compared against the latest scan results for the target branch
+    upon PR creation. Optionally, new scans can be run upon PR changes,
+    creating new PR comments that show the issue delta compared to the
+    previous scan for this PR.
+      
 parameters:
   - name: release
     cliAliases: rel
@@ -44,7 +53,7 @@ parameters:
     required: true
     defaultValue: ${#substringAfter(#env('GITHUB_REPOSITORY'),'/')}
   - name: pr
-    description: 'Required PR number. Default value: Taken from GITHUB_REF_NAME environment variable.'
+    description: "Required PR number. Default value: Taken from GITHUB_REF_NAME environment variable. Note that default value will only work on GitHub pull_request triggers; if this fcli action is invoked through any other GitHub trigger, it will fail unless an explicit PR number is passed through this option." 
     required: true
     defaultValue: ${#substringBefore(#env('GITHUB_REF_NAME'),'/')}
   - name: commit
@@ -125,9 +134,9 @@ valueTemplates:
 
   - name: reviewBody
     contents: |
-      ## Fortify vulnerability summary
+      ## Fortify vulnerability summary (PREVIEW)
       
-      Any issues listed below are based on comparing the latest scan results against the previous scan results for FoD release [${parameters.release.applicationName}${#isNotBlank(parameters.release.microserviceNae)?'- '+parameters.release.microserviceName:''} - ${parameters.release.releaseName}](${#fod.releaseBrowserUrl(parameters.release)}). To avoid interference from scans for other PR's or branches, it is recommended to track each PR/branch in a separate FoD release.
+      Any issues listed below are based on comparing the latest scan results against the previous scan results in FoD release [${parameters.release.applicationName}${#isNotBlank(parameters.release.microserviceNae)?'- '+parameters.release.microserviceName:''} - ${parameters.release.releaseName}](${#fod.releaseBrowserUrl(parameters.release)}). This is for informational purposes only and, depending on workflow, may not be an accurate representation of what issues will be introduced into or removed from the target branch when merging this PR.   
       
       ### New Issues
       

diff --git a/fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/setup-release.yaml b/fcli-core/fcli-fod/src/main/resources/com/fortify/cli/fod/actions/zip/setup-release.yaml
@@ -4,15 +4,19 @@ author: Fortify
 usage:
   header: (PREVIEW) Set up application release. 
   description: |
-    This action is primarily meant for use in CI/CD integrations, allowing users to 
-    provide a custom action with a customized application release setup process. For 
-    example, such a custom action could define standard profiles (based on team,
-    business unit, application type/risk, ...) with predefined SDLC status and/or 
-    scan setup. Of course, instead of having a single custom action that defines 
-    profiles, you could also provide multiple custom actions that users can select 
-    from, or you can use a combination; each business unit or team providing their 
-    own custom action, with each of these custom actions defining profiles for 
-    different application types/risk. This built-in action only provides a 'default' 
+    his action is primarily meant for use in CI/CD integrations, allowing users to 
+    rovide a custom action with a customized application release setup process if
+    ecessary. 
+      
+    For example, such a custom action could define standard profiles (based on team,
+    business unit, application type/risk, ...) with predefined users, attributes or 
+    issue template to be set on newly created application releases. Of course, instead
+    of having a single custom action that defines profiles, you could also provide
+    multiple custom actions that users can select from, or you can use a combination;
+    each business unit or team providing their own custom action, with each of these
+    custom actions defining profiles for different application types/risk. 
+      
+    This built-in action only provides a 'default' 
     profile that simply invokes the `fcli fod release create` and optionally
     `fcli fod sast-scan setup` commands with some default options, amended with
     options passed to this action.

diff --git a/fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/github-pr-comment.yaml b/fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/github-pr-comment.yaml
@@ -8,18 +8,26 @@ author: Fortify
 usage:
   header: (PREVIEW) Add GitHub Pull Request review comments.  
   description: |
-    This action adds review comments to a GitHub Pull Request. Currently
-    this is marked as PREVIEW as we build out this functionality; later
-    versions may have different behavior and/or require different action
-    parameters. In particular, note that comments are generated based on
-    current (latest) SSC application state, i.e., based on the last 
-    uploaded scan results. As such, to ensure the comments are accurate
-    for the given PR/commit id, this action should be run immediately 
-    after scan results have been published (and approved if necessary), 
-    before any subsequent scans are being published. Also, for now this
-    action doesn't generate any source code annotations, as GitHub will
-    return an error if vulnerability path & file name don't match exactly 
-    with repository path & file name.
+      This action adds review comments to a GitHub Pull Request. Currently
+      this is marked as PREVIEW as we build out this functionality; later
+      versions may have different behavior and/or require different action
+      parameters. 
+      
+      The current implementation simply compares current scan results 
+      against previous scan results in the given SSC application version, 
+      listing all new, re-introduced and removed issues in a new PR comment. 
+      
+      For best results, this fcli action should only be run on GitHub 
+      pull_request triggers. Upon PR creation, a new SSC application version 
+      should be created, copying state from the SSC application version that 
+      represents the branch into which the PR will be merged, and a new scan 
+      hould be run on the current PR branch before invoking this fcli action.
+      
+      This will ensure that scan results for the current PR will be
+      compared against the latest scan results for the target branch
+      upon PR creation. Optionally, new scans can be run upon PR changes,
+      creating new PR comments that show the issue delta compared to the
+      previous scan for this PR.
   
 parameters:
   - name: appversion
@@ -49,7 +57,7 @@ parameters:
     required: true
     defaultValue: ${#substringAfter(#env('GITHUB_REPOSITORY'),'/')}
   - name: pr
-    description: 'Required PR number. Default value: Taken from GITHUB_REF_NAME environment variable.'
+    description: "Required PR number. Default value: Taken from GITHUB_REF_NAME environment variable. Note that default value will only work on GitHub pull_request triggers; if this fcli action is invoked through any other GitHub trigger, it will fail unless an explicit PR number is passed through this option."
     required: true
     defaultValue: ${#substringBefore(#env('GITHUB_REF_NAME'),'/')}
   - name: commit
@@ -131,9 +139,9 @@ valueTemplates:
 
   - name: reviewBody
     contents: |
-      ## Fortify vulnerability summary
+      ## Fortify vulnerability summary (PREVIEW)
       
-      Any issues listed below are based on comparing the latest scan results against the previous scan results for SSC application version [${parameters.appversion.project.name} - ${parameters.appversion.name}](${#ssc.appversionBrowserUrl(parameters.appversion,null)}). To avoid interference from scans for other PR's or branches, it is recommended to track each PR/branch in a separate SSC application version.
+      Any issues listed below are based on comparing the latest scan results against the previous scan results in SSC application version [${parameters.appversion.project.name} - ${parameters.appversion.name}](${#ssc.appversionBrowserUrl(parameters.appversion,null)}). This is for informational purposes only and, depending on workflow, may not be an accurate representation of what issues will be introduced into or removed from the target branch when merging this PR.
       
       ### New Issues
       

diff --git a/fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/setup-appversion.yaml b/fcli-core/fcli-ssc/src/main/resources/com/fortify/cli/ssc/actions/zip/setup-appversion.yaml
@@ -5,15 +5,18 @@ usage:
   header: (PREVIEW) Set up application version. 
   description: |
     This action is primarily meant for use in CI/CD integrations, allowing users to 
-    provide a custom action with a customized application version setup process. For 
-    example, such a custom action could define standard profiles (based on team,
+    provide a custom action with a customized application version setup process if
+    necessary. 
+    
+    For example, such a custom action could define standard profiles (based on team,
     business unit, application type/risk, ...) with predefined users, attributes or 
     issue template to be set on newly created application versions. Of course, instead
     of having a single custom action that defines profiles, you could also provide
     multiple custom actions that users can select from, or you can use a combination;
     each business unit or team providing their own custom action, with each of these
-    custom actions defining profiles for different application types/risk. This 
-    built-in action only provides a 'default' profile that simply invokes the 
+    custom actions defining profiles for different application types/risk. 
+    
+    This built-in action only provides a 'default' profile that simply invokes the 
     `fcli ssc appversion create` command, passing the following options by default: 
     `--skip-if-exists`, `--auto-required-attrs`, `--refresh`, `--refresh-timeout 300s`.
     Additional creation options can be passed through the various action options, which