Security Developer Guideline

[Assafv]

Microsoft's best practices for building custom visuals in PowerBI

Power BI enables developers to build their own custom visuals, and to visualize their business metrics the way they want them to be. 

As a developer of custom visuals, you need to be aware of the security implications and take steps to make sure your visuals are as secure as possible. 

Here are a few of the common web-based threats you should be aware of: 

• Data leakage
• XSS attack
• Session hijack
• Malicious infected files

Power BI infrastructure and iframe sandboxing, along with today's browsers security, blocks most malicious attacks, but there are several precautions you can take to increase security even more. 

Packages

Before building a custom visual, you should consider the quality and popularity of packages and libraries you want to utilize. 

Although there’s no strict policy about importing 3rd party vendor's libraries, we still review all packages before approving them. 

There could be many security issues for an unknown package, so it’s worthwhile to use Microsoft's recommended packages, such as D3, for creating graphics and charts, or Bootstrap if you want a modern CSS look and feel. 

  

Install an external JavaScript library by using any package manager (such as npm, yarn, etc.). 

To install external libraries onto a custom visual, please visit the following link for more information:

https://github.com/Microsoft/PowerBI-visuals/blob/master/Tutorial/ExternalLibraries.md 

Resources

Before publishing a custom visual, we recommend reviewing the resources it includes. 

Following the guidance in the following sections will help keep your visual as safe as possible: 

  

• Do not use local resources that might disclose private information about you, your organization, or anything that's not specifically related to the Power BI visual. 
• Try not to keep TODO tasks as comments inside the code, these can be viewed when debugging the visual at any point from the browser. 
• Do not accept user input as a resource. For example, if you provide a set of colors to choose from, make sure to provide an element with hardcoded values, or values that came from your resource file. Do not let the user type the name of the color as a free text. Although programmatically this is possible, it requires a more robust input validation so it won't be bypassed, possibly causing a Code Injection or an XSS

HTTP Requests

When running a custom visual, inspect the network requests it sends and gets. 

We recommend that developers keep control of their visuals’ network traffic and any external resources they consume.

Sandboxing

PowerBI contains each custom visual in a secure sandbox of its own,

This structure provides the necessary data isolation on the client side from one visual to another.

Read more about sandbox attribute.

Linting

Linting helps developers align with the best developing practices, security practices and syntax standards. 

  

Microsoft's recommended linting rule sets are the following:

https://github.com/Microsoft/tslint-microsoft-contrib 

  

Tslint 

https://github.com/palantir/tslint 

  

The following commands install the necessary packages to properly lint your code” 

npm install tslint --save-dev
npm install typings --save-dev
npm install tslint-microsoft-contrib --save-dev
tslint --init ( if tslint.json does not exist already )

TypeScript

TypeScript is a programming language developed by Microsoft. 

It is a strict superset of JavaScript meant to assist developers building large applications using static types, class-based OOP and modularity. 

Even though it restricts the base code to types and classes, using TypeScript does not mean the code is safe from vulnerabilities. 

XSS attacks are possible if using a string that is not parsed correctly. 

  

Here are some rules you should keep in mind:  

• Never trust user input or data 
• Encode everything 
• Keep data and markup separated 
• Use DOM properties manipulation like setAttribute(), getAttribute() , .attr(), .append(element), etc'. 

Read more about element properties. 

More about TypeScript.

Parsing user input

Avoid using .innerHTML, .HTML, .settimeout(paint()..., eval() and other risky JavaScript functions. 

If you want to add content to an element inside a visual please use the proper DOM API for it, for example: .append, .setAttribute, element.TextContext, element.text, etc.... 

We recommend using the D3 library, since D3 was tested and is very popular, it is safer to set and get user input with. 

When you use the D3 and the DOM API correctly, there is no need to perform vast input escaping - the browser API makes sure user input resides between the text apostrophes, rendered as text and not as HTML Markup, eliminating the risk of code injection and XSS attacks. 

  

Examples how to use D3 in a custom visual are found in the following location: 

PowerBI-visuals/Tutorial 

  

In addition, you may want to check the latest OWASP recommendations. 

XSS Prevention Rules Summary

The following HTML snippets demonstrate how to safely render untrusted data in a variety of different contexts. 

Data Type Context Code Sample Defense

String	HTML Body	<span>UNTRUSTED DATA</span>	HTML Entity Encoding
String	Safe HTML Attributes	<input type="text" name="fname" value="UNTRUSTED DATA">	Aggressive HTML Entity Encoding Only place untrusted data into a whitelist of safe attributes (listed below). Strictly validate unsafe attributes such as background, id and name.
String	GET Parameter	<a href="/site/search?value=UNTRUSTED DATA">clickme</a>	URL Encoding
String	Untrusted URL in a SRC or HREF attribute	<a href="UNTRUSTED URL">clickme</a> <iframe src="UNTRUSTED URL" />	Canonicalize input URL Validation Safe URL verification Whitelist http and https URL's only (Avoid the JavaScript Protocol to Open a new Window) Attribute encoder
String	CSS Value	<div style="width: UNTRUSTED DATA;">Selection</div>	Strict structural validation CSS Hex encoding Good design of CSS Features
String	JavaScript Variable	<script>var currentValue='UNTRUSTED DATA';</script> <script>someFunction('UNTRUSTED DATA');</script>	Ensure JavaScript variables are quoted JavaScript Hex Encoding JavaScript Unicode Encoding Avoid backslash encoding (\" or \' or \\)
HTML	HTML Body	<div>UNTRUSTED HTML</div>	HTML Validation (JSoup, AntiSamy, HTML Sanitizer)
String	DOM XSS	<script>document.write("UNTRUSTED INPUT: " + document.location.hash);<script/>	DOM based XSS Prevention Cheat Sheet

OWASP XSS CHEATSHEET

Privacy

When developing a visual on your local workstation, developers sometimes test it with our own files, which usually contains some data, which you may not always want to expose or publish. 

In custom visuals there are several sections to check, in terms of ensuring security, before releasing a custom visual.

1. Do not include private files or folders such as node_modules, dist, all temp folders 
2. Check files signature - verify no private information is contained in your files (images, text files) 
3. Do not keep private configuration files on the git repository. (use .gitignore) 
4. Do not push temporary or redundant files to the git repository - only the files that the visual is using ( what pbiviz new creates for you + optional sample data for project ) 
5. Make sure sample data is free of private company data. 

Recap

Packages, Resources, HTTP Requests, Sandboxing, Linting, TypeScript, Parsing user input, and Privacy 

Custom visuals provide a perfect platform to share your data visualization within, or out of your company, but make sure you keep the data & information safe on your side.

It is highly recommended to go through all the sections described in this document so you can harden your visuals before releasing them.

Stay safe,

Assaf Vilmovski

Power BI Custom visuals