chore: Incomplete doc updates

action.yml

@@ -13,15 +13,15 @@ inputs:
 runs:
   using: composite
   steps:
-    - uses: fortify/github-action/fod-sast-scan@main
+    - uses: fortify/github-action/fod-sast-scan@doc-updates
       if: inputs['sast-scan']=='true' && env.FOD_URL 
       env:
         DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }}
-    - uses: fortify/github-action/sc-sast-scan@main
+    - uses: fortify/github-action/sc-sast-scan@doc-updates
       if: inputs['sast-scan']=='true' && env.SSC_URL 
       env:
         DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }}
-    - uses: fortify/github-action/ssc-debricked-scan@main
+    - uses: fortify/github-action/ssc-debricked-scan@doc-updates
       if: inputs['sast-scan']=='false' && inputs['debricked-sca-scan']=='true' && env.SSC_URL 
 
 branding:

doc-resources/action/_root/readme.md

@@ -0,0 +1,70 @@
+This GitHub Action allows for easy integration of Fortify Application Security Testing (AST) into your GitHub Action workflows. It  provides out-of-the-box support for Static Application Security Testing (SAST) and Software Composition Analysis (SCA); support for Dynamic or Mobile Application Security Testing (DAST & MAST) may be added in the future. Apart from utilizing the standard scan workflows provided by this GitHub Action, you may also choose to utilize the various building blocks to implement custom workflows, which can be either customized SAST or SCA workflows, or your own DAST or MAST workflows.
+
+The following sections describe these topics in more detail:
+
+* [Prerequisites](#prerequisites)
+* [Application Security Testing with Fortify on Demand](#application-security-testing-with-fortify-on-demand)
+* [Application Security Testing with SSC/ScanCentral](#application-security-testing-with-ssc-scancentral)
+* [Building blocks for custom workflows](#building-blocks-for-custom-workflows)
+
+{{include:action/generic/prerequisites-h2.md}}
+
+## Application Security Testing with Fortify on Demand
+
+The standard workflow provided by this GitHub Action allows for running a Static scan and optional open-source scan (software composition analysis) on Fortify on Demand. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow:
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run FoD SAST Scan
+        uses: fortify/github-action@{{var:action-major-version}}
+        with:
+          sast-scan: true
+          debricked-sca-scan: true
+        env:
+{x{include:nocomments.env-fod-sast-scan-sample.md}}
+```
+
+In this example, the `with` clause specifies what scans to run:
+
+{{include:action/generic/nocomments.input-table-header.md}}
+| `sast-scan` | If set to `true`, run a static scan. If not specified or set to `false`, the action will run neither static or open-source scan (independent of `debricked-sca-scan` setting), as open-source scans are currently only run in combination with a static scan. |
+| `debricked-sca-scan` | Configure the static scan to also run an open-source scan. Depending on FoD configuration, this may be either a Debricked or a Sonatype scan. Effectively, this adds dependency data to the scan payload, and enables the open-source scan setting in the FoD scan configuration. Note that any existing FoD scan configuration will not be updated, so if the scan has already been configured in FoD, an open-source scan will only be performed if previously enabled in the existing scan configuration. |
+
+The `env` clause specifies environment variables to configure those scans. The following environment variables are currently supported:
+
+{x{include:env-fod-sast-scan.md}}
+
+{x{include:env-setup.md}}
+
+
+## Application Security Testing with SSC/ScanCentral
+
+The standard workflow provided by this GitHub Action allows for running a static scan on ScanCentral SAST and/or running software composition analysis on Debricked. The following sample snippet demonstrates how to invoke this GitHub Action from a GitHub Actions workflow:
+
+```yaml
+    steps:    
+      - name: Check out source code
+        uses: actions/checkout@v4  
+      - name: Run FoD SAST Scan
+        uses: fortify/github-action@{{var:action-major-version}}
+        with:
+          sast-scan: true
+          debricked-sca-scan: true
+        env:
+{x{include:nocomments.env-sc-sast-scan-sample.md}}
+```
+
+{{include:action/generic/nocomments.input-section-and-table-header.md}}
+| `sast-scan` | If set to `true`, run a static scan. If not specified or set to `false`, no static scan will be run. |
+| `debricked-sca-scan` | If set to `true`, run Debricked Software Composition Analysis. If not specified or set to `false`, no software composition analysis will be performed. |
+
+{{include:action/generic/nocomments.env-section-and-table-header.md}}
+
+{x{include:env-sc-sast-scan.md}}
+
+{x{include:env-setup.md}}
+
+## Building blocks for custom workflows
+

doc-resources/action/fod-export/nocomments.env-export-optional.md

@@ -0,0 +1 @@
+| DO_EXPORT<br/>EXPORT_ACTION<br/>EXPORT_EXTRA_OPTS | If `DO_EXPORT` is set to `true` (implied if any of the other two `EXPORT_*` variables are set, and implies `DO_WAIT`), 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) 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 to allow an unsigned custom action to be used.<br/><br/>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. |

doc-resources/action/fod-export/nocomments.env-export.md

@@ -0,0 +1 @@
+| EXPORT_ACTION<br/>EXPORT_EXTRA_OPTS | 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) 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 to allow an unsigned custom action to be used. |

doc-resources/action-fod-export.md → doc-resources/action/fod-export/readme.md

@@ -1,16 +1,6 @@
 This action exports the latest vulnerability data from an FoD release to the GitHub 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.
 
-{{include:action-prerequisites.md}}
-
-### Action environment variable inputs
-
-{{include:env-fod-connection.md}}
-
-{{include:env-fod-release.md}}
-
-{{include:env-do-export.md}}
-
-{{include:env-setup.md}}
+{{include:action/generic/prerequisites-h3.md}}
 
 ### Sample usage
 
@@ -21,7 +11,13 @@ The sample workflow below demonstrates how to configure the action for exporting
       - name: Export FoD vulnerability data to GitHub
         uses: fortify/github-action/fod-export@{{var:action-major-version}}
         env:
-{{include:nocomments.env-fod-connection-sample.md}}
-{{include:nocomments.env-fod-release-sample.md}}
-{{include:nocomments.env-setup-sample.md}}
+{{include:action/generic/fod/nocomments.snippet-fod-login.md}}
+{{include:action/generic/fod/nocomments.snippet-fod-release.md}}
+{{include:action/setup/nocomments.snippet-tool-definitions.md}}
 ```
+
+{{include:action/generic/nocomments.env-section-and-table-header.md}}
+{{include:action/generic/fod/nocomments.env-fod-login.md}}
+{{include:action/generic/fod/nocomments.env-fod-release.md}}
+{{include:action/fod-export/nocomments.env-export.md}}
+{{include:action/setup/nocomments.env-tool-definitions.md}}

doc-resources/action/fod-sast-scan/TODO-PR-extra-info.md

@@ -0,0 +1,19 @@
+Note that pull request comments will only be generated under the following conditions:
+
+* Standard `GITHUB_REF_NAME` environment variable points to a pull request, which is only the case on GitHub `pull_request` triggers and not for example `manual` triggers (even if the branch is associated with a current pull request).
+* All other standard GitHub environment variables like `GITHUB_TOKEN`, `GITHUB_REPOSITORY` and `GITHUB_SHA` are set.
+
+PR comments are generated by comparing scan results from the current GitHub Action run against the previous scan in the same application version/release; it won't detect any new/removed issues from older scans. For best results, you should configure your workflow as follows:
+
+- For any branches for which you might want to generate PR comments, have the workflow trigger only on `pull_request` events. Note that you can have a single workflow that is triggered on both `push` events for your main branch, and only `pull_request` events for all other branches.
+- Don't set `FOD_RELEASE` or `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name.
+- Set `DO_RELEASE_SETUP` or `DO_APPVERSION_SETUP` to `true`, to allow a branch-specific application version/release to be automatically created.
+- Include `--copy-from` option in `RELEASE_SETUP_EXTRA_OPTS` or `APPVERSION_SETUP_EXTRA_OPTS` to copy state from the version/release that represents the PR target branch into the newly created application version/release.
+
+With a setup like this, whenever a new PR is created, the GitHub Action will:
+- Create a new application version/release named `<repository owner>/<repository name>:<branch name>`.
+- Copy state from the application version/release identified by the `--copy-from` option to this new application version/release.
+- Run a new scan of the branch associated with the current PR, and upload results to the application version/release created above.
+- Generate a PR comment listing new and removed issues, based on comparing the results of the new scan that was run in the previous step against the scan results that were copied from the version/release identified by the `--copy-from` option.
+
+If any subsequent updates are pushed to the PR and the workflow is also being triggered on PR update events, the GitHub Action will run a new scan of the branch associated with the PR, publish results to the existing branch-specific application version/release, and generate a new PR comment that shows any new/removed issues in the new scan compared to the previous scan for the same branch/PR.

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

@@ -0,0 +1,11 @@
+{{include:action/generic/fod/nocomments.env-fod-login.md}}
+{{include:action/generic/fod/nocomments.env-fod-release.md}}
+{{include:action/fod-sast-scan/nocomments.env-setup.md}}
+{{include:action/package/nocomments.env-package-extra-opts.md}}
+|FOD_SAST_SCAN_EXTRA_OPTS<br/>EXTRA_FOD_SAST_SCAN_OPTS|Extra FoD SAST scan options; see [`fcli fod sast-scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.|
+{{include:action/generic/nocomments.env-do-wait.md}}
+{{include:action/fod-sast-scan/nocomments.env-policy-check.md}}
+{{include:action/fod-sast-scan/nocomments.env-job-summary.md}}
+{{include:action/fod-export/nocomments.env-export.md}}
+{{include:action/fod-sast-scan/nocomments.env-pr-comment.md}}
+{{include:action/setup/nocomments.env-tool-definitions.md}}

doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md

@@ -0,0 +1 @@
+|DO_JOB_SUMMARY<br/>JOB_SUMMARY_ACTION<br/>JOB_SUMMARY_EXTRA_OPTS|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, 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 allow an unsigned custom action to be used.

doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md

@@ -0,0 +1 @@
+|DO_POLICY_CHECK<br/>CHECK_POLICY_ACTION<br/>CHECK_POLICY_EXTRA_OPTS|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, 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 `--rel` option. Any extra options for a 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.|

doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md

@@ -0,0 +1 @@
+|(PREVIEW)<br/>DO_PR_COMMENT<br/>PR_COMMENT_ACTION<br/>PR_COMMENT_EXTRA_OPTS|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) 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 allow an unsigned custom action to be used.|