Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@rl-devops
rl-devops committed Mar 28, 2024
1 parent f2f3aa1 commit 850d311
Show file tree
Hide file tree
Showing 2 changed files with 19 additions and 19 deletions.
36 changes: 18 additions & 18 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# ReversingLabs GitHub Action: rl-scanner-cloud-only

ReversingLabs provides officially supported GitHub Actions for a faster and easier way to integrate the [secure.software Portal](https://docs.secure.software/portal/) with CI/CD workflows.
ReversingLabs provides officially supported GitHub Actions for a faster and easier way to integrate the [Spectra Assure Portal](https://docs.secure.software/portal/) with CI/CD workflows.

The `rl-scanner-cloud-only` action uses the official [reversinglabs/rl-scanner-cloud](https://hub.docker.com/r/reversinglabs/rl-scanner-cloud)
Docker image to upload and scan a single build artifact on a secure.software Portal instance, generate the analysis report on the Portal, and display the analysis status as one of the checks in the GitHub interface.
Docker image to upload and scan a single build artifact on a Spectra Assure Portal instance, generate the analysis report on the Portal, and display the analysis status as one of the checks in the GitHub interface.

This action is most suitable for experienced users who want to integrate it into more complex workflows.
If you're looking for a solution with more functionality out-of-the-box, try the ReversingLabs [rl-scanner-cloud-composite](https://github.com/reversinglabs/gh-action-rl-scanner-cloud-composite) GitHub Action.


## What is the secure.software Portal?
## What is the Spectra Assure Portal?

The secure.software Portal is a SaaS solution that's part of the [secure.software platform](https://www.secure.software/) - a new ReversingLabs solution for software supply chain security.
The Spectra Assure Portal is a SaaS solution that's part of the [Spectra Assure platform](https://www.reversinglabs.com/products/software-supply-chain-security) - a new ReversingLabs solution for software supply chain security.
More specifically, the Portal is a web-based application for improving and managing the security of your software releases and verifying third-party software used in your organization.

With the secure.software Portal, you can:
With the Spectra Assure Portal, you can:

- Scan your software packages to detect potential risks before release.
- Improve your SDLC by applying actionable advice from security scan reports to all phases of software development.
Expand All @@ -36,13 +36,13 @@ The container connects to a Portal instance and uploads the specified build arti
On the Portal, the artifact is added as a package version to a new or an existing project and package.
When the security scan is done, the container automatically shuts down, and the action outputs the analysis result as a status message (PASS, FAIL, ERROR).

Portal users can then view the analysis report and [manage the analyzed file](https://docs.secure.software/portal/projects#work-with-package-versions-releases) from the Portal web interface or via the Portal Public APIs like any other package version.
Portal users can then view the analysis report and [manage the analyzed file](https://docs.secure.software/portal/projects#work-with-package-versions-releases) from the Portal web interface or via the Portal APIs like any other package version.


## Requirements

1. **An active secure.software Portal account and a Personal Access Token generated for it.** If you don't already have a Portal account, you may need to contact the administrator of your Portal organization to [invite you](https://docs.secure.software/portal/members#invite-a-new-member).
Alternatively, if you're not a secure.software customer yet, you can [contact ReversingLabs](https://docs.secure.software/portal/#get-access-to-securesoftware-portal) to sign up for a Portal account.
1. **An active Spectra Assure Portal account and a Personal Access Token generated for it.** If you don't already have a Portal account, you may need to contact the administrator of your Portal organization to [invite you](https://docs.secure.software/portal/members#invite-a-new-member).
Alternatively, if you're not a Spectra Assure customer yet, you can [contact ReversingLabs](https://docs.secure.software/portal/#get-access-to-securesoftware-portal) to sign up for a Portal account.
When you have an account set up, follow the instructions to [generate a Personal Access Token](https://docs.secure.software/api/generate-api-token).


Expand All @@ -53,13 +53,13 @@ contact your GitHub organization administrators for help.

## Environment variables

This action requires authentication to a secure.software Portal instance with a Personal Access Token.
This action requires authentication to a Spectra Assure Portal instance with a Personal Access Token.
The token must be passed via the environment using the following environment variables.


| Environment variable | Description |
| :--------- | :------ |
| `RLPORTAL_ACCESS_TOKEN` | **Required.** A Personal Access Token for authenticating requests to the secure.software Portal. Before you can use this GitHub Action, you must [create the token](https://docs.secure.software/api/generate-api-token) in your Portal settings. Tokens can expire and be revoked, in which case you'll have to update the value of this environment variable. It's strongly recommended to treat this token as a secret and manage it according to your organization's security best practices. |
| `RLPORTAL_ACCESS_TOKEN` | **Required.** A Personal Access Token for authenticating requests to the Spectra Assure Portal. Before you can use this GitHub Action, you must [create the token](https://docs.secure.software/api/generate-api-token) in your Portal settings. Tokens can expire and be revoked, in which case you'll have to update the value of this environment variable. It's strongly recommended to treat this token as a secret and manage it according to your organization's security best practices. |


ReversingLabs strongly recommends [defining secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow) on the level of your GitHub organization or repository.
Expand Down Expand Up @@ -87,7 +87,7 @@ In the Portal web interface, the new version will be marked as "Derived" from th

## Optional proxy configuration

In some cases, proxy configuration may be required to access the internet and connect to a secure.software Portal instance.
In some cases, proxy configuration may be required to access the internet and connect to a Spectra Assure Portal instance.
You can configure proxy settings with the `rl-proxy-*` parameters for any self-hosted runner, including local GitHub Enterprise setups.

When using the `rl-proxy-server` parameter, you must also specify the port with `rl-proxy-port`.
Expand All @@ -99,11 +99,11 @@ If the proxy requires authentication, the proxy credentials for authentication c

| Input parameter | Required | Description |
| :--------- | :------ | :------ |
| `artifact-to-scan` | **Yes** | The build artifact you want to scan. Provide the artifact file path relative to the `github.workspace`. The file must be in any of the [formats supported by secure.software](https://docs.secure.software/concepts/reference). The file size on disk must not exceed 10 GB. |
| `rl-portal-server` | **Yes** | Name of the secure.software Portal instance to use for the scan. The Portal instance name usually matches the subdirectory of `my.secure.software` in your Portal URL. For example, if your portal URL is `my.secure.software/demo`, the instance name to use with this parameter is `demo`. |
| `rl-portal-org` | **Yes** | The name of a secure.software Portal organization to use for the scan. The organization must exist on the Portal instance specified with `rl-portal-server`. The user account authenticated with the token must be a member of the specified organization and have the appropriate permissions to upload and scan a file. Organization names are case-sensitive. |
| `rl-portal-group` | **Yes** | The name of a secure.software Portal group to use for the scan. The group must exist in the Portal organization specified with `rl-portal-org`. Group names are case-sensitive. |
| `rl-package-url` | **Yes** | The package URL (PURL) used to associate the build artifact with a project and package on the Portal. PURLs are unique identifiers in the format `<project></package><@version>`. When scanning a build artifact, you must assign a PURL to it, so that it can be placed into the specified project and package as a version. If the project and package you specified don't exist in the Portal, they will be automatically created. |
| `artifact-to-scan` | **Yes** | The build artifact you want to scan. Provide the artifact file path relative to the `github.workspace`. The file must be in any of the [formats supported by Spectra Assure](https://docs.secure.software/concepts/reference). The file size on disk must not exceed 10 GB. |
| `rl-portal-server` | **Yes** | Name of the Spectra Assure Portal instance to use for the scan. The Portal instance name usually matches the subdirectory of `my.secure.software` in your Portal URL. For example, if your portal URL is `my.secure.software/demo`, the instance name to use with this parameter is `demo`. |
| `rl-portal-org` | **Yes** | Name of the Spectra Assure Portal organization to use for the scan. The organization must exist on the Portal instance specified with `rl-portal-server`. The user account authenticated with the token must be a member of the specified organization and have the appropriate permissions to upload and scan a file. Organization names are case-sensitive. |
| `rl-portal-group` | **Yes** | Name of the Spectra Assure Portal group to use for the scan. The group must exist in the Portal organization specified with `rl-portal-org`. Group names are case-sensitive. |
| `rl-package-url` | **Yes** | The package URL (purl) used to associate the build artifact with a project and package on the Portal. Package URLs are unique identifiers in the format `<project></package><@version>`. When scanning a build artifact, you must assign a package URL to it, so that it can be placed into the specified project and package as a version. If the project and package you specified don't exist in the Portal, they will be automatically created. |
| `report-path` | No | The directory where the action will store analysis reports for the build artifact. The directory must be empty. Provide the directory path relative to the `github.workspace`. Default value is `MyReportDir`. If you specify an empty string ("") as the value, report downloads will be disabled and no reports will be downloaded.|
| `rl-diff-with` | No | This optional parameter lets you specify a previous version against which you want to compare (diff) the artifact version you're scanning. The specified version must exist in the same project and package as the artifact you're scanning. |
| `rl-timeout` | No | This optional parameter lets you specify how long to wait for analysis to complete before failing (in minutes). The parameter accepts any integer from 10 to 1440. The default timeout is 20 minutes. |
Expand All @@ -127,7 +127,7 @@ If the proxy requires authentication, the proxy credentials for authentication c

The following example is a basic GitHub workflow that runs on pull requests (PRs) and commit pushes to the `main` branch in your repository.

The workflow checks out your repository, builds an artifact, uses the `rl-scanner-cloud-only` GitHub action to scan the artifact on the secure.software Portal, and outputs the analysis results.
The workflow checks out your repository, builds an artifact, uses the `rl-scanner-cloud-only` GitHub action to scan the artifact on the Spectra Assure Portal, and outputs the analysis results.


name: ReversingLabs rl-scanner-cloud only
Expand Down Expand Up @@ -205,6 +205,6 @@ Read more about [storing workflow data as artifacts](https://docs.github.com/en/
# Useful resources

- The official `reversinglabs/rl-scanner-cloud` Docker image [on Docker Hub](https://hub.docker.com/r/reversinglabs/rl-scanner-cloud)
- The official [secure.software Portal documentation](https://docs.secure.software/portal/)
- The official [Spectra Assure Portal documentation](https://docs.secure.software/portal/)
- The [rl-scanner-cloud-composite](https://github.com/reversinglabs/gh-action-rl-scanner-cloud-composite) GitHub Action
- Introduction to [secure software release processes](https://www.reversinglabs.com/solutions/secure-software-release-processes) with ReversingLabs
2 changes: 1 addition & 1 deletion action.yml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# action.yml
name: 'gh-action-rl-scanner-cloud-only'
author: 'ReversingLabs'
description: 'Scan an artifact with ReversingLabs secure.software Portal'
description: 'Scan an artifact with ReversingLabs Spectra Assure Portal'

branding:
icon: 'shield'
Expand Down

0 comments on commit 850d311

Please sign in to comment.