From 3ab132173ad157ca0fb0d3f7e74583a9132209d3 Mon Sep 17 00:00:00 2001 From: Aron Gunn Date: Fri, 19 Jul 2024 16:08:56 -0500 Subject: [PATCH 1/4] 7/19/24 - ritz303 : Reviewed README, made edits, and added a CHANGELOG --- CHANGELOG.md | 3 + README.md | 159 ++++++++++++++++++++++++++------------------------- 2 files changed, 84 insertions(+), 78 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6c640b4 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,3 @@ +# Change Log +## 1.0 (?) +- informational - Initial release of GitHub Actions for Red Hat Dependency Analytics. \ No newline at end of file diff --git a/README.md b/README.md index e1a3e03..e9a79da 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Red Hat Dependency Analytics (RHDA) +# Red Hat Dependency Analytics GitHub Actions [![CI Checks](https://github.com/RHEcosystemAppEng/rhda-github-action/actions/workflows/ci.yaml/badge.svg)](https://github.com/RHEcosystemAppEng/rhda-github-action/actions/workflows/ci.yaml)
@@ -16,62 +16,64 @@ [![license badge](https://img.shields.io/github/license/RHEcosystemAppEng/rhda-github-action)](./LICENSE) [![size badge](https://img.shields.io/github/size/RHEcosystemAppEng/rhda-github-action/dist/index.js)](./dist) -The **RHDA** Github Action provides you with awareness to security concerns within the code sumited to your github code repository. The Red Hat Dependency Analytics platform uses vulnerability data sources to report the most up-to-date vulnerability information available. +Red Hat Dependency Analytics (RHDA) Github Actions gives you awareness to security concerns when doing code commits to your GitHub repository. +The RHDA platform uses vulnerability data sources to report the most up-to-date vulnerability information available. -The RHDA report is uploaded to the GitHub repository as an artifact and as a [SARIF](https://sarifweb.azurewebsites.net/) file, and vulnerabilities found are reported to repository maintainers in the **Security** tab. +Dependency Analytics uploads a report to the GitHub repository as an artifact, and as a [SARIF](https://sarifweb.azurewebsites.net/) file. +Repository maintainers can find discovered vulnerabilities on the **Security** tab. -## What is Supported +## Supported ecosystems | Ecosystem | Required Binaries and Prerequisites | Supported Manifests / Files | | --------- | ----------------------------------- | --------------------------- | -| Java - Maven | `mvn` | pom.xml | -| Gradle - Gradle Installation | `gradle` | build.gradle | -| JavaScript - Npm | `npm` | package.json | -| Golang - Go Modules | `go` | go.mod | -| Python - pip Installer | `pip` | requirements.txt | -| [docker](https://docs.docker.com/get-docker/) | [`syft`](https://github.com/anchore/syft?tab=readme-ov-file#installation), [`skopeo`](https://github.com/containers/skopeo/blob/main/install.md) , Java version 20 or later | Dockerfile | -| [Podman](https://podman.io/docs/installation) | [`syft`](https://github.com/anchore/syft?tab=readme-ov-file#installation), [`skopeo`](https://github.com/containers/skopeo/blob/main/install.md) , Java version 20 or later | Containerfile | +| Java - Maven | `mvn` | `pom.xml` | +| Gradle - Gradle Installation | `gradle` | `build.gradle` | +| JavaScript - Npm | `npm` | `package.json` | +| Golang - Go Modules | `go` | `go.mod` | +| Python - pip Installer | `pip` | `requirements.txt` | +| [docker](https://docs.docker.com/get-docker/) | [`syft`](https://github.com/anchore/syft?tab=readme-ov-file#installation),[`skopeo`](https://github.com/containers/skopeo/blob/main/install.md), Java version 20 or later | Dockerfile | +| [Podman](https://podman.io/docs/installation) | [`syft`](https://github.com/anchore/syft?tab=readme-ov-file#installation),[`skopeo`](https://github.com/containers/skopeo/blob/main/install.md), Java version 20 or later | Containerfile | In future releases, Red Hat plans to support other programming languages. -## Configuration +## Configuring RHDA GitHub Actions -You can refer to [the examples in this repository](./.github/workflows) for a simple example of scanning each supported language. Or, skip to the [example below](#example). +You can configure GitHub Actions to use RHDA for your coding environment. +You can see [examples of scanning](./.github/workflows) for each supported language, or you can use the [example below](#example). -### 1. Set up the tool stack -Unless already done, you must set up the tool stack for your project depending on the ecosystem you wish to analyse. +**Prerequisites** -Refer to the setup actions for: +* GitHub Actions configured for your environment: - [Go](https://github.com/actions/setup-go) - [Java](https://github.com/actions/setup-java) - [Node.js](https://github.com/actions/setup-node) - [Python](https://github.com/actions/setup-python) - -`syft` and `skopeo` can ge set up using script: -```yaml -- name: Setup syft - run: | - curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin -``` -```yaml -- name: Setup skopeo - run: | - sudo apt-get -y update - sudo apt-get -y install skopeo -``` - -### 2. Set up RHDA scan -Install RHDA from the [**RHEcosystemAppEng/rhda-github-action**](https://github.com/RHEcosystemAppEng/rhda-github-action) GitHub repository. - -```yaml -- name: RHDA Scan - id: rhda_scan - uses: RHEcosystemAppEng/rhda-github-action@main -``` - -## Example - -The example workflow job below shows how the **RHDA** action can be used to scan vulnerabilities in a Node.js project and upload the result to GitHub. + - For `syft` you can use the following script: + ```yaml + - name: Setup syft + run: | + curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin + ``` + - For `skopeo` you can use the following script: + ```yaml + - name: Setup skopeo + run: | + sudo apt-get -y update + sudo apt-get -y install skopeo + ``` + +**Procedure** + +1. Add the RHDA scanner to your project's GitHub Actions configuration: + ```yaml + - name: RHDA Scan + id: rhda_scan + uses: RHEcosystemAppEng/rhda-github-action@main + ``` + +**Example** + +This Node.js example shows you how to use the RHDA scanner, and uploading the results to GitHub. ```yaml steps: @@ -87,60 +89,61 @@ steps: id: rhda_scan uses: RHEcosystemAppEng/rhda-github-action@main ``` -The following snapshot is an example of a RHDA run on a Node.js project. +An example screenshot of a Node.js RHDA scan: ![Workflow run](./images/workflow_run.png) ## Action Inputs | Input | Description | Default | | ----- | ----------- | --------- | -| manifest_directory | Path to the directory containing the manifest_file. | -| manifest_file | Name (basename) of the manifest file to analyze. This file must exist in the manifest_directory. | -| rhda_report_name | Name of the file where the Red Hat Dependency Analytics report will be saved. | `redhat-dependency-analytics-report` -| github_token | Github token to upload SARIF file to the GitHub | [`${{ github.token }}`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) -| upload_sarif | Upload the generated SARIF file, by default it is set to "true". If you don't want to upload SARIF file set this input to "false". | `true` -| upload_artifact | Upload the generated RHDA report JSON file and SARIF file as an artifact. | `true` -| artifact_filename | File name of the artifact to upload. By default it is named as 'redhat-dependency-analytics-report' | `redhat-dependency-analytics-report` -| fail_on | Fail the workflow if vulnerability is found in the project. To set failure when vulnerability severity level is either "error" or "warning" set this input to "warning". By default it is set to fail when severity level is "error", or if you don't want to fail the action set this input to "never" | `error` -| use_python_virtual_environment | Automates the installation of missing packages in a Python virtual environment when set to true. | `false` -| use_go_mvs | Use the Minimal Version Selection (MVS) algorithm to select a set of module versions to use when building Go packages. | `false` -| enable_python_best_efforts_installation | Installs Python packages tailored to the Python version in use, disregarding declared versions. Note: Requires settings Match Manifest Versions to be set to false and Use Python Virtual Environment to be set to true. | `false` -| use_pip_dep_tree | Use lightweight pipdeptree command line tool as the data source for building the Python dependency tree. This may significantly enhance analysis time. | `false` -| match_manifest_version | Restricts RHDA from performing analysis on dependency tags that do not match the tags requested within the manifest files. | `false` -| mvn_executable_path | Specifies absolute path of mvn executable. | `mvn` -| gradle_executable_path | Specifies absolute path of gradle executable. | `gradle` -| npm_executable_path | Specifies absolute path of npm executable. | `npm` -| go_executable_path | Specifies absolute path of go executable. | `go` -| python3_executable_path | Specifies absolute path of python3 executable, python3 takes precedence over python. | `python3` -| pip3_executable_path | Specifies absolute path of pip3 executable, pip3 takes precedence over pip. | `pip3` -| python_executable_path | Specifies absolute path of python executable, python3 takes precedence over python. | `python` -| pip_executable_path | Specifies absolute path of pip executable, pip3 takes precedence over pip. | `pip` -| syft_executable_path | Specifies absolute path of syft executable. | `syft` -| syft_config_path | Specifies absolute path to the syft configuration file. | -| skopeo_executable_path | Specifies absolute path of skopeo executable. | `skopeo` -| skopeo_config_path | Specifies absolute path to the authentication file used by 'skopeo inspect'. | -| docker_executable_path | Specifies absolute path of docker executable. | `docker` -| podman_executable_path | Specifies absolute path of podman executable. | `podman` -| image_platform | Specifies platform used for multi-arch images. | +| `manifest_directory` | Path to the directory containing the `manifest_file`. | +| `manifest_file` | Name (`basename`) of the manifest file to analyze. This file must exist in the `manifest_directory`. | +| `rhda_report_name` | The saved file name of the Red Hat Dependency Analytics report. | `redhat-dependency-analytics-report` +| `github_token` | GitHub token to upload a SARIF file to the GitHub. | [`${{ github.token }}`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) +| `upload_sarif` | Upload the generated SARIF file. The default is `true`. If you do not want to upload a SARIF file, then set the input to `false`. | `true` +| `upload_artifact` | Upload the generated RHDA report JSON file and SARIF file as an artifact. | `true` +| `artifact_filename` | File name of the artifact to upload. The default name is, `redhat-dependency-analytics-report`.| `redhat-dependency-analytics-report` +| `fail_on` | A found vulnerability fails the workflow within the project. To fail the workflow when the vulnerability severity level is either `error` or `warning`, set this to `warning`. The default severity level is `error`. If you do not want to fail the action set this input to `never`. | `error` +| `use_python_virtual_environment` | Automates the installation of missing packages in a Python virtual environment when set to true. | `false` +| `use_go_mvs` | Use the Minimal Version Selection (MVS) algorithm to select a set of module versions to use when building Go packages. | `false` +| `enable_python_best_efforts_installation` | Installs Python packages tailored to the Python version in use, disregarding declared versions. This requires setting the `Match Manifest Versions` option to `false`, and the `Use Python Virtual Environment` option to `true`. | `false` +| `use_pip_dep_tree` | Use lightweight `pipdeptree` command line tool as the data source for building the Python dependency tree. This might significantly enhance analysis time. | `false` +| `match_manifest_version` | Restricts RHDA from performing analysis on dependency tags that do not match the tags requested within the manifest files. | `false` +| `mvn_executable_path` | Specifies absolute path of `mvn` binary. | `mvn` +| `gradle_executable_path` | Specifies absolute path of `gradle` binary. | `gradle` +| `npm_executable_path` | Specifies absolute path of `npm` binary. | `npm` +| `go_executable_path` | Specifies absolute path of `go` binary. | `go` +| `python3_executable_path` | Specifies absolute path of `python3` binary, `python3` takes precedence over `python`. | `python3` +| `pip3_executable_path` | Specifies absolute path of `pip3` binary, `pip3` takes precedence over `pip`. | `pip3` +| `python_executable_path` | Specifies absolute path of `python` binary, `python3` takes precedence over `python`. | `python` +| `pip_executable_path` | Specifies absolute path of `pip` binary, `pip3` takes precedence over `pip`. | `pip` +| `syft_executable_path` | Specifies absolute path of `syft` binary. | `syft` +| `syft_config_path` | Specifies absolute path to the Syft configuration file. | +| `skopeo_executable_path` | Specifies absolute path of `skopeo` binary. | `skopeo` +| `skopeo_config_path` | Specifies absolute path to the authentication file used by `skopeo inspect`. | +| `docker_executable_path` | Specifies absolute path of `docker` binary. | `docker` +| `podman_executable_path` | Specifies absolute path of `podman` binary. | `podman` +| `image_platform` | Specifies platform used for multi-arch images. | ## Action Outputs -- **rhda_report_json**: Path to generated Red Hat Dependency Analytics Report in JSON format. -- **rhda_report_sarif**: Path to generated Red Hat Dependency Analytics Report in SARIF format. -- **artifact_id**: ID of the uploaded artifact. +- **rhda_report_json**: Path to the generated Red Hat Dependency Analytics report in JSON format. +- **rhda_report_sarif**: Path to the generated Red Hat Dependency Analytics report in SARIF format. +- **artifact_id**: The identifier of the uploaded artifact. ## Scanning Pull Requests -This action can run RHDA scans on pull requests. Because the action must check out the pull request's code in order to scan it, the [`pull_request_target` trigger](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target) must be used. - -After the RHDA scan is approved and the workflow runs, a label indicating the scan result will be added to the pull request. +
This action can also run RHDA scans on pull requests. +Because the action must check out the pull request's code to scan it, you must use a [`pull_request_target` trigger](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target). -The following snapshot shows vulnerability details in the GitHub UI for a pull request. +
After approving the RHDA scan, the workflow runs, and labels the scanning results to the pull request. +The following screenshot shows vulnerability details in the GitHub UI for a pull request. ![PR vulnerability details](./images/vul_details.png) Use the following snippet to enable pull request scans in your repository: + ``` yaml on: pull_request_target: From d98788d6991fdb5ac3557409abedce2ec2edcd95 Mon Sep 17 00:00:00 2001 From: Aron Gunn Date: Mon, 22 Jul 2024 14:31:57 -0500 Subject: [PATCH 2/4] 7/22/24 - gunnage : Edits from feedback --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e9a79da..f54f4ac 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Red Hat Dependency Analytics GitHub Actions +# Red Hat Dependency Analytics [![CI Checks](https://github.com/RHEcosystemAppEng/rhda-github-action/actions/workflows/ci.yaml/badge.svg)](https://github.com/RHEcosystemAppEng/rhda-github-action/actions/workflows/ci.yaml)
@@ -36,7 +36,7 @@ Repository maintainers can find discovered vulnerabilities on the **Security** t In future releases, Red Hat plans to support other programming languages. -## Configuring RHDA GitHub Actions +## Configuring RHDA GitHub Action You can configure GitHub Actions to use RHDA for your coding environment. You can see [examples of scanning](./.github/workflows) for each supported language, or you can use the [example below](#example). From 281a469b6de220596944c915b1a88ba13c68f232 Mon Sep 17 00:00:00 2001 From: Aron Gunn Date: Mon, 22 Jul 2024 14:33:57 -0500 Subject: [PATCH 3/4] 7/22/24 - gunnage : Edits from feedback --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f54f4ac..abd0409 100644 --- a/README.md +++ b/README.md @@ -137,7 +137,7 @@ An example screenshot of a Node.js RHDA scan:
This action can also run RHDA scans on pull requests. Because the action must check out the pull request's code to scan it, you must use a [`pull_request_target` trigger](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request_target). -
After approving the RHDA scan, the workflow runs, and labels the scanning results to the pull request. +
After the workflow runs, and labels the scanning results to the pull request. The following screenshot shows vulnerability details in the GitHub UI for a pull request. ![PR vulnerability details](./images/vul_details.png) From d146150990d6ffb5cd9aa3967fae13516eb9e0bb Mon Sep 17 00:00:00 2001 From: Aron Gunn Date: Tue, 23 Jul 2024 14:21:39 -0500 Subject: [PATCH 4/4] 7/23/24 - ritz303 : Removed prerequisite heading --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index abd0409..00a37b3 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,7 @@ In future releases, Red Hat plans to support other programming languages. You can configure GitHub Actions to use RHDA for your coding environment. You can see [examples of scanning](./.github/workflows) for each supported language, or you can use the [example below](#example). -**Prerequisites** - -* GitHub Actions configured for your environment: +* GitHub Actions for your environment: - [Go](https://github.com/actions/setup-go) - [Java](https://github.com/actions/setup-java) - [Node.js](https://github.com/actions/setup-node)