Use Lucent Sky AVM with GitHub Actions

This article describes how to integrate Lucent Sky AVM with GitHub Actions. By integrating Lucent Sky AVM with an application's continuous integration pipelines, developers can ensure that only code changes meeting the security standards are committed or deployed.

The Lucent Sky AVM CLI commands used in this article favor simplicity over scalability. For example, asynchronous methods such as BeginAnalyze might be more suitable than their synchronous counterparts when working with a large application. To learn about more advanced functionalities of the CLI, view the following article in the Lucent Sky Knowledge Base:
Lucent Sky AVM CLI reference

In this article, you will learn how to:

• Prepare Lucent Sky AVM CLI for use in GitHub Actions.
• Start a scan in GitHub Actions.
• Download and evaluate a scan report in GitHub Actions.
• Download the remediated source code and create a pull request in GitHub Actions.

At the end, you will be use Lucent Sky AVM in GitHub Actions to start a scan, download and evaluate reports, and work with remediated source code in GitHub Actions.

Prepare Lucent Sky AVM CLI for use in GitHub Actions

Lucent Sky AVM CLI needs to be downloaded to the GitHub Actions runner before it can be used. How the CLI is downloaded varies and depends on each organization's needs and requirements, and the CLI might already be present if using a self-hosted runner.

For macOS or Ubuntu runners, the scripts in this article may need to be modified to prepend mono before calls of Lucent Sky AVM CLI executable. For example, mono ./SkyAnalyzer.Interface.Console.exe.

To learn more about how to install Lucent Sky AVM CLI on different operating systems, view the following article in the Lucent Sky Knowledge Base: Administration guide to Lucent Sky AVM CLI

1. Navigate to the Settings > Secret section of the GitHub project. Create a repository secret named ApiKey with the value of an API key to the Lucent Sky AVM server.

2. Navigate to the Actions section of the GibHub project and edit the .yml file of the workflow.

3. In the .yml file, locate the env section and add the following variables:

    env:
      # Replace <InstanceFqdn> with the FQDN or IP address of the Lucent Sky AVM instance
      InstanceFqdn: <InstanceFqdn>
      # Replace <ApplicationId> with the value of the project's application ID on the Lucent Sky AVM instance
      ApplicationId: <ApplicationId>
   

4. In the .yml file, locate an appropriate location to download the CLI, such as after the application build is completed.

5. Insert the following code to the .yml file, which downloads the CLI setup file to $Env:RUNNER_TOOL_CACHE/tools/clear-cli.zip and extracts its content to $Env:RUNNER_TOOL_CACHE/tools/clear-cli.

    - name: Download CLI
      run: |
        Invoke-WebRequest -Uri 'https://lsky.co/clearcli' -OutFile "$Env:RUNNER_TOOL_CACHE/clear-cli.zip"
        Expand-Archive -Path "$Env:RUNNER_TOOL_CACHE/clear-cli.zip" -DestinationPath "$Env:RUNNER_TOOL_CACHE/clear-cli"
        Remove-Item -Path "$Env:RUNNER_TOOL_CACHE/clear-cli.zip"
      shell: powershell
   

   The URL https://lsky.co/clearcli points to the latest Lucent Sky AVM CLI. To pin the CLI to a specific version, append -version after the URL. For example, https://lsky.co/clearcli-2406.

6. Insert the following code to the .yml file, which configures the CLI to use a remote Lucent Sky AVM instance.

    - name: Configure CLI
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        ./SkyAnalyzer.Interface.Console.exe --Interface config --Method set --Value "endpoint = $:5759"
      shell: powershell
   

Start a scan in GitHub Actions

1. Open the .yml file of the workflow, and locate an appropriate location to start the scan, such as after the build artifacts are available.

2. Insert the following code to the .yml file, which generates a random scan ID.

    - name: Generate scan ID
      run: |
        # Replace <> with the 
        Write-Output "ApplicationId=<ApplicationId>" | Out-File -FilePath $Env:GITHUB_ENV -Append
        Write-Output "ScanId=$(New-Guid)" | Out-File -FilePath $Env:GITHUB_ENV -Append
      shell: powershell
   

3. Insert the following code to the .yml file, which creates a scan under the application on Lucent Sky AVM server, and uploads the build artifact for analysis.

    - name: Create and start scan
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method Create --ApplicationId $ --ScanId $
        ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method Analyze --ScanId $ --SourceCodePath "$Env:GITHUB_WORKSPACE/target/ContosoWeb.war"
      shell: powershell
   

4. Insert the following code to the .yml file, which checks the scan result code to determine if the scan was completed successfully.

    - name: Get scan result
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        $scanResult = ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method GetResult --ScanId $
        if ($scanResult -lt 0) { [Console]::Error.WriteLine("Scan failed ($scanResult)"); exit $scanResult }
      shell: powershell
   

Download and evaluate a scan report in GitHub Actions

1. Open the .yml file of the workflow, and locate an appropriate location to evaluate the scan report, such as after the scan is completed.

2. Insert the following code to the .yml file, which generates and downloads the XML report of the scan.

    - name: Download XML report
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method Report --ScanId $ --ReportPath "$Env:RUNNER_TEMP/ScanResults/Xml-Report.zip" --ReportFormat xml
      shell: powershell
   

3. Insert the following code to the .yml file, which extracts the XML report.

    - name: Extract XML report
      run: |
        Expand-Archive -Path "$Env:RUNNER_TEMP/ScanResults/Xml-Report.zip" -DestinationPath "$Env:RUNNER_TEMP/ScanResults"
      shell: powershell
   

4. Insert the following code to the .yml file, which queries the XML report to evaluate if the scan has found any vulnerability with a priority score of 2 or higher.

    - name: Query XML report
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        $resultCount = ./SkyAnalyzer.Interface.Console.exe --Interface Query --Method Execute --QueryDataSource "$Env:RUNNER_TEMP/ScanResults/Report.xml" --QueryStatement "SELECT COUNT(ID) FROM Results WHERE PRIORITY <= 2"
        Write-Output "ResultCount=$resultCount" | Out-File -FilePath $Env:GITHUB_ENV -Append
      shell: powershell
   

5. Insert the following code to the .yml file, which publishes the build artifact as a pipeline artifact named war if no vulnerability with a priority score of 2 or higher was found.

    - uses: actions/upload-artifact@v2
      if: ${{ env.ResultCount == 0 }}
      with:
        name: 'war'
        path: $/target/ContosoWeb.war
   

6. Insert the following code to the .yml file, which generates and downloads the HTML report when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Download HTML report
      if: ${{ env.ResultCount > 0 }}
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method Report --ScanId $ --ReportPath "$Env:RUNNER_TEMP/ScanResults/Html-Report.zip" --ReportFormat html
      shell: powershell
   

7. Insert the following code to the .yml file, which extracts the HTML report when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Extract HTML report
      if: ${{ env.ResultCount > 0 }}
      run: |
        Expand-Archive -Path "$Env:RUNNER_TEMP/ScanResults/Xml-Report.zip" -DestinationPath "$Env:RUNNER_TEMP/ScanResults"
      shell: powershell
   

8. Insert the following code to the .yml file, which publishes the HTML report as a pipeline artifact named report when at least one vulnerability with a priority score of 2 or higher was found.

    - uses: actions/upload-artifact@v2
      if: ${{ env.ResultCount > 0 }}
      with:
        name: 'report'
        path: $/ScanResults/Report.html
   

Download the remediated source code and create a pull request in GitHub Actions

1. Open the .yml file of the workflow, and locate an appropriate location to work with the remediated source code, such as after the pipeline failed security policy evaluation.

2. Insert the following code to the .yml file, which configures Git on the GitHub Actions runner and creates a branch for the remediated source code when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Configure Git
      if: ${{ env.ResultCount > 0 }}
      run: |
        # Replace <UserEmail> with the user email to use for Git
        $UserEmail = "<UserEmail>"
        # Replace <UserName> with the user name to use for Git
        $UserName = "<UserName>"
        git config --global user.email "$UserEmail"
        git config --global user.name "$UserName"
        git checkout -b scan-$
      shell: powershell
      working-directory: $
   

3. Insert the following code to the .yml file, which generates and downloads the remediated source code when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Download remediated source code
      if: ${{ env.ResultCount > 0 }}
      run: |
        cd "$Env:RUNNER_TOOL_CACHE/clear-cli"
        ./SkyAnalyzer.Interface.Console.exe --Key $ --Interface Scan --Method Remediate --ScanId $ --RemediatedSourceCodePath "$Env:RUNNER_TEMP/ScanResults/RemediatedSource.zip" --RemediationOption 0
      shell: powershell
   

4. Insert the following code to the .yml file, which extracts the remediated source code over the original source code when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Extract remediated source code
      if: ${{ env.ResultCount > 0 }}
      run: |
        Expand-Archive -Path "$Env:RUNNER_TEMP/ScanResults/RemediatedSource.zip" -DestinationPath "$Env:GITHUB_WORKSPACE"
      shell: powershell
   

5. Insert the following code to the .yml file, which commits the remediated source code to a branch when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Commit and push remediated source code
      if: ${{ env.ResultCount > 0 }}
      run: |
        # Replace <AplPath> with Application Protection Library files suitable for the framework of the project
        AplPath="<AplPath>"
        git add **/$AplPath;
        git commit -m "Instant Fixes from scan $"
        git push -u origin scan-$
      shell: powershell
      working-directory: $
   

6. Insert the following code to the .yml file, which fails the pipeline when at least one vulnerability with a priority score of 2 or higher was found.

    - name: Fail pipeline
      if: ${{ env.ResultCount > 0 }}
      run: |
        [Console]::Error.WriteLine('This build did not pass the scan criteria.')
        exit -1
      shell: powershell
   

7. Navigate to the Pull requests section of the GitHub project, and create a pull request from the branch containing the remediated source code.