NAV Navbar
Logo pro
JSON

Overview

Configuring Puma Scan Professional can be done by editing the Settings.json file in the following directory:

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

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.

NOTE: The VSIX extension will add an Options -> Puma Scan options menu. This is currently under construction. The configuration must be done by editing the Settings.json file directly.

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.

General Settings

The following JSON block shows the general setting options:

"GeneralSettings": {
    "LicenseFileDirectory": "C:\\Users\\BobbyTables\\AppData\\Roaming\\Microsoft\\VisualStudio\\Puma.Security.Rules",
    "DataflowAnaylsisEnabled": true,
    "DataflowAnalysisReportIndeterminates": false,
    "ProductionConfigurationTransform": "Release"
  },

The GeneralSettings section of the Settings.json file contains global options that affect how the scanner works. The following options are supported:

LicenseFileDirectory

Defines the directory that contains the Puma Scan Professional license file. The default location is %appdata%\Microsoft\VisualStudio\Puma.Security.Rules.

NOTE: Double slashes are required to escape the C# escape character (\).

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 in Visual Studio, 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”.

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.

All Rules

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

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

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.

SEC0007 - Forms Authentication: Weak Timeout

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

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.

SEC0017 - Identity Weak Password Complexity

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

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.

SEC0020 - Weak Session Timeout

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

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.

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 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": "*"
}

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

Web

Web Service

Database

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.

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 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:

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 (*).

Custom Tainted Source Example

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);
}

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).

.NET Compiler SDK

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

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

Syntax Visualizer

Figure 2: Syntax Visualizer - Finding the Syntax Type

Figure 3: Syntax Visualizer - Symbol Properties

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

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 2). To locate these values, right click the node in the Syntax Tree and select “View Symbol”. The following properties will provide the remaining fields:

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

Adding A New Tainted Source

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"
    }
]

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

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 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"
  },

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

Data Types

Internal Methods

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:

LDAP Injection Cleanse Methods

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

Unvalidated Redirect Cleanse Methods

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

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.

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

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:

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 (*).

Custom Cleanse Method Example

Prerequisites

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

Adding A New Cleanse Method

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

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

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:

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

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.