NAV

Getting Started

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

Release Notes

1.0.5

Support has been added for both Visual Studio 2017 and Visual Studio 2015.

Git Issues Closed:

1.0.4

New Rules:

Git Issues Closed:

1.0.3

1.0.2

1.0.1

Version 1.0 is the first official release and includes 42 different secure coding rules targeting C# applications. See the Rules Documentation for details on the current rule support.

Prerequisites

Visual Studio 2015


# 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 versions 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

NuGet

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

To install the Puma Scan NuGet Package for all projects that require analysis, use the Tools > NuGet Package Manager > Package Manager Console and run the command for all projects:

Extension

To use Puma Scan for all projects in the Visual Studio instance, open the Tools menu and select the Extensions and Updates… menu item. In the Online > Visual Studio Galley, search for “Puma Scan” and download the extension.

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

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

To use Puma Scan in Continuous Integration (CI) tools, you must install Puma Scan in each project via the NuGet package. Running the commands from the Package Manager console to install the .NET compilers, CodeAnalysis, and Puma Scan packages will enable scanning in CI/CD pipelines.





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 repo handles parsing the warnings.log file and capturing only the Puma Scan results. 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.

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 the performance of the IDE. 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