ReversingLabs provides officially supported GitHub Actions for a faster and easier way to integrate the Spectra Assure Portal with CI/CD workflows.
The rl-scanner-cloud-composite action uses the official reversinglabs/rl-scanner-cloud
Docker image to:
- upload and scan a single build artifact on a Spectra Assure Portal instance;
- display the analysis status as one of the checks in the GitHub interface;
- return the exit status message.
This action is most suitable for users who want to quickly set up a working security scanning solution. If you already manage workflows for different purposes and want to integrate security scanning as a step under specific conditions, try the rl-scanner-cloud-only GitHub Action by ReversingLabs.
Compared to rl-scanner-cloud-only, this action is more convenient out-of-the-box because it scans the artifact and sets the result status all at once.
In the rl-scanner-cloud-only action, everything except the scan has to be provided by the user creating the workflow.
The Spectra Assure Portal is a SaaS solution that's part of the Spectra Assure platform - 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 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.
- Organize your software projects and automatically compare package versions to detect potentially dangerous behavior changes in the code.
- Manage software quality policies on the fly to ensure compliance and achieve maturity in your software releases.
The rl-scanner-cloud-composite action relies on a few different
contexts to access and reuse information across its steps,
and on the following external actions:
- ouzi-dev/commit-status-updater
- actions/upload-artifact
- github/codeql-action/upload-sarif
This action expects that the build artifact is produced in the current workspace before the action is called.
It requires specifying the path of the artifact as the input to the action.
The path must be relative to the github.workspace.
Optionally, users can specify the report directory.
If it is specified, the action saves all supported analysis report formats for the artifact into the directory.
The report directory path must be relative to the github.workspace.
If the report directory is not specified, the action saves the analysis reports into the default directory.
When called, the action runs the following steps:
- Set the commit status to pending.
- Pull the latest version of the
reversinglabs/rl-scanner-cloudDocker image. - Connect to a Spectra Assure Portal instance from the container and upload the artifact to the Portal for scanning.
- Upload the analysis report to GitHub as
report-sha, whereshacorresponds to the SHA identifier of the commit or PR that triggered the action. This makes the report names unique and helps relate them to specific commits if necessary. - Upload the SARIF report file as
report.sarif.jsonto the report directory. - Change the commit status from pending to success/failure depending on the scan result with a descriptive message.
- Return the exit status. This allows controlling any subsequent or dependent tasks; for example, blocking the merge if the status is not "success".
- 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. Alternatively, if you're not a Spectra Assure customer yet, you can contact ReversingLabs to sign up for a Portal account. When you have an account set up, follow the instructions to generate a Personal Access Token.
Note for GitHub Enterprise users: GitHub Actions must be enabled and appropriately configured for the repository where you want to use this action. If you don't have access to the repository settings, contact your GitHub organization administrators for help.
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 Spectra Assure Portal. Before you can use this GitHub Action, you must create the 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 on the level of your GitHub organization or repository.
The most common use-case for this action is to add it to the "test" stage in a workflow, after the build artifact has been created.
To use the Portal security scanning functionality, an active account on a Portal instance is required, together with a Personal Access Token for Portal API authentication.
To compare a new version of an artifact against a previously scanned version, you can use the rl-diff-with parameter when scanning the new version.
Both versions must be in the same Portal project and package.
This comparison is also known as the diff scan.
To perform the diff scan, specify the package URL (purl) of the previously scanned version with the rl-diff-with parameter.
The action will verify that the requested artifact version was actually scanned before on the Portal, and ignore the request for a diff scan if there are no results for the requested package URL.
After a successful diff scan, the analysis report of the new artifact version will contain the Diff tab with all the differences between the two versions. In the Portal web interface, the new version will be marked as "Derived" from the previous version.
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.
If the proxy requires authentication, the proxy credentials for authentication can be configured with rl-proxy-user and rl-proxy-password.
| 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 Spectra Assure. 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. |
rl-submit-only |
No | Set to true to skip waiting for the analysis result. The default is false. |
rl-verbose |
No | Set totrue to provide more feedback in the output while running the scan. The default is false. |
rl-proxy-server |
No | Server URL for proxy configuration (IP address or DNS name). |
rl-proxy-port |
No | Network port on the proxy server for proxy configuration. Required if rl-proxy-server is used. |
rl-proxy-user |
No | User name for proxy authentication. |
rl-proxy-password |
No | Password for proxy authentication. Required if rl-proxy-user is used. |
| Output parameter | Description |
|---|---|
description |
The result of the action - a string terminating in FAIL or PASS. |
status |
The single-word status (as is used by the GitHub Status API), representing the result of the action. It can be any of the following: success, failure, error. Success indicates that the resulting string contains PASS. Failure indicates the resulting string contains FAIL. Error indicates that something went wrong during the scan and the action was not able to retrieve the resulting string. |
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,
and uses the rl-scanner-cloud-composite GitHub action to scan the artifact on the Spectra Assure Portal.
When the scan is done, the GitHub status is updated.
Portal users can then view the analysis report and manage the analyzed file from the Portal web interface or via the Portal APIs like any other package version.
name: ReversingLabs rl-scanner-cloud
run-name: rl-scanner-cloud-composite
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
jobs:
checkout-build-scan-action:
runs-on: ubuntu-latest
permissions:
statuses: write
pull-requests: write
# The next 3 permissions are used for SARIF report upload
security-events: write
actions: read
contents: read
steps:
# Need to check out data before we can do anything
- uses: actions/checkout@v4
# Replace this step with your build process.
# Need to produce one file as the build artifact in scanfile=<relative file path>.
- name: Create the build artifact
id: build
shell: bash
run: |
# Prepare the build process
python3 -m pip install --upgrade pip
pip install example
python3 -m pip install --upgrade build
# Run the build
python3 -m build
# Produce a single artifact to scan and set the scanfile output parameter
echo "scanfile=$( ls dist/*.whl )" >> $GITHUB_OUTPUT
# Use the rl-scanner-cloud-composite action
- name: Scan build artifact on the Portal
id: rl-scan
env:
RLPORTAL_ACCESS_TOKEN: ${{ secrets.RLPORTAL_ACCESS_TOKEN }}
uses: reversinglabs/gh-action-rl-scanner-cloud-composite@v1
with:
rl-verbose: true
rl-portal-server: guidedTour
rl-portal-org: ReversingLabs
rl-portal-group: Demo
rl-timeout: 20
rl-submit-only: false
artifact-to-scan: ${{ steps.build.outputs.scanfile }}
report-path: MyReportsDirectory
rl-package-url: my-project/[email protected]
- The official
reversinglabs/rl-scanner-cloudDocker image on Docker Hub - The official Spectra Assure Portal documentation
- The rl-scanner-cloud-only GitHub Action
- Introduction to secure software release processes with ReversingLabs