SCA and Continuous Integration (CI)
  • 11 Jul 2022
  • 5 Minutes to read
  • Dark
    Light
  • PDF

SCA and Continuous Integration (CI)

  • Dark
    Light
  • PDF

The easiest way to perform Software Composition Analysis (SCA) on your applications is to run a command-line tool named pgscan during your build / Continuous Integration (CI) process.

pgscan will scan your just-built code, identify the open-source components that are being used, and publish that information to the ProGet server for further analysis.

This article will explain how pgscan works, where to integrate it into your CI process, and provide a sample PowerShell script.

Identifying Components with pgscan

pgscan is a free and open-source tool that's designed to be run immediately after building your application, generally as part of the Continuous Integration (CI) process.

When run, pgscan will scan the build outputs, identify open-source components in .NET, npm, and Python projects, and then publish that information to your ProGet server. It is available as a standalone tool for Windows/Linux, an installable dotnet tool, or a .NET class library.

HOWTO: Use pgscan Command-line Interface (CLI)

Before installing pgscan on your build server, we recommend create an API Key with "Upload SBOM" permissions for pgscan to use.

The easiest way to install pgscan on your server is by either:

  • Downloading from the GitHub releases page, and saving it in a folder
  • Installing as a dotnet tool using dotnet tool install --global pgscan

Once pgscan is installed, simply invoke the identify command after building your application. For example:

pgscan identify
 --api-key=mySecretKey1000
 --proget-url=https://proget.corp.local/
 --input=MyApplication.csproj 
 --type=nuget
 --project-name="My Application"
 --version=5.00.21

After running this command, pgscan publish the third-party, open-source components found in the application to the target ProGet server.

In the above example, the ProGet server would create a project named MyApplication and publish add those packages to the 5.00.21 release (which it would also create it if it didn't exist).

Note that the project-name and version command-line arguments will generally be passed in as variables from the build/CI process.

See the pgscan GitHub Repository for more details on command-line arguments.

Using CycloneDX Instead of pgscan

If you're already using a tool like CycloneDX in your CI/CD pipeline to generate SBOM documents, you can simply upload those SBOMs to ProGet using the SCA API.

curl 
  -d @output/MySBomFile.xml
  -H "X-ApiKey: mySecretKey1000"
   https://proget.corp.local/api/sca/upload-sbom

Behind the scenes, this is what pgscan identify will do: generate an SBOM file, then uploads it the API.

Integrating psgcan Into Your CI Process

Continuous Integration (CI) is very specific to the technology that your application uses (i.e. .NET, Python, Java, etc.) as well as the CI tool (Jenkins, Azure DevOps, TeamCity, etc.) that you use. However, at a high-level, they all follow a very similar process of retrieving source code, building it, and packaging.

General CI Process

The following steps illustrate a "generic" continuous integration process, and show where you'll want to run pgscan:

  1. Get Source Code; download/retrieve the desired source code from a source control repository like Git
  2. Prepare Source Code; prior to compiling the code, you'll often have steps that will prepare the code so that it can be built by your build tool
    • Modify Source Files; for exampe, editing the AssemblyInfo.cs
    • Restore Packages; using a command like nuget restore, this will download the packages required to build/compile the code from your repository (e.g. ProGet)
  3. Build/Compile Code; using a tool like dotnet build, this will run your build/compilation script
  4. NEW STEP Run pgscan; this will inspect the built/compiled code, generate a SBOM document and publish it to ProGet
  5. Automated Unit Testing; an optional step that involves running code to test your code before it's packaged for deployment
  6. Package/Capture Artifacts; save the required build output (such as .exe) that you will deploy later

Sample PowerShell Script For pgscan

This is a script that you can adapt and incorporate.

# variables set by your CI process
$ProjectPath = "MyDotNetProject1\something.csproj"
$ApplicationName = "MyDotNetProject1"
$ReleaseNumber = "4.3.2"

# configuration
$ProGetBaseUrl = "https://proget.mycompany.corp/"
$ProGetApiKey = "184a14b1-ddef-45e4-8954-4ad159bb5306"

# ensure tha pgscan is installed
dotnet tool install --global pgscan

# run pgscan...
dotnet pgscan identify
 --api-key=$ProGetApiKey
 --proget-url=$ProGetBaseUrl `
 --input=$ProjectPath `
 --type=nuget `
 --project-name=$ApplicationName `
 --version=$ReleaseNumber

Modifying Script for Your CI server

Azure DevOps

Use a local dotnet tool action to run pgscan on Windows and Linux build agents.

  1. Create a ProGet API key
  2. Once the API Key is created in ProGet, you will need to add it as a secrete Variable on your pipeline.
    1. Navigate to your pipeline in Azure DevOps
    2. Click Edit
    3. Click Variables and then the plus icon
    4. Enter a name (ex: PROGETAPIKEY) and your API key as the value
    5. Check "Keep this value Secret"
    6. Click OK
  3. Commit a dotnet tool manifest
    1. At the root of your repository, run dotnet new tool-manifest (see Microsoft's dotnet local tool documentation for more information)
    2. Commit this to your git repository
  4. Add .NET 6.0 in your pipeline
    • If you are already using dotnet 6 in your pipeline, go to the next step.
    • Add the following to your workflow:
    - task: UseDotNet@2
      inputs:
        packageType: 'sdk'
        version: '6.0.x'
    
    • This can be added anywhere before the pgscan steps, but is typically added at the beginning
  5. Add the pgscan steps after build/publish steps of your code
    - script: dotnet tool install pgscan
    - script: dotnet tool run pgscan identify --type=nuget --input=MyProject.csproj --project-name=MyProject --version=1.0.0 --project-type=application --proget-url=https://proget.local --api-key=$(PROGETAPIKEY)
    

GitHub Actions

Use a local dotnet tool action to run pgscan on Windows and Linux build agents.

  1. Create a ProGet API key
    1. Once the API Key is created in ProGet, you will need to add it as a Secret on your GitHub project
    2. Navigate to your project in GitHub
    3. Click "Settings"
    4. Navigate to "Secrets -> Actions" on the right
    5. Click "New repository secret"
    6. Enter a name (ex: PROGETAPIKEY) and your API key as the secret value
  2. Commit a dotnet tool manifest
    1. At the root of your repository, run dotnet new tool-manifest (see Microsoft's local tool documentation for more information)
    2. Commit this to your git repository
  3. Setup .NET 6.0 in your workflow
    • If you are already using dotnet 6 in your workflow, go to the next step.
    • Add the following to your workflow:
        - name: Setup .NET
          uses: actions/setup-dotnet@v2
          with:
            dotnet-version: 6.0.x
    
    • This can be added anywhere before the pgscan steps, but is typically added at the beginning
  4. Add the pgscan steps after build/publish steps of your code
    - name: Install pgscan
      run: dotnet tool install pgscan
    - name: Run pgscan
      working-directory: ProfiteCalcNet.Console
      run: dotnet tool run pgscan identify --type=nuget --input=MyProject.csproj --project-name=MyProject --version=1.0.0 --project-type=application --proget-url=https://proget.local --api-key=${{ secrets.PROGETAPIKEY }}

Was this article helpful?