NAV Navbar
Logo pro

Professional Edition

The following instructions will get your development teams up and running with the Puma Scan Professional Edition. In less than 15 minutes, the Puma’s static analysis rules can be running as code is written within your organization.

Release Notes

0.5.2

Version 0.5.2 is a patch release to fix the following items:

0.5.1

Version 0.5.1 is a patch release to fix the following items:

0.5

Version 0.5 is the first official professional beta release and includes the following advanced features:

See the Rules Documentation for details on the current rule support.

Prerequisites

Visual Studio


# Chocolatey powershell command to install VS 2015Community edition
choco install visualstudio2015community

# Chocolatey powershell command to updgrate to VS 2015 Community edition
choco upgrade visualstudio2015community

Roslyn code analyzer extensions are supported by Visual Studio 2015 and higher. Either install Visual Studio Community or a licensed version from your MSDN Subscription account.

Alternatively, PC’s configured with the Chocolatey can install the Visual Studio Community package.

Installation

Visual Studio Extension

The Puma Scan Professional Visual Studio Extension installs the security rules in a single instance of Visual Studio on a users local workstation. A single user license is allowed to be installed on up to three (3) workstations owned by an individual.

To install the Visual Studio extension, open the Tools menu and select the Extensions and Updates… menu item. In the Online > Visual Studio Marketplace, search for “Puma Scan Professional” and download the extension.

NuGet

Installing the Puma Scan Professional NuGetPackage on all projects in a solution:

PM > Get-Project -All | Install-Package Puma.Security.Rules.Pro

The Puma Scan Professional NuGet Package installs the security rules

To install the security rules via the NuGet package for all projects in a solution, use the Tools > NuGet Package Manager > Package Manager Console. Run the command shown to the right.

MSBuild

Installing Puma Scan to run during calls to MSBuild:

PM > Get-Project -All | Install-Package Microsoft.Net.Compilers
PM > Get-Project -All | Install-Package Microsoft.CodeAnalysis
PM > Get-Project -All | Install-Package Puma.Security.Rules.Pro

Example command to invoke MSBuild in a Jenkins task and output the warnings log file.

MSBuild.exe /p:DeployOnBuild=true /p:Configuration=Release /p:OutDir=../Publish /fl1 /fl2 /fl3 /flp1:logfile=build.log /flp2:logfile=build_errors.log;errorsonly /flp3:logfile=build_warnings.log;warningsonly %WORKSPACE%\WidgetTown.sln

Shell command to invoke the Puma Parser utility and export Puma Scan warnings to the puma_warnings.log file.

"C:\Program Files\dotnet\dotnet.exe" "C:\Tools\Puma.Security.Parser\Puma.Security.Parser.dll" --file "%WORKSPACE%\build_warnings.log" --workspace "%WORKSPACE%" --output puma_warnings.log

The Puma Scan Professional Continuous Integration (CI) license allows the security rules to be run in a build pipeline for an unlimited number of projects.

Run the commands from the Package Manager console to install the .NET Compiler, Code Analysis, and Puma Scan Professional packages. This will allow the security rules to execute during calls to MSBuild.





From a CI server (e.g. Jenkins) run MSBuild using a command similar to the one shown here. This will produce a warnings.log file, which contains all of the build warnings. This file contains all of the Puma Scan findings.




The Puma Parser utility in the public repository parses the warnings.log file and captures the Puma Scan results to a new MSBuild formatted file. Running this command in a new CI step allows you to process the Puma Scan results and set thresholds to meet your organizations risk tolerance.

License File

The Settings.json file identifies the directory that contains the license file.

{
  "GeneralSettings": {
    "LicenseFileDirectory": "C:\\Users\\Bobby\\Licenses"

Upon purchasing Puma Scan Professional, you will receive a license file to install on a workstation (for user licenses) or server (for CI licenses) running the security rules.

To install the license file, save the file into the default data directory:

%appdata%\Microsoft\VisualStudio\Puma.Security.Rules

Or, modify the Settings.json file located in the settings directory above. Change the GeneralSettings:LicenseFileDirectory property to the directory containing your license file. NOTE: The backslash must be escaped in the path (eg. \ instead of \).

See the Configuration Documentation for the full documentation.

Full Solution Analysis

Figure 1: Enabling full solution analysis

Starting with Visual Studio 2015 Update 3, live code analysis in the IDE disabled by default to improve performance. For the rules to execute against your code, do the following. See Figure 1 for details.

Additional File Analysis

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>
    <ProductVersion></ProductVersion>
    <SchemaVersion>2.0</SchemaVersion>
    <ProjectGuid>{C4DAED55-B428-4A9E-9664-2FCB2EB39D4E}</ProjectGuid>
    <ProjectTypeGuids>{349c5851-65df-11da-9384-00065b846f21};{fae04ec0-301f-11d3-bf4b-00c04f79efbc}</ProjectTypeGuids>
    <OutputType>Library</OutputType>
    <AppDesignerFolder>Properties</AppDesignerFolder>
    <RootNamespace>MyAwesomeProject</RootNamespace>
    <AssemblyName>MyAwesomeProject</AssemblyName>
    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
    <MvcBuildViews>false</MvcBuildViews>
    <UseIISExpress>true</UseIISExpress>
    <IISExpressSSLPort>44300</IISExpressSSLPort>
    <IISExpressAnonymousAuthentication />
    <IISExpressWindowsAuthentication />
    <IISExpressUseClassicPipelineMode />
    <!-- NEW ADDITIONAL FILE NAMES ELEMENT -->
    <AdditionalFileItemNames>$(AdditionalFileItemNames);Content</AdditionalFileItemNames>
    <TargetFrameworkProfile />
  </PropertyGroup>

Puma’s non-code file analyzers (e.g. configuration and view markup files) rely on Roslyn’s additional files feature, which is not currently enabled by default. To enable additional file analysis, you must manually edit each project file (.csproj and .vbproj) and add a new “AdditionalFileItemNames” element to the project’s main “PropertyGroup”. See the associated code examples for details.

Currently, Puma creates an Information diagnostic alerting users about any project files that do not have additional file analysis enabled.

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

More details on enhancing Roslyn and Visual Studio to treat non-code files as first class citizens can be found here: https://github.com/dotnet/roslyn/issues/11097