Click here to view special pricing

Puma Scan Configuration Guide

The Puma Scan Professional Edition has many configuration options that allow development teams to control the scanner, rules, edit tainted sources, and edit cleanse methods. The following documentation describes the configuration options and how each one affects the scanning engine.

Configuration Settings

The Puma Scan Professional edition relies on the Settings.json file for configuring the scanner, rule options, custom tainted sources, custom cleanse methods, and suppressing false positives.

Teams customizing the Settings.json file should keep a separate copy in a secure backup location. While we don’t expect future versions, updates, or reinstallation to overwrite your customization, it would be a shame to lose work. Please consider keeping the master Settings.json file in a source control repository to ensure the scanner configuration history is properly tracked.

The following configuration features are available in the profession version only. Community edition users should visit the GitHub Repository to view, fork, and customize the source code directly.

Default Location

End User Edition

The End User Edition creates the Settings.json file with the default settings during the first analysis. To generate this file:

  • Install the Puma Scan Visual Studio extension
  • Open a solution or project to analyze
  • Open Windows explorer and browse to the file location shown in Figure 1.


Server Edition

The Server Edition’s installer creates the Settings.json file during the installation. The Settings.json file is placed in the default installation directory. See Figure 2 for a screenshot.

 

Figure 1: The End User Edition’s Settings.json file is in the following location.

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

Figure 2: The Server Edition’s Settings.json file is in the installation directory selected .

General Settings

The GeneralSettings section of the Settings.json file contains global options that affect how the scanner works. Puma Scan supports the following general configuration options:

DataflowAnalysisEnabled

Puma Scan Professional performs data flow analysis in many analyzers to determine if the source of an input comes from an untrusted source (e.g. request parameter, web service API, etc.). This setting turns the data flow feature on (true) or off (false). If you are experiencing performance issues with Puma Scan, disabling this feature will improve performance. However, more false positives will occur. The default value is true.

DataflowAnalysisReportIndeterminates

Puma Scan Professional performs data flow analysis in many analyzers to determine if the source of an input comes from an untrusted source (e.g. request parameter, web service API, etc.). In some cases, the data flow analyzer may be unable to perform a complete trace and cannot confidently determine if a vulnerability exists. These sinks are marked as indeterminate. This setting tells the scanner if indeterminate issues should be reported in the scan results (true) or be suppressed by the scanner (false). The default is false.

ProductionConfigurationTransform

Puma Scan Professional will perform a web.config transformation prior to running configuration analysis if a transform file exists. This setting tells the analyzer which configuration transform file you would like to use for analysis. For example, if your configuration transform is called “Web.Production.config”, then you should change this setting to “Production”. The default value is “Release”, which tells the analyzers to look for a file called “Web.Release.config”.

 

The following JSON block shows the general setting options:

"GeneralSettings": {
    "DataflowAnaylsisEnabled": true,
    "DataflowAnalysisReportIndeterminates": false,
    "ProductionConfigurationTransform": "Release"
},

Rule Options

The Puma Scan Professional edition provides configuration options for each analysis rule (e.g. SEC0001). The configuration options are defined in the RuleOptions list.

The following configuration features are available in the profession version only. Community edition users should visit the GitHub Repository to view, fork, and customize the source code directly.

All Rules

All analysis rules have the following options:

RiskRating

Sets a risk rating for the rule. The risk rating is displayed in the detailed diagnostic message and used in downstream Puma Scan reports. Options include High, Medium, or Low. The default risk rating is determined per rule by Puma Security application security engineers.

Severity

Sets the build severity for the rule. This setting allows diagnostics to be raised as diagnostics in the Error List Window as an Error, Warning, or Info item. It is important to realize that using the “Error” option will cause the build to break.

Valid options include Error, Warning, or Info. The default severity for all rules in Warning.

Enabled

Turns an analysis rule on (true) or off (false). The default is true.

 

The following example shows the default configuration options that exist for all rules.

{
    "Id": "SEC0001",
    "RiskRating": "Low",
    "Severity": "Warning",
    "Enabled": true
},

SEC0007 - Forms Authentication: Weak Timeout

The following options allow users to configure their forms authentication timeout policy.

TimeoutMax

Defines the maximum forms authentication timeout value (in minutes). The default value is 30.

 

The following example shows the SEC0007 TimeoutMax option for configuration a custom timeout.

{
    "Id": "SEC0007",
    "TimeoutMax": 30,
    "Enabled": true
},

SEC0017 - Identity Weak Password Complexity

The following options allow users to configure their own custom password policy.

Length

Defines the minimum number of characters to require for the password length. The default value is 10.

RequireNumber

Indicates if the password complexity should require a numeric character. The default value is true.

RequireLowerCase

Indicates if the password complexity should require a lower case character. The default value is true.

RequireUpperCase

Indicates if the password complexity should require an upper case character. The default value is true.

RequireSpecialCharacter

Indicates if the password complexity should require a special character. The default value is true.

 

The following example shows the SEC0017 password configuration options.

{
    "Id": "SEC0017",
    "Length": 10,
    "RequireNumber": true,
    "RequireLowerCase": true,
    "RequireUpperCase": true,
    "RequireSpecialCharacter": true,
    "Enabled": true
},

SEC0020 - Weak Session Timeout

The following options allow users to configure their session state timeout policy.

TimeoutMax

Defines the maximum session state timeout value (in minutes). The default value is 30.

 

The following example shows the SEC0020 timeout configuration option.

{
"Id": "SEC0020",
"TimeoutMax": 30,
"Enabled": true
},

Tainted Sources

The Puma Scan Professional Edition scanner performs data flow analysis from data entering a vulnerable sink to the original source of the data. For rules performing data flow analysis, the source type (e.g. request parameter) ultimately determines if a diagnostic is raised by the scanner. The following documentation provides a list of the sources automatically built into the scanner and examples showing how to create custom tainted sources.

Default Tainted Sources

The following tainted sources are built into the scanner out of the box:

Web

  • System.Web.HttpRequest
  • System.Web.UI.Page.Request
  • System.Web.UI.WebControls
  • System.Web.UI.HtmlControls
  • System.Web.Mvc.Controller
  • Microsoft.AspNetCore.Mvc.Controller
  • Microsoft.AspNetCore.Http.Request

Web Service

  • System.ServiceModel.ClientBase
  • System.Web.Services.Protocols.SoapHttpClientProtocol
  • System.Net.Http.HttpClient
  • System.Web.Http.ApiController
  • Microsoft.AspNetCore.Mvc.Controller

Database

  • System.Data.SqlClient.SqlDataReader
  • System.Data.Linq.DataContext
  • System.Data.Entity.DbContext
  • Microsoft.EntityFrameworkCore.DbContext

 

The following example shows a default tainted source that flags all data coming from the System.Web.HttpRequest object as tainted.

{
    "RuleIds": [],
    "Flag": "Web",
    "Syntax": "ElementAccessExpressionSyntax",
    "Namespace": "System.Web",
    "Type": "HttpRequest",
    "Property": "this[]",
    "Method": "*"
}

The following example shows a default tainted source that flags all methods (including the parameters) in classes inheriting from System.Web.Mvc.Controller as tainted.

{
    "RuleIds": [],
    "Flag": "Web",
    "Syntax": "SimpleBaseTypeSyntax",
    "Namespace": "System.Web.Mvc",
    "Type": "Controller",
    "Property": "*",
    "Method": "*"
}

Custom Tainted Sources

The Puma Scan Professional Edition allows users to define custom tainted sources to help identify third party or custom entry points that should be marked as tainted. Common examples include third party frameworks that accept user request data or libraries that retrieve external data from web service APIs.

Custom Tainted Source Schema

The following section describes the schema for adding custom tainted sources to the scanner:

RuleIds

The RuleIds array limits the custom tainted source to a set rule id or ids. The example to the right shows how to limit the custom source to only rule id SEC0106, SEC0107, and SEC0108. The default value is an empty array (e.g. []), which means the new tainted source will apply to all diagnostic rules.

Flag

Logical grouping to help define the custom tainted source. This field is not required for the analyzers to pick up additional sources. Valid options are as follows:

  • None
  • Web
  • Service
  • Database

The default is None.

Syntax

The dotnet compiler API represents the different syntax nodes nodes in a syntax tree with classes inside the Microsoft.CodeAnalysis namespace. This property is required to be set to the appropriate syntax type to register the new custom source with the scanner. For more information on how to locate the correct syntax type, please see Syntax Visualizer section.

Namespace

The namespace containing the custom tainted sources. In the Telerik example to the right, the namespace containing the object to add to the tainted sources list is Telerik.Web.UI. This field is required.

Type

Filters the tainted source in a namespace down to an individual object type. This could also be referred to as the class name. In the example to the right, the tainted sources in the Telerik.Web.UI namespace is filtered down to only instances coming from the RadAutoCompleteBox type. This field is required and supports the wildcard character (*) to tell the scanner to taint all types in a given namespace.

Property

Filters the tainted source in an object down to a specific property (getter / setter). In the example to the right, the tainted source will only come from the “Text” property, which will contain user supplied input. This field is required and supports the wildcard character (*). If identifying a method only (see below), set this field to the wildcard character (*).

Method

Filters the tainted source in an object down to a specific method. This attribute can be used independently of the property field above (e.g., Object.DoSomething()). Or in combination with the property field above to filter a property down to the getter (e.g., “get”) or setter (e.g., “set”). In the example to the right, the tainted source will only come from the “get” method called on the “Text” property. This field is required and supports the wildcard character (*).

 

The following example shows how to create a new tainted source identifying unsafe data coming from the third party Telerik RadAutoCompleteBox control.

{
    "RuleIds": ["SEC0106", "SEC0107", "SEC0108"],
    "Flag": "Web",
    "Syntax": "ElementAccessExpressionSyntax",
    "Namespace": "Telerik.Web.UI",
    "Type": "RadAutoCompleteBox",
    "Property": "Text",
    "Method": "get"
}

Custom Tainted Source Example

Let’s walk through an example showing how to create a custom tainted source. Consider the code snippet to the right. In this example, the GenerateReport method reads a Report from a shared library and passes the data into a vulnerable Entity Framework query. Should this code block raise a SQL Injection warning? Well, it depends on the source of the report.Name data element.

Let’s assume that the Report library is an internal DLL and we don’t have the source code. Puma Scan’s source code analyzer is unable to trace calls into reference DLLs (aka third party libraries) to determine the source of the report data. By default, no warning will be raised.

In cases like this, you need to tell the source code analyzer if specific properties or methods in external libraries should be treated as unsafe (e.g., tainted).

 

The following example shows the GenerateReport GET request action reading a user’s report data and using the Name field to construct a SQL query. While it is obviously vulnerable to SQL Injection, exploiting the issue depends on the source of the Name value.

[HttpGet]
public ActionResult GenerateReport()
{
    //Get report data for the current user
    Guid userId = new Guid(User.Identity.GetUserId());
    Report report = Report.GetReport(userId);

    //Mark the report as generated
    using (var context = new RabbitDBContext())
    {
            string query = string.Format("UPDATE Report SET Status = 1 WHERE Name = {0}", report.Name);
            context.Database.ExecuteSqlCommand(query);
    }

    //Return report data to the view
    return View(report);
}

.NET Compiler SDK

To do this, ensure you have installed the .NET Compiler Platform SDK.

Visual Studio 2017

In Visual Studio 2017, run the Visual Studio Installer, press “Modify”, and browse to “Individual Components > Compilers, Build Tools, and Runtimes”. Select and install the “.NET Compiler Platform SDK” (shown to the right in Figure 3).

Visual Studio 2015

In Visual Studio 2015, this is a Visual Studio Extension available in the Visual Studio Marketplace.

 

Figure 3: Visual Studio 2017 - Adding the Compiler SDK option

Syntax Visualizer

Using the Syntax Visualizer, inspect the tainted source code and identify the syntax type of the custom source. To do this:

  • Open the View > Other Windows > Syntax Visualizer window.
  • Open the document containing the new custom source
  • Highlight the line of code and observe Syntax Visualizer filling in the details
  • Note the Syntax Type (highlighted in red in Figure 4)

In this example, the syntax type is the InvocationExpressionSyntax, which should be entered for new the custom source’s Syntax property.
Next, use the Syntax Visualizer to locate the Namespace, Type, Property, and Method values (highlighted to the right in Figure 5). To locate these values, right click the node in the Syntax Tree and select “View Symbol”. The following properties will provide the remaining fields:

  • Namespace: The ContainingNamespace property will indicate the namespace.
  • Type: The ContainingType property will list the fully qualified type. Use the type name in the last position.
  • Property: The Kind property will guide this value. If the Kind is a Method, then this attribute does not matter. Just enter a wildcard (*) and move on. If the Kind is a Property, then the *Name property will tell you the value to enter.
  • Method: The Kind property will guide this value. If the Kind is a Property, then enter one of the following values: Wildcard (*), “get”, or “set”. If the Kind is a Method, then the Name property will tell you the name of the method.

More details on using the Syntax Visualizer can be found in the Roslyn Documentation.

 

Figure 4: Syntax Visualizer - Finding the Syntax Type*

Figure 5: Syntax Visualizer - Symbol Properties*

Adding A New Tainted Source

Finally, let’s add the new tainted source identifying the Puma.Prey.Common.Report.GetReport method as unsafe.

  • Open the Settings.json file and locate the CustomTaintedSources array.
  • Add a new array and set the required properties.
  • Using the data gathered above in the Syntax Visualizer, enter the values shown in the code snippet shown to the right.
  • Save the Settings.json file
  • Restart Visual Studio for the changes to take effect.

 

The following example shows the new custom tainted source to identify the Puma.Prey.Common.Report.GetReport method as a tainted source.

"CustomTaintedSources": [
    {
        "RuleIds": [] ,
        "Flag": "Web",
        "Syntax": "InvocationExpressionSyntax",
        "Namespace": "Puma.Prey.Common",
        "Type": "Report",
        "Property": "*",
        "Method": "GetReport"
    }
]

Cleanse Methods

The Puma Scan Professional Edition performs data flow analysis from data entering a vulnerable sink back to the original source of the data. For rules performing data flow analysis, data passing through a valid cleanse method will suppress the diagnostic warning. The following documentation provides a list of cleanse methods built into the scanner and examples showing how to create custom cleanse methods.

Default Cleanse Methods

The following cleanse methods are built into the scanner out of the box to suppress diagnostics related to injection vulnerabilities:

Data Types

  • System.Decimal
  • System.Double
  • System.DateTime
  • System.DateTimeOffset
  • System.Int16
  • System.Int32
  • System.Int64
  • System.Guid

Internal Methods

  • System.Convert.ToBoolean
  • System.Convert.ToDateTime
  • System.Convert.ToDecimal
  • System.Convert.ToDouble
  • System.Convert.ToInt16
  • System.Convert.ToInt32
  • System.Convert.ToInt64
  • System.Convert.ToUInt32
  • System.Convert.ToUInt32

Cross-Site Scripting Cleanse Methods

Cross-site Scripting rules (SEC0024, SEC0100, SEC0101, SEC0102, SEC0103, SEC0104, SEC0105) will suppress tainted sources passing through the following methods:

  • Microsoft.Security.Application.Encoder.HtmlEncode
  • System.Web.HttpServerUtility.HtmlEncode
  • System.Text.Encodings.Web.HtmlEncoder.Encode
  • System.Text.Encodings.Web.JavaScriptEncoder.Encode
  • System.Text.Encodings.Web.UrlEncoder.Encode

LDAP Injection Cleanse Methods

LDAP Injection rules (SEC0014) will suppress tainted sources passing through the following methods:

  • Microsoft.Security.Application.LdapFilterEncode
  • Microsoft.Security.Application.LdapDistinguishedNameEncode

Unvalidated Redirect Cleanse Methods

Unvalidated redirect rules (SEC0109, SEC0110) will suppress tainted sources passing through the following methods:

  • System.Web.Mvc.IsLocalUrl
  • System.Uri.TryCreate
  • Microsoft.AspNetCore.Mvc.UrlHelper.IsLocalUrl

 

The following example shows a custom cleanse method that will cleanse XSS tainted source data before raising a diagnostic in cross-scripting rules. The configuration marks data passing through an InvocationExpressionSyntax in the System.Web.Security.AntiXss.AntiXssEncoder.HtmlEncode method as safe.

{
    "RuleIds": ["SEC0024", "SEC0100", "SEC0101", "SEC0102", "SEC0103", "SEC0104", "SEC0105"],
    "Flag": "Web",
    "Syntax": "InvocationExpressionSyntax",
    "Namespace": "System.Web.Security.AntiXss",
    "Type": "AntiXssEncoder",
    "Method": "HtmlEncode"
},

Custom Cleanse Methods

The Puma Scan Professional Edition allows users to define custom cleanse methods to identify security controls within the application and eliminate false positives. Common examples include validation routines and encoding libraries.

Custom Cleanse Method Schema


RuleIds

The RuleIds array limits the custom cleanse methods to a set rule id or ids. The example to the right shows how to limit the custom source to only rule id SEC0024. The default value is an empty array (e.g. []), which means the new cleanse method will apply to all diagnostic rules.

Flag

Logical grouping to help define the custom cleanse methods. This field is not required for the analyzers to pick up new cleanse methods. Valid options are as follows:

  • None
  • Web
  • Service
  • Database

The default is None.

Syntax

The dotnet compiler API represents the different syntax nodes nodes in a syntax tree with classes inside the Microsoft.CodeAnalysis namespace. This property is required to be set to the appropriate syntax type to register the new cleanse method with the scanner. For more information on how to locate the correct syntax type for a given method, please see Syntax Visualizer section.

Namespace

The namespace containing the cleanse method. In the example to the right, the namespace containing the cleanse method is is Microsoft.Security.Application. This field is required.

Type

Filters the cleanse methods in a namespace down to an individual object type. This could also be referred to as the class name. In the example to the right, the class containing the cleanse method in the Microsoft.Security.Application namespace is filtered down to the Encoder class type. This field is required and supports the wildcard character (*) to register all classes in the namespace.

Method

Filters the cleanse method in an class to a specific method name. In the example to the right, the cleanse method is set to HtmlEncode. This field is required and supports the wildcard character (*).

 

The following example shows a custom cleanse method that will cleanse XSS tainted source data before raising a diagnostic in SEC0024. The configuration marks data passing through an InvocationExpressionSyntax in the Microsoft.Security.Application.Encoder.HtmlEncode method as safe.

{
    "RuleIds": ["SEC0024"],
    "Flag": "Web",
    "Syntax": "InvocationExpressionSyntax",
    "Namespace": "Microsoft.Security.Application",
    "Type": "Encoder",
    "Method": "HtmlEncode"
},

Custom Cleanse Method Example

Prerequisites

To create a custom cleanse method, ensure you have done the following:


Adding A New Cleanse Method

Let’s walk through an example showing how to create a custom cleanse method. Consider the code snippet to the right. In this example, the Download method accepts a request parameter called fileName that is eventually concatenated into a file path used to download a file from the file system. Should this code block raise a path tampering vulnerability? Well, it depends on the effectiveness of the Validator.IsValidFilePath method.

During our code review, we determine that the Validator.IsValidFilePath method is using strong whitelist validation to restrict input to alphanumeric characters. But, the Puma Scan analyzer is raising a diagnostic warning because this method is not registered as a valid cleanse method.

In cases like this, you need to tell the source code analyzer that the custom cleanse method mitigates the vulnerability. Doing so will suppress the diagnostic warning if a tainted source passes through the cleanse method.

Let’s add the new cleanse method and prevent the path tampering false positive. To do this:

  • Open the Settings.json file and locate the CustomCleanseMethods array.
  • Use the Syntax Visualizer to find the syntax type of the cleanse method.
  • Fill in the appropriate fields. The example is shown in the snippet to the right and described below.
  • Save the Settings.json file and restart Visual Studio for the changes to take effect.


RuleIds

The path tampering false positive is from rule id SEC0111. As shown in the configuration to the right, add “SEC0111” to the RuleIds array.

Flag

This flag can help with grouping and querying the cleanse methods. In this case, because the cleanse method is in a web entry point, we can set the value to “Web”. You can set this to “None” if you do not want to use this field.

Syntax

Using the Syntax Visualizer, we identified that the invocation of the cleanse method is a InvocationExpressionSyntax type.

Namespace

The namespace containing the path tampering validation method is Puma.Prey.Common.Validation.

Type

The type / class name is Validator.

Method

The cleanse method is called IsValidFilePath.

 

The following code example shows a download method accepting a fileName request parameter, which is then validated by a custom method called Validator.IsValidFilePath.

[HttpPost]
public ActionResult Download(string fileName)
{
    if (!Validator.IsValidFilePath(fileName))
        return new HttpNotFoundResult();

    return new FilePathResult("C:\\temp\\downloads\\" + fileName, "application/octet-stream");
}

The following custom cleanse method removes SEC0111 warnings when source data passes through the Puma.Prey.Common.Validation method.

"CustomCleanseMethods": [
    {
        "RuleIds": [
        "SEC0111"
        ],
        "Flag": "Web",
        "Syntax": "InvocationExpressionSyntax",
        "Namespace": "Puma.Prey.Common.Validation",
        "Type": "Validator",
        "Method": "IsValidFilePath"
    }
]