|
1 | | -# rhda-github-action |
| 1 | +# Red Hat Dependency Analytics (RHDA) |
2 | 2 |
|
3 | | -This action reflects the Red Hat Dependency Analytics VSCode extension for Github Actions. |
| 3 | +<!-- [](https://github.com/redhat-actions/crda/actions/workflows/ci.yml) |
| 4 | +[](https://github.com/redhat-actions/crda/actions/workflows/link_checker.yml) |
| 5 | +<br> |
| 6 | +<br> |
| 7 | +[](https://github.com/redhat-actions/crda/actions/workflows/scan_go.yml) |
| 8 | +[](https://github.com/redhat-actions/crda/actions/workflows/scan_java.yml) |
| 9 | +[](https://github.com/redhat-actions/crda/actions/workflows/scan_node.yml) |
| 10 | +[](https://github.com/redhat-actions/crda/actions/workflows/scan_python.yml) |
| 11 | +<br> |
| 12 | +<br> |
| 13 | +[](https://github.com/redhat-actions/crda/tags) --> |
| 14 | +[](./LICENSE) |
| 15 | +[](./dist) |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +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. |
| 20 | + |
| 21 | +## What is Supported |
| 22 | + |
| 23 | +| Ecosystem | Required Binaries and Prerequisites | Supported Manifests / Files | |
| 24 | +| --------- | ----------------------------------- | --------------------------- | |
| 25 | +| <a href="https://www.java.com/">Java</a> - <a href="https://maven.apache.org/">Maven</a> | `mvn` | pom.xml | |
| 26 | +| <a href="https://gradle.org//">Gradle</a> - <a href="https://gradle.org/install//">Gradle Installation</a> | `gradle` | build.gradle | |
| 27 | +| <a href="https://www.javascript.com//">JavaScript</a> - <a href="https://www.npmjs.com//">Npm</a> | `npm` | package.json | |
| 28 | +| <a href="https://go.dev//">Golang</a> - <a href="https://go.dev/blog/using-go-modules//">Go Modules</a> | `go` | go.mod | |
| 29 | +| <a href="https://go.dev//">Python</a> - <a href="https://pypi.org/project/pip//">pip Installer</a> | `pip` | requirements.txt | |
| 30 | +| [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 | |
| 31 | +| [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 | |
| 32 | + |
| 33 | +In future releases, Red Hat plans to support other programming languages. |
| 34 | + |
| 35 | +## Configuration |
| 36 | + |
| 37 | +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). |
| 38 | + |
| 39 | +### 1. Set up the tool stack |
| 40 | +Unless already done, you must set up the tool stack for your project depending on the ecosystem you wish to analyse. |
| 41 | + |
| 42 | +Refer to the setup actions for: |
| 43 | + - [Go](https://github.com/actions/setup-go) |
| 44 | + - [Java](https://github.com/actions/setup-java) |
| 45 | + - [Node.js](https://github.com/actions/setup-node) |
| 46 | + - [Python](https://github.com/actions/setup-python) |
| 47 | + |
| 48 | +`syft` and `skopeo` can ge set up using script: |
| 49 | +```yaml |
| 50 | +- name: Setup syft |
| 51 | + run: | |
| 52 | + curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin |
| 53 | +``` |
| 54 | +```yaml |
| 55 | +- name: Setup skopeo |
| 56 | + run: | |
| 57 | + sudo apt-get -y update |
| 58 | + sudo apt-get -y install skopeo |
| 59 | +``` |
| 60 | +
|
| 61 | +### 2. Set up RHDA scan |
| 62 | +Install RHDA from the [**RHEcosystemAppEng/rhda-github-action**](https://github.com/RHEcosystemAppEng/rhda-github-action) GitHub repository. |
| 63 | +
|
| 64 | +```yaml |
| 65 | +- name: RHDA Scan |
| 66 | + id: rhda_scan |
| 67 | + uses: RHEcosystemAppEng/rhda-github-action@main |
| 68 | +``` |
| 69 | +
|
| 70 | +## Example |
| 71 | +
|
| 72 | +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. |
| 73 | +
|
| 74 | +```yaml |
| 75 | +steps: |
| 76 | + - name: Checkout repository |
| 77 | + uses: actions/checkout@v4 |
| 78 | + |
| 79 | + - name: Setup Node.js |
| 80 | + uses: actions/setup-node@v4 |
| 81 | + with: |
| 82 | + node-version: 20 |
| 83 | + |
| 84 | + - name: RHDA Scan |
| 85 | + id: rhda_scan |
| 86 | + uses: RHEcosystemAppEng/rhda-github-action@main |
| 87 | +``` |
| 88 | +The following snapshot is an example of a RHDA run on a Node.js project. |
| 89 | +
|
| 90 | + |
| 91 | +
|
| 92 | +## Action Inputs |
| 93 | +
|
| 94 | +| Input | Description | Default | |
| 95 | +| ----- | ----------- | --------- | |
| 96 | +| manifest_directory | Path to the directory containing the manifest_file. | |
| 97 | +| manifest_file | Name (basename) of the manifest file to analyze. This file must exist in the manifest_directory. | |
| 98 | +| rhda_report_name | Name of the file where the Red Hat Dependency Analytics report will be saved. | `redhat-dependency-analytics-report` |
| 99 | +| 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) <!-- markdown-link-check-disable-line --> |
| 100 | +| 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` |
| 101 | +| upload_artifact | Upload the generated RHDA report JSON file and SARIF file as an artifact. | `true` |
| 102 | +| artifact_filename | File name of the artifact to upload. By default it is named as 'redhat-dependency-analytics-report' | `redhat-dependency-analytics-report` |
| 103 | +| 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` |
| 104 | +| use_python_virtual_environment | Automates the installation of missing packages in a Python virtual environment when set to true. | `false` |
| 105 | +| use_go_mvs | Use the Minimal Version Selection (MVS) algorithm to select a set of module versions to use when building Go packages. | `false` |
| 106 | +| 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` |
| 107 | +| 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` |
| 108 | +| match_manifest_version | Restricts RHDA from performing analysis on dependency tags that do not match the tags requested within the manifest files. | `false` |
| 109 | +| mvn_executable_path | Specifies absolute path of mvn executable. | `mvn` |
| 110 | +| gradle_executable_path | Specifies absolute path of gradle executable. | `gradle` |
| 111 | +| npm_executable_path | Specifies absolute path of npm executable. | `npm` |
| 112 | +| go_executable_path | Specifies absolute path of go executable. | `go` |
| 113 | +| python3_executable_path | Specifies absolute path of python3 executable, python3 takes precedence over python. | `python3` |
| 114 | +| pip3_executable_path | Specifies absolute path of pip3 executable, pip3 takes precedence over pip. | `pip3` |
| 115 | +| python_executable_path | Specifies absolute path of python executable, python3 takes precedence over python. | `python` |
| 116 | +| pip_executable_path | Specifies absolute path of pip executable, pip3 takes precedence over pip. | `pip` |
| 117 | +| syft_executable_path | Specifies absolute path of syft executable. | `syft` |
| 118 | +| syft_config_path | Specifies absolute path to the syft configuration file. | |
| 119 | +| skopeo_executable_path | Specifies absolute path of skopeo executable. | `skopeo` |
| 120 | +| skopeo_config_path | Specifies absolute path to the authentication file used by 'skopeo inspect'. | |
| 121 | +| docker_executable_path | Specifies absolute path of docker executable. | `docker` |
| 122 | +| podman_executable_path | Specifies absolute path of podman executable. | `podman` |
| 123 | +| image_platform | Specifies platform used for multi-arch images. | |
| 124 | + |
| 125 | +## Action Outputs |
| 126 | + |
| 127 | +- **rhda_report_json**: Path to generated Red Hat Dependency Analytics Report in JSON format. |
| 128 | +- **rhda_report_sarif**: Path to generated Red Hat Dependency Analytics Report in SARIF format. |
| 129 | +- **artifact_id**: ID of the uploaded artifact. |
| 130 | + |
| 131 | +## Scanning Pull Requests |
| 132 | + |
| 133 | +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. <!-- markdown-link-check-disable-line --> |
| 134 | + |
| 135 | +After the RHDA scan is approved and the workflow runs, a label indicating the scan result will be added to the pull request. |
| 136 | + |
| 137 | +The following snapshot shows vulnerability details in the GitHub UI for a pull request. |
| 138 | + |
| 139 | + |
| 140 | + |
| 141 | +Use the following snippet to enable pull request scans in your repository: |
| 142 | +``` yaml |
| 143 | +on: |
| 144 | + pull_request_target: |
| 145 | + # These types are all required for RHDA to scan pull requests correctly and securely. |
| 146 | + types: [ opened, synchronize, reopened, labeled, edited ] |
| 147 | +``` |
0 commit comments