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.

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.
Navigate to the Actions section of the GibHub project and edit the .yml file of the workflow.
In the .yml file, locate an appropriate location to download the CLI, such as after the application build is completed.
Insert the following code to the .yml file, which downloads the CLI setup file to $(System.DefaultWorkingDirectory)/tools/clear-cli.zip and extracts its content to $(System.DefaultWorkingDirectory)/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-2309.

Insert the following code to the .yml file, which configures the CLI to use a remote CLEAR Engine host at clear.contoso.com.

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

Start a scan in GitHub Actions

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

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

 - name: Generate scan ID
   run: |
     Write-Output "ScanId=$(New-Guid)" | Out-File -FilePath $Env:GITHUB_ENV -Append
   shell: powershell

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

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

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

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

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

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: Download 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

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
```

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

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

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

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.

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: |
     git config --global user.email "[email protected]"
     git config --global user.name "GitHub Actions"
     git checkout -b scan-$
   shell: powershell
   working-directory: $

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

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

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: |
     git add **/ApplicationProtectionLibrary.jar
     git commit -m "Instant Fixes from scan $"
     git push -u origin scan-$
   shell: powershell
   working-directory: $

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

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