Puma Scan Installation Instructions

End User Edition licenses can be installed on up to three (3) workstations owned by a single named user.

Server Edition licenses can be installed on one (1) build server and activated on up to five (5) build agents.

Azure DevOps licenses are priced by the number of pipeline installations. Pricing starts at twenty (20) pipelines with the ability to purchase unlimited.

END USER EDITION

Installation Guide

The Puma Scan End User Edition allows individual users to scan their .NET C# code for vulnerabilities inside of Visual Studio. Puma Scan's security analyzers are installed through a Visual Studio Extension, which is activated by purchasing a license file from pumascan.com. End User license files can be activated on up to three (3) workstations owned by a single user.

Step 1

Purchase Puma Scan End User License

  • Create an account (if you do not have one) at pumascan.com
  • Sign In to pumascan.com
  • Press the Buy Now button to purchase a Puma Scan Pro: End User License

Step 2

Install Visual Studio Extension

  • In Visual Studio, open the Tools menu and select the Extensions and Updates… menu item. NOTE: Visual Studio 2019 moved this menu item to Extensions > Manage Extensions.
  • In the Online > Visual Studio Marketplace, search for “Puma Scan” and download the Puma Scan Professional extension.
  • Close Visual Studio to start the installation wizard.



Step 3

Activate Puma Scan

  • Open Visual Studio and press the PumaScan > Activate Puma Scan menu item. NOTE: Visual Studio 2019 moved the menu item to Extensions > PumaScan > Activate Puma Scan.



  • Enter your Puma Scan username and password and press the Sign In button to view your purchased license files.



  • Find your Puma Scan Pro: End User license in the list and press the Select button.



  • If all went well, you should see a message indicating the activation was successful.

  • You can verify the your license was download into the %appdata%\PumaSecurity\PumaScan directory.

Step 4

Enable Full Solution Analysis

Starting with Visual Studio 2015 Update 3, live code analysis in the IDE is disabled by default to improve performance. For the rules to execute against your code, do the following (see image below for details):

  • Open the Tools > Options dialog box
  • Choose Text Editor > C# > Advanced
  • Check the “Enable full solution analysis” option



  • You are now ready to open a solution and look for Puma Scan warnings in Visual Studio.

Step 5

Optional: Enable Additional File Analysis

To enable Puma’s non-code file analyzers (e.g. configuration and view markup files), you must manually edit each project file (.csproj and .vbproj) and add a new “AdditionalFileItemNames” element to the project’s main “PropertyGroup”.

The following XML snippet shows an example project file’s main “PropertyGroup” with the required “AdditionalFileItemNames” element adding all content files for analysis.

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
   <PropertyGroup>
      <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
      <Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
      ...
      <!-- ADD THE FOLLOWING NEW ELEMENT -->
      <AdditionalFileItemNames>$(AdditionalFileItemNames);Content</AdditionalFileItemNames>
   </PropertyGroup>

You must do this for every project (.csproj, .vbproj) file in a solution.

After enabling the non-code file analyzers, you will notice there are still some limitations for analysis in non-code files:

  • Error list navigation (e.g. double clicking on the warning) to a non-code file is not supported. For now, Puma inserts the file path and offending line of code in the diagnostic message displayed in the error list.

  • Non-code files do not have the same “spellcheck” support as code files. (e.g. no light bulbs, squiggles, or code fix suggestions)

  • Rule suppression for non-code warnings is documented in the User Guide.

  • More details on this limitation and related ticket to treat non-code files as first class citizens can be found here: https://github.com/dotnet/roslyn/issues/11097

Step 6

Optional: Puma Prey Test Scan

To verify your installation is successful, feel free to scan our Puma Prey vulnerable application. This source code contains a number of vulnerabilities that will cause Puma Scan analysis results to appear in the Error List Window.

  • Clone the puma-prey repository to your local development machine, as shown in the following git clone command:

      git clone https://github.com/pumasecurity/puma-prey.git
    
  • In Visual Studio, open the PumaPrey.sln file.

  • Wait a few moments for Puma Scan to display vulnerabilities in the Error List window. See the following image for an example.

Step 7

Optional: Puma Scan Custom Configuration

After Puma Scan successfully runs for the first time, the AppData’s PumaScan directory will contain a Settings.json file. The Settings.json file contains all of the configuration options for controlling how Puma Scan runs. The JSON can also be stored in an individual application’s root directory as a .pumafile for application-specific settings. See the User Guide for details on configuring Puma Scan.

You must restart Visual Studio after modifying the Settings.json file for configuration changes to take effect.

SERVER EDITION

Installation Guide

The Puma Scan Server Edition allows development teams to scan their .NET C# code for vulnerabilities in their build pipelines. Puma Scan's security analyzers are installed on the build server, which is activated by purchasing a server edition license file from pumascan.com. Server Edition license files can be activated on up to five (5) build agents. Additional build agents can be purchased in packages of five (5) to meet your needs.

Step 1

Purchase Your License File

  • Create an account (if you do not have one) at pumascan.com
  • Sign In to pumascan.com Portal
  • Press the Buy Now button to purchase a Puma Scan Pro: Server License
  • Browse to the My Profile screen to confirm your license details.

Step 2

Download Installer Package

  • Sign In to pumascan.com
  • Browse to the My Profile screen
  • Press the Downloads tab to view and download the latest installer package

Step 3

Build Agent Prerequisites

The Puma Scan Server Edition currently only supports Windows build agents. The installer will automatically install the following packages during installation if they do not exist:

  • .NET Framework 4.7.1

The installer will prompt the user to manually install the following packages and the server edition will not run correctly until the packages exist:

  • Build Tools for Visual Studio 2017

    • To install the Build Tools, browse to the Downloads For Visual Studio screen.

    • In the All Downloads list, locate the Build Tools for Visual Studio 2017 item and press the download button.

    • Run the Build Tools installer and select the following options:

      • Workloads: .NET Core Build Tools



      • Individual Components: NuGet Targets and Build Tasks
      • Individual Components: Static analysis tools

Step 4

Run Installer Package

  • Browse to the Downloads directory and run the PumaScanPro_ServerEdition_X.Y.Z.exe installation package.

Step 5

Complete The Installation Wizard

  • Start by pressing the Install button.



  • To install Puma Scan Professional, you are required to accept the End User License Agreement (EULA). You can view the full EULA here. Then press Next.



  • Enter your Puma Scan username and password and press the Sign In button to view your purchased license files.



  • Find your Puma Scan Pro: Server Edition license in the list and press the Select button.



  • If all went well, you should see a message indicating the activation was successful. You can verify the your license was download into the %appdata%\PumaSecurity\PumaScan directory. Then, press Next.


  • The installer defaults to C:\Program Files (x86)\Puma Security\Puma Scan Pro for the installation directory. To avoid permissions problems and path errors invoking the analyzers from the command line, we recommend installing the Puma Scan Server Edition into the tools directory used by your build agent. Avoid using whitespace in the directory name. For example, a recommend install path for a hosted Azure DevOps build agent would be C:\TfsBuildAgent\externals\puma-scan-pro\



  • Press Next to complete the installation wizard and ensure no errors occur during the install.
  • View the User Guide to start scanning!

AZURE DEVOPS EDITION

Installation Guide

The Puma Scan Azure DevOps Edition allows the Puma Scan analyzers to be run inside cloud-hosted Azure DevOps pipelines. DevOps teams install the Puma Scan Azure DevOps extension, add the build task to a pipeline, and purchase an Azure DevOps license from pumascan.com. Azure DevOps Edition licenses are priced by the number of pipelines starting a five (5). Additional pipelines can be purchased in packages of five (5) to meet your needs.

Step 1

Purchase an Azure DevOps License

  • Create a Puma Scan Account (if you do not already have one)
  • Sign In to pumascan.com.
  • Press the Buy Now button and purchase a Puma Scan Pro: Azure DevOps License
  • Browse to the My Profile screen to view your license(s)
  • Copy your Azure DevOps license information to the clipboard by pressing the Copy button.

Step 2

Install Puma Scan Azure DevOps Extension

  • Open a browser and sign in to your Azure DevOps organization
  • Navigate to the Organization settings > Extensions
  • Click the Browse Marketplace link to view the marketplace.



  • Search for “Puma Scan” in the Azure DevOps Extension Marketplace.
  • Open the Puma Scan Professional Azure DevOps extension and press the Get button.



  • Confirm the installation by selecting the appropriate organization and pressing the Install button.



  • Use the Proceed to organization button and view the Organization settings > Extensions screen again to confirm the Puma Scan extension was successfully installed.

Step 3

Configure The Puma Scan Azure DevOps License

  • Select the build pipeline you will be adding the Puma Scan extension and use the Edit button to modify the pipeline.

  • Edit the build pipeline variables and add a new variable:

  • Set the value of the variable name to PumaLicense.

  • Paste the your Puma Scan Azure DevOps license (copied to the clipboard in Step 1 above) into the Value field.

  • Press the lock icon to protect the secret value.

Step 4

Configure The Puma Scan Build Task

  • Add a new Puma Scan Professional task by pressing the plus button.



  • Search for the Puma Scan Professional build task and press the Add button.

  • Select and configure the Puma Scan Professional Build Task by setting the following values:
    • Path to Solution File: Relative path to the solution or project file to scan.
    • Scan Results Format: Select one or more output result formats. Options include HTML, JSON, and MSBuild.
    • Path to Output File: Relative path and base name of the output files. The extension will be automatically added based on the formats selected above.
    • Path to Settings file: Relative path to the .pumafile (settings file) in the source control repository. This file includes the scanner configuration, custom sources, cleanse methods, and exceptions for the given application.
    • Puma Scan License: Reference the name of the pipeline variable containing your license information. If you followed the instructions above, this value should be $(PumaLicense).
    • Verbose: Tells the scanner to write verbose output to the console when the build task runs.

Step 5

Execute Your Build Pipeline

  • Execute the build pipeline and wait for the tasks to finish.
  • Review the build logs and ensure the Puma Scan Professional task successfully completed.

  • Click on the Puma Scan Professional task to view the build output.

Step 6

Activating New Pipelines

  • Puma Scan’s Azure DevOps edition pricing is based on the number of pipelines using the extension. New pipelines will be activated the first time the pipeline is executed. When activating a new pipeline, the Puma Scan task will fail.

  • To finish activating the new pipeline, click the title of the build task (e.g. Puma Scan Professional in the screenshot below) to view build logs. Find the following message in the console output and copy the new the license data JSON (including the curly braces) onto the clipboard:

      2019-01-02T18:22:00.9329278Z ERROR: License does not have the activation data for the requested Azure DevOps pipeline.
      2019-01-02T18:22:00.9331080Z The Azure DevOps pipeline has been automatically activated. Please use the following license data: {'LicenseData':'...','Signature':'...'}
    
  • Edit the build pipeline and view the pipeline variables again.

  • Find the PumaLicense variable and press the lock icon to unlock the value.

  • Paste the your Puma Scan Azure DevOps license data (copied to the clipboard from the build logs above)into the Value field.

  • Press the lock icon to protect the new secret value and save the pipeline.

  • Queue the pipeline again and verify the Puma Scan build task completes successfully.

Step 7

Puma Scan Results and Build Artifacts

  • View the build pipeline Summary tab to view the artifacts, warnings, and Puma Scan Pro summary.

  • View the build pipeline Puma Scan Pro tab to view the detailed scan results.

  • Download the Puma Scan vulnerability reports using the build Artifacts dropdown list.

  • View the User Guide to start scanning!

Want to collect more data? Check out our Server Data Plans.

 

Contact Us

650 S Prairie View Dr.
Suite 125, #151
West Des Moines, IA 50266
Technical or Installation Questions
support [at] pumascan [dot] com
More information or to get a quote
sales [at] pumascan [dot] com
Your message has been sent. Our team will contact you shortly.
There was an error sending your message. Please contact support for assistance.
Please enter your name.
Please enter your email address.
Please enter a subject.
Please enter a message.