diff --git a/CHANGELOG.md b/CHANGELOG.md index c19eb4d..310eec4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,22 +1,3 @@ -## [1.5.1](https://github.com/fortify/github-action/compare/v1.4.0...v1.5.1) (2024-11-01) - - -### Features - -* FoD: Add support for creating application through `DO_SETUP` ([2d91e3c](https://github.com/fortify/github-action/commit/2d91e3c5c405391e5ee2cfe725a77b0ded38dcd0)) -* FoD: Automatically set `--app-owner` if `FOD_USER` is configured ([345ddda](https://github.com/fortify/github-action/commit/345ddda04de863b34e9566df5ea088f5872eeef4)) -* FoD: Improve handling of `--copy-from` option in `SETUP_EXTRA_OPTS` ([2d91e3c](https://github.com/fortify/github-action/commit/2d91e3c5c405391e5ee2cfe725a77b0ded38dcd0)) -* Major documentation usability improvements ([22ea8e9](https://github.com/fortify/github-action/commit/22ea8e9ef9edb24e364d1dc66230649726ad450c)) -* Simplify setup of Debricked scans on FoD ([7c25788](https://github.com/fortify/github-action/commit/7c25788b4c57582d2039d70a1ad9aeb228e34c6c)) -* Update fcli to 2.9.0 ([2d91e3c](https://github.com/fortify/github-action/commit/2d91e3c5c405391e5ee2cfe725a77b0ded38dcd0)) -* Update ScanCentral Client to 24.4.0 ([f3246ac](https://github.com/fortify/github-action/commit/f3246ac1d35a20a34df0a2d404479f1fabeae574)) - - -### Bug Fixes - -* Improve parsing of boolean flags in `*_EXTRA_OPTS` ([2d91e3c](https://github.com/fortify/github-action/commit/2d91e3c5c405391e5ee2cfe725a77b0ded38dcd0)) -* Update Debricked CLI to 2.1.7 ([2d91e3c](https://github.com/fortify/github-action/commit/2d91e3c5c405391e5ee2cfe725a77b0ded38dcd0)) - # Changelog ## [2.2.0](https://github.com/fortify/github-action/compare/v2.1.1...v2.2.0) (2025-11-19) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 970bdd2..09f19db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to Fortify GitHub Actions +# Contributing to Fortify GitHub Action ## Contribution Agreement @@ -10,33 +10,32 @@ Contributions like bug fixes and enhancements may be submitted through Pull Requ ## Information for Developers ### Repository initialization -After cloning this repository, please run ./configure.sh to install npm modules and configure git hooks. When adding a new NodeJS-based action, you'll need to update `/configure.sh` to add the action directory to the for-loop. - -### Action documentation -Action documentation is generated from the `doc-resources` directory, using functionality provided by https://github.com/fortify/shared-doc-resources. The `doc-resources` directory contains the following: - -* `action/_generic/**/*`: Generic includes referenced from action documentation -* `action/_root/readme.md`: Documentation for the top-level action -* `action/`: - * `readme.md`: Documentation for `` sub-action - * `nocomments.env-*.md`: Markdown table rows describing environment variable inputs - * `nocomments.snippet-*.md`: Sample YAML snippets -* `repo-devinfo.md`: Information for developers -* `repo-usage.md`: Used to generated top-level USAGE.md, just refers to README.md -* `template-values.md`: Defines variables used in documentation resources -* `templates/README.template.md`: Template for the top-level `README.md` file -* `templates//README.template.md`: Template for the README.md file for each sub-action -* `update-repo-docs.sh`: Script to generate documentation resources - -If you need to update the documentation for an existing action, you'll want to edit the corresponding `action//readme.md` file or the included files. - -When adding a new action, you should: -* Create a corresponding directory in the `doc-resources/templates` directory -* Copy an existing `README.template.md` from one of the other action template directories -* Change the header and include statement in the new `README.template.md` to match the new action -* Create a new `action//readme.md` file in the `doc-resources` directory - -After any documentation updates, you may want to manually run `doc-resources/update-repo-docs.sh` to verify whether all includes can be found, and to review the generated README.md files for each action. +After cloning this repository, please run `./configure.sh` to install npm modules and configure git hooks. + +### Documentation structure +Documentation is generated from the `doc-resources` directory using functionality provided by https://github.com/fortify/shared-doc-resources. The structure is straightforward: + +* `repo-intro.md`: Introduction text included in README.md +* `repo-usage.md`: Usage instructions included in USAGE.md +* `repo-resources.md`: Links to resources (contributing, license, etc.) +* `repo-devinfo.md`: Information for developers (this file) +* `repo-usage-text.md`: Include file with links to detailed documentation (used in both intro and usage) +* `template-values.md`: Variables used throughout the documentation +* `update-repo-docs.sh`: Script to regenerate README.md, USAGE.md, and other files + +To update documentation, edit the appropriate `.md` files in `doc-resources/`, then run `doc-resources/update-repo-docs.sh` to regenerate the top-level documentation files. + +### Building the action + +The action uses the `@fortify/setup` NPM package published to [npmjs.org](https://www.npmjs.com/package/@fortify/setup). To build: + +```bash +cd setup +npm install +npm run build +``` + +This creates a bundled `dist/index.js` file that includes all dependencies. The action is ready to use once the dist directory is committed. diff --git a/README.md b/README.md index c5da1ec..571c7b6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# fortify/github-action@v2 +# Fortify GitHub Action @@ -9,335 +9,124 @@ - + -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 `fortify/github-action` GitHub Action allows for easy integration of OpenText Fortify Application Security Testing (AST) into your GitHub Action workflows by bootstrapping the latest [fcli v3 release](https://github.com/fortify/fcli/releases/v3) using the [`@fortify/setup` NPM component](https://www.npmjs.com/package/@fortify/setup), and then running the `fcli action run ci` command. -The following sections describe these topics in more detail: +As such, this GitHub Action automatically benefits from new features and bug fixes as they are introduced in fcli, although there are options to use a fixed fcli version in case you need more stability. At the time of writing, the fcli `ci` action 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. -* [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-sscscancentral) -* [Building blocks for custom workflows](#building-blocks-for-custom-workflows) +Apart from the top-level `fortify/github-action` for running the fcli-based `ci` workflow, this repository also provides the `fortify/github-action/setup` GitHub Action. This action allows for setting up fcli and other Fortify tools like ScanCentral Client for use in a custom GitHub Actions workflow, for example for implementing a fully customized AST scan workflow or some other automation workflow that needs to interact with Fortify products. - + -## Prerequisites +### Quick Start - - - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - - - - -## 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: +#### OpenText Core Application Security (Fortify on Demand) ```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Fortify on Demand SAST & SCA Scan - uses: fortify/github-action@v2 - with: - sast-scan: true - debricked-sca-scan: true +name: Fortify on Demand Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_CLIENT_ID: ${{secrets.FOD_CLIENT_ID}} - # FOD_CLIENT_SECRET: ${{secrets.FOD_CLIENT_SECRET}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # DO_SETUP: true - # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml - # SETUP_EXTRA_OPTS: --copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}" - # SC_CLIENT_VERSION: 24.4.1 - # DO_PACKAGE_DEBUG: true - # PACKAGE_EXTRA_OPTS: -oss -bt mvn - # FOD_SAST_SCAN_EXTRA_OPTS: - # DO_WAIT: true - # DO_POLICY_CHECK: true - # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml - # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore - # DO_JOB_SUMMARY: true - # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml - # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore - # DO_PR_COMMENT: true - # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml - # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore - # DO_EXPORT: true - # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml - # EXPORT_EXTRA_OPTS: --on-unsigned=ignore - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip + FOD_URL: ${{ vars.FOD_URL }} + FOD_CLIENT_ID: ${{ secrets.FOD_CLIENT_ID }} + FOD_CLIENT_SECRET: ${{ secrets.FOD_CLIENT_SECRET }} + # FOD_RELEASE: MyApp:main # Optional: defaults to repo:branch + # FCLI_BOOTSTRAP_VERSION: v3.15 # Optional if you prefer stability over latest ``` -### Action inputs - -This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. - -| Action input | Description | -| :--- | :--- | -| 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 Fortify on Demand 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 Fortify on Demand scan configuration. Note that any existing scan configuration will not be updated, so if the scan has already been configured in Fortify on Demand, an open-source scan will only be performed if previously enabled in the existing scan configuration. | - -### Action environment variable inputs - -This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - -| Environment variable | Description | -| :--- | :--- | -| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to Fortify on Demand to be rendered incorrectly, for example in GitHub Action job summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | -| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: Fortify on Demand Client ID (API key) and Secret (API secret). | -| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: Fortify on Demand tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | -| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | Extra login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| -| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | -|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [`setup-release`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable. Depending on your Git workflow, it is recommended to have each newly created release copy state from the release representing your default branch by passing `--copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}"` through `SETUP_EXTRA_OPTS`. To allow the GitHub Action to create new applications, you must (also) provide the `--app-owner ` option through `SETUP_EXTRA_OPTS` if authenticating with client credentials. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| -| SC_CLIENT_VERSION | By default, this action uses ScanCentral Client 25.4.0 for packaging. This environment variable allows for overriding the ScanCentral Client version used for packaging. | -|DO_PACKAGE_DEBUG| If set to true, this will enable the `-debug` option on the `scancentral` command, and store both ScanCentral logs and the `package.zip` file as job artifacts.| -|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2540/sc-sast-ugd-html-25.4.0/doc/2404_25.4/home.html) for more information on available options. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| -|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.| -| DO_WAIT | By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating job summaries. This behavior is documented in the applicable environment variable descriptions. | -|DO_POLICY_CHECK
CHECK_POLICY_ACTION
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 [`check-policy`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| -|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
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`), a job summary listing scan status and issue counts will be generated using the fcli-provided [`release-summary`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details. | -| DO_EXPORT
EXPORT_ACTION
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`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [`github-sast-report`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.

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. | -|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
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`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [`github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) and [Pull Request Comments](#fortify-on-demand-pull-request-comments) sections below for more details.| -| TOOL_DEFINITIONS | 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. | - - - - -### Fortify on Demand Fcli Actions - - - - - - -As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - -For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v3.13.1/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - - - - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. - - - - - - - -### Fortify on Demand Pull Request Comments - - - -This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [`github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. - -**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - -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 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`, to use the default value that corresponds to repository and branch name. -- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. -- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. +#### OpenText Application Security (Fortify Software Security Center) -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application release named `/:`. -- Copy state from the application release identified by the `--copy-from` option to this new application release. -- Run a new scan of the branch associated with the current PR, and upload results to the application 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 application 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 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. - - - - -## Application Security Testing with SSC/ScanCentral +```yaml +name: Fortify SSC Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans + env: + SSC_URL: ${{ vars.SSC_URL }} + SSC_TOKEN: ${{ secrets.SSC_TOKEN }} + SC_SAST_TOKEN: ${{ secrets.SC_SAST_TOKEN }} + # SSC_APPVERSION: MyApp:main # Optional: defaults to repo:branch +``` -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: +#### Custom workflow ```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run ScanCentral SAST & Debricked scan - uses: fortify/github-action@v2 +name: Custom Fortify Workflow +on: [push] + +jobs: + custom-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: fortify/github-action/setup@v3 with: - sast-scan: true - debricked-sca-scan: true + fcli: bootstrapped # Set up bootstrapped fcli version. May also specify specific version, but + # then fcli may be downloaded twice (bootstrap version and requested version). env: - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - SC_SAST_TOKEN: ${{secrets.SC_SAST_CLIENT_AUTH_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s - DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} - # SSC_APPVERSION: MyApp:MyVersion - # DO_SETUP: true - # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml - # SETUP_EXTRA_OPTS: --on-unsigned=ignore - # SC_CLIENT_VERSION: 24.4.1 - # DO_PACKAGE_DEBUG: true - # PACKAGE_EXTRA_OPTS: -oss -bt mvn - # SC_SAST_SENSOR_VERSION: 24.4.1 - # EXTRA_SC_SAST_SCAN_OPTS: - # DO_WAIT: true - # DO_POLICY_CHECK: true - # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml - # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore - # DO_JOB_SUMMARY: true - # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml - # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore - # DO_PR_COMMENT: true - # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml - # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore - # DO_EXPORT: true - # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml - # EXPORT_EXTRA_OPTS: --on-unsigned=ignore - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip + FCLI_BOOTSTRAP_VERSION: v3.15.0 # Defaults to latest v3.x.y, pin to specific version for stability + - name: Run custom fcli commands + run: | + fcli fod session login ... + # Your custom workflow here + fcli fod session logout ... ``` -### Action inputs - -This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. - -| Action input | Description | -| :--- | :--- | -| 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. | - -### Action environment variable inputs - -This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - -| Environment variable | Description | -| :--- | :--- | -|**SSC_URL**|Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets.| -|**SSC_TOKEN**|Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`.| -|**SSC_USER
SSC_PASSWORD**|Required when authenticating with SSC user credentials.| -|**SC_SAST_TOKEN**|ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. This environment variable is required when running a ScanCentral SAST scan.| -|SSC_LOGIN_EXTRA_OPTS
EXTRA_SSC_LOGIN_OPTS|Extra SSC login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli ssc session login` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-ssc-session-login.html). Note that `EXTRA_SSC_LOGIN_OPTS` is deprecated; please use `SSC_LOGIN_EXTRA_OPTS`.| -|**DEBRICKED_TOKEN**|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.| -|SSC_APPVERSION|Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`.| -|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the SSC application version will be automatically created if they do not yet exist, using the fcli-provided [`setup-appversion`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_setup_appversion) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy state from an existing application version using the `--copy-from` option, or to allow an unsigned custom action to be used. Note that if setup is enabled, `SSC_APPVERSION` must be configured with a qualified application version name; you cannot use application version id. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.| -| SC_CLIENT_VERSION | By default, this action uses ScanCentral Client 25.4.0 for packaging. This environment variable allows for overriding the ScanCentral Client version used for packaging. | -|DO_PACKAGE_DEBUG| If set to true, this will enable the `-debug` option on the `scancentral` command, and store both ScanCentral logs and the `package.zip` file as job artifacts.| -|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2540/sc-sast-ugd-html-25.4.0/doc/2404_25.4/home.html) for more information on available options. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| -|SC_SAST_SENSOR_VERSION|Version of the ScanCentral SAST sensor on which the scan should be performed; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-sc-sast-scan-start.html) for details.| -|SC_SAST_SCAN_EXTRA_OPTS
EXTRA_SC_SAST_SCAN_OPTS|Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-sc-sast-scan-start.html). Note that `EXTRA_SC_SAST_SCAN_OPTS` is deprecated; please use `SC_SAST_SCAN_EXTRA_OPTS`.| -| DO_WAIT | By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating job summaries. This behavior is documented in the applicable environment variable descriptions. | -|DO_POLICY_CHECK
CHECK_POLICY_ACTION
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 [SSC `check-policy`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. 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. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.| -|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
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`), a job summary listing scan status and issue counts will be generated using the fcli-provided [SSC `appversion-summary`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_appversion_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. 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 or to specify an SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details. | -| DO_EXPORT
EXPORT_ACTION
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 GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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 or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.

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. | -|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
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`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [SSC `github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. 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 or to specify a different SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) and [SSC Pull Request Comments](#ssc-pull-request-comments) sections below for more details.| -| TOOL_DEFINITIONS | 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. | - - - - -### SSC Fcli Actions - - - - - - -As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - -For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v3.13.1/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - - - - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--av` / `--appversion` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the SSC application version to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. - - - - - - - -### SSC Pull Request Comments - - - -This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [SSC `github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/ssc-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. - -**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - -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; 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 `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_SETUP` to `true`, to allow a branch-specific application version to be automatically created. -- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the application version that represents the PR target branch or your main branch into the newly created application version. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version named `/:`. -- Copy state from the application version identified by the `--copy-from` option to this new application version. -- Run a new scan of the branch associated with the current PR, and upload results to the application version 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 application version 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, 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. +### Detailed Documentation - +Given that these GitHub Actions are just thin wrappers around `@fortify/setup` and `fcli`, detailed usage documentation is available on the fcli documentation website: +* [`fortify/github-action` for OpenText Application Security Code (Fortify on Demand)](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/ast-action-fod.html) +* [`fortify/github-action` for OpenText Software Security Center (Fortify SSC)](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/ast-action-ssc.html) +* [`fortify/github-action/setup`](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/setup-action.html) + -## Building blocks for custom workflows -This GitHub Action provides a lot of flexibility with regards to what operations to run as controlled through the various `DO_*` environment variables, and also allows for customizing some of these operations by utilizing custom fcli actions through the `*_ACTION` environment variables. However, there may be situations where the standard workflow provided by this GitHub Action doesn't meet your needs, for example if you need to run Dynamic or Mobile scans. + -The modular implementation of this GitHub Action allows for implementing custom workflows based on the various re-usable sub-actions available in this repository. The following sub-actions that can be used as building blocks for custom workflows are currently available for public use: -| Action | Description | -| :--- | :--- | -| [fortify/github‑action/setup](https://github.com/fortify/github-action/tree/v2/setup#readme) | This sub-action allows for installing various Fortify tools like fcli or ScanCentral Client for later use in your GitHub Actions workflow. This allows for implementing fully customized workflows that can easily utilize the various Fortify tools to interact with Fortify products and Debricked. | -| [fortify/github‑action/package](https://github.com/fortify/github-action/tree/v2/package#readme) | This sub-action can be used to easily package your source code for static scans, with the action handling low-level details like installation of ScanCentral Client and required Java version. | -| [fortify/github‑action/fod‑export](https://github.com/fortify/github-action/tree/v2/fod-export#readme) | This sub-action allows for exporting vulnerability data from Fortify on Demand to the GitHub Security dashboard, with the action handling low-level details like installing the necessary Fortify tools, exporting the vulnerability data, and uploading this data to GitHub. | -| [fortify/github‑action/ssc‑export](https://github.com/fortify/github-action/tree/v2/ssc-export#readme) | This sub-action allows for exporting vulnerability data from SSC to the GitHub Security dashboard, with the action handling low-level details like installing the necessary Fortify tools, exporting the vulnerability data, and uploading this data to GitHub. | +## Resources -The `fortify/github-action` repository also provides the publicly available sub-actions listed in the table below, but these provide the full scan workflows as provided by this GitHub Action, with the top-level `fortify/github-action` simply invoking one of these sub-actions based on action inputs and environment variables. As such, these sub-actions are not meant to provide re-usable building blocks, but it may be useful to look at the implementations of these sub-actions if you want to re-use any of their functionality in your custom workflows. -| Action | Description | -| :--- | :--- | -| [fortify/github‑action/fod‑sast‑scan](https://github.com/fortify/github-action/tree/v2/fod-sast-scan#readme) | Run a Fortify on Demand SAST scan. | -| [fortify/github‑action/sc‑sast‑scan](https://github.com/fortify/github-action/tree/v2/sc-sast-scan#readme) | Run a ScanCentral SAST scan and optional Debricked scan. | -| [fortify/github‑action/ssc‑debricked‑scan](https://github.com/fortify/github-action/tree/v2/ssc-debricked-scan#readme) | Run a Debricked-only scan and import scan results into SSC. | + -These actions utilize the re-usable building blocks mentioned above, in combination with several sub-actions that are meant for internal use only. However, the source code of these internal-only sub-actions is publicly available, allowing you to gain a better understanding of how these are used to implement the functionality provided by `fortify/github-action` and potentially re-use some of the ideas or code in your custom workflows. In particular, the `bash` scripts provided by the [`fortify/github-action/internal/run-script`](https://github.com/fortify/github-action/tree/v2/internal/run-script/scripts) provide some of the core functionality provided by this GitHub Action. +* **Contributing Guidelines**: [CONTRIBUTING.md](CONTRIBUTING.md) +* **Code of Conduct**: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) +* **License**: [LICENSE.txt](LICENSE.txt) - + @@ -356,4 +145,4 @@ You may also consider raising questions or issues through the [GitHub Issues pag --- -*[This document was auto-generated; do not edit by hand](https://github.com/fortify/shared-doc-resources/blob/main/USAGE.md)* +*[This document was auto-generated from README.template.md; do not edit by hand](https://github.com/fortify/shared-doc-resources/blob/main/USAGE.md)* diff --git a/USAGE.md b/USAGE.md index 2058021..d97f35c 100644 --- a/USAGE.md +++ b/USAGE.md @@ -3,7 +3,102 @@ ## Usage instructions -Please see the README.md file for usage instructions. + + + +### Quick Start + +#### OpenText Core Application Security (Fortify on Demand) + +```yaml +name: Fortify on Demand Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans + env: + FOD_URL: ${{ vars.FOD_URL }} + FOD_CLIENT_ID: ${{ secrets.FOD_CLIENT_ID }} + FOD_CLIENT_SECRET: ${{ secrets.FOD_CLIENT_SECRET }} + # FOD_RELEASE: MyApp:main # Optional: defaults to repo:branch + # FCLI_BOOTSTRAP_VERSION: v3.15 # Optional if you prefer stability over latest +``` + +#### OpenText Application Security (Fortify Software Security Center) + +```yaml +name: Fortify SSC Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans + env: + SSC_URL: ${{ vars.SSC_URL }} + SSC_TOKEN: ${{ secrets.SSC_TOKEN }} + SC_SAST_TOKEN: ${{ secrets.SC_SAST_TOKEN }} + # SSC_APPVERSION: MyApp:main # Optional: defaults to repo:branch +``` + +#### Custom workflow + +```yaml +name: Custom Fortify Workflow +on: [push] + +jobs: + custom-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: fortify/github-action/setup@v3 + with: + fcli: bootstrapped # Set up bootstrapped fcli version. May also specify specific version, but + # then fcli may be downloaded twice (bootstrap version and requested version). + env: + FCLI_BOOTSTRAP_VERSION: v3.15.0 # Defaults to latest v3.x.y, pin to specific version for stability + - name: Run custom fcli commands + run: | + fcli fod session login ... + # Your custom workflow here + fcli fod session logout ... +``` + +### Detailed Documentation + +Given that these GitHub Actions are just thin wrappers around `@fortify/setup` and `fcli`, detailed usage documentation is available on the fcli documentation website: + +* [`fortify/github-action` for OpenText Application Security Code (Fortify on Demand)](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/ast-action-fod.html) +* [`fortify/github-action` for OpenText Software Security Center (Fortify SSC)](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/ast-action-ssc.html) +* [`fortify/github-action/setup`](https://fortify.github.io/fcli/v3/ci/github/v3.0.x/setup-action.html) + + + diff --git a/action.yml b/action.yml index f99c9db..090d6a1 100644 --- a/action.yml +++ b/action.yml @@ -2,27 +2,43 @@ name: 'Fortify AST Scan' description: 'Find and fix vulnerabilities to build secure software with Fortify Code Security.' author: 'Fortify' inputs: - sast-scan: - description: 'Run a SAST scan, takes either true or false (default)' - default: 'false' + debug: + description: 'Whether to generate and collect debug logs; note that these may contain sensitive data like access tokens or credentials. Automatically enabled when workflow is re-run with "Enable debug logging" checked.' required: false - debricked-sca-scan: - description: 'Run a Debricked Software Composition Analysis, takes either true or false (default)' default: 'false' + debug-artifact-name: + description: 'Name for the debug artifacts archive; defaults to "fortify-debug-logs"' + required: false + default: 'fortify-debug-logs' + debug-retention-days: + description: 'Number of days to retain debug artifacts; defaults to 1' required: false + default: '1' runs: using: composite steps: - - uses: fortify/github-action/fod-sast-scan@main - if: inputs['sast-scan']=='true' && env.FOD_URL - env: - DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }} - - uses: fortify/github-action/sc-sast-scan@main - if: inputs['sast-scan']=='true' && env.SSC_URL + - name: Set Fortify data directory + run: echo "FORTIFY_DATA_DIR=${{ runner.temp }}/fortify-data" >> $GITHUB_ENV + shell: bash + - uses: fortify/github-action/setup@feat/fcli-ci + with: + fcli: bootstrapped + export-path: false + - run: | + mkdir -p "${FORTIFY_DATA_DIR}" && cd "${FORTIFY_DATA_DIR}" + "${FCLI_CMD}" action run ci --debug=${{ inputs.debug == 'true' || runner.debug == '1' }} + shell: bash env: - DO_DEBRICKED_SCAN: ${{ inputs['debricked-sca-scan'] }} - - uses: fortify/github-action/ssc-debricked-scan@main - if: inputs['sast-scan']=='false' && inputs['debricked-sca-scan']=='true' && env.SSC_URL + GITHUB_TOKEN: ${{ github.token }} + SAST_EXPORT_EXTRA_OPTS: --publish=true ${{ env.SAST_EXPORT_EXTRA_OPTS || '' }} + DEBRICKED_EXPORT_EXTRA_OPTS: --publish=true ${{ env.DEBRICKED_EXPORT_EXTRA_OPTS || '' }} + - name: Upload debug logs + if: ${{ always() && (inputs.debug == 'true' || runner.debug == '1') }} + uses: actions/upload-artifact@v4 + with: + name: ${{ inputs.debug-artifact-name }}-${{ github.job }} + path: ${{ env.FORTIFY_DATA_DIR }} + retention-days: ${{ inputs.debug-retention-days }} branding: icon: 'shield' diff --git a/doc-resources/action/_generic/debricked/nocomments.env-debricked-token.md b/doc-resources/action/_generic/debricked/nocomments.env-debricked-token.md deleted file mode 100644 index 8215029..0000000 --- a/doc-resources/action/_generic/debricked/nocomments.env-debricked-token.md +++ /dev/null @@ -1 +0,0 @@ -|**DEBRICKED_TOKEN**|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.| \ No newline at end of file diff --git a/doc-resources/action/_generic/debricked/nocomments.snippet-debricked-token.md b/doc-resources/action/_generic/debricked/nocomments.snippet-debricked-token.md deleted file mode 100644 index a9eb261..0000000 --- a/doc-resources/action/_generic/debricked/nocomments.snippet-debricked-token.md +++ /dev/null @@ -1 +0,0 @@ - DEBRICKED_TOKEN: ${{secrets.DEBRICKED_TOKEN}} \ No newline at end of file diff --git a/doc-resources/action/_generic/fcli-actions.md b/doc-resources/action/_generic/fcli-actions.md deleted file mode 100644 index ba1edee..0000000 --- a/doc-resources/action/_generic/fcli-actions.md +++ /dev/null @@ -1,4 +0,0 @@ -As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - -For more information on fcli actions and custom action development, please see the [fcli action documentation]({{var:fcli-doc-base-url}}#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - diff --git a/doc-resources/action/_generic/fod/fod-fcli-actions.md b/doc-resources/action/_generic/fod/fod-fcli-actions.md deleted file mode 100644 index 645e8db..0000000 --- a/doc-resources/action/_generic/fod/fod-fcli-actions.md +++ /dev/null @@ -1,9 +0,0 @@ -### Fortify on Demand Fcli Actions - - - -{{include:action/_generic/fcli-actions.md}} - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. diff --git a/doc-resources/action/_generic/fod/fod-pr.md b/doc-resources/action/_generic/fod/fod-pr.md deleted file mode 100644 index 28be975..0000000 --- a/doc-resources/action/_generic/fod/fod-pr.md +++ /dev/null @@ -1,27 +0,0 @@ -### Fortify on Demand Pull Request Comments - - - -This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [`github-pr-comment`]({{var:fcli-doc-base-url}}fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. - -**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - -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 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`, to use the default value that corresponds to repository and branch name. -- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. -- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application release named `/:`. -- Copy state from the application release identified by the `--copy-from` option to this new application release. -- Run a new scan of the branch associated with the current PR, and upload results to the application 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 application 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 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. diff --git a/doc-resources/action/_generic/fod/nocomments.env-fod-login.md b/doc-resources/action/_generic/fod/nocomments.env-fod-login.md deleted file mode 100644 index 63c7a95..0000000 --- a/doc-resources/action/_generic/fod/nocomments.env-fod-login.md +++ /dev/null @@ -1,4 +0,0 @@ -| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to Fortify on Demand to be rendered incorrectly, for example in GitHub Action job summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | -| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: Fortify on Demand Client ID (API key) and Secret (API secret). | -| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: Fortify on Demand tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | -| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | Extra login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/_generic/fod/nocomments.env-fod-release.md b/doc-resources/action/_generic/fod/nocomments.env-fod-release.md deleted file mode 100644 index a19db74..0000000 --- a/doc-resources/action/_generic/fod/nocomments.env-fod-release.md +++ /dev/null @@ -1 +0,0 @@ -| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | \ No newline at end of file diff --git a/doc-resources/action/_generic/fod/nocomments.snippet-fod-login.md b/doc-resources/action/_generic/fod/nocomments.snippet-fod-login.md deleted file mode 100644 index c797136..0000000 --- a/doc-resources/action/_generic/fod/nocomments.snippet-fod-login.md +++ /dev/null @@ -1,7 +0,0 @@ - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_CLIENT_ID: ${{secrets.FOD_CLIENT_ID}} - # FOD_CLIENT_SECRET: ${{secrets.FOD_CLIENT_SECRET}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/action/_generic/fod/nocomments.snippet-fod-release.md b/doc-resources/action/_generic/fod/nocomments.snippet-fod-release.md deleted file mode 100644 index a82a186..0000000 --- a/doc-resources/action/_generic/fod/nocomments.snippet-fod-release.md +++ /dev/null @@ -1 +0,0 @@ - # FOD_RELEASE: MyApp:MyRelease \ No newline at end of file diff --git a/doc-resources/action/_generic/fod/nocomments.snippet-fod-setup.md b/doc-resources/action/_generic/fod/nocomments.snippet-fod-setup.md deleted file mode 100644 index f569369..0000000 --- a/doc-resources/action/_generic/fod/nocomments.snippet-fod-setup.md +++ /dev/null @@ -1,3 +0,0 @@ - # DO_SETUP: true - # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml - # SETUP_EXTRA_OPTS: --copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}" \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.env-do-wait.md b/doc-resources/action/_generic/nocomments.env-do-wait.md deleted file mode 100644 index 4b06081..0000000 --- a/doc-resources/action/_generic/nocomments.env-do-wait.md +++ /dev/null @@ -1 +0,0 @@ -| DO_WAIT | By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating job summaries. This behavior is documented in the applicable environment variable descriptions. | diff --git a/doc-resources/action/_generic/nocomments.env-section-and-table-header.md b/doc-resources/action/_generic/nocomments.env-section-and-table-header.md deleted file mode 100644 index 1c75e09..0000000 --- a/doc-resources/action/_generic/nocomments.env-section-and-table-header.md +++ /dev/null @@ -1,5 +0,0 @@ -### Action environment variable inputs - -This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - -{{include:action/_generic/nocomments.env-table-header.md}} \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.env-table-header.md b/doc-resources/action/_generic/nocomments.env-table-header.md deleted file mode 100644 index e988eb5..0000000 --- a/doc-resources/action/_generic/nocomments.env-table-header.md +++ /dev/null @@ -1,2 +0,0 @@ -| Environment variable | Description | -| :--- | :--- | \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.input-section-and-table-header.md b/doc-resources/action/_generic/nocomments.input-section-and-table-header.md deleted file mode 100644 index dbd602d..0000000 --- a/doc-resources/action/_generic/nocomments.input-section-and-table-header.md +++ /dev/null @@ -1,5 +0,0 @@ -### Action inputs - -This section lists the inputs that can be specified in the `with:` clause for this GitHub Action. Any inputs marked in **bold** are required. - -{{include:action/_generic/nocomments.input-table-header.md}} \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.input-table-header.md b/doc-resources/action/_generic/nocomments.input-table-header.md deleted file mode 100644 index 2397370..0000000 --- a/doc-resources/action/_generic/nocomments.input-table-header.md +++ /dev/null @@ -1,2 +0,0 @@ -| Action input | Description | -| :--- | :--- | \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-do-wait.md b/doc-resources/action/_generic/nocomments.snippet-do-wait.md deleted file mode 100644 index cd0477d..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-do-wait.md +++ /dev/null @@ -1 +0,0 @@ - # DO_WAIT: true \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-export-optional.md b/doc-resources/action/_generic/nocomments.snippet-export-optional.md deleted file mode 100644 index f087cce..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-export-optional.md +++ /dev/null @@ -1,2 +0,0 @@ - # DO_EXPORT: true -{{include:action/_generic/nocomments.snippet-export.md}} \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-export.md b/doc-resources/action/_generic/nocomments.snippet-export.md deleted file mode 100644 index 49399f8..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-export.md +++ /dev/null @@ -1,2 +0,0 @@ - # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml - # EXPORT_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-job-summary.md b/doc-resources/action/_generic/nocomments.snippet-job-summary.md deleted file mode 100644 index 78a89d3..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-job-summary.md +++ /dev/null @@ -1,3 +0,0 @@ - # DO_JOB_SUMMARY: true - # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml - # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-policy-check.md b/doc-resources/action/_generic/nocomments.snippet-policy-check.md deleted file mode 100644 index 37af8fd..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-policy-check.md +++ /dev/null @@ -1,3 +0,0 @@ - # DO_POLICY_CHECK: true - # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml - # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-pr-comment.md b/doc-resources/action/_generic/nocomments.snippet-pr-comment.md deleted file mode 100644 index c5b682d..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-pr-comment.md +++ /dev/null @@ -1,3 +0,0 @@ - # DO_PR_COMMENT: true - # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml - # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/_generic/nocomments.snippet-setup.md b/doc-resources/action/_generic/nocomments.snippet-setup.md deleted file mode 100644 index 58aa83e..0000000 --- a/doc-resources/action/_generic/nocomments.snippet-setup.md +++ /dev/null @@ -1,3 +0,0 @@ - # DO_SETUP: true - # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml - # SETUP_EXTRA_OPTS: --on-unsigned=ignore \ No newline at end of file diff --git a/doc-resources/action/_generic/prerequisites-h2.md b/doc-resources/action/_generic/prerequisites-h2.md deleted file mode 100644 index ad92744..0000000 --- a/doc-resources/action/_generic/prerequisites-h2.md +++ /dev/null @@ -1,3 +0,0 @@ -## Prerequisites - -{{include:action/_generic/prerequisites.md}} \ No newline at end of file diff --git a/doc-resources/action/_generic/prerequisites-h3.md b/doc-resources/action/_generic/prerequisites-h3.md deleted file mode 100644 index 3b1563b..0000000 --- a/doc-resources/action/_generic/prerequisites-h3.md +++ /dev/null @@ -1,3 +0,0 @@ -### Prerequisites - -{{include:action/_generic/prerequisites.md}} \ No newline at end of file diff --git a/doc-resources/action/_generic/prerequisites.md b/doc-resources/action/_generic/prerequisites.md deleted file mode 100644 index 5220ca8..0000000 --- a/doc-resources/action/_generic/prerequisites.md +++ /dev/null @@ -1,6 +0,0 @@ -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` \ No newline at end of file diff --git a/doc-resources/action/_generic/ssc/nocomments.env-ssc-appversion.md b/doc-resources/action/_generic/ssc/nocomments.env-ssc-appversion.md deleted file mode 100644 index 7729d07..0000000 --- a/doc-resources/action/_generic/ssc/nocomments.env-ssc-appversion.md +++ /dev/null @@ -1 +0,0 @@ -|SSC_APPVERSION|Fortify SSC application version to use with this action. This can be specified either as a numeric application version id, or by providing application and version name in the format `:`. Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`.| \ No newline at end of file diff --git a/doc-resources/action/_generic/ssc/nocomments.env-ssc-login.md b/doc-resources/action/_generic/ssc/nocomments.env-ssc-login.md deleted file mode 100644 index 2155134..0000000 --- a/doc-resources/action/_generic/ssc/nocomments.env-ssc-login.md +++ /dev/null @@ -1,5 +0,0 @@ -|**SSC_URL**|Fortify Software Security Center URL, for example https://ssc.customer.fortifyhosted.net/. Note: Using GitHub Secrets to define this URL may cause links back to SSC to be rendered incorrectly, for example in GitHub Action workflow summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets.| -|**SSC_TOKEN**|Required when authenticating with an SSC token (recommended). Most actions should work fine with a `CIToken`.| -|**SSC_USER
SSC_PASSWORD**|Required when authenticating with SSC user credentials.| -|**SC_SAST_TOKEN**|ScanCentral SAST Client Authentication Token for authenticating with ScanCentral SAST Controller. This environment variable is required when running a ScanCentral SAST scan.| -|SSC_LOGIN_EXTRA_OPTS
EXTRA_SSC_LOGIN_OPTS|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). Note that `EXTRA_SSC_LOGIN_OPTS` is deprecated; please use `SSC_LOGIN_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-appversion.md b/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-appversion.md deleted file mode 100644 index 903c00e..0000000 --- a/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-appversion.md +++ /dev/null @@ -1 +0,0 @@ - # SSC_APPVERSION: MyApp:MyVersion \ No newline at end of file diff --git a/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-login.md b/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-login.md deleted file mode 100644 index 52e504c..0000000 --- a/doc-resources/action/_generic/ssc/nocomments.snippet-ssc-login.md +++ /dev/null @@ -1,4 +0,0 @@ - SSC_URL: ${{vars.SSC_URL}} - SSC_TOKEN: ${{secrets.SSC_TOKEN}} - SC_SAST_TOKEN: ${{secrets.SC_SAST_CLIENT_AUTH_TOKEN}} - # SSC_LOGIN_EXTRA_OPTS: --socket-timeout=60s \ No newline at end of file diff --git a/doc-resources/action/_generic/ssc/ssc-fcli-actions.md b/doc-resources/action/_generic/ssc/ssc-fcli-actions.md deleted file mode 100644 index 3db9565..0000000 --- a/doc-resources/action/_generic/ssc/ssc-fcli-actions.md +++ /dev/null @@ -1,9 +0,0 @@ -### SSC Fcli Actions - - - -{{include:action/_generic/fcli-actions.md}} - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--av` / `--appversion` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the SSC application version to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. diff --git a/doc-resources/action/_generic/ssc/ssc-pr.md b/doc-resources/action/_generic/ssc/ssc-pr.md deleted file mode 100644 index a8a9024..0000000 --- a/doc-resources/action/_generic/ssc/ssc-pr.md +++ /dev/null @@ -1,27 +0,0 @@ -### SSC Pull Request Comments - - - -This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [SSC `github-pr-comment`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. - -**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - -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; 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 `SSC_APPVERSION`, to use the default value that corresponds to repository and branch name. -- Set `DO_SETUP` to `true`, to allow a branch-specific application version to be automatically created. -- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the application version that represents the PR target branch or your main branch into the newly created application version. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application version named `/:`. -- Copy state from the application version identified by the `--copy-from` option to this new application version. -- Run a new scan of the branch associated with the current PR, and upload results to the application version 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 application version 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, 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. diff --git a/doc-resources/action/_root/readme.md b/doc-resources/action/_root/readme.md deleted file mode 100644 index 7e1b393..0000000 --- a/doc-resources/action/_root/readme.md +++ /dev/null @@ -1,136 +0,0 @@ -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-sscscancentral) -* [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 Fortify on Demand SAST & SCA Scan - uses: fortify/github-action@{{var:action-major-version}} - with: - sast-scan: true - debricked-sca-scan: true - env: -{{include:action/_generic/fod/nocomments.snippet-fod-login.md}} -{{include:action/_generic/fod/nocomments.snippet-fod-release.md}} -{{include:action/_generic/fod/nocomments.snippet-fod-setup.md}} -{{include:action/package/nocomments.snippet-sc-client-version.md}} -{{include:action/package/nocomments.snippet-package-extra-opts.md}} -{{include:action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md}} -{{include:action/_generic/nocomments.snippet-do-wait.md}} -{{include:action/_generic/nocomments.snippet-policy-check.md}} -{{include:action/_generic/nocomments.snippet-job-summary.md}} -{{include:action/_generic/nocomments.snippet-pr-comment.md}} -{{include:action/_generic/nocomments.snippet-export-optional.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.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`, 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 Fortify on Demand 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 Fortify on Demand scan configuration. Note that any existing scan configuration will not be updated, so if the scan has already been configured in Fortify on Demand, an open-source scan will only be performed if previously enabled in the existing scan configuration. | - -{{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-sast-scan/nocomments.env-setup.md}} -{{include:action/package/nocomments.env-sc-client-version.md}} -{{include:action/package/nocomments.env-package-extra-opts.md}} -{{include:action/fod-sast-scan/nocomments.env-fod-sast-scan.md}} -{{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-optional.md}} -{{include:action/fod-sast-scan/nocomments.env-pr-comment.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/fod/fod-fcli-actions.md}} - -{{include:action/_generic/fod/fod-pr.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 ScanCentral SAST & Debricked scan - uses: fortify/github-action@{{var:action-major-version}} - with: - sast-scan: true - debricked-sca-scan: true - env: -{{include:action/_generic/ssc/nocomments.snippet-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.snippet-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.snippet-ssc-appversion.md}} -{{include:action/_generic/nocomments.snippet-setup.md}} -{{include:action/package/nocomments.snippet-sc-client-version.md}} -{{include:action/package/nocomments.snippet-package-extra-opts.md}} -{{include:action/sc-sast-scan/nocomments.snippet-sc-sast-scan.md}} -{{include:action/_generic/nocomments.snippet-do-wait.md}} -{{include:action/_generic/nocomments.snippet-policy-check.md}} -{{include:action/_generic/nocomments.snippet-job-summary.md}} -{{include:action/_generic/nocomments.snippet-pr-comment.md}} -{{include:action/_generic/nocomments.snippet-export-optional.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.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}} -{{include:action/_generic/ssc/nocomments.env-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.env-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-appversion.md}} -{{include:action/sc-sast-scan/nocomments.env-setup.md}} -{{include:action/package/nocomments.env-sc-client-version.md}} -{{include:action/package/nocomments.env-package-extra-opts.md}} -{{include:action/sc-sast-scan/nocomments.env-sc-sast-scan.md}} -{{include:action/_generic/nocomments.env-do-wait.md}} -{{include:action/sc-sast-scan/nocomments.env-policy-check.md}} -{{include:action/sc-sast-scan/nocomments.env-job-summary.md}} -{{include:action/ssc-export/nocomments.env-export-optional.md}} -{{include:action/sc-sast-scan/nocomments.env-pr-comment.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/ssc/ssc-fcli-actions.md}} - -{{include:action/_generic/ssc/ssc-pr.md}} - - -## Building blocks for custom workflows - -This GitHub Action provides a lot of flexibility with regards to what operations to run as controlled through the various `DO_*` environment variables, and also allows for customizing some of these operations by utilizing custom fcli actions through the `*_ACTION` environment variables. However, there may be situations where the standard workflow provided by this GitHub Action doesn't meet your needs, for example if you need to run Dynamic or Mobile scans. - -The modular implementation of this GitHub Action allows for implementing custom workflows based on the various re-usable sub-actions available in this repository. The following sub-actions that can be used as building blocks for custom workflows are currently available for public use: - -| Action | Description | -| :--- | :--- | -| [fortify/github‑action/setup]({{var:repo-url}}/tree/{{var:action-major-version}}/setup#readme) | This sub-action allows for installing various Fortify tools like fcli or ScanCentral Client for later use in your GitHub Actions workflow. This allows for implementing fully customized workflows that can easily utilize the various Fortify tools to interact with Fortify products and Debricked. | -| [fortify/github‑action/package]({{var:repo-url}}/tree/{{var:action-major-version}}/package#readme) | This sub-action can be used to easily package your source code for static scans, with the action handling low-level details like installation of ScanCentral Client and required Java version. | -| [fortify/github‑action/fod‑export]({{var:repo-url}}/tree/{{var:action-major-version}}/fod-export#readme) | This sub-action allows for exporting vulnerability data from Fortify on Demand to the GitHub Security dashboard, with the action handling low-level details like installing the necessary Fortify tools, exporting the vulnerability data, and uploading this data to GitHub. | -| [fortify/github‑action/ssc‑export]({{var:repo-url}}/tree/{{var:action-major-version}}/ssc-export#readme) | This sub-action allows for exporting vulnerability data from SSC to the GitHub Security dashboard, with the action handling low-level details like installing the necessary Fortify tools, exporting the vulnerability data, and uploading this data to GitHub. | - -The `fortify/github-action` repository also provides the publicly available sub-actions listed in the table below, but these provide the full scan workflows as provided by this GitHub Action, with the top-level `fortify/github-action` simply invoking one of these sub-actions based on action inputs and environment variables. As such, these sub-actions are not meant to provide re-usable building blocks, but it may be useful to look at the implementations of these sub-actions if you want to re-use any of their functionality in your custom workflows. - -| Action | Description | -| :--- | :--- | -| [fortify/github‑action/fod‑sast‑scan]({{var:repo-url}}/tree/{{var:action-major-version}}/fod-sast-scan#readme) | Run a Fortify on Demand SAST scan. | -| [fortify/github‑action/sc‑sast‑scan]({{var:repo-url}}/tree/{{var:action-major-version}}/sc-sast-scan#readme) | Run a ScanCentral SAST scan and optional Debricked scan. | -| [fortify/github‑action/ssc‑debricked‑scan]({{var:repo-url}}/tree/{{var:action-major-version}}/ssc-debricked-scan#readme) | Run a Debricked-only scan and import scan results into SSC. | - -These actions utilize the re-usable building blocks mentioned above, in combination with several sub-actions that are meant for internal use only. However, the source code of these internal-only sub-actions is publicly available, allowing you to gain a better understanding of how these are used to implement the functionality provided by `fortify/github-action` and potentially re-use some of the ideas or code in your custom workflows. In particular, the `bash` scripts provided by the [`fortify/github-action/internal/run-script`]({{var:repo-url}}/tree/{{var:action-major-version}}/internal/run-script/scripts) provide some of the core functionality provided by this GitHub Action. diff --git a/doc-resources/action/fod-export/nocomments.env-export-optional.md b/doc-resources/action/fod-export/nocomments.env-export-optional.md deleted file mode 100644 index 5b2170c..0000000 --- a/doc-resources/action/fod-export/nocomments.env-export-optional.md +++ /dev/null @@ -1 +0,0 @@ -| DO_EXPORT
EXPORT_ACTION
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`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [`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`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.

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. | \ No newline at end of file diff --git a/doc-resources/action/fod-export/nocomments.env-export.md b/doc-resources/action/fod-export/nocomments.env-export.md deleted file mode 100644 index ae4b6cb..0000000 --- a/doc-resources/action/fod-export/nocomments.env-export.md +++ /dev/null @@ -1 +0,0 @@ -| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [`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`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action/fod-export/readme.md b/doc-resources/action/fod-export/readme.md deleted file mode 100644 index f07c9f3..0000000 --- a/doc-resources/action/fod-export/readme.md +++ /dev/null @@ -1,26 +0,0 @@ -This action exports the latest vulnerability data from a Fortify on Demand 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/_generic/prerequisites-h3.md}} - -### Sample usage - -The sample workflow below demonstrates how to configure the action for exporting Fortify on Demand SAST vulnerability data to the GitHub Security Code Scanning dashboard. - -```yaml - steps: - - name: Export Fortify on Demand vulnerability data to GitHub - uses: fortify/github-action/fod-export@{{var:action-major-version}} - env: -{{include:action/_generic/fod/nocomments.snippet-fod-login.md}} -{{include:action/_generic/fod/nocomments.snippet-fod-release.md}} -{{include:action/_generic/nocomments.snippet-export.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}} - -{{include:action/_generic/fod/fod-fcli-actions.md}} \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md deleted file mode 100644 index 7517f74..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.env-fod-sast-scan.md +++ /dev/null @@ -1 +0,0 @@ -|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra 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`.| diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md b/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md deleted file mode 100644 index 6d7cf41..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.env-job-summary.md +++ /dev/null @@ -1 +0,0 @@ -|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
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`), a job summary listing scan status and issue counts will be generated using the fcli-provided [`release-summary`]({{var:fcli-doc-base-url}}fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md b/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md deleted file mode 100644 index 0a4f8b2..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.env-policy-check.md +++ /dev/null @@ -1 +0,0 @@ -|DO_POLICY_CHECK
CHECK_POLICY_ACTION
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 [`check-policy`]({{var:fcli-doc-base-url}}fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md b/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md deleted file mode 100644 index f5ade17..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.env-pr-comment.md +++ /dev/null @@ -1 +0,0 @@ -|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
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`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [`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`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) and [Pull Request Comments](#fortify-on-demand-pull-request-comments) sections below for more details.| diff --git a/doc-resources/action/fod-sast-scan/nocomments.env-setup.md b/doc-resources/action/fod-sast-scan/nocomments.env-setup.md deleted file mode 100644 index 58c0163..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.env-setup.md +++ /dev/null @@ -1 +0,0 @@ -|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [`setup-release`]({{var:fcli-doc-base-url}}fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable. Depending on your Git workflow, it is recommended to have each newly created release copy state from the release representing your default branch by passing `--copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}"` through `SETUP_EXTRA_OPTS`. To allow the GitHub Action to create new applications, you must (also) provide the `--app-owner ` option through `SETUP_EXTRA_OPTS` if authenticating with client credentials. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md b/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md deleted file mode 100644 index a4220d4..0000000 --- a/doc-resources/action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md +++ /dev/null @@ -1 +0,0 @@ - # FOD_SAST_SCAN_EXTRA_OPTS: \ No newline at end of file diff --git a/doc-resources/action/fod-sast-scan/readme.md b/doc-resources/action/fod-sast-scan/readme.md deleted file mode 100644 index fca1b5a..0000000 --- a/doc-resources/action/fod-sast-scan/readme.md +++ /dev/null @@ -1,57 +0,0 @@ -This action performs a SAST scan on Fortify on Demand. If software composition analysis of open source has been purchased and configured on the applicable release, this action can be used to perform a combined SAST and SCA (open source) scan. - -The SAST and optional open source scan performed by this action consists of the following steps: - -* Login to Fortify on Demand -* Package application source code using ScanCentral Client -* Submit the source code package to be scanned to Fortify on Demand -* Optionally wait for the scan to complete -* Optionally export scan results to the GitHub Code Scanning dashboard - -{{include:action/_generic/prerequisites-h3.md}} - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on Fortify on Demand. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Fortify on Demand SAST Scan - uses: fortify/github-action/fod-sast-scan@{{var:action-major-version}} - env: -{{include:action/_generic/fod/nocomments.snippet-fod-login.md}} -{{include:action/_generic/fod/nocomments.snippet-fod-release.md}} -{{include:action/_generic/fod/nocomments.snippet-fod-setup.md}} -{{include:action/package/nocomments.snippet-sc-client-version.md}} -{{include:action/package/nocomments.snippet-package-extra-opts.md}} -{{include:action/fod-sast-scan/nocomments.snippet-fod-sast-scan.md}} - # DO_DEBRICKED_SCAN: true -{{include:action/_generic/nocomments.snippet-do-wait.md}} -{{include:action/_generic/nocomments.snippet-policy-check.md}} -{{include:action/_generic/nocomments.snippet-job-summary.md}} -{{include:action/_generic/nocomments.snippet-pr-comment.md}} -{{include:action/_generic/nocomments.snippet-export-optional.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-sast-scan/nocomments.env-setup.md}} -{{include:action/package/nocomments.env-sc-client-version.md}} -{{include:action/package/nocomments.env-package-extra-opts.md}} -{{include:action/fod-sast-scan/nocomments.env-fod-sast-scan.md}} -|DO_DEBRICKED_SCAN|Configure the static scan to also run an open-source scan. Depending on Fortify on Demand 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 Fortify on Demand scan configuration. Note that any existing scan configuration will not be updated, so if the scan has already been configured in Fortify on Demand, an open-source scan will only be performed if previously enabled in the existing scan configuration.| -{{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-optional.md}} -{{include:action/fod-sast-scan/nocomments.env-pr-comment.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/fod/fod-fcli-actions.md}} - -{{include:action/_generic/fod/fod-pr.md}} diff --git a/doc-resources/action/package/nocomments.env-package-extra-opts.md b/doc-resources/action/package/nocomments.env-package-extra-opts.md deleted file mode 100644 index 4e04187..0000000 --- a/doc-resources/action/package/nocomments.env-package-extra-opts.md +++ /dev/null @@ -1,2 +0,0 @@ -|DO_PACKAGE_DEBUG| If set to true, this will enable the `-debug` option on the `scancentral` command, and store both ScanCentral logs and the `package.zip` file as job artifacts.| -|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. See [Command-line options for the package command]({{var:sc-client-doc-url}}) for more information on available options. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/package/nocomments.env-sc-client-version.md b/doc-resources/action/package/nocomments.env-sc-client-version.md deleted file mode 100644 index ddd1578..0000000 --- a/doc-resources/action/package/nocomments.env-sc-client-version.md +++ /dev/null @@ -1 +0,0 @@ -| SC_CLIENT_VERSION | By default, this action uses ScanCentral Client {{var:sc-client-version}} for packaging. This environment variable allows for overriding the ScanCentral Client version used for packaging. | diff --git a/doc-resources/action/package/nocomments.snippet-package-extra-opts.md b/doc-resources/action/package/nocomments.snippet-package-extra-opts.md deleted file mode 100644 index 5f7a778..0000000 --- a/doc-resources/action/package/nocomments.snippet-package-extra-opts.md +++ /dev/null @@ -1,2 +0,0 @@ - # DO_PACKAGE_DEBUG: true - # PACKAGE_EXTRA_OPTS: -oss -bt mvn \ No newline at end of file diff --git a/doc-resources/action/package/nocomments.snippet-sc-client-version.md b/doc-resources/action/package/nocomments.snippet-sc-client-version.md deleted file mode 100644 index 188d2aa..0000000 --- a/doc-resources/action/package/nocomments.snippet-sc-client-version.md +++ /dev/null @@ -1 +0,0 @@ - # SC_CLIENT_VERSION: 24.4.1 \ No newline at end of file diff --git a/doc-resources/action/package/readme.md b/doc-resources/action/package/readme.md deleted file mode 100644 index ecb4542..0000000 --- a/doc-resources/action/package/readme.md +++ /dev/null @@ -1,24 +0,0 @@ -This action packages application source code using [ScanCentral Client]({{var:sc-client-doc-url}}). The output package is saved as `package.zip`. - -{{include:action/_generic/prerequisites-h3.md}} - -### Sample usage - -The sample workflow below demonstrates how to configure the action packaging application source code. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Package source code - uses: fortify/github-action/package@{{var:action-major-version}} - env: -{{include:action/package/nocomments.snippet-sc-client-version.md}} -{{include:action/package/nocomments.snippet-package-extra-opts.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.md}} -``` - -{{include:action/_generic/nocomments.env-section-and-table-header.md}} -{{include:action/package/nocomments.env-sc-client-version.md}} -{{include:action/package/nocomments.env-package-extra-opts.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/nocomments.env-job-summary.md b/doc-resources/action/sc-sast-scan/nocomments.env-job-summary.md deleted file mode 100644 index 7d2c162..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.env-job-summary.md +++ /dev/null @@ -1 +0,0 @@ -|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
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`), a job summary listing scan status and issue counts will be generated using the fcli-provided [SSC `appversion-summary`]({{var:fcli-doc-base-url}}ssc-actions.html#_appversion_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. 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 or to specify an SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/nocomments.env-policy-check.md b/doc-resources/action/sc-sast-scan/nocomments.env-policy-check.md deleted file mode 100644 index 9128487..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.env-policy-check.md +++ /dev/null @@ -1 +0,0 @@ -|DO_POLICY_CHECK
CHECK_POLICY_ACTION
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 [SSC `check-policy`]({{var:fcli-doc-base-url}}ssc-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. 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. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/nocomments.env-pr-comment.md b/doc-resources/action/sc-sast-scan/nocomments.env-pr-comment.md deleted file mode 100644 index 811c02d..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.env-pr-comment.md +++ /dev/null @@ -1 +0,0 @@ -|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
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`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [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`. 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 or to specify a different SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) and [SSC Pull Request Comments](#ssc-pull-request-comments) sections below for more details.| diff --git a/doc-resources/action/sc-sast-scan/nocomments.env-sc-sast-scan.md b/doc-resources/action/sc-sast-scan/nocomments.env-sc-sast-scan.md deleted file mode 100644 index 1632144..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.env-sc-sast-scan.md +++ /dev/null @@ -1,2 +0,0 @@ -|SC_SAST_SENSOR_VERSION|Version of the ScanCentral SAST sensor on which the scan should be performed; see [`fcli sc-sast scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-sc-sast-scan-start.html) for details.| -|SC_SAST_SCAN_EXTRA_OPTS
EXTRA_SC_SAST_SCAN_OPTS|Extra ScanCentral SAST scan options; see [`fcli sc-sast scan start` documentation]({{var:fcli-doc-base-url}}/manpage/fcli-sc-sast-scan-start.html). Note that `EXTRA_SC_SAST_SCAN_OPTS` is deprecated; please use `SC_SAST_SCAN_EXTRA_OPTS`.| \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/nocomments.env-setup.md b/doc-resources/action/sc-sast-scan/nocomments.env-setup.md deleted file mode 100644 index 4a8f679..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.env-setup.md +++ /dev/null @@ -1 +0,0 @@ -|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the SSC application version will be automatically created if they do not yet exist, using the fcli-provided [`setup-appversion`]({{var:fcli-doc-base-url}}ssc-actions.html#_setup_appversion) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable, for example to copy state from an existing application version using the `--copy-from` option, or to allow an unsigned custom action to be used. Note that if setup is enabled, `SSC_APPVERSION` must be configured with a qualified application version name; you cannot use application version id. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.| \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/nocomments.snippet-sc-sast-scan.md b/doc-resources/action/sc-sast-scan/nocomments.snippet-sc-sast-scan.md deleted file mode 100644 index c17ac53..0000000 --- a/doc-resources/action/sc-sast-scan/nocomments.snippet-sc-sast-scan.md +++ /dev/null @@ -1,2 +0,0 @@ - # SC_SAST_SENSOR_VERSION: 24.4.1 - # EXTRA_SC_SAST_SCAN_OPTS: \ No newline at end of file diff --git a/doc-resources/action/sc-sast-scan/readme.md b/doc-resources/action/sc-sast-scan/readme.md deleted file mode 100644 index 89bb516..0000000 --- a/doc-resources/action/sc-sast-scan/readme.md +++ /dev/null @@ -1,61 +0,0 @@ -This action performs a SAST scan on ScanCentral SAST, consisting of the following steps: - -* 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 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 - -{{include:action/_generic/prerequisites-h3.md}} - -Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: - -* If Debricked scanning is enabled, the [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) must be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on ScanCentral SAST. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run ScanCentral SAST Scan - uses: fortify/github-action/sc-sast-scan@{{var:action-major-version}} - env: -{{include:action/_generic/ssc/nocomments.snippet-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.snippet-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.snippet-ssc-appversion.md}} -{{include:action/_generic/nocomments.snippet-setup.md}} -{{include:action/package/nocomments.snippet-sc-client-version.md}} -{{include:action/package/nocomments.snippet-package-extra-opts.md}} -{{include:action/sc-sast-scan/nocomments.snippet-sc-sast-scan.md}} - # DO_DEBRICKED_SCAN: true -{{include:action/_generic/nocomments.snippet-do-wait.md}} -{{include:action/_generic/nocomments.snippet-policy-check.md}} -{{include:action/_generic/nocomments.snippet-job-summary.md}} -{{include:action/_generic/nocomments.snippet-pr-comment.md}} -{{include:action/_generic/nocomments.snippet-export-optional.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.md}} -``` - -{{include:action/_generic/nocomments.env-section-and-table-header.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.env-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-appversion.md}} -{{include:action/sc-sast-scan/nocomments.env-setup.md}} -|DO_DEBRICKED_SCAN|If set to `true`, this GitHub Action will also run a Debricked Software Composition Analysis scan and publish the results to SSC. 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.| -{{include:action/package/nocomments.env-sc-client-version.md}} -{{include:action/package/nocomments.env-package-extra-opts.md}} -{{include:action/sc-sast-scan/nocomments.env-sc-sast-scan.md}} -{{include:action/_generic/nocomments.env-do-wait.md}} -{{include:action/sc-sast-scan/nocomments.env-policy-check.md}} -{{include:action/sc-sast-scan/nocomments.env-job-summary.md}} -{{include:action/ssc-export/nocomments.env-export-optional.md}} -{{include:action/sc-sast-scan/nocomments.env-pr-comment.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/ssc/ssc-fcli-actions.md}} - -{{include:action/_generic/ssc/ssc-pr.md}} \ No newline at end of file diff --git a/doc-resources/action/setup/nocomments.env-tool-definitions.md b/doc-resources/action/setup/nocomments.env-tool-definitions.md deleted file mode 100644 index 82e90e0..0000000 --- a/doc-resources/action/setup/nocomments.env-tool-definitions.md +++ /dev/null @@ -1 +0,0 @@ -| TOOL_DEFINITIONS | 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. | diff --git a/doc-resources/action/setup/nocomments.snippet-tool-definitions.md b/doc-resources/action/setup/nocomments.snippet-tool-definitions.md deleted file mode 100644 index aae4dc4..0000000 --- a/doc-resources/action/setup/nocomments.snippet-tool-definitions.md +++ /dev/null @@ -1 +0,0 @@ - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip \ No newline at end of file diff --git a/doc-resources/action/setup/readme.md b/doc-resources/action/setup/readme.md deleted file mode 100644 index 97ed061..0000000 --- a/doc-resources/action/setup/readme.md +++ /dev/null @@ -1,59 +0,0 @@ -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-url}}) -* [FoDUploader](https://github.com/fod-dev/fod-uploader-java) -* [FortifyVulnerabilityExporter](https://github.com/fortify/FortifyVulnerabilityExporter) -* [FortifyBugTrackerUtility](https://github.com/fortify-ps/FortifyBugTrackerUtility) - -{{include:action/_generic/prerequisites-h3.md}} - -### Sample usage - -The sample workflow below demonstrates how to configure the action for installing the various Fortify tools and how to run these tools. Some notes: - -* The `export-path` and `bugtracker-utility` inputs are set to their default values, and thus could have been omitted. -* The action supports semantic versioning, so the `vuln-exporter` input will install the latest known v2.x.y version of FortifyVulnerabilityExporter. - -```yaml - steps: - - 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 - run: ${FCLI_CMD} -V -``` - -{{include:action/_generic/nocomments.input-section-and-table-header.md}} -| export‑path | Whether to add the installed tools to the system PATH variable. Allowed values: `true` (default) or `false` | -| tool‑definitions | 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 | 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. | -| sc‑client | The ScanCentral Client version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `23.1` will install the latest known `23.1.y` patch version. Version may be specified either with or without the `v` prefix, for example `v23.1` and `23.1` are semantically the same. | -| fod‑uploader | The FoDUploader version to install. Allowed values: `skip` (default value, do not install), `latest`, or specific version number. Supports semantic versioning, for example `v5` will install the latest known `5.x.y` version. Version may be specified either with or without the `v` prefix, for example `v5.4.0` and `5.4.0` are semantically the same. | -| vuln‑exporter | The FortifyVulnerabilityExporter version to install. Allowed values: `skip` (default value, do not install), `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.4` and `2.0.4` are semantically the same. | -| bugtracker‑utility | 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 | 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. | - -{{include:action/_generic/nocomments.env-section-and-table-header.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -### Action outputs - -For each tool being installed, the action outputs several environment variables for use by later workflow steps. - -{{include:action/_generic/nocomments.env-table-header.md}} -| PATH | If the `export-path` action input was set to `true` (default), the bin-directory of the installed tool will be added to the workflow `PATH` environment variable. | -| <TOOL_NAME>_INSTALL_DIR | Directory where the corresponding tool was installed. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_INSTALL_DIR`. | -| <TOOL_NAME>_BIN_DIR | Bin-directory that holds the executables for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_BIN_DIR`. | -| <TOOL_NAME>_CMD | Fully qualified path to the (primary) executable/script for the corresponding tool. `` corresponds to the various action inputs, but converted to uppercase and dashes replaced by underscore, for example `FOD_UPLOADER_CMD`. | diff --git a/doc-resources/action/ssc-debricked-scan/readme.md b/doc-resources/action/ssc-debricked-scan/readme.md deleted file mode 100644 index 4e7bf06..0000000 --- a/doc-resources/action/ssc-debricked-scan/readme.md +++ /dev/null @@ -1,54 +0,0 @@ -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 - -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/_generic/prerequisites-h3.md}} - -Apart from the generic action prerequisites listed above, the following prerequisites apply to this specific action: - -* The [Fortify SSC Parser Plugin for Debricked results](https://github.com/fortify/fortify-ssc-parser-debricked-cyclonedx) must be installed on Fortify SSC, to allow for SSC to accept and process the Debricked scan results submitted by this action. - -### 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:action/_generic/ssc/nocomments.snippet-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.snippet-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.snippet-ssc-appversion.md}} -{{include:action/_generic/nocomments.snippet-setup.md}} -{{include:action/_generic/nocomments.snippet-do-wait.md}} -{{include:action/_generic/nocomments.snippet-policy-check.md}} -{{include:action/_generic/nocomments.snippet-job-summary.md}} -{{include:action/_generic/nocomments.snippet-pr-comment.md}} -{{include:action/_generic/nocomments.snippet-export-optional.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.md}} -``` - -{{include:action/_generic/nocomments.env-section-and-table-header.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-login.md}} -{{include:action/_generic/debricked/nocomments.env-debricked-token.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-appversion.md}} -{{include:action/sc-sast-scan/nocomments.env-setup.md}} -{{include:action/_generic/nocomments.env-do-wait.md}} -{{include:action/sc-sast-scan/nocomments.env-policy-check.md}} -{{include:action/sc-sast-scan/nocomments.env-job-summary.md}} -{{include:action/ssc-export/nocomments.env-export-optional.md}} -{{include:action/sc-sast-scan/nocomments.env-pr-comment.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/ssc/ssc-fcli-actions.md}} - -{{include:action/_generic/ssc/ssc-pr.md}} - diff --git a/doc-resources/action/ssc-export/nocomments.env-export-optional.md b/doc-resources/action/ssc-export/nocomments.env-export-optional.md deleted file mode 100644 index 5b8819c..0000000 --- a/doc-resources/action/ssc-export/nocomments.env-export-optional.md +++ /dev/null @@ -1 +0,0 @@ -| DO_EXPORT
EXPORT_ACTION
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 GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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 or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details.

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. | \ No newline at end of file diff --git a/doc-resources/action/ssc-export/nocomments.env-export.md b/doc-resources/action/ssc-export/nocomments.env-export.md deleted file mode 100644 index 27c0b8c..0000000 --- a/doc-resources/action/ssc-export/nocomments.env-export.md +++ /dev/null @@ -1 +0,0 @@ -| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [SSC `github-sast-report`]({{var:fcli-doc-base-url}}ssc-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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 or to specify an alternative SSC filter set. Please see the [SSC Fcli Actions](#ssc-fcli-actions) section below for more details. | \ No newline at end of file diff --git a/doc-resources/action/ssc-export/readme.md b/doc-resources/action/ssc-export/readme.md deleted file mode 100644 index 1582a01..0000000 --- a/doc-resources/action/ssc-export/readme.md +++ /dev/null @@ -1,26 +0,0 @@ -This action exports the latest vulnerability data from an SSC application version 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/_generic/prerequisites-h3.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. - -```yaml - steps: - - name: Export SSC vulnerability data to GitHub - uses: fortify/github-action/ssc-export@{{var:action-major-version}} - env: -{{include:action/_generic/ssc/nocomments.snippet-ssc-login.md}} -{{include:action/_generic/ssc/nocomments.snippet-ssc-appversion.md}} -{{include:action/_generic/nocomments.snippet-export.md}} -{{include:action/setup/nocomments.snippet-tool-definitions.md}} -``` - -{{include:action/_generic/nocomments.env-section-and-table-header.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-login.md}} -{{include:action/_generic/ssc/nocomments.env-ssc-appversion.md}} -{{include:action/ssc-export/nocomments.env-export.md}} -{{include:action/setup/nocomments.env-tool-definitions.md}} - -{{include:action/_generic/ssc/ssc-fcli-actions.md}} diff --git a/doc-resources/repo-devinfo.md b/doc-resources/repo-devinfo.md index 73ff500..215f3d3 100644 --- a/doc-resources/repo-devinfo.md +++ b/doc-resources/repo-devinfo.md @@ -1,30 +1,29 @@ ## Information for Developers ### Repository initialization -After cloning this repository, please run ./configure.sh to install npm modules and configure git hooks. When adding a new NodeJS-based action, you'll need to update `/configure.sh` to add the action directory to the for-loop. - -### Action documentation -Action documentation is generated from the `doc-resources` directory, using functionality provided by https://github.com/fortify/shared-doc-resources. The `doc-resources` directory contains the following: - -* `action/_generic/**/*`: Generic includes referenced from action documentation -* `action/_root/readme.md`: Documentation for the top-level action -* `action/`: - * `readme.md`: Documentation for `` sub-action - * `nocomments.env-*.md`: Markdown table rows describing environment variable inputs - * `nocomments.snippet-*.md`: Sample YAML snippets -* `repo-devinfo.md`: Information for developers -* `repo-usage.md`: Used to generated top-level USAGE.md, just refers to README.md -* `template-values.md`: Defines variables used in documentation resources -* `templates/README.template.md`: Template for the top-level `README.md` file -* `templates//README.template.md`: Template for the README.md file for each sub-action -* `update-repo-docs.sh`: Script to generate documentation resources - -If you need to update the documentation for an existing action, you'll want to edit the corresponding `action//readme.md` file or the included files. - -When adding a new action, you should: -* Create a corresponding directory in the `doc-resources/templates` directory -* Copy an existing `README.template.md` from one of the other action template directories -* Change the header and include statement in the new `README.template.md` to match the new action -* Create a new `action//readme.md` file in the `doc-resources` directory - -After any documentation updates, you may want to manually run `doc-resources/update-repo-docs.sh` to verify whether all includes can be found, and to review the generated README.md files for each action. +After cloning this repository, please run `./configure.sh` to install npm modules and configure git hooks. + +### Documentation structure +Documentation is generated from the `doc-resources` directory using functionality provided by https://github.com/fortify/shared-doc-resources. The structure is straightforward: + +* `repo-intro.md`: Introduction text included in README.md +* `repo-usage.md`: Usage instructions included in USAGE.md +* `repo-resources.md`: Links to resources (contributing, license, etc.) +* `repo-devinfo.md`: Information for developers (this file) +* `repo-usage-text.md`: Include file with links to detailed documentation (used in both intro and usage) +* `template-values.md`: Variables used throughout the documentation +* `update-repo-docs.sh`: Script to regenerate README.md, USAGE.md, and other files + +To update documentation, edit the appropriate `.md` files in `doc-resources/`, then run `doc-resources/update-repo-docs.sh` to regenerate the top-level documentation files. + +### Building the action + +The action uses the `@fortify/setup` NPM package published to [npmjs.org](https://www.npmjs.com/package/@fortify/setup). To build: + +```bash +cd setup +npm install +npm run build +``` + +This creates a bundled `dist/index.js` file that includes all dependencies. The action is ready to use once the dist directory is committed. diff --git a/doc-resources/repo-intro.md b/doc-resources/repo-intro.md new file mode 100644 index 0000000..9eac509 --- /dev/null +++ b/doc-resources/repo-intro.md @@ -0,0 +1,9 @@ +The `fortify/github-action` GitHub Action allows for easy integration of OpenText Fortify Application Security Testing (AST) into your GitHub Action workflows by bootstrapping the latest [fcli v3 release](https://github.com/fortify/fcli/releases/v3) using the [`@fortify/setup` NPM component](https://www.npmjs.com/package/@fortify/setup), and then running the `fcli action run ci` command. + +As such, this GitHub Action automatically benefits from new features and bug fixes as they are introduced in fcli, although there are options to use a fixed fcli version in case you need more stability. At the time of writing, the fcli `ci` action 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 the top-level `fortify/github-action` for running the fcli-based `ci` workflow, this repository also provides the `fortify/github-action/setup` GitHub Action. This action allows for setting up fcli and other Fortify tools like ScanCentral Client for use in a custom GitHub Actions workflow, for example for implementing a fully customized AST scan workflow or some other automation workflow that needs to interact with Fortify products. + +{{include:repo-usage-text.md}} + + diff --git a/doc-resources/repo-resources.md b/doc-resources/repo-resources.md new file mode 100644 index 0000000..84a82f4 --- /dev/null +++ b/doc-resources/repo-resources.md @@ -0,0 +1 @@ +{{include:resources/nocomments.li.contrib-conduct-licence.md}} \ No newline at end of file diff --git a/doc-resources/repo-usage-text.md b/doc-resources/repo-usage-text.md new file mode 100644 index 0000000..b0e794f --- /dev/null +++ b/doc-resources/repo-usage-text.md @@ -0,0 +1,92 @@ +### Quick Start + +#### OpenText Core Application Security (Fortify on Demand) + +```yaml +name: Fortify on Demand Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans + env: + FOD_URL: ${{ vars.FOD_URL }} + FOD_CLIENT_ID: ${{ secrets.FOD_CLIENT_ID }} + FOD_CLIENT_SECRET: ${{ secrets.FOD_CLIENT_SECRET }} + # FOD_RELEASE: MyApp:main # Optional: defaults to repo:branch + # FCLI_BOOTSTRAP_VERSION: v3.15 # Optional if you prefer stability over latest +``` + +#### OpenText Application Security (Fortify Software Security Center) + +```yaml +name: Fortify SSC Scan +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + fortify: + runs-on: ubuntu-latest + # permissions: # When overriding default permissions, following are required: + # contents: read # Required for checkout action + # security-events: write # Required for publishing security reports to GitHub Security tab + # pull-requests: write # Required if DO_PR_COMMENT is set to true + steps: + - uses: actions/checkout@v4 # Check out source code + - uses: actions/setup-@vX # Set up build tool(s) required to build your project + - uses: fortify/github-action@v3 # Run Fortify scans + env: + SSC_URL: ${{ vars.SSC_URL }} + SSC_TOKEN: ${{ secrets.SSC_TOKEN }} + SC_SAST_TOKEN: ${{ secrets.SC_SAST_TOKEN }} + # SSC_APPVERSION: MyApp:main # Optional: defaults to repo:branch +``` + +#### Custom workflow + +```yaml +name: Custom Fortify Workflow +on: [push] + +jobs: + custom-scan: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: fortify/github-action/setup@v3 + with: + fcli: bootstrapped # Set up bootstrapped fcli version. May also specify specific version, but + # then fcli may be downloaded twice (bootstrap version and requested version). + env: + FCLI_BOOTSTRAP_VERSION: v3.15.0 # Defaults to latest v3.x.y, pin to specific version for stability + - name: Run custom fcli commands + run: | + fcli fod session login ... + # Your custom workflow here + fcli fod session logout ... +``` + +### Detailed Documentation + +Given that these GitHub Actions are just thin wrappers around `@fortify/setup` and `fcli`, detailed usage documentation is available on the fcli documentation website: + +* [`fortify/github-action` for OpenText Application Security Code (Fortify on Demand)]({{var:fcli-doc-base-url}}/ci/github/{{var:action-doc-version}}/ast-action-fod.html) +* [`fortify/github-action` for OpenText Software Security Center (Fortify SSC)]({{var:fcli-doc-base-url}}/ci/github/{{var:action-doc-version}}/ast-action-ssc.html) +* [`fortify/github-action/setup`]({{var:fcli-doc-base-url}}/ci/github/{{var:action-doc-version}}/setup-action.html) + + diff --git a/doc-resources/repo-usage.md b/doc-resources/repo-usage.md index bbf372b..5debbcd 100644 --- a/doc-resources/repo-usage.md +++ b/doc-resources/repo-usage.md @@ -1,4 +1,4 @@ ## Usage instructions -Please see the README.md file for usage instructions. +{{include:repo-usage-text.md}} diff --git a/doc-resources/template-values.md b/doc-resources/template-values.md index b80fe30..0b0b3d9 100644 --- a/doc-resources/template-values.md +++ b/doc-resources/template-values.md @@ -1,5 +1,5 @@ # repo-title -Fortify GitHub Actions +Fortify GitHub Action # repo-url https://github.com/fortify/github-action @@ -7,14 +7,8 @@ https://github.com/fortify/github-action # copyright-years {{var:current-year}} -# action-major-version -v2 - # fcli-doc-base-url -https://fortify.github.io/fcli/v3.13.1/ - -# sc-client-version -25.4.0 +https://fortify.github.io/fcli/v3 -# sc-client-doc-url -https://www.microfocus.com/documentation/fortify-software-security-center/2540/sc-sast-ugd-html-25.4.0/doc/2404_25.4/home.html +# action-doc-version +v3.0.x diff --git a/doc-resources/templates/README.template.md b/doc-resources/templates/README.template.md deleted file mode 100644 index dde6a65..0000000 --- a/doc-resources/templates/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/_root/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/fod-export/README.template.md b/doc-resources/templates/fod-export/README.template.md deleted file mode 100644 index b8da685..0000000 --- a/doc-resources/templates/fod-export/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/fod-export@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/fod-export/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/fod-sast-scan/README.template.md b/doc-resources/templates/fod-sast-scan/README.template.md deleted file mode 100644 index 63c57e8..0000000 --- a/doc-resources/templates/fod-sast-scan/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/fod-sast-scan@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/fod-sast-scan/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/package/README.template.md b/doc-resources/templates/package/README.template.md deleted file mode 100644 index a7b78ef..0000000 --- a/doc-resources/templates/package/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/package@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/package/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/sc-sast-scan/README.template.md b/doc-resources/templates/sc-sast-scan/README.template.md deleted file mode 100644 index 45ba0ae..0000000 --- a/doc-resources/templates/sc-sast-scan/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/sc-sast-scan@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/sc-sast-scan/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/setup/README.template.md b/doc-resources/templates/setup/README.template.md deleted file mode 100644 index e0e05a6..0000000 --- a/doc-resources/templates/setup/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/setup@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/setup/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/ssc-debricked-scan/README.template.md b/doc-resources/templates/ssc-debricked-scan/README.template.md deleted file mode 100644 index e273f22..0000000 --- a/doc-resources/templates/ssc-debricked-scan/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/ssc-debricked-scan@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/ssc-debricked-scan/readme.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)* \ No newline at end of file diff --git a/doc-resources/templates/ssc-export/README.template.md b/doc-resources/templates/ssc-export/README.template.md deleted file mode 100644 index 9fddf86..0000000 --- a/doc-resources/templates/ssc-export/README.template.md +++ /dev/null @@ -1,11 +0,0 @@ -# fortify/github-action/ssc-export@{{var:action-major-version}} - -{{include:p.marketing-intro.md}} - -{{include:action/ssc-export/readme.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)* \ No newline at end of file diff --git a/fod-export/README.md b/fod-export/README.md deleted file mode 100644 index 73ac9df..0000000 --- a/fod-export/README.md +++ /dev/null @@ -1,116 +0,0 @@ -# fortify/github-action/fod-export@v2 - - - - -[Fortify Application Security](https://www.microfocus.com/en-us/solutions/application-security) provides your team with solutions to empower [DevSecOps](https://www.microfocus.com/en-us/cyberres/use-cases/devsecops) practices, enable [cloud transformation](https://www.microfocus.com/en-us/cyberres/use-cases/cloud-transformation), and secure your [software supply chain](https://www.microfocus.com/en-us/cyberres/use-cases/securing-the-software-supply-chain). As the sole Code Security solution with over two decades of expertise and acknowledged as a market leader by all major analysts, Fortify delivers the most adaptable, precise, and scalable AppSec platform available, supporting the breadth of tech you use and integrated into your preferred toolchain. We firmly believe that your great code [demands great security](https://www.microfocus.com/cyberres/application-security/developer-security), and with Fortify, go beyond 'check the box' security to achieve that. - - - - - - - -This action exports the latest vulnerability data from a Fortify on Demand 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. - - - - -### Prerequisites - - - - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for exporting Fortify on Demand SAST vulnerability data to the GitHub Security Code Scanning dashboard. - -```yaml - steps: - - name: Export Fortify on Demand vulnerability data to GitHub - uses: fortify/github-action/fod-export@v2 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_CLIENT_ID: ${{secrets.FOD_CLIENT_ID}} - # FOD_CLIENT_SECRET: ${{secrets.FOD_CLIENT_SECRET}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml - # EXPORT_EXTRA_OPTS: --on-unsigned=ignore - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - -### Action environment variable inputs - -This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - -| Environment variable | Description | -| :--- | :--- | -| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to Fortify on Demand to be rendered incorrectly, for example in GitHub Action job summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | -| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: Fortify on Demand Client ID (API key) and Secret (API secret). | -| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: Fortify on Demand tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | -| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | Extra login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| -| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | -| EXPORT_ACTION
EXPORT_EXTRA_OPTS | This GitHub Action will will export scan results to the GitHub Security Code Scanning dashboard using the fcli-provided [`github-sast-report`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details. | -| TOOL_DEFINITIONS | 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. | - - - - -### Fortify on Demand Fcli Actions - - - - - - -As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - -For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v3.13.1/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - - - - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. - - - - - - - - - - -## Support - -For general assistance, please join the [Fortify Community](https://community.opentext.com/cybersec/fortify/) to get tips and tricks from other users and the OpenText team. - -OpenText customers can contact our world-class [support team](https://www.opentext.com/support/opentext-enterprise/) for questions, enhancement requests and bug reports. You can also raise questions and issues through your OpenText Fortify representative like Customer Success Manager or Technical Account Manager if applicable. - -You may also consider raising questions or issues through the [GitHub Issues page](https://github.com/fortify/github-action/issues) (if available for this repository), providing public visibility and allowing anyone (including all contributors) to review and comment on your question or issue. Note that this requires a GitHub account, and given public visibility, you should refrain from posting any confidential data through this channel. - - - - ---- - -*[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-export/action.yml b/fod-export/action.yml deleted file mode 100644 index 7943b10..0000000 --- a/fod-export/action.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: 'Export FoD vulnerability data to GitHub' -description: 'Export FoD vulnerability data to GitHub' -author: 'Fortify' -runs: - using: composite - steps: - - uses: fortify/github-action/internal/set-fod-var-defaults@main - - uses: fortify/github-action/setup@main - with: - export-path: false - fcli: action-default - - uses: fortify/github-action/internal/fod-login@main - - uses: fortify/github-action/internal/run-script@main - with: - script: export.sh - env: - PRODUCT: fod - DEFAULT_OPTS: --rel "${{env.FOD_RELEASE}}" --source-dir="${{github.workspace}}" -f ./gh-fortify-sast.sarif - - uses: github/codeql-action/upload-sarif@v3 - with: - sarif_file: ./gh-fortify-sast.sarif - - # Optionally store the generated file for troubleshooting purposes. - - uses: actions/upload-artifact@v4 - if: always() - with: - name: ${{ github.job }}-${{ strategy.job-index }}-sarif-files - path: ./gh-fortify-sast.sarif - -branding: - icon: 'shield' - color: 'blue' - diff --git a/fod-sast-scan/README.md b/fod-sast-scan/README.md deleted file mode 100644 index 0299e69..0000000 --- a/fod-sast-scan/README.md +++ /dev/null @@ -1,190 +0,0 @@ -# fortify/github-action/fod-sast-scan@v2 - - - - -[Fortify Application Security](https://www.microfocus.com/en-us/solutions/application-security) provides your team with solutions to empower [DevSecOps](https://www.microfocus.com/en-us/cyberres/use-cases/devsecops) practices, enable [cloud transformation](https://www.microfocus.com/en-us/cyberres/use-cases/cloud-transformation), and secure your [software supply chain](https://www.microfocus.com/en-us/cyberres/use-cases/securing-the-software-supply-chain). As the sole Code Security solution with over two decades of expertise and acknowledged as a market leader by all major analysts, Fortify delivers the most adaptable, precise, and scalable AppSec platform available, supporting the breadth of tech you use and integrated into your preferred toolchain. We firmly believe that your great code [demands great security](https://www.microfocus.com/cyberres/application-security/developer-security), and with Fortify, go beyond 'check the box' security to achieve that. - - - - - - - -This action performs a SAST scan on Fortify on Demand. If software composition analysis of open source has been purchased and configured on the applicable release, this action can be used to perform a combined SAST and SCA (open source) scan. - -The SAST and optional open source scan performed by this action consists of the following steps: - -* Login to Fortify on Demand -* Package application source code using ScanCentral Client -* Submit the source code package to be scanned to Fortify on Demand -* Optionally wait for the scan to complete -* Optionally export scan results to the GitHub Code Scanning dashboard - - - - -### Prerequisites - - - - -This action assumes the standard software packages as provided by GitHub-hosted runners to be available. If you are using self-hosted runners, you may need to install some of these software packages in order to successfully use this action. In particular, not having the following software installed is known to cause issues when running `fortify/github-action` or one of its sub-actions: - -* Node.js -* Visual C++ Redistributable (Windows-based runners only) -* Bash shell - If using Windows runners, this must be a Windows-based `bash` variant, for example as provided by MSYS2. You must make sure that this Windows-based `bash` variant is used for `run` steps that specify `shell: bash`. Actions will fail if the GitHub runner executes `bash` commands on the WSL-provided `bash.exe` - - - - - - - -### Sample usage - -The sample workflow below demonstrates how to configure the action for running a SAST scan on Fortify on Demand. - -```yaml - steps: - - name: Check out source code - uses: actions/checkout@v4 - - name: Run Fortify on Demand SAST Scan - uses: fortify/github-action/fod-sast-scan@v2 - env: - FOD_URL: https://ams.fortify.com - FOD_TENANT: ${{secrets.FOD_TENANT}} - FOD_USER: ${{secrets.FOD_USER}} - FOD_PASSWORD: ${{secrets.FOD_PAT}} - # FOD_CLIENT_ID: ${{secrets.FOD_CLIENT_ID}} - # FOD_CLIENT_SECRET: ${{secrets.FOD_CLIENT_SECRET}} - # FOD_LOGIN_EXTRA_OPTS: --socket-timeout=60s - # FOD_RELEASE: MyApp:MyRelease - # DO_SETUP: true - # SETUP_ACTION: https://scm.my.org/shared-repos/fcli-actions/setup.yaml - # SETUP_EXTRA_OPTS: --copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}" - # SC_CLIENT_VERSION: 24.4.1 - # DO_PACKAGE_DEBUG: true - # PACKAGE_EXTRA_OPTS: -oss -bt mvn - # FOD_SAST_SCAN_EXTRA_OPTS: - # DO_DEBRICKED_SCAN: true - # DO_WAIT: true - # DO_POLICY_CHECK: true - # POLICY_CHECK_ACTION: https://scm.my.org/shared-repos/fcli-actions/check-policy.yaml - # POLICY_CHECK_EXTRA_OPTS: --on-unsigned=ignore - # DO_JOB_SUMMARY: true - # JOB_SUMMARY_ACTION: https://scm.my.org/shared-repos/fcli-actions/job-summary.yaml - # JOB_SUMMARY_EXTRA_OPTS: --on-unsigned=ignore - # DO_PR_COMMENT: true - # PR_COMMENT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-pr-comment.yaml - # PR_COMMENT_EXTRA_OPTS: --on-unsigned=ignore - # DO_EXPORT: true - # EXPORT_ACTION: https://scm.my.org/shared-repos/fcli-actions/github-sast-report.yaml - # EXPORT_EXTRA_OPTS: --on-unsigned=ignore - # TOOL_DEFINITIONS: https://ftfy.mycompany.com/tool-definitions/v1/tool-definitions.yaml.zip -``` - - -### Action environment variable inputs - -This section lists the environment variables that can be specified in the `env:` clause for this GitHub Action. Any environment variables marked in **bold** are required. - -| Environment variable | Description | -| :--- | :--- | -| **FOD_URL** | Fortify on Demand URL, for example https://ams.fortify.com. Note: Using GitHub Secrets to define this URL may cause links back to Fortify on Demand to be rendered incorrectly, for example in GitHub Action job summaries. It is highly recommended to either hard-code the URL in your workflow, or to use [GitHub Variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) instead of GitHub Secrets. | -| **FOD_CLIENT_ID**
**FOD_CLIENT_SECRET** | Required when authenticating with an API key: Fortify on Demand Client ID (API key) and Secret (API secret). | -| **FOD_TENANT**
**FOD_USER**
**FOD_PASSWORD** | Required when authenticating with user credentials: Fortify on Demand tenant, user and password. It's recommended to use a Personal Access Token instead of an actual user password. | -| FOD_LOGIN_EXTRA_OPTS
EXTRA_FOD_LOGIN_OPTS | Extra login options, for example for disabling SSL checks or changing connection time-outs; see [`fcli fod session login` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-fod-session-login.html) . Note that `EXTRA_FOD_LOGIN_OPTS` is deprecated; please use `FOD_LOGIN_EXTRA_OPTS`.| -| FOD_RELEASE | Fortify on Demand release to use with this action. This can be specified either as a numeric release id, `:` (for non-microservices applications) or `::` (for microservices applications). Default value is based on repository and branch name, for example `myOrg/myRepo:myBranch`. Note that you'll need to explicitly configure `FOD_RELEASE` for microservices applications, as the default value lacks a microservice name. | -|DO_SETUP
SETUP_ACTION
SETUP_EXTRA_OPTS|If `DO_SETUP` is set to `true` (implied if any of the other two `SETUP_*` variables are set), the application and/or release will be automatically created if they do not yet exist and static scan settings will be configured if not configured already, using the fcli-provided [`setup-release`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_setup_release) or, if specified, the custom fcli action specified through `SETUP_ACTION`. Extra options for the fcli action can be passed through the `SETUP_EXTRA_OPTS` environment variable. Depending on your Git workflow, it is recommended to have each newly created release copy state from the release representing your default branch by passing `--copy-from "${{ github.repository }}:${{ github.event.repository.default_branch }}"` through `SETUP_EXTRA_OPTS`. To allow the GitHub Action to create new applications, you must (also) provide the `--app-owner ` option through `SETUP_EXTRA_OPTS` if authenticating with client credentials. Note that if setup is enabled, `FOD_RELEASE` must be configured with a qualified release name; you cannot use release id. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| -| SC_CLIENT_VERSION | By default, this action uses ScanCentral Client 25.4.0 for packaging. This environment variable allows for overriding the ScanCentral Client version used for packaging. | -|DO_PACKAGE_DEBUG| If set to true, this will enable the `-debug` option on the `scancentral` command, and store both ScanCentral logs and the `package.zip` file as job artifacts.| -|PACKAGE_EXTRA_OPTS
EXTRA_PACKAGE_OPTS| By default, this action runs `scancentral package -o package.zip` to package application source code. Use `PACKAGE_EXTRA_OPTS` to specify additional packaging options, for example `PACKAGE_EXTRA_OPTS: -bt mvn -bf `. See [Command-line options for the package command](https://www.microfocus.com/documentation/fortify-software-security-center/2540/sc-sast-ugd-html-25.4.0/doc/2404_25.4/home.html) for more information on available options. Note that `EXTRA_PACKAGE_OPTS` is deprecated; please use `PACKAGE_EXTRA_OPTS`.| -|FOD_SAST_SCAN_EXTRA_OPTS
EXTRA_FOD_SAST_SCAN_OPTS|Extra SAST scan options; see [`fcli fod sast-scan start` documentation](https://fortify.github.io/fcli/v3.13.1//manpage/fcli-fod-sast-scan-start.html). Note that `EXTRA_FOD_SAST_SCAN_OPTS` is deprecated; please use `FOD_SAST_SCAN_EXTRA_OPTS`.| -|DO_DEBRICKED_SCAN|Configure the static scan to also run an open-source scan. Depending on Fortify on Demand 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 Fortify on Demand scan configuration. Note that any existing scan configuration will not be updated, so if the scan has already been configured in Fortify on Demand, an open-source scan will only be performed if previously enabled in the existing scan configuration.| -| DO_WAIT | By default, this action will not wait until scans have been completed. To have the workflow wait until all scans have been completed, set the `DO_WAIT` environment variable to `true`. Note that some other environment variables imply `DO_WAIT`, for example when exporting vulnerability data or generating job summaries. This behavior is documented in the applicable environment variable descriptions. | -|DO_POLICY_CHECK
CHECK_POLICY_ACTION
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 [`check-policy`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_check_policy) or, if specified, the custom fcli action specified through `CHECK_POLICY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.| -|DO_JOB_SUMMARY
JOB_SUMMARY_ACTION
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`), a job summary listing scan status and issue counts will be generated using the fcli-provided [`release-summary`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_release_summary) or, if specified, the custom fcli action specified through `JOB_SUMMARY_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details. | -| DO_EXPORT
EXPORT_ACTION
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`), scan results will be exported to the GitHub Security Code Scanning dashboard using the fcli-provided [`github-sast-report`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_sast_report) action or, if specified, the custom fcli action specified through `EXPORT_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) section below for more details.

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. | -|(PREVIEW)
DO_PR_COMMENT
PR_COMMENT_ACTION
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`), a pull request comment listing new, re-introduced and removed issues will be generated using the fcli-provided [`github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_pr_comment) action or, if specified, the custom fcli action specified through `PR_COMMENT_ACTION`. 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. Please see the [Fcli Actions](#fortify-on-demand-fcli-actions) and [Pull Request Comments](#fortify-on-demand-pull-request-comments) sections below for more details.| -| TOOL_DEFINITIONS | 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. | - - - - -### Fortify on Demand Fcli Actions - - - - - - -As indicated in the [Action environment variable inputs](#action-environment-variable-inputs) section above, this GitHub Action utilizes one or more fcli actions to perform certain activities. These fcli-provided actions are used as building blocks that can be re-used across different CI/CD platforms to provide consistent behavior across those platforms. This GitHub Action also provides the ability to override the default built-in fcli actions with custom fcli actions, allowing for rich customization capabilities. For example, such custom fcli actions could define different default values for some action options, perform some additional activities, and/or provide fully customized behavior. - -For more information on fcli actions and custom action development, please see the [fcli action documentation](https://fortify.github.io/fcli/v3.13.1/#_actions). Such custom actions may be hosted either on the local file system (for example stored in your source code repository) or some remote location; the `*_ACTION` environment variables may point to either a local file or URL. To easily share custom actions across multiple pipelines, you may want to consider hosting these in a dedicated source code repository that's accessible by all pipelines. This provides an easy hosting location, and allows for easy maintenance of such custom actions. - - - - -When developing custom actions, please note that the GitHub Action expects certain action parameters to be supported by such a custom action. A common example is the `--rel` / `--release` command-line option, which the GitHub Action will automatically pass to most or all fcli actions to specify the release to operate on. What command-line options are automatically passed to the fcli action may also depend on GitHub Action configuration. If the custom action doesn't support those action parameters, the action invocation will fail. You will also need to consider any options explicitly configured through the `*_EXTRA_OPTS` environment variable; for backward compatibility with existing GitHub Action workflows that have been configured with some extra action options, you should be careful with removing or renaming any action parameters. - -Future versions of this documentation may provide more details on what command-line options are automatically passed to fcli actions. Until then, you'll need to review workflow logs and/or GitHub Action source code to identify what action parameters are being automatically passed by the GitHub Action. Alternatively, you may want to consider simply duplicating all action parameters from the fcli built-in action, even if some of those parameters will not be used by your custom action. - - - - - - - -### Fortify on Demand Pull Request Comments - - - -This section provides more information on Pull Request Comments that will be generated if `DO_PR_COMMENT` is set to `true`. This information is based on the fcli-provided [`github-pr-comment`](https://fortify.github.io/fcli/v3.13.1/fod-actions.html#_github_pr_comment) action and may not apply when using a custom fcli action through `PR_COMMENT_ACTION`. - -**Important note:** Pull Request comments are currently considered preview functionality. Configuration settings, behavior and output may significantly change in future GitHub Action releases as we work on improving and fine-tuning our PR decoration capabilities. - -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 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`, to use the default value that corresponds to repository and branch name. -- Set `DO_SETUP` to `true`, to allow a branch-specific application release to be automatically created. -- Include `--copy-from` option in `SETUP_EXTRA_OPTS` to copy state from the release that represents the PR target branch or your main branch into the newly created application release. - -With a setup like this, whenever a new PR is created, the GitHub Action will: -- Create a new application release named `/:`. -- Copy state from the application release identified by the `--copy-from` option to this new application release. -- Run a new scan of the branch associated with the current PR, and upload results to the application 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 application 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 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. - - - - - - - - - - -## Support - -For general assistance, please join the [Fortify Community](https://community.opentext.com/cybersec/fortify/) to get tips and tricks from other users and the OpenText team. - -OpenText customers can contact our world-class [support team](https://www.opentext.com/support/opentext-enterprise/) for questions, enhancement requests and bug reports. You can also raise questions and issues through your OpenText Fortify representative like Customer Success Manager or Technical Account Manager if applicable. - -You may also consider raising questions or issues through the [GitHub Issues page](https://github.com/fortify/github-action/issues) (if available for this repository), providing public visibility and allowing anyone (including all contributors) to review and comment on your question or issue. Note that this requires a GitHub account, and given public visibility, you should refrain from posting any confidential data through this channel. - - - - ---- - -*[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/action.yml b/fod-sast-scan/action.yml deleted file mode 100644 index c423edf..0000000 --- a/fod-sast-scan/action.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: 'Perform SAST scan' -description: 'Perform a SAST scan on Fortify on Demand' -author: 'Fortify' -runs: - using: composite - steps: - - uses: fortify/github-action/internal/set-fod-var-defaults@main - - uses: fortify/github-action/setup@main - 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-script@main - with: - script: fod-scan.sh - env: - DO_SAST_SCAN: true # Not used for now - GITHUB_TOKEN: ${{ github.token }} - - if: env.DO_EXPORT == 'true' - uses: fortify/github-action/fod-export@main - -branding: - icon: 'shield' - color: 'blue' - diff --git a/internal/README.md b/internal/README.md deleted file mode 100644 index a88274b..0000000 --- a/internal/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Fortify GitHub Actions for internal use - -The GitHub Actions under this folder are meant for internal use by other Fortify GitHub Actions only, not meant for public use. Even between minor versions, these actions may change significantly, potentially breaking any pipelines that use these actions directly. - -These are mostly actions that need to be combined with other steps (as defined by the Fortify GitHub Actions that use these internal actions) to be of any use, just handling individual tasks as required by the calling action. This includes activities like running fcli login/logout commands, which have no use on their own, but need to be combined with other fcli commands. - -Given that underlying tool version (like fcli version) must match between the various workflow steps, and command-line options passed to the underlying tool by these actions need to be compatible with the tool version installed by the calling action, these internal actions are not suitable for external use. - -As an example, suppose a user workflow uses github-action/internal/fod-login@v1, effectively using v1.0.0 of this action. The calling workflow would be responsible for installing an fcli version that's compatible with the command-line options used by the fod-login action. Now, for v1.0.1 of the actions, we decide to use a different internal fcli version that requires us to change the fcli command-line options used by the fod-login action. Now, the login options used by the fod-login action are no longer compatible with the fcli version installed by the calling workflow, causing the action and thus workflow to fail. - -Of course, the calling workflow could decide to install the action-default fcli version instead, which would ensure compatibility between the fcli version and any fcli command-line options used by these internal actions. However, the calling workflow would also contain direct fcli invocations (as otherwise it wouldn't make sense to run fcli login/logout commands through these actions), which again would potentially break if we decide to have the action-default version point to a different fcli version. \ No newline at end of file diff --git a/internal/fod-login/action.yml b/internal/fod-login/action.yml deleted file mode 100644 index e8071d9..0000000 --- a/internal/fod-login/action.yml +++ /dev/null @@ -1,19 +0,0 @@ -name: 'Run "fcli fod session login" command' -description: 'Run "fcli fod session login" command based on environment variables, auto-logout on job termination' -author: 'Fortify' -runs: - using: composite - steps: - # If not run before: check preconditions, run fcli login command, and run - # post-job fcli logout command. - # Note that the calling action/workflow is responsible for installing fcli - - uses: fortify/github-action/internal/run-script@main - if: ${{ !env._FOD_LOGGED_IN }} - with: - script: fod-login.sh - post: fod-logout.sh - -branding: - icon: 'shield' - color: 'blue' - diff --git a/internal/run-script/README.md b/internal/run-script/README.md deleted file mode 100644 index 955c533..0000000 --- a/internal/run-script/README.md +++ /dev/null @@ -1,34 +0,0 @@ -# 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: