ReversingLabs provides officially supported GitHub Actions for faster and easier deployment of the rl-secure solution in CI/CD workflows.

The rl-scanner-only action uses the official reversinglabs/rl-scanner Docker image to scan a single build artifact with rl-secure, generate the analysis report, 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-composite GitHub Action.

rl-secure is a CLI tool that's part of the secure.software platform - a new ReversingLabs solution for software supply chain protection.

With rl-secure, you can:

• Scan your software release packages on-premises and in your CI/CD pipelines to prevent threats from reaching production.
• Compare package versions to ensure no vulnerabilities are introduced in the open source libraries and third-party components you use.
• Prevent private keys, tokens, credentials and other sensitive information from leaking into production.
• Improve developer experience and ensure compliance with security best practices.
• Generate actionable analysis reports to help you prioritize and remediate issues in collaboration with your DevOps and security teams.

The rl-scanner-only action relies on a few different contexts to access and reuse information across its steps.

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 root of the GitHub repository.

Optionally, users can specify the report directory name. If it is specified, the action saves all supported analysis report formats for the artifact into the report directory. The directory path must be relative to the github.workspace.

If the report directory name is not specified, the action saves the analysis reports into the default directory.

When called, the action runs a set of commands that pull the latest version of the reversinglabs/rl-scanner Docker image and scan the provided artifact inside a container. 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).

1. A valid rl-secure license with site key. If you don't already have a site-wide deployment license, follow the instructions in the official rl-secure documentation to get it from ReversingLabs. You don't need to activate the license - just save the license file and the site key for later use. You must convert your license file into a Base64-encoded string to use it with the Docker image.

2. Your rl-secure license information added as secrets to your GitHub organization or repository. Use predefined environment variables to provide the secrets to the action.

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 the rl-secure license data to be passed via the environment using the following environment variables.

ReversingLabs strongly recommends following best security practices and defining these 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 rl-secure security scanning functionality, a valid site-wide deployment license is required. This type of license has two parts: the site key and the license file. ReversingLabs sends both parts of the license to users on request. Users must then encode the license file with the Base64 algorithm. The Base64-encoded license string and the site key must be provided to the action using environment variables.

The action creates the reports in directory: ${{ inputs.report-path }}.

Users can control the report-path as an input parameter.

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, scans it with rl-secure, and displays the analysis results.

name: Example rl-secure workflow
run-name: rl-scanner-only

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:
  checkout-build-scan-only:
    runs-on: ubuntu-latest

    permissions:
      statuses: write
      pull-requests: write

    steps:
      # Need to check out data before we can do anything
      - uses: actions/checkout@v3

      # Replace this with your build process
      # Need to produce one file as the build artifact in scanfile=<relative file path>
      - name: Create 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-only action
      - name: Scan build artifact
        id: rl-scan

        env:
          RLSECURE_ENCODED_LICENSE: ${{ secrets.RLSECURE_ENCODED_LICENSE }}
          RLSECURE_SITE_KEY: ${{ secrets.RLSECURE_SITE_KEY }}

        uses: reversinglabs/gh-action-rl-scanner-only@v1

        with:
          artifact-to-scan: ${{ steps.build.outputs.scanfile }}
          report-path: "My_Report_Dir"

      # The report needs to be displayed even if the scan fails, so we're using a conditional expression to specify that
      - name: Show analysis report
        if: success() || failure()
        shell: bash
        run: |
          ls -la
          ls -l 'My_Report_Dir'

The following example will scan a build artifact called project-1.0.1.tgz and produce the analysis report in ${{ inputs.report-path }}/report that can be picked up from the workspace.

- name: Scan packages with rl-secure
  id: scan
  env:
    RLSECURE_ENCODED_LICENSE: ${{ secrets.RLSECURE_ENCODED_LICENSE }}
    RLSECURE_SITE_KEY: ${{ secrets.RLSECURE_SITE_KEY }}
  uses: reversinglabs/gh-action-rl-scanner-only@v1
  with:
    artifact-to-scan: 'project-1.0.1.tgz'

Use an explicit if condition so that the status always gets extracted if the scan result is PASS or FAIL, as in the following example.

- name: Get the scan status output
  if: success() || failure()
  run: |
    echo "The status is: '${{ steps.scan.outputs.status }}'"
    echo "The description is: '${{ steps.scan.outputs.description }}'"

Use an explicit if condition so that the report always gets uploaded if the scan result is PASS or FAIL, as in the following example.

For this, you need to use the external action actions/upload-artifact.

- name: Archive the report
  if: success() || failure()
  uses: actions/upload-artifact@v3
  with:
    name: report
    path: ${{ inputs.report-path }}

Alternatively, you can use the rl-scanner-composite GitHub Action that provides a more seamless approach than rl-scanner-only. It uploads the report automatically without requiring separate configuration in your workflows. The rl-scanner-composite action also uploads the SARIF report for the analyzed artifacts, allowing you to manage code scanning alerts in your repository.

If you want to use this action in a reusable workflow, keep in mind that such workflows don't share or inherit the workspace with any previous jobs or steps.

This action needs direct access to the build artifact. You can only use it in a reusable workflow if a previous job that builds the artifact also uploads the artifact to GitHub. Then the reusable workflow where you use this action needs to download the artifact and scan it.

Read more about storing workflow data as artifacts in the GitHub documentation.

• The official reversinglabs/rl-scanner Docker image on Docker Hub
• Supported file formats and language coverage for rl-secure
• The rl-scanner-composite GitHub Action
• Introduction to secure software release processes with ReversingLabs
• Software supply chain security for application security teams (link to a PDF document)