chore: Add setup functionality, doc updates

feat: Add support for performing application version/release creation/setup docs: Consistency improvements
fortify · Sep 17, 2024 · e2606fe · e2606fe
1 parent 004e128
commit e2606fe
Show file tree

Hide file tree

Showing 19 changed files with 174 additions and 48 deletions.
diff --git a/README.md b/README.md
diff --git a/doc-resources/env-do-export.md b/doc-resources/env-do-export.md
@@ -1,4 +1,4 @@
 **`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL    
-If `DO_EXPORT` is set to `true` (implied if any of the other `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided `github-sast-report` action or, if specified, the custom fcli action specified through `EXPORT_ACTION`.  `EXPORT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see [Fcli action documentation]({{var:fcli-doc-base-url}}#_actions) for more information on fcli actions, and documentation for [FoD `github-sast-report` action]({{var:fcli-doc-base-url}}fod-actions.html#_github_sast_report) or [SSC `github-sast-report` action]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report).
+If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`]({{var:fcli-doc-base-url}}fod-actions.html#_github_sast_report) or [SSC `github-sast-action`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`.  `EXPORT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used.
 
 Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub.
diff --git a/doc-resources/env-do-job-summary.md b/doc-resources/env-do-job-summary.md
@@ -1,2 +1,2 @@
 **`DO_JOB_SUMMARY`, `JOB_SUMMARY_ACTION`, `JOB_SUMMARY_EXTRA_OPTS`** - OPTIONAL    
-If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided `release-summary` (FoD) or `appversion-summary` (SSC) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used. Please see [Fcli action documentation]({{var:fcli-doc-base-url}}#_actions) for more information on fcli actions, and documentation for [FoD `release-summary` action]({{var:fcli-doc-base-url}}fod-actions.html#_release_summary) or [SSC `appversion-summary` action]({{var:fcli-doc-base-url}}ssc-actions.html#_appversion_summary).
+If `DO_JOB_SUMMARY` is set to `true` (implied if any of the other two `JOB_SUMMARY_*` variables are set, and implies `DO_WAIT`), this action will generate a job summary listing scan status and issue counts using the fcli-provided [FoD `release-summary`]({{var:fcli-doc-base-url}}fod-actions.html#_release_summary) or [SSC `appversion-summary`]({{var:fcli-doc-base-url}}ssc-actions.html#_appversion_summary) action, or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. `JOB_SUMMARY_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `JOB_SUMMARY_EXTRA_OPTS` environment variable, for example to specify the SSC filter sets to be included in the summary, or to allow an unsigned custom action to be used.
diff --git a/doc-resources/env-do-policy-check.md b/doc-resources/env-do-policy-check.md
@@ -1,2 +1,2 @@
 **`DO_POLICY_CHECK`, `CHECK_POLICY_ACTION`, `CHECK_POLICY_EXTRA_OPTS`** - OPTIONAL    
-If `DO_POLICY_CHECK` is set to `true` (implied if any of the other `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided `check-policy` action or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. `POLICY_CHECK_ACTION` may point to a local file or URL; this custom fcli action must accept at least the `--av` (for SSC) or `--rel` (for FoD) option. Any extra options for this custom fcli action can be passed through the `CHECK_POLICY_EXTRA_OPTS` environment variable, which may include fcli options to allow unsigned custom actions to be used. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient. Please see [Fcli action documentation]({{var:fcli-doc-base-url}}#_actions) for more information on fcli actions, and documentation for [FoD `check-policy` action]({{var:fcli-doc-base-url}}fod-actions.html#_check_policy) or [SSC `check-policy` action]({{var:fcli-doc-base-url}}ssc-actions.html#_check_policy).
+If `DO_POLICY_CHECK` is set to `true` (implied if any of the other two `CHECK_POLICY_*` variables are set, and implies `DO_WAIT`), a policy check will be run after scan completion using the fcli-provided [FoD `check-policy`]({{var:fcli-doc-base-url}}fod-actions.html#_check_policy) or [SSC `check-policy`]({{var:fcli-doc-base-url}}ssc-actions.html#_check_policy) action or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. `POLICY_CHECK_ACTION` may point to a local file or URL; this custom fcli action must accept at least the `--av` (for SSC) or `--rel` (for FoD) option. Any extra options for this custom fcli action can be passed through the `CHECK_POLICY_EXTRA_OPTS` environment variable, which may include fcli options to allow unsigned custom actions to be used. Note that for FoD, the fcli-provided `check-policy` action will check the outcome of the FoD security policy. As SSC doesn't provide any similar security policy features, the fcli-provided action executes some sample policy checks that will likely fail in many cases. As security policies are different for every Fortify customer, you should consider implementing your own custom fcli policy check action(s), unless FoD-provided security policy functionality is sufficient.
diff --git a/doc-resources/env-do-pr-comment.md b/doc-resources/env-do-pr-comment.md
@@ -1,5 +1,5 @@
 **`DO_PR_COMMENT`, `PR_COMMENT_ACTION`, `PR_COMMENT_EXTRA_OPTS`** - OPTIONAL    
-If `DO_PR_COMMENT` is set to `true` (implied if any of the other `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided `github-pr-comment` action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. `PR_COMMENT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see [Fcli action documentation]({{var:fcli-doc-base-url}}#_actions) for more information on fcli actions, and documentation for [FoD `github-pr-comment` action]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment` action]({{var:fcli-doc-base-url}}ssc-actions.html#_github_pr_comment).
+If `DO_PR_COMMENT` is set to `true` (implied if any of the other two `PR_COMMENT_*` variables are set, and implies `DO_WAIT`), this action will generate a pull request comment listing new, re-introduced and removed issues using the fcli-provided [FoD `github-pr-comment`]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) or [SSC `github-pr-comment`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. `PR_COMMENT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `PR_COMMENT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used.
 
 Note that pull request comments will only be generated under the following conditions:
 

diff --git a/doc-resources/env-do-setup.md b/doc-resources/env-do-setup.md
@@ -0,0 +1,4 @@
+**`DO_SETUP`, `SETUP_ACTION`, `SETUP_EXTRA_OPTS`** - OPTIONAL    
+If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), this action will set up the FoD release / SSC application version, creating those if they do not yet exist, using the fcli-provided [FoD `setup-release`]({{var:fcli-doc-base-url}}fod-actions.html#_setup_release)  or [SSC `setup-appversion`]({{var:fcli-doc-base-url}}ssc-actions.html#_setup_appversion) action, or, if specified, the custom fcli action specified through `SETUP_ACTION`. `SETUP_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy from an existing release/application version, or to allow an unsigned custom action to be used.
+
+Note that if setup is enabled, `FOD_RELEASE` or `SSC_APPVERSION` must be configured with a qualified release/version name; you cannot use release/version id.
diff --git a/doc-resources/env-fod-sast-scan.md b/doc-resources/env-fod-sast-scan.md
@@ -3,6 +3,8 @@
 
 {{include:env-fod-release.md}}
 
+{{include:env-do-setup.md}}
+
 {{include:env-fod-package.md}}
 
 **`EXTRA_FOD_SAST_SCAN_OPTS` (deprecated), `FOD_SAST_SCAN_EXTRA_OPTS`** - OPTIONAL    

diff --git a/doc-resources/env-sc-sast-scan.md b/doc-resources/env-sc-sast-scan.md
@@ -12,6 +12,8 @@ Required when performing a Debricked Software Composition Analysis scan; see the
 
 {{include:env-ssc-appversion.md}}
 
+{{include:env-do-setup.md}}
+
 {{include:env-package.md}}
 
 **`SC_SAST_SENSOR_VERSION`** - REQUIRED     

diff --git a/doc-resources/env-ssc-debricked-scan.md b/doc-resources/env-ssc-debricked-scan.md
@@ -7,6 +7,8 @@ See the [Generate access token](https://docs.debricked.com/product/administratio
 
 {{include:env-ssc-appversion.md}}
 
+{{include:env-do-setup.md}}
+
 {{include:env-do-wait.md}}
 
 {{include:env-do-policy-check.md}}

diff --git a/fod-export/README.md b/fod-export/README.md
@@ -58,7 +58,7 @@ Fortify on Demand release to use with this action. This can be specified either
 <!-- START-INCLUDE:env-do-export.md -->
 
 **`DO_EXPORT`, `EXPORT_ACTION`, `EXPORT_EXTRA_OPTS`** - OPTIONAL    
-If `DO_EXPORT` is set to `true` (implied if any of the other `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided `github-sast-report` action or, if specified, the custom fcli action specified through `EXPORT_ACTION`.  `EXPORT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used. Please see [Fcli action documentation](https://fortify.github.io/fcli/dev_develop/#_actions) for more information on fcli actions, and documentation for [FoD `github-sast-report` action](https://fortify.github.io/fcli/dev_develop/fod-actions.html#_github_sast_report) or [SSC `github-sast-report` action](https://fortify.github.io/fcli/dev_develop/ssc-actions.html#_github_sast_report).
+If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`) or when explicitly invoking the `fortify/github-action/fod-export` or `fortify/github-action/ssc-export` actions, this action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [FoD `github-sast-report`](https://fortify.github.io/fcli/dev_develop/fod-actions.html#_github_sast_report) or [SSC `github-sast-action`](https://fortify.github.io/fcli/dev_develop/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`.  `EXPORT_ACTION` may point to a local file or URL; this custom fcli action must support (at least) the exact same action parameters (including any environment variable based default values for those parameters) as the built-in fcli action. Any extra options for the fcli action can be passed through the `EXPORT_EXTRA_OPTS` environment variable, for example to specify the SSC filter set from which to load issue data, or to allow an unsigned custom action to be used.
 
 Note that this may require a [GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security) subscription, unless you're running this action on a public github.com repository. GitHub only supports importing SAST results; other results will not exported to GitHub.